Skip to content

Ethos and Banner Prerequisites

Jump to bottom
s9terpsync-release-bot edited this page Aug 10, 2026 · 2 revisions

Ethos & Banner Prerequisites

This page is for whoever administers your Banner/Oracle database and your Ellucian Ethos environment. Everything here needs to exist before S9TerpSync can talk to your ERP: a Banner/Oracle integration user with the right grants, and an Ethos application/proxy exposing the right resources.

Getting these grants right matters in both directions. Under-granting means S9TerpSync fails at runtime with 401/403 errors against Ethos or Banner. Over-granting means the integration user can read or write more of Banner than this tool actually uses — a real security and audit concern for any Banner DBA. The tables below are scoped to exactly what this version of S9TerpSync implements; nothing more.

1. Create an integration user (Oracle / Banner)

1.1 Integration user definition

  1. Username: choose an account name that identifies it as a service/integration account (this page uses SLATE_USR_API as an example — pick whatever fits your institution's naming convention).
  2. Oracle user configuration:
    1. Create or alter the Oracle user:
      1. Authorize BANPROXY: checked
      2. Authorize BANJSPROXY: checked
      3. Default tablespace: UNLIMITED TABLESPACE
      4. Default role: USR_DEFAULT_CONNECT
      5. Profile: NOEXPIRE
    2. Ensure the integration user has the following Oracle role grants:
GRANTEE GRANTED_ROLE ADMIN_OPTION DELEGATE_OPTION DEFAULT_ROLE COMMON INHERITED
SLATE_USR_API BAN_DEFAULT_M NO NO NO NO NO
SLATE_USR_API USR_DEFAULT_CONNECT NO NO YES NO NO
SLATE_USR_API BAN_DEFAULT_Q NO NO NO NO NO
SLATE_USR_API CONNECT NO NO YES NO NO

This shape (the user account, its Oracle role membership) is standard for any Banner/Ethos integration user and doesn't depend on which specific resources a given tool consumes — a general Banner DBA reference, not something specific to S9TerpSync.

1.2 Banner object privileges (GURUOBJ)

This is the part that does depend on what S9TerpSync actually does. The table below grants object privileges only for Banner objects backing a resource this version of S9TerpSync implements — see section 3 for the full resource list. Every row states which implemented resource justifies it.

Important

Banner object privileges and their exact names vary by Banner version and by institution-specific GURUOBJ/GURAOBJ customization. Most rows below map directly to a named Ethos resource this version implements, but a couple (SPAIDEN's coverage of address maintenance, SGASTDN's tie to student attribute/cohort data) are based on general Banner domain knowledge of what those forms typically govern, not an explicit object-level statement in this project's own resource documentation. Have your Banner DBA validate every object name against your actual instance before applying these grants — treat this table as a starting point for that review, not a substitute for it.

OBJECT_NAME GRANTED_ROLE Integration purpose
SPAIDEN BAN_DEFAULT_M General person identification, biographical data, and address maintenance (persons v12; general-person-identification-address v1)
SAAADMS BAN_DEFAULT_M Admissions application header, curricula, entry term/level/campus/program codes (admissions-application-curricula v1)
SAADCRV BAN_DEFAULT_M Admissions decision processing — admit/deny/waitlist codes (admissions-decision-processing v1)
SOAFOLK BAN_DEFAULT_M Parent and guardian biographical/relationship records (guardian-information v1)
SOAHSCH BAN_DEFAULT_M Prior high school details — school code, graduation date, GPA (high-school-information-high-school-details v1)
SGASTDN BAN_DEFAULT_M Student attribute and student cohort record maintenance (admissions-application-contacts-cohorts-attributes v1)
GUAINIT BAN_DEFAULT_M Baseline Ethos/API initialization access required for any Banner integration user account (not tied to a single resource)
GUAGMNU BAN_DEFAULT_M Baseline menu/system object navigation access required for the integration user account to operate (not tied to a single resource)
STVNATN BAN_DEFAULT_Q ISO-3166 nation code validation, supporting the country codes written by address resources (persons v12 addresses; general-person-identification-address v1)

1.3 DBA grant script

Grant the underlying database SELECT permissions needed for Ethos BPAPI/EEDM metadata access. These are generic Ethos integration metadata tables, independent of which specific resources are enabled:

-- Execute as SYS or DBA in the target Banner database environment
grant select on bansecr.gubiprf to SLATE_USR_API;
grant select on general.gubobjs to SLATE_USR_API;
grant select on general.gubpage to SLATE_USR_API;
grant select on bansecr.guraobj to SLATE_USR_API;
grant select on bansecr.guruobj to SLATE_USR_API;
grant select on bansecr.gurownr to SLATE_USR_API;

2. Configure Ethos Hub & Application Proxy

2.1 Create the Ethos application

  1. App name: choose a name that identifies this as the S9TerpSync integration (for example, s9terpsync-proxy).
  2. Description: something identifying its purpose, e.g. "Slate CRM to Banner Admissions integration service."
  3. Connect authoritative services — point the application at the same Banner integration user created in section 1 for each authoritative source Ethos requires:
    • Student API authoritative source: the integration user's credentials
    • Integration API authoritative source: the integration user's credentials
    • Business Process API authoritative source: the integration user's credentials

Consult your Ethos Hub administrator's own documentation for the exact steps in your Ethos portal version — this section describes the general shape of the process (create an app, wire it to your Banner authoritative sources), not a click-by-click walkthrough.

2.2 Issue an Ethos API key

Once the application is connected to its authoritative sources, issue an API key for it in the Ethos Hub portal. That key is what goes into S9TerpSync's configuration — see section 4.

3. Ethos resources this version uses

Grant the Ethos application access to exactly these resources — no more. This list is sourced from what's actually implemented in this version, not from any hypothetical future integration surface.

Resource Version Read/Write Used for
persons v12 Read/Write Person matching and biographical read-merge-write
persons-credentials v11 Read Banner-ID / Slate-ID credential matching
guardian-information v1 Read/Write Family relationship (parent/guardian) records
high-school-information-high-school-details v1 Read/Write Prior school (high school) details
general-person-identification-address v1 Read/Write Family address
admissions-application-curricula v1 Read/Write Admission application (curricula, term/level/campus/program)
admissions-decision-processing v1 Read/Write Admission decision (admit/deny/waitlist)
admissions-application-contacts-cohorts-attributes v1 Read/Write Student attribute and student cohort records

Reference data (read-only, used to validate and crosswalk codes rather than to move applicant data):

Resource Version
races v6
address-types v6
alternative-credential-types v1
ethnicities v6
interests v6
relationship-types v1.0.0

The six reference-data domains above, plus persons-credentials, are directly pinned by config keys in ethos.resourceVersions in config/s9terpsync.example.yaml (race, addressType, alternativeCredentialType, ethnicity, interest, relationshipType, personCredential) — if your Ethos application's granted version for one of these doesn't match what's configured, requests will fail at runtime with a version-mismatch error. The other seven resources (persons, guardian-information, high-school-information-high-school-details, general-person-identification-address, admissions-application-curricula, admissions-decision-processing, admissions-application-contacts-cohorts-attributes) are not config-pinned version keys at all — their versions are fixed by the implementation itself, so your Ethos application still needs to expose the exact major version listed above, but there's no corresponding YAML key to check it against.

4. Where the API key goes

The Ethos API key issued in section 2.2 is never written directly into s9terpsync.yaml. Configuration only holds a reference to where the key lives — either an environment variable or a file on disk:

ethos:
  apiKeySecretRef: file:/etc/s9terpsync/secrets/ethos-api-key
  # or: apiKeySecretRef: env:ETHOS_API_KEY

See the Configuration Reference page for the full ethos: block and how secret references (file: and env:) are resolved at runtime. The raw key should never appear in the YAML file itself, in version control, or in logs.

Clone this wiki locally