Sign in
latestOpenAPI 3.1.02026-08-194237902.5 MB

563848e0ecc0

EgressTemplate

Create an egress template with mapping CSV

Uploads a CSV column-mapping file and associated metadata to define a new egress template for data export.

When to use: call this when no existing template covers the target tenant and entity type. To replace the CSV or update metadata on a template that already exists, use PUT /api/v1/egress-templates/{templateId} instead.

Preconditions: tenant-id header must be present and non-blank (returns 400 if missing). templateName and entityType are required form fields; entityType must be one of practitioner, facility, group. status on creation is limited to draft or active — inactive is rejected with 400 at create time.

Defaults applied when omitted: outputFormat -> csv, separator -> ,, status -> draft, scheduleEnabled -> false, scheduleFrequency -> daily, scheduleTime -> 02:00, scheduleTimezone -> UTC (the scheduleFrequency/scheduleTime defaults are skipped when scheduleCron is supplied).

Schedule field rules: scheduleFrequency accepts daily, weekly, monthly, or custom. scheduleCron (Quartz cron syntax, not Unix cron) is required when scheduleFrequency=custom and is rejected for any other frequency. scheduleTime (24-hour HH:mm) is required for daily/weekly/monthly. scheduleDayOfWeek (1 = Sunday ... 7 = Saturday) is required, and only allowed, for weekly. scheduleDayOfMonth (1-31) is required, and only allowed, for monthly.

CSV constraints: maximum file size is 5 MB; exceeding this returns 400. Column attribute paths are validated against the entity type's field schema.

Side effects: the CSV is uploaded to GCS before the template record is written. If the data-store write fails after a successful GCS upload, the GCS object is rolled back so no orphaned file is left behind. Not idempotent — each successful call creates a new template.

Returns: the created template, including the server-assigned id, version set to 1, and mappingsCsvUrl pointing at the uploaded CSV in GCS.

post/api/v1/egress-templates

Headers

tenant-idstring
x-user-idstring

Response

The newly created egress template, with server-assigned id, version=1, and the mappings CSV's GCS URL

idstring

Server-assigned unique identifier of the template.

tenantIdstring

ID of the tenant that owns this template.

createdAtstring date-time
createdBystring

ID of the user who created the template.

updatedAtstring date-time
updatedBystring

ID of the user who last updated the template.

templateNamestring

Human-readable template name.

descriptionstring

Free-text description of the template's purpose.

entityTypestring

Entity type this template maps: practitioner, facility, or group. Immutable after creation.

outputFormatstring

Output file format produced by exports run from this template, e.g. csv.

separatorstring

Delimiter used in the output CSV.

statusstring

Template lifecycle status: draft, active, or inactive (soft-deleted).

versioninteger

Version number, incremented on each successful update. Not incremented by delete.

mappingsCsvUrlstring

GCS URL of the current mapping CSV for this template version.

scheduleEnabledboolean

Whether scheduled (unattended) exports are enabled for this template.

scheduleFrequencystring

Schedule cadence: daily, weekly, monthly, or custom. Null when no schedule is configured.

scheduleTimestring

Time of day the schedule runs, 24-hour HH:mm. Null when scheduleFrequency is custom or no schedule is configured.

scheduleDayOfWeekinteger

Day of week the schedule runs: 1 = Sunday ... 7 = Saturday. Only set when scheduleFrequency=weekly.

scheduleDayOfMonthinteger

Day of month (1-31) the schedule runs. Only set when scheduleFrequency=monthly.

scheduleCronstring

Quartz cron expression (6-7 fields, not standard 5-field Unix cron) defining the schedule. Only set when scheduleFrequency=custom.

scheduleTimezonestring

IANA timezone identifier the schedule runs in, e.g. America/New_York.

scheduleDaysOfWeekstring

Comma-separated days of week the schedule runs: 1 = Sunday ... 7 = Saturday. Only set when scheduleFrequency=weekly.

scheduleIntervalinteger

Interval in hours between runs (1, 2, 3, 4, 6, 8 or 12 — divisors of 24). Only set when scheduleFrequency=hourly.

lastExportAtstring date-time
nextExportAtstring date-time
jobTypestring

Derived export trigger type for the Activity Center UI: SCHEDULED when a schedule is enabled, MANUAL otherwise. Not persisted by the data store.

createdByNamestring

Display name resolved from createdBy, when resolvable. Null if resolution failed or has not been attempted; callers should fall back to createdByEmail then createdBy in that case.

createdByEmailstring

Email resolved from createdBy, when resolvable. Null if resolution failed or has not been attempted; used as the display fallback between createdByName and the raw createdBy id.

bqExportEnabledboolean
bqTableNamestring
bqDatasetstring

Example response

{
  "createdAt": "2022-03-10T16:15:50Z",
  "updatedAt": "2022-03-10T16:15:50Z",
  "scheduleCron": "0 0 8 ? * MON",
  "scheduleDaysOfWeek": "2,4,6",
  "scheduleInterval": 6,
  "lastExportAt": "2022-03-10T16:15:50Z",
  "nextExportAt": "2022-03-10T16:15:50Z"
}