Configuration Reference

Configuration Reference

This page is for whoever writes s9terpsync.yaml — the single file that describes your institution, your Slate source, your Ethos connection, and how S9TerpSync behaves at runtime. It walks the shipped example, config/s9terpsync.example.yaml, top to bottom, and documents the three config subcommands you use to create, check, and inspect that file.

It doesn't cover what your Ethos application needs to expose, or what Banner grants your integration user needs — that's Ethos & Banner Prerequisites. It doesn't cover the separate diagnose command either — that's a top-level CLI command, not part of config, and it's covered on Diagnostics & Troubleshooting.

Secret references

Before walking the fields: three of them (sources.sftp.passwordSecretRef, sources.slateApi.authenticationSecretRef, ethos.apiKeySecretRef) hold a reference to a secret, never the secret itself. A secret reference is one of two forms:

• file:/absolute/path — read the trimmed contents of the file at that absolute path.
• env:NAME — read the environment variable NAME.

No raw password, token, or API key is ever written directly into the YAML file. This is enforced by the config schema (any key ending in SecretRef must match one of those two patterns) and by config show (see below), which redacts every *SecretRef value regardless of which form it uses.

The example file, section by section

The full annotated example ships at config/s9terpsync.example.yaml. What follows walks it top to bottom.

Top-level fields

schemaVersion: 1
institutionId: example-university
environment: development
stateDirectory: /var/lib/s9terpsync

• schemaVersion — always 1. This is the only value the current schema accepts; it exists so a future breaking change to the configuration shape has somewhere to hang a version bump.
• institutionId — a non-empty string identifying your institution. It's the value config validate echoes back on success and has no other runtime meaning beyond identification.
• environment — either development or production. This isn't cosmetic: production tightens validation elsewhere in the file (for example, it requires an SFTP host key pin and an HTTPS Slate API URL — see the notes under sources below).
• stateDirectory — an absolute path (must start with /) where S9TerpSync keeps its file-based state: run manifests, locks, and audit records. There's no database to provision; this directory is where that data lives instead.

http

http:
  host: 127.0.0.1
  port: 4010

The bind address and port for S9TerpSync's local HTTP surface. Both fields default to the values shown (127.0.0.1 and 4010) if omitted.

schedule

schedule:
  enabled: false
  cron: '0 2 * * *'
  timeZone: America/Chicago
  mode: DRY_RUN
  source: auto

• enabled — whether the service runs on a schedule at all. When false, the rest of this block is still validated but has no effect until you flip it on.
• cron — a standard cron expression for when scheduled runs fire.
• timeZone — the IANA time zone the cron expression is interpreted in (for example America/Chicago).
• mode — DRY_RUN or LIVE. This is required whenever enabled is true — an enabled schedule with no mode fails validation. DRY_RUN exercises the full pipeline (source read, matching, crosswalks, target planning) without writing to Ethos; LIVE actually mutates Banner data through Ethos.
• source — which configured source a scheduled run reads from: auto (pick whichever of sftp/slateApi is enabled — see the sources block; exactly one is expected to be enabled in practice), sftp, or slate-api.

sources.sftp

sources:
  sftp:
    enabled: true
    host: sftp.example.edu
    port: 22
    operationTimeoutMs: 5000
    username: s9terpsync
    passwordSecretRef: file:/etc/s9terpsync/secrets/sftp-password
    hostKeySha256: sha256:aaaa...
    claimPath: /claim
    inboundPath: /inbound
    processedPath: /processed
    reportsPath: /reports
    fileNamePattern: '^slate.*'
    delimiter: '|'

• enabled — whether the SFTP source is active. At least one of sources.sftp or sources.slateApi must be enabled; the config is invalid if neither is.
• host, port — the SFTP server address. port defaults to 22.
• operationTimeoutMs — timeout, in milliseconds, applied to individual SFTP operations. Defaults to 5000.
• username — the SFTP login user.
• passwordSecretRef — a secret reference (see above) to the SFTP password. At least one of passwordSecretRef or privateKeySecretRef (not shown in the example, but accepted) is required for authentication.
• hostKeySha256 — the pinned SFTP host key, formatted sha256:<64 lowercase hex characters>. This is required in production, and also required in development unless the host is a loopback address (127.0.0.1, localhost, ::1) — pinning a real remote host key is expected even in development.
• claimPath, inboundPath, processedPath, reportsPath — absolute, normalized remote directory paths S9TerpSync uses to claim, read, and archive files, and to write run reports. claimPath must differ from each of the other three.
• fileNamePattern — a regular expression (JavaScript syntax) matched case-insensitively against filenames in inboundPath to select which files this source picks up.
• delimiter — the single-character field delimiter for the fixed-format Slate export files read from SFTP. Defaults to |.

sources.slateApi

sources:
  slateApi:
    enabled: false
    baseUrl: http://localhost:4001/slate/applicants
    authenticationSecretRef: file:/etc/s9terpsync/secrets/slate-api-token
    requestMethod: GET
    responseFormat: flat-json
    timeoutMs: 5000
    retry:
      maxAttempts: 3
      retryableStatusCodes: [429, 500, 502, 503, 504]
      maxDelayMs: 1000
    pagination:
      strategy: none
      pageSize: 500
      pageParameter: page
      offsetParameter: offset
      limitParameter: limit
      cursorParameter: cursor
      recordsJsonPath: records
      nextCursorJsonPath: nextCursor
      maxPages: 100
    csv:
      delimiter: ','

• enabled — whether the Slate API source is active (same at-least-one-source rule as sftp above).
• baseUrl — the Slate API endpoint. Outside development-loopback addresses, this must be HTTPS; in production it must always be HTTPS. It must not embed credentials (no user:pass@ userinfo).
• authenticationSecretRef — a secret reference to the Slate API auth token.
• requestMethod — GET or POST.
• responseFormat — flat-json or csv.
• timeoutMs — request timeout in milliseconds. Defaults to 5000.

retry — how failed Slate API requests are retried:

• maxAttempts — up to 5. Defaults to 3.
• retryableStatusCodes — HTTP status codes that trigger a retry. Defaults to [429, 500, 502, 503, 504].
• maxDelayMs — the retry backoff ceiling, in milliseconds. Defaults to 1000.

pagination — how multi-page Slate API responses are walked:

• strategy — none, page, offset, or cursor. Defaults to none. csv responses only support none — pairing responseFormat: csv with any other pagination strategy fails validation.
• pageSize — records requested per page. Defaults to 500.
• pageParameter, offsetParameter, limitParameter, cursorParameter — the query parameter names used for page, offset/limit, and cursor pagination respectively, so this can be adapted to whatever parameter names your Slate API instance expects.
• recordsJsonPath, nextCursorJsonPath — dot-separated JSON paths (into the response body) for locating the records array and, for cursor pagination, the next cursor value.
• maxPages — an upper bound on pages fetched per run, as a safety limit. Defaults to 100.

csv — only meaningful when responseFormat: csv:

• delimiter — the single-character CSV field delimiter. Defaults to ,.

ethos

ethos:
  baseUrl: https://integrate.elluciancloud.com
  apiKeySecretRef: file:/etc/s9terpsync/secrets/ethos-api-key
  timeoutMs: 30000
  retry:
    maxAttempts: 3
    initialDelayMs: 250
    retryableStatusCodes: [500, 502, 503, 504]
    maxDelayMs: 1000
    multiplier: 2
  resourceVersions:
    race: '6'
    addressType: '6'
    alternativeCredentialType: '1'
    ethnicity: '6'
    interest: '6'
    relationshipType: '1.0.0'
    personCredential: '11'
  personLookup:
    credentialContractVerified: false
    slateCredentialTypeId: null

• baseUrl — your Ethos environment's base URL (for example, https://integrate.elluciancloud.com).
• apiKeySecretRef — a secret reference to the Ethos API key. What that key needs to be authorized for — which authoritative sources it's connected to, and which Ethos resources are granted — is covered on Ethos & Banner Prerequisites, not here.
• timeoutMs — request timeout in milliseconds for Ethos calls.

retry — Ethos request retry behavior:

• maxAttempts — up to 5. Defaults to 3.
• initialDelayMs — the first retry delay, in milliseconds. Defaults to 250. Must not exceed maxDelayMs.
• retryableStatusCodes — defaults to [500, 502, 503, 504].
• maxDelayMs — the backoff ceiling. Defaults to 1000.
• multiplier — the backoff growth factor between attempts (1–10). Defaults to 2.

resourceVersions — pins the exact version of each version-sensitive Ethos resource this config expects the Ethos application to expose: race ('6'), addressType ('6'), alternativeCredentialType ('1'), ethnicity ('6'), interest ('6'), relationshipType ('1.0.0'), personCredential ('11'). These are the shipped defaults and, for this version of S9TerpSync, the only values the schema currently accepts. Which Ethos resources these keys correspond to, and why a version mismatch fails at runtime rather than at config-validate time, is covered on Ethos & Banner Prerequisites — that page also lists the other Ethos resources this version uses that aren't version-pinned in config at all.

personLookup — tuning for how S9TerpSync looks up an existing person record in Ethos before creating one:

• credentialContractVerified — boolean, defaults to false.
• slateCredentialTypeId — a UUID identifying the Slate-ID credential type in Ethos, or null if not set.

referenceData

referenceData:
  enabledDomains: []
  pageSize: 100

• enabledDomains — which reference-data domains to pull and cache from Ethos: any of race, addressType, alternativeCredentialType, ethnicity, interest, relationshipType, with no duplicates. Defaults to an empty list.
• pageSize — how many reference-data records to request per page when populating the cache. Defaults to 100.

crosswalks

crosswalks:
  - domain: gender
    sourceValue: Female
    targetCode: F
    enabled: true

Each entry maps one source-side value to a target-side code (and/or ID) within a named domain:

• domain — a non-blank string naming the crosswalk domain (for example gender).
• sourceValue — the value as it appears in the Slate-side data.
• targetCode — the code to map it to on the Ethos/Banner side. (A crosswalk entry may instead — or additionally — supply targetId; at least one of targetCode/targetId is required, though only targetCode appears in the shipped example.)
• enabled — whether this crosswalk entry is active.

Defaults to an empty list if omitted.

retention

retention:
  runs:
    action: retain
  reports:
    action: retain
  referenceCache:
    action: retain
  archives:
    action: retain

Four independent retention policies, one each for run manifests, run reports, the reference-data cache, and archived files. Each accepts an action of retain, archive, or delete (defaulting to retain), with one exception: archives cannot itself use archive as its action (only retain or delete) — archiving the archive location doesn't mean anything. Choosing archive or delete for any policy also requires an afterDays value (a positive integer) stating how many days to wait before that action applies; that key isn't shown in the example because every policy here is retain, which doesn't need one. See Retention, Replay & Recovery for how these policies are applied.

CLI commands

Three config subcommands cover the full lifecycle of s9terpsync.yaml: generating a starting point, checking it's valid, and inspecting the effective configuration without exposing secrets.

config init

s9terpsync config init --source <source> --institution-id <id> --environment <environment> [--out <path>]

• --source (required) — sftp, slate-api, or both. Determines which sources.* block(s) the generated file includes.
• --institution-id (required) — becomes institutionId in the generated file.
• --environment (required) — development or production. Also affects the generated sources.slateApi.baseUrl (a loopback URL for development, an HTTPS placeholder for production).
• --out (optional) — write the generated YAML to this path instead of printing it to stdout. The file is written with mode 0640 and fails if the target already exists (it will not silently overwrite an existing config).

Example:

s9terpsync config init --source both --institution-id example-university --environment development --out ./s9terpsync.yaml

config validate

s9terpsync config validate --file <path>

• --file (required) — path to the YAML file to validate.

Loads and validates the file against the full configuration schema (all the field rules described above — required-secret combinations, production-only checks, cross-field constraints, and so on). On success it prints configuration valid for <institutionId>. On failure it prints one <location>: <problem> line per validation failure to stderr and exits non-zero, so a config with several unrelated issues (say, a bad hostKeySha256 and a duplicate crosswalk domain) reports all of them in one pass rather than stopping at the first.

config show

s9terpsync config show --file <path> --redacted

• --file (required) — path to the YAML file to load.
• --redacted (required) — there is no unredacted show mode. Omitting --redacted fails the command outright (config show throws before it does anything else) rather than printing secrets. When present, it loads and validates the file the same way config validate does, then prints the effective configuration as YAML with every *SecretRef value replaced by <redacted> — this includes values defaulted in by the schema, not just the ones you wrote explicitly. The output carries a header noting it's for display only and shouldn't be used as runtime input.

Example:

s9terpsync config show --file ./s9terpsync.yaml --redacted

Where to go next

• Ethos & Banner Prerequisites — what your Ethos application and Banner integration user need before ethos.apiKeySecretRef and ethos.resourceVersions mean anything at runtime.
• Diagnostics & Troubleshooting — the separate, top-level diagnose --file <path> command, which checks a config file against your live environment (connectivity, credentials, and so on) rather than just its shape.
• Running S9TerpSync — using a validated config file to actually run a sync.