> For the complete documentation index, see [llms.txt](https://developer.emporix.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.emporix.io/api-references/readme/api-reference-33/models.md). # Models ## The errorMessage object ```json {"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"errorMessage":{"title":"Error","description":"Schema for specific API errors.","type":"object","properties":{"code":{"type":"integer","description":"HTTP status code.","minimum":100,"maximum":599},"status":{"description":"HTTP status.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"details":{"description":"List of problems causing this error.","type":"array","items":{"title":"Error Detail","description":"Error details.","type":"string"}}},"required":["status","code","message"]}}}} ``` ## The ImportConfig object ```json {"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"ImportConfig":{"title":"Import configuration","type":"object","description":"An import configuration grouping one or more streams.","properties":{"id":{"type":"string","format":"uuid","description":"The configuration identifier."},"tenant":{"type":"string","description":"The owning tenant."},"name":{"type":"string","description":"The configuration name."},"description":{"type":"string","description":"A free-text description."},"sourceConnId":{"type":"string","format":"uuid","description":"The default source connection for the configuration's streams."},"aiEnabled":{"type":"boolean","description":"Whether AI-assisted mapping suggestions are enabled for the configuration."},"enabled":{"type":"boolean","description":"Whether the configuration is active."},"version":{"type":"integer","description":"Incremented on every change to the configuration."},"healthThresholds":{"$ref":"#/components/schemas/HealthThresholds"},"createdBy":{"type":"string","description":"The identifier of the user who created the configuration."},"createdAt":{"type":"string","format":"date-time","description":"When the configuration was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the configuration was last updated."}}},"HealthThresholds":{"title":"Health thresholds","type":"object","description":"The limits that decide whether a stream is reported as `GREEN`, `AMBER`, or `RED`. Each field is optional and resolves independently. An unset field falls back through the hierarchy, from the most specific level to the least specific: stream, configuration, tenant, then the built-in default.","properties":{"failureRatioAmber":{"type":"number","format":"double","description":"The share of failed records (0..1) at or above which the stream is `AMBER`."},"failureRatioRed":{"type":"number","format":"double","description":"The share of failed records (0..1) at or above which the stream is `RED`."},"staleAmberHours":{"type":"integer","description":"The age threshold, in hours, for the stream's newest data. The stream is `AMBER` when the data's age reaches or exceeds this threshold."},"staleRedHours":{"type":"integer","description":"The age threshold, in hours, for the stream's newest data. The stream is `RED` when the data's age reaches or exceeds this threshold."},"failedRunIsRed":{"type":"boolean","description":"Whether a failed most-recent run makes the stream `RED` regardless of the other limits."}}}}}} ``` ## The ImportStream object ```json {"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"ImportStream":{"title":"Stream","type":"object","description":"A stream that extracts from a source, maps fields, and upserts into an Emporix target type.","properties":{"id":{"type":"string","format":"uuid","description":"The stream identifier."},"configId":{"type":"string","format":"uuid","description":"The parent configuration."},"name":{"type":"string","description":"The stream name."},"sourceEntity":{"type":"string","description":"The logical source entity or record."},"targetWriter":{"type":"string","description":"The target writer code, for example `emporix.customEntity`."},"targetType":{"type":"string","description":"The default target type (custom-entity type identifier)."},"mode":{"type":"string","enum":["STANDALONE","COMPOSITE_CHILD","COMPOSITE_MERGE"],"description":"How the stream contributes to the target."},"deltaField":{"type":"string","description":"The source field whose value is tracked as the delta watermark. A delta run extracts only the records whose value is newer than the last run's."},"deltaFieldFormat":{"type":"string","enum":["DATE","UNIX_SECONDS","UNIX_MILLIS"],"description":"How the delta field's values are formatted, so they can be compared correctly."},"compositeParent":{"type":"string","description":"For a composite child stream, the name of the stream it contributes to."},"linkingField":{"type":"string","description":"For a composite child stream, the source field holding its parent's key."},"embedAttribute":{"type":"string","description":"For a composite child stream, the parent attribute its records are embedded into."},"childStrategy":{"type":"string","enum":["EMBED","PATCH"],"description":"How a composite child's records reach the parent object."},"writeStrategy":{"type":"string","enum":["PATCH","MERGE_PUT","REPLACE_PUT"],"description":"How an existing target object is updated. `PATCH` changes only the mapped fields and preserves everything else; `REPLACE_PUT` replaces the whole object, so fields this import does not manage are cleared."},"discriminatorField":{"type":"string","description":"A source field whose value routes each record to a different target type, as defined by `discriminatorMap`."},"discriminatorMap":{"type":"object","additionalProperties":{"type":"string"},"description":"Maps a discriminator value to the target type that receives those records."},"deleteConfig":{"type":"object","description":"How deletes are detected in the source and propagated to the target. Omit for an upsert-only\nstream. `MARKER`: a field on the record flags it as deleted. `TOMBSTONE`: a separate source\nrecord lists the deleted IDs.","properties":{"mode":{"type":"string","enum":["MARKER","TOMBSTONE"],"description":"How a deleted record is recognised."},"markerField":{"type":"string","description":"`MARKER` only. The source field that flags a record as deleted."},"markerValues":{"type":"array","items":{"type":"string"},"description":"`MARKER` only. The values of `markerField` that mean deleted."},"record":{"type":"string","description":"`TOMBSTONE` only. The explicit name of the source record that lists deleted IDs. Omit this\nproperty when the name can be derived from the imported record by adding a prefix or suffix —\nfor example, `invoice_deleted` for an `invoice` stream. Specify it when the deletion record\ndoes not follow that naming convention."}}},"healthThresholds":{"$ref":"#/components/schemas/HealthThresholds"},"createdAt":{"type":"string","format":"date-time","description":"When the stream was created."},"enabled":{"type":"boolean","description":"Whether the stream is active."}}},"HealthThresholds":{"title":"Health thresholds","type":"object","description":"The limits that decide whether a stream is reported as `GREEN`, `AMBER`, or `RED`. Each field is optional and resolves independently. An unset field falls back through the hierarchy, from the most specific level to the least specific: stream, configuration, tenant, then the built-in default.","properties":{"failureRatioAmber":{"type":"number","format":"double","description":"The share of failed records (0..1) at or above which the stream is `AMBER`."},"failureRatioRed":{"type":"number","format":"double","description":"The share of failed records (0..1) at or above which the stream is `RED`."},"staleAmberHours":{"type":"integer","description":"The age threshold, in hours, for the stream's newest data. The stream is `AMBER` when the data's age reaches or exceeds this threshold."},"staleRedHours":{"type":"integer","description":"The age threshold, in hours, for the stream's newest data. The stream is `RED` when the data's age reaches or exceeds this threshold."},"failedRunIsRed":{"type":"boolean","description":"Whether a failed most-recent run makes the stream `RED` regardless of the other limits."}}}}}} ``` ## The Schedule object ```json {"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"Schedule":{"title":"Schedule","type":"object","description":"A cron schedule for a configuration.","properties":{"id":{"type":"string","format":"uuid","description":"The schedule identifier."},"configId":{"type":"string","format":"uuid","description":"The scheduled configuration."},"cron":{"type":"string","description":"A Spring cron expression with six fields."},"timezone":{"type":"string","description":"The IANA time zone the cron is evaluated in."},"enabled":{"type":"boolean","description":"Whether the schedule is active."},"nextFireAt":{"type":"string","format":"date-time","description":"The next fire time."}},"required":["cron"]}}}} ``` ## The ImportRun object ```json {"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"ImportRun":{"title":"Run","type":"object","description":"An import run and its reconciled counters.","properties":{"id":{"type":"string","format":"uuid","description":"The run identifier."},"configId":{"type":"string","format":"uuid","description":"The configuration the run belongs to."},"tenant":{"type":"string","description":"The owning tenant."},"trigger":{"type":"string","enum":["MANUAL","SCHEDULED"],"description":"What triggered the run."},"dryRunSample":{"type":"array","description":"Dry-run only. A sample of the mapped records that would be written, so the mapping can be previewed without a real import. Absent on normal runs. Each stream is sampled separately, up to the `sampleSize` set in the run request. A parent stream's records include the records of its composite child streams that have `childStrategy` set to `EMBED` or `PATCH`. Those child records appear in the parent attribute named by the child stream's `embedAttribute`, as a real import writes them. Only child records inside the child stream's own sample are included, so a sampled parent record can show fewer child records than the source contains for that parent, or none. Child records are also sampled under their own stream.","items":{"type":"object","properties":{"stream":{"type":"string","description":"The stream that produced the sample record."},"targetType":{"type":"string","description":"The resolved target type the record would be written to."},"key":{"type":"string","description":"The record's natural/deterministic key."},"fields":{"type":"object","additionalProperties":true,"description":"The mapped target fields that would be written."}}}},"origin":{"type":"string","description":"What requested the run. The `origin` value from the trigger request, or the `trigger` value when `origin` was omitted. Use this field to distinguish a dashboard run from a run started by an integration scenario. The field is absent on runs recorded before it existed."},"status":{"type":"string","enum":["QUEUED","RUNNING","RESUMABLE","SUCCEEDED","PARTIAL","FAILED","CANCELLED","ABORTED"],"description":"The run status. Possible values:\n\n* `QUEUED` – the run waits to start. Nothing has been read yet, and the run has no per-stream\n progress. `queueWaitingFor` says what the run waits for.\n* `RUNNING` – the run is executing.\n* `RESUMABLE` – the run was interrupted, for example by a service restart, and resumes automatically\n from its last checkpoint. It is not a final status.\n* `SUCCEEDED` – the run finished, and every record was processed.\n* `PARTIAL` – the run finished, but not completely: some records failed, a limit skipped records,\n or a stream was not run. The `message` field and the per-stream progress give the details.\n* `FAILED` – the run stopped because of an error.\n* `CANCELLED` – the run was cancelled.\n* `ABORTED` – the service refused to start the run because of the import configuration, for example\n mappings that have never been published or a changed target schema. Nothing was read or written."},"mode":{"type":"string","enum":["FULL","DELTA"],"description":"The run mode."},"startedAt":{"type":"string","format":"date-time","description":"When the run was requested. If the run was queued first, it began executing later, at `executionStartedAt`."},"executionStartedAt":{"type":"string","format":"date-time","nullable":true,"description":"When the run began executing. Equal to `startedAt`, or later by the time the run spent in the queue. `null` while the run is `QUEUED`, and on runs recorded before the field existed."},"finishedAt":{"type":"string","format":"date-time","description":"When the run finished."},"queuePosition":{"type":"integer","minimum":1,"description":"`QUEUED` runs only. The run's position among the queued runs that can start, where `1` starts next. Runs of all tenants share the queue, and a tenant with fewer runs executing goes first. The value is approximate, because the queue changes while you read it. The field is absent when the run is not queued, when it waits for something other than a worker, or when the service has not yet calculated it."},"queueWaitingFor":{"type":"string","enum":["WORKER","PREVIOUS_RUN","TENANT_LIMIT"],"description":"`QUEUED` runs only. What the run waits for. Possible values:\n\n* `WORKER` – the run waits for a free worker. `queuePosition` gives its place in the queue.\n* `PREVIOUS_RUN` – the run waits for the configuration's current run to finish.\n* `TENANT_LIMIT` – the run waits for one of the tenant's runs to finish, because\n `maxConcurrentImports` runs are already executing.\n\nThe field is absent when the run is not queued, or when the service has not yet calculated it."},"supersededRequests":{"type":"integer","description":"The number of later scheduled run requests that were added to this run while it was queued. A configuration has at most one queued run, so a scheduled request that arrives while a real run of the whole configuration is queued does not queue a second run."},"lastRequestedAt":{"type":"string","format":"date-time","description":"When the latest scheduled run request counted in `supersededRequests` was made. Absent when `supersededRequests` is `0`."},"recordsRead":{"type":"integer","description":"Records read (created + updated + skipped + deleted + failed)."},"created":{"type":"integer","description":"Records created."},"updated":{"type":"integer","description":"Records updated."},"skipped":{"type":"integer","description":"Records skipped because they were unchanged."},"failed":{"type":"integer","description":"Records that failed."},"deleted":{"type":"integer","description":"Records deleted."},"duplicateKeys":{"type":"integer","description":"Source rows that repeat a key already imported in this run. The import keeps the last row of each repeated key and discards earlier rows. Duplicate keys do not fail the run; they mean the source feed is not unique on the key the stream imports by."},"unresolvedParents":{"type":"integer","description":"Child records that were not imported because their parent could not be found. Counted separately from `skipped`, which counts records that were already up to date."},"message":{"type":"string","description":"A terminal status message, typically set on failure."},"retryOfRunId":{"type":"string","format":"uuid","description":"When the run retries another run's failed records, the identifier of that original run."},"force":{"type":"boolean","description":"Whether the run rewrote every record, bypassing the skip-if-unchanged check."},"dryRun":{"type":"boolean","description":"Whether the run only extracted, mapped, and validated, writing nothing to the target. A dry run legitimately reports zero for every counter, so this distinguishes it from a run that wrote nothing because it failed."},"cancelRequested":{"type":"boolean","description":"Whether cancellation has been requested for a run that is still finishing."},"dryRunSampleSize":{"type":"integer","description":"For a dry run, how many mapped records were kept as a sample."},"dryRunPublished":{"type":"boolean","description":"Dry-run only. Whether the dry run used the published mappings (`true`) or the draft mappings (`false`)."},"mappingVersions":{"type":"array","description":"The published mapping version each stream uses in this run, fixed when the run starts executing. Version `0` means that the stream has no published mappings. The field is absent while the run is `QUEUED`, on a dry run of the draft mappings, and on runs recorded before it existed.","items":{"type":"object","properties":{"streamId":{"type":"string","format":"uuid","description":"The stream identifier."},"version":{"type":"integer","description":"The published mapping version the stream uses."}}}}}}}}} ``` ## The ImportRunStream object ```json {"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"ImportRunStream":{"title":"Run stream progress","type":"object","description":"The per-stream progress within a run.","properties":{"id":{"type":"string","format":"uuid","description":"The run-stream identifier."},"runId":{"type":"string","format":"uuid","description":"The run this progress belongs to."},"streamId":{"type":"string","format":"uuid","description":"The stream this progress belongs to."},"streamName":{"type":"string","description":"The stream name."},"status":{"type":"string","enum":["QUEUED","RUNNING","SUCCEEDED","PARTIAL","FAILED","SKIPPED","ABORTED"],"description":"The stream's status within the run. `ABORTED` means the service refused to run the stream because of its configuration, for example because its mappings have never been published. It indicates a configuration problem to fix. The `message` field gives the reason."},"recordsRead":{"type":"integer","description":"Records read for this stream."},"created":{"type":"integer","description":"Records created."},"updated":{"type":"integer","description":"Records updated."},"skipped":{"type":"integer","description":"Records skipped."},"failed":{"type":"integer","description":"Records that failed."},"deleted":{"type":"integer","description":"Records deleted."},"duplicateKeys":{"type":"integer","description":"Source rows that repeat a key already imported in this run. The import keeps the last row of each repeated key and discards earlier rows. Duplicate keys do not fail the run; they mean the source feed is not unique on the key the stream imports by."},"unresolvedParents":{"type":"integer","description":"Child records that were not imported because their parent could not be found. Counted separately from `skipped`, which counts records that were already up to date."},"message":{"type":"string","description":"A per-stream status message."}}}}}} ``` ## The RunDetail object ```json {"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"RunDetail":{"title":"Run detail","type":"object","description":"A run together with its per-stream progress.","properties":{"run":{"$ref":"#/components/schemas/ImportRun"},"streams":{"type":"array","description":"The per-stream progress.","items":{"$ref":"#/components/schemas/ImportRunStream"}}}},"ImportRun":{"title":"Run","type":"object","description":"An import run and its reconciled counters.","properties":{"id":{"type":"string","format":"uuid","description":"The run identifier."},"configId":{"type":"string","format":"uuid","description":"The configuration the run belongs to."},"tenant":{"type":"string","description":"The owning tenant."},"trigger":{"type":"string","enum":["MANUAL","SCHEDULED"],"description":"What triggered the run."},"dryRunSample":{"type":"array","description":"Dry-run only. A sample of the mapped records that would be written, so the mapping can be previewed without a real import. Absent on normal runs. Each stream is sampled separately, up to the `sampleSize` set in the run request. A parent stream's records include the records of its composite child streams that have `childStrategy` set to `EMBED` or `PATCH`. Those child records appear in the parent attribute named by the child stream's `embedAttribute`, as a real import writes them. Only child records inside the child stream's own sample are included, so a sampled parent record can show fewer child records than the source contains for that parent, or none. Child records are also sampled under their own stream.","items":{"type":"object","properties":{"stream":{"type":"string","description":"The stream that produced the sample record."},"targetType":{"type":"string","description":"The resolved target type the record would be written to."},"key":{"type":"string","description":"The record's natural/deterministic key."},"fields":{"type":"object","additionalProperties":true,"description":"The mapped target fields that would be written."}}}},"origin":{"type":"string","description":"What requested the run. The `origin` value from the trigger request, or the `trigger` value when `origin` was omitted. Use this field to distinguish a dashboard run from a run started by an integration scenario. The field is absent on runs recorded before it existed."},"status":{"type":"string","enum":["QUEUED","RUNNING","RESUMABLE","SUCCEEDED","PARTIAL","FAILED","CANCELLED","ABORTED"],"description":"The run status. Possible values:\n\n* `QUEUED` – the run waits to start. Nothing has been read yet, and the run has no per-stream\n progress. `queueWaitingFor` says what the run waits for.\n* `RUNNING` – the run is executing.\n* `RESUMABLE` – the run was interrupted, for example by a service restart, and resumes automatically\n from its last checkpoint. It is not a final status.\n* `SUCCEEDED` – the run finished, and every record was processed.\n* `PARTIAL` – the run finished, but not completely: some records failed, a limit skipped records,\n or a stream was not run. The `message` field and the per-stream progress give the details.\n* `FAILED` – the run stopped because of an error.\n* `CANCELLED` – the run was cancelled.\n* `ABORTED` – the service refused to start the run because of the import configuration, for example\n mappings that have never been published or a changed target schema. Nothing was read or written."},"mode":{"type":"string","enum":["FULL","DELTA"],"description":"The run mode."},"startedAt":{"type":"string","format":"date-time","description":"When the run was requested. If the run was queued first, it began executing later, at `executionStartedAt`."},"executionStartedAt":{"type":"string","format":"date-time","nullable":true,"description":"When the run began executing. Equal to `startedAt`, or later by the time the run spent in the queue. `null` while the run is `QUEUED`, and on runs recorded before the field existed."},"finishedAt":{"type":"string","format":"date-time","description":"When the run finished."},"queuePosition":{"type":"integer","minimum":1,"description":"`QUEUED` runs only. The run's position among the queued runs that can start, where `1` starts next. Runs of all tenants share the queue, and a tenant with fewer runs executing goes first. The value is approximate, because the queue changes while you read it. The field is absent when the run is not queued, when it waits for something other than a worker, or when the service has not yet calculated it."},"queueWaitingFor":{"type":"string","enum":["WORKER","PREVIOUS_RUN","TENANT_LIMIT"],"description":"`QUEUED` runs only. What the run waits for. Possible values:\n\n* `WORKER` – the run waits for a free worker. `queuePosition` gives its place in the queue.\n* `PREVIOUS_RUN` – the run waits for the configuration's current run to finish.\n* `TENANT_LIMIT` – the run waits for one of the tenant's runs to finish, because\n `maxConcurrentImports` runs are already executing.\n\nThe field is absent when the run is not queued, or when the service has not yet calculated it."},"supersededRequests":{"type":"integer","description":"The number of later scheduled run requests that were added to this run while it was queued. A configuration has at most one queued run, so a scheduled request that arrives while a real run of the whole configuration is queued does not queue a second run."},"lastRequestedAt":{"type":"string","format":"date-time","description":"When the latest scheduled run request counted in `supersededRequests` was made. Absent when `supersededRequests` is `0`."},"recordsRead":{"type":"integer","description":"Records read (created + updated + skipped + deleted + failed)."},"created":{"type":"integer","description":"Records created."},"updated":{"type":"integer","description":"Records updated."},"skipped":{"type":"integer","description":"Records skipped because they were unchanged."},"failed":{"type":"integer","description":"Records that failed."},"deleted":{"type":"integer","description":"Records deleted."},"duplicateKeys":{"type":"integer","description":"Source rows that repeat a key already imported in this run. The import keeps the last row of each repeated key and discards earlier rows. Duplicate keys do not fail the run; they mean the source feed is not unique on the key the stream imports by."},"unresolvedParents":{"type":"integer","description":"Child records that were not imported because their parent could not be found. Counted separately from `skipped`, which counts records that were already up to date."},"message":{"type":"string","description":"A terminal status message, typically set on failure."},"retryOfRunId":{"type":"string","format":"uuid","description":"When the run retries another run's failed records, the identifier of that original run."},"force":{"type":"boolean","description":"Whether the run rewrote every record, bypassing the skip-if-unchanged check."},"dryRun":{"type":"boolean","description":"Whether the run only extracted, mapped, and validated, writing nothing to the target. A dry run legitimately reports zero for every counter, so this distinguishes it from a run that wrote nothing because it failed."},"cancelRequested":{"type":"boolean","description":"Whether cancellation has been requested for a run that is still finishing."},"dryRunSampleSize":{"type":"integer","description":"For a dry run, how many mapped records were kept as a sample."},"dryRunPublished":{"type":"boolean","description":"Dry-run only. Whether the dry run used the published mappings (`true`) or the draft mappings (`false`)."},"mappingVersions":{"type":"array","description":"The published mapping version each stream uses in this run, fixed when the run starts executing. Version `0` means that the stream has no published mappings. The field is absent while the run is `QUEUED`, on a dry run of the draft mappings, and on runs recorded before it existed.","items":{"type":"object","properties":{"streamId":{"type":"string","format":"uuid","description":"The stream identifier."},"version":{"type":"integer","description":"The published mapping version the stream uses."}}}}}},"ImportRunStream":{"title":"Run stream progress","type":"object","description":"The per-stream progress within a run.","properties":{"id":{"type":"string","format":"uuid","description":"The run-stream identifier."},"runId":{"type":"string","format":"uuid","description":"The run this progress belongs to."},"streamId":{"type":"string","format":"uuid","description":"The stream this progress belongs to."},"streamName":{"type":"string","description":"The stream name."},"status":{"type":"string","enum":["QUEUED","RUNNING","SUCCEEDED","PARTIAL","FAILED","SKIPPED","ABORTED"],"description":"The stream's status within the run. `ABORTED` means the service refused to run the stream because of its configuration, for example because its mappings have never been published. It indicates a configuration problem to fix. The `message` field gives the reason."},"recordsRead":{"type":"integer","description":"Records read for this stream."},"created":{"type":"integer","description":"Records created."},"updated":{"type":"integer","description":"Records updated."},"skipped":{"type":"integer","description":"Records skipped."},"failed":{"type":"integer","description":"Records that failed."},"deleted":{"type":"integer","description":"Records deleted."},"duplicateKeys":{"type":"integer","description":"Source rows that repeat a key already imported in this run. The import keeps the last row of each repeated key and discards earlier rows. Duplicate keys do not fail the run; they mean the source feed is not unique on the key the stream imports by."},"unresolvedParents":{"type":"integer","description":"Child records that were not imported because their parent could not be found. Counted separately from `skipped`, which counts records that were already up to date."},"message":{"type":"string","description":"A per-stream status message."}}}}}} ``` ## The CancelResult object ```json {"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"CancelResult":{"title":"Cancellation result","type":"object","description":"The outcome of a cancellation request.","properties":{"runId":{"type":"string","format":"uuid","description":"The run the cancellation targeted."},"force":{"type":"boolean","description":"Whether a hard stop was requested."},"accepted":{"type":"boolean","description":"Whether the cancellation was accepted. `false` when the run is unknown or already finished."}}}}}} ``` ## The ErrorRecord object ```json {"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"ErrorRecord":{"title":"Error record","type":"object","description":"A single error recorded during a run.","properties":{"id":{"type":"string","format":"uuid","description":"The error identifier."},"runId":{"type":"string","format":"uuid","description":"The run the error occurred in."},"streamId":{"type":"string","format":"uuid","description":"The stream the error occurred in."},"naturalKey":{"type":"string","description":"The source natural key of the offending record."},"targetEntity":{"type":"string","description":"The target writer the record was bound for."},"stage":{"type":"string","description":"The pipeline stage the error occurred in."},"errorCode":{"type":"string","description":"A machine-readable error code."},"message":{"type":"string","description":"A human-readable error message."},"createdAt":{"type":"string","format":"date-time","description":"When the error was recorded."}}}}}} ``` ## The ImportedRecord object ```json {"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"ImportedRecord":{"title":"Imported record","type":"object","description":"A record that was imported. Holds keys and outcome; for composite parents it also holds the embedded child arrays.","properties":{"id":{"type":"string","format":"uuid","description":"The imported-record identifier."},"configId":{"type":"string","format":"uuid","description":"The configuration the record belongs to."},"streamId":{"type":"string","format":"uuid","description":"The stream that produced the record."},"runId":{"type":"string","format":"uuid","description":"The run that last touched the record."},"targetEntity":{"type":"string","description":"The target writer code."},"targetType":{"type":"string","description":"The target type."},"naturalKey":{"type":"string","description":"The source natural key."},"targetId":{"type":"string","description":"The deterministic Emporix instance ID the record was written under. It's derived from the natural key and allows the record to be located in the target."},"fields":{"type":"object","description":"The stored fields."},"outcome":{"type":"string","description":"The last outcome, one of `UPSERTED`, `DELETED`, `DELETED_TARGET`, `FAILED`, or `DRY_RUN`."},"importedAt":{"type":"string","format":"date-time","description":"When the record was last imported."}}}}}} ``` ## The Page object ```json {"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"Page":{"title":"Page","type":"object","description":"Pagination metadata for a page of results.","properties":{"totalElements":{"type":"integer","description":"The total number of elements across all pages."},"totalPages":{"type":"integer","description":"The total number of pages."},"number":{"type":"integer","description":"The current zero-based page number."},"size":{"type":"integer","description":"The page size."}}}}}} ``` ## The ImportRunPage object ```json {"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"ImportRunPage":{"title":"Run page","allOf":[{"$ref":"#/components/schemas/Page"},{"type":"object","properties":{"content":{"type":"array","description":"The runs on this page.","items":{"$ref":"#/components/schemas/ImportRun"}}}}]},"Page":{"title":"Page","type":"object","description":"Pagination metadata for a page of results.","properties":{"totalElements":{"type":"integer","description":"The total number of elements across all pages."},"totalPages":{"type":"integer","description":"The total number of pages."},"number":{"type":"integer","description":"The current zero-based page number."},"size":{"type":"integer","description":"The page size."}}},"ImportRun":{"title":"Run","type":"object","description":"An import run and its reconciled counters.","properties":{"id":{"type":"string","format":"uuid","description":"The run identifier."},"configId":{"type":"string","format":"uuid","description":"The configuration the run belongs to."},"tenant":{"type":"string","description":"The owning tenant."},"trigger":{"type":"string","enum":["MANUAL","SCHEDULED"],"description":"What triggered the run."},"dryRunSample":{"type":"array","description":"Dry-run only. A sample of the mapped records that would be written, so the mapping can be previewed without a real import. Absent on normal runs. Each stream is sampled separately, up to the `sampleSize` set in the run request. A parent stream's records include the records of its composite child streams that have `childStrategy` set to `EMBED` or `PATCH`. Those child records appear in the parent attribute named by the child stream's `embedAttribute`, as a real import writes them. Only child records inside the child stream's own sample are included, so a sampled parent record can show fewer child records than the source contains for that parent, or none. Child records are also sampled under their own stream.","items":{"type":"object","properties":{"stream":{"type":"string","description":"The stream that produced the sample record."},"targetType":{"type":"string","description":"The resolved target type the record would be written to."},"key":{"type":"string","description":"The record's natural/deterministic key."},"fields":{"type":"object","additionalProperties":true,"description":"The mapped target fields that would be written."}}}},"origin":{"type":"string","description":"What requested the run. The `origin` value from the trigger request, or the `trigger` value when `origin` was omitted. Use this field to distinguish a dashboard run from a run started by an integration scenario. The field is absent on runs recorded before it existed."},"status":{"type":"string","enum":["QUEUED","RUNNING","RESUMABLE","SUCCEEDED","PARTIAL","FAILED","CANCELLED","ABORTED"],"description":"The run status. Possible values:\n\n* `QUEUED` – the run waits to start. Nothing has been read yet, and the run has no per-stream\n progress. `queueWaitingFor` says what the run waits for.\n* `RUNNING` – the run is executing.\n* `RESUMABLE` – the run was interrupted, for example by a service restart, and resumes automatically\n from its last checkpoint. It is not a final status.\n* `SUCCEEDED` – the run finished, and every record was processed.\n* `PARTIAL` – the run finished, but not completely: some records failed, a limit skipped records,\n or a stream was not run. The `message` field and the per-stream progress give the details.\n* `FAILED` – the run stopped because of an error.\n* `CANCELLED` – the run was cancelled.\n* `ABORTED` – the service refused to start the run because of the import configuration, for example\n mappings that have never been published or a changed target schema. Nothing was read or written."},"mode":{"type":"string","enum":["FULL","DELTA"],"description":"The run mode."},"startedAt":{"type":"string","format":"date-time","description":"When the run was requested. If the run was queued first, it began executing later, at `executionStartedAt`."},"executionStartedAt":{"type":"string","format":"date-time","nullable":true,"description":"When the run began executing. Equal to `startedAt`, or later by the time the run spent in the queue. `null` while the run is `QUEUED`, and on runs recorded before the field existed."},"finishedAt":{"type":"string","format":"date-time","description":"When the run finished."},"queuePosition":{"type":"integer","minimum":1,"description":"`QUEUED` runs only. The run's position among the queued runs that can start, where `1` starts next. Runs of all tenants share the queue, and a tenant with fewer runs executing goes first. The value is approximate, because the queue changes while you read it. The field is absent when the run is not queued, when it waits for something other than a worker, or when the service has not yet calculated it."},"queueWaitingFor":{"type":"string","enum":["WORKER","PREVIOUS_RUN","TENANT_LIMIT"],"description":"`QUEUED` runs only. What the run waits for. Possible values:\n\n* `WORKER` – the run waits for a free worker. `queuePosition` gives its place in the queue.\n* `PREVIOUS_RUN` – the run waits for the configuration's current run to finish.\n* `TENANT_LIMIT` – the run waits for one of the tenant's runs to finish, because\n `maxConcurrentImports` runs are already executing.\n\nThe field is absent when the run is not queued, or when the service has not yet calculated it."},"supersededRequests":{"type":"integer","description":"The number of later scheduled run requests that were added to this run while it was queued. A configuration has at most one queued run, so a scheduled request that arrives while a real run of the whole configuration is queued does not queue a second run."},"lastRequestedAt":{"type":"string","format":"date-time","description":"When the latest scheduled run request counted in `supersededRequests` was made. Absent when `supersededRequests` is `0`."},"recordsRead":{"type":"integer","description":"Records read (created + updated + skipped + deleted + failed)."},"created":{"type":"integer","description":"Records created."},"updated":{"type":"integer","description":"Records updated."},"skipped":{"type":"integer","description":"Records skipped because they were unchanged."},"failed":{"type":"integer","description":"Records that failed."},"deleted":{"type":"integer","description":"Records deleted."},"duplicateKeys":{"type":"integer","description":"Source rows that repeat a key already imported in this run. The import keeps the last row of each repeated key and discards earlier rows. Duplicate keys do not fail the run; they mean the source feed is not unique on the key the stream imports by."},"unresolvedParents":{"type":"integer","description":"Child records that were not imported because their parent could not be found. Counted separately from `skipped`, which counts records that were already up to date."},"message":{"type":"string","description":"A terminal status message, typically set on failure."},"retryOfRunId":{"type":"string","format":"uuid","description":"When the run retries another run's failed records, the identifier of that original run."},"force":{"type":"boolean","description":"Whether the run rewrote every record, bypassing the skip-if-unchanged check."},"dryRun":{"type":"boolean","description":"Whether the run only extracted, mapped, and validated, writing nothing to the target. A dry run legitimately reports zero for every counter, so this distinguishes it from a run that wrote nothing because it failed."},"cancelRequested":{"type":"boolean","description":"Whether cancellation has been requested for a run that is still finishing."},"dryRunSampleSize":{"type":"integer","description":"For a dry run, how many mapped records were kept as a sample."},"dryRunPublished":{"type":"boolean","description":"Dry-run only. Whether the dry run used the published mappings (`true`) or the draft mappings (`false`)."},"mappingVersions":{"type":"array","description":"The published mapping version each stream uses in this run, fixed when the run starts executing. Version `0` means that the stream has no published mappings. The field is absent while the run is `QUEUED`, on a dry run of the draft mappings, and on runs recorded before it existed.","items":{"type":"object","properties":{"streamId":{"type":"string","format":"uuid","description":"The stream identifier."},"version":{"type":"integer","description":"The published mapping version the stream uses."}}}}}}}}} ``` ## The DiagnosticPage object ```json {"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"DiagnosticPage":{"type":"object","description":"A page of diagnostic rows with metadata that indicates whether the response contains all recorded rows or only part of a capped sample. Use `recorded`, `cap`, and `sampleTruncated` to interpret the page. The run's counters show the total number of affected rows.","properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/DiagnosticRecord"}},"returned":{"type":"integer","description":"How many rows this response contains."},"recorded":{"type":"integer","description":"How many rows were recorded in total for this scope."},"cap":{"type":"integer","description":"The per-stream, per-kind recording cap."},"sampleTruncated":{"type":"boolean","description":"Whether at least one stream reached the cap. When true, these rows are a sample, and the run's\nown counters show the total number of affected rows."},"note":{"type":"string","description":"A human-readable statement of what this response is."}}},"DiagnosticRecord":{"type":"object","description":"One row behind a feed-quality counter.","properties":{"id":{"type":"string","format":"uuid"},"runId":{"type":"string","format":"uuid"},"streamId":{"type":"string","format":"uuid"},"streamName":{"type":"string","description":"The stream that recorded the row."},"kind":{"type":"string","enum":["UNRESOLVED_PARENT","REPEATED_KEY"],"description":"`UNRESOLVED_PARENT`: a child line whose parent instance did not exist when it was written.\n`REPEATED_KEY`: a source row whose natural key this run had already imported."},"naturalKey":{"type":"string","description":"The record's own natural key in the source."},"linkingField":{"type":"string","description":"`UNRESOLVED_PARENT` only. The field that points at the parent."},"linkingValue":{"type":"string","description":"`UNRESOLVED_PARENT` only. The parent key the line pointed at — the value to look up in the\nsource system."},"targetType":{"type":"string","description":"The target type the row was headed for."},"waitingLines":{"type":"integer","description":"`UNRESOLVED_PARENT` only. The number of child lines waiting for this parent."},"occurrence":{"type":"integer","description":"`REPEATED_KEY` only. How many times this key had already been seen in this run."},"createdAt":{"type":"string","format":"date-time"}}}}}} ``` ## The DiagnosticRecord object ```json {"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"DiagnosticRecord":{"type":"object","description":"One row behind a feed-quality counter.","properties":{"id":{"type":"string","format":"uuid"},"runId":{"type":"string","format":"uuid"},"streamId":{"type":"string","format":"uuid"},"streamName":{"type":"string","description":"The stream that recorded the row."},"kind":{"type":"string","enum":["UNRESOLVED_PARENT","REPEATED_KEY"],"description":"`UNRESOLVED_PARENT`: a child line whose parent instance did not exist when it was written.\n`REPEATED_KEY`: a source row whose natural key this run had already imported."},"naturalKey":{"type":"string","description":"The record's own natural key in the source."},"linkingField":{"type":"string","description":"`UNRESOLVED_PARENT` only. The field that points at the parent."},"linkingValue":{"type":"string","description":"`UNRESOLVED_PARENT` only. The parent key the line pointed at — the value to look up in the\nsource system."},"targetType":{"type":"string","description":"The target type the row was headed for."},"waitingLines":{"type":"integer","description":"`UNRESOLVED_PARENT` only. The number of child lines waiting for this parent."},"occurrence":{"type":"integer","description":"`REPEATED_KEY` only. How many times this key had already been seen in this run."},"createdAt":{"type":"string","format":"date-time"}}}}}} ``` ## The ErrorRecordPage object ```json {"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"ErrorRecordPage":{"title":"Error record page","allOf":[{"$ref":"#/components/schemas/Page"},{"type":"object","properties":{"content":{"type":"array","description":"The error records on this page.","items":{"$ref":"#/components/schemas/ErrorRecord"}}}}]},"Page":{"title":"Page","type":"object","description":"Pagination metadata for a page of results.","properties":{"totalElements":{"type":"integer","description":"The total number of elements across all pages."},"totalPages":{"type":"integer","description":"The total number of pages."},"number":{"type":"integer","description":"The current zero-based page number."},"size":{"type":"integer","description":"The page size."}}},"ErrorRecord":{"title":"Error record","type":"object","description":"A single error recorded during a run.","properties":{"id":{"type":"string","format":"uuid","description":"The error identifier."},"runId":{"type":"string","format":"uuid","description":"The run the error occurred in."},"streamId":{"type":"string","format":"uuid","description":"The stream the error occurred in."},"naturalKey":{"type":"string","description":"The source natural key of the offending record."},"targetEntity":{"type":"string","description":"The target writer the record was bound for."},"stage":{"type":"string","description":"The pipeline stage the error occurred in."},"errorCode":{"type":"string","description":"A machine-readable error code."},"message":{"type":"string","description":"A human-readable error message."},"createdAt":{"type":"string","format":"date-time","description":"When the error was recorded."}}}}}} ``` ## The ImportedRecordPage object ```json {"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"ImportedRecordPage":{"title":"Imported record page","allOf":[{"$ref":"#/components/schemas/Page"},{"type":"object","properties":{"content":{"type":"array","description":"The imported records on this page.","items":{"$ref":"#/components/schemas/ImportedRecord"}}}}]},"Page":{"title":"Page","type":"object","description":"Pagination metadata for a page of results.","properties":{"totalElements":{"type":"integer","description":"The total number of elements across all pages."},"totalPages":{"type":"integer","description":"The total number of pages."},"number":{"type":"integer","description":"The current zero-based page number."},"size":{"type":"integer","description":"The page size."}}},"ImportedRecord":{"title":"Imported record","type":"object","description":"A record that was imported. Holds keys and outcome; for composite parents it also holds the embedded child arrays.","properties":{"id":{"type":"string","format":"uuid","description":"The imported-record identifier."},"configId":{"type":"string","format":"uuid","description":"The configuration the record belongs to."},"streamId":{"type":"string","format":"uuid","description":"The stream that produced the record."},"runId":{"type":"string","format":"uuid","description":"The run that last touched the record."},"targetEntity":{"type":"string","description":"The target writer code."},"targetType":{"type":"string","description":"The target type."},"naturalKey":{"type":"string","description":"The source natural key."},"targetId":{"type":"string","description":"The deterministic Emporix instance ID the record was written under. It's derived from the natural key and allows the record to be located in the target."},"fields":{"type":"object","description":"The stored fields."},"outcome":{"type":"string","description":"The last outcome, one of `UPSERTED`, `DELETED`, `DELETED_TARGET`, `FAILED`, or `DRY_RUN`."},"importedAt":{"type":"string","format":"date-time","description":"When the record was last imported."}}}}}} ``` ## The HealthThresholds object ```json {"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"HealthThresholds":{"title":"Health thresholds","type":"object","description":"The limits that decide whether a stream is reported as `GREEN`, `AMBER`, or `RED`. Each field is optional and resolves independently. An unset field falls back through the hierarchy, from the most specific level to the least specific: stream, configuration, tenant, then the built-in default.","properties":{"failureRatioAmber":{"type":"number","format":"double","description":"The share of failed records (0..1) at or above which the stream is `AMBER`."},"failureRatioRed":{"type":"number","format":"double","description":"The share of failed records (0..1) at or above which the stream is `RED`."},"staleAmberHours":{"type":"integer","description":"The age threshold, in hours, for the stream's newest data. The stream is `AMBER` when the data's age reaches or exceeds this threshold."},"staleRedHours":{"type":"integer","description":"The age threshold, in hours, for the stream's newest data. The stream is `RED` when the data's age reaches or exceeds this threshold."},"failedRunIsRed":{"type":"boolean","description":"Whether a failed most-recent run makes the stream `RED` regardless of the other limits."}}}}}} ``` ## The HealthSettings object ```json {"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"HealthSettings":{"title":"Tenant health thresholds","type":"object","description":"The tenant-wide thresholds, together with the built-in defaults they fall back to.","properties":{"thresholds":{"$ref":"#/components/schemas/HealthThresholds"},"builtInDefaults":{"$ref":"#/components/schemas/HealthThresholds"}}},"HealthThresholds":{"title":"Health thresholds","type":"object","description":"The limits that decide whether a stream is reported as `GREEN`, `AMBER`, or `RED`. Each field is optional and resolves independently. An unset field falls back through the hierarchy, from the most specific level to the least specific: stream, configuration, tenant, then the built-in default.","properties":{"failureRatioAmber":{"type":"number","format":"double","description":"The share of failed records (0..1) at or above which the stream is `AMBER`."},"failureRatioRed":{"type":"number","format":"double","description":"The share of failed records (0..1) at or above which the stream is `RED`."},"staleAmberHours":{"type":"integer","description":"The age threshold, in hours, for the stream's newest data. The stream is `AMBER` when the data's age reaches or exceeds this threshold."},"staleRedHours":{"type":"integer","description":"The age threshold, in hours, for the stream's newest data. The stream is `RED` when the data's age reaches or exceeds this threshold."},"failedRunIsRed":{"type":"boolean","description":"Whether a failed most-recent run makes the stream `RED` regardless of the other limits."}}}}}} ``` ## The JobGroup object ```json {"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"JobGroup":{"title":"Job group","type":"object","description":"A named set of import configurations, used to scope the import statistics.","properties":{"id":{"type":"string","format":"uuid","description":"The job group identifier."},"name":{"type":"string","description":"The job group name. Unique within the tenant."},"configIds":{"type":"array","description":"The configurations in the group.","items":{"type":"string","format":"uuid"}},"createdAt":{"type":"string","format":"date-time","description":"When the group was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the group was last changed."}}}}}} ``` ## The ImportLicense object ```json {"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"ImportLicense":{"title":"Import limits","type":"object","description":"The import limits that apply to the tenant.","properties":{"maxRecordsPerEntity":{"type":"integer","description":"The maximum number of records a single run may write per target type. Records beyond the limit are skipped and the run finishes as `PARTIAL`."},"maxConcurrentImports":{"type":"integer","description":"The maximum number of runs that can execute at once for the tenant. A run requested beyond this limit is not rejected. It waits in the `QUEUED` status until one of the tenant's runs finishes."},"batchSize":{"type":"integer","description":"The number of records written to the target per request."},"workers":{"type":"integer","description":"The number of target writes performed in parallel."}}}}}} ``` ## The ImportStatsSummary object ```json {"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"ImportStatsSummary":{"title":"Statistics summary","type":"object","description":"Headline totals for the window. Rates are fractions between 0 and 1.","properties":{"totalRuns":{"type":"integer","description":"The number of runs started in the window."},"succeeded":{"type":"integer","description":"The number of runs that finished successfully."},"partial":{"type":"integer","description":"The number of runs that finished with some records failing."},"failed":{"type":"integer","description":"The number of runs that failed."},"cancelled":{"type":"integer","description":"The number of runs that were cancelled."},"recordsRead":{"type":"integer","description":"The number of source records read."},"created":{"type":"integer","description":"The number of target objects created."},"updated":{"type":"integer","description":"The number of target objects updated."},"skipped":{"type":"integer","description":"The number of records skipped because nothing had changed."},"deleted":{"type":"integer","description":"The number of target objects deleted."},"failedRecords":{"type":"integer","description":"The number of records that could not be imported."},"successRate":{"type":"number","format":"double","description":"The share of runs that finished successfully."},"failureRate":{"type":"number","format":"double","description":"The share of records that failed."},"deletionRate":{"type":"number","format":"double","description":"The share of processed records that resulted in a deletion."},"skipRate":{"type":"number","format":"double","description":"The share of records skipped as unchanged."},"avgRunDurationSec":{"type":"number","format":"double","description":"The mean duration of a finished run, in seconds, measured from when the run began executing (`executionStartedAt`). Time spent in the queue is not counted."},"avgCreatedPerRun":{"type":"number","format":"double","description":"The mean number of objects created per run."},"avgUpdatedPerRun":{"type":"number","format":"double","description":"The mean number of objects updated per run."},"distinctEntities":{"type":"integer","description":"The number of distinct target objects currently held by the imports in scope."},"activeRuns":{"type":"integer","description":"The number of runs currently in the `QUEUED`, `RUNNING`, or `RESUMABLE` status. When you filter by `streamId`, queued runs are not counted, because they have not started any stream yet."}}}}}} ``` ## The ImportStatsPoint object ```json {"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"ImportStatsPoint":{"title":"Statistics time bucket","type":"object","description":"One bucket of the time series, in UTC.","properties":{"bucket":{"type":"string","format":"date-time","description":"The start of the bucket."},"runs":{"type":"integer"},"succeeded":{"type":"integer"},"failed":{"type":"integer"},"recordsRead":{"type":"integer"},"created":{"type":"integer"},"updated":{"type":"integer"},"deleted":{"type":"integer"},"skipped":{"type":"integer"},"failedRecords":{"type":"integer"}}}}}} ``` ## The ImportStreamHealth object ```json {"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"ImportStreamHealth":{"title":"Stream health","type":"object","description":"The health of one stream over the window, and the thresholds the verdict used.","properties":{"streamId":{"type":"string","format":"uuid"},"configId":{"type":"string","format":"uuid","description":"The configuration the stream belongs to."},"name":{"type":"string"},"targetType":{"type":"string","description":"The target type the stream writes to."},"lastRunStatus":{"type":"string","description":"The status of the stream's most recent run."},"lastRunAt":{"type":"string","format":"date-time"},"watermarkAgeSeconds":{"type":"integer","description":"The number of seconds since the stream last detected new data."},"failureRatio":{"type":"number","format":"double","description":"The share of the stream's records that failed in the window."},"health":{"type":"string","enum":["GREEN","AMBER","RED"],"description":"The stream's health verdict."},"thresholds":{"$ref":"#/components/schemas/ImportEffectiveThresholds"}}},"ImportEffectiveThresholds":{"title":"Effective thresholds","type":"object","description":"The threshold values the verdict was actually computed with, after resolving every level.","properties":{"failureRatioAmber":{"type":"number","format":"double"},"failureRatioRed":{"type":"number","format":"double"},"staleAmberHours":{"type":"integer"},"staleRedHours":{"type":"integer"},"failedRunIsRed":{"type":"boolean"},"customised":{"type":"boolean","description":"Whether any level overrides the built-in defaults."}}}}}} ``` ## The ImportEffectiveThresholds object ```json {"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"ImportEffectiveThresholds":{"title":"Effective thresholds","type":"object","description":"The threshold values the verdict was actually computed with, after resolving every level.","properties":{"failureRatioAmber":{"type":"number","format":"double"},"failureRatioRed":{"type":"number","format":"double"},"staleAmberHours":{"type":"integer"},"staleRedHours":{"type":"integer"},"failedRunIsRed":{"type":"boolean"},"customised":{"type":"boolean","description":"Whether any level overrides the built-in defaults."}}}}}} ``` ## The ImportStatsNamedCount object ```json {"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"ImportStatsNamedCount":{"title":"Named count","type":"object","properties":{"streamId":{"type":"string","format":"uuid"},"name":{"type":"string"},"count":{"type":"integer"}}}}}} ``` ## The ImportStatsErrorBucket object ```json {"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"ImportStatsErrorBucket":{"title":"Error bucket","type":"object","description":"A count of errors sharing the same stage and code.","properties":{"stage":{"type":"string","description":"The pipeline stage the error occurred in."},"errorCode":{"type":"string"},"count":{"type":"integer"}}}}}} ``` ## The ImportStreamChanges object ```json {"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"ImportStreamChanges":{"title":"Stream changes","type":"object","description":"The counts of streams added and removed during the time window.","properties":{"added":{"type":"integer"},"removed":{"type":"integer"},"trackingSince":{"type":"string","format":"date-time","description":"When stream tracking began for the tenant. Streams created before this point are not counted, so a window reaching further back is not comparable."},"series":{"type":"array","items":{"type":"object","properties":{"bucket":{"type":"string","format":"date-time"},"added":{"type":"integer"},"removed":{"type":"integer"}}}}}}}}} ``` ## The ImportStats object ```json {"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"ImportStats":{"title":"Import statistics","type":"object","description":"Aggregated import metrics for the requested window and scope. A section that was not requested via the `sections` parameter is returned as `null`.","properties":{"summary":{"$ref":"#/components/schemas/ImportStatsSummary"},"series":{"type":"array","description":"Activity per time bucket, ordered oldest first and gap-free.","items":{"$ref":"#/components/schemas/ImportStatsPoint"}},"streamHealth":{"type":"array","description":"The health of each stream in scope.","items":{"$ref":"#/components/schemas/ImportStreamHealth"}},"topFailingStreams":{"type":"array","description":"The streams with the most errors during the time window, ordered by error count in descending order.","items":{"$ref":"#/components/schemas/ImportStatsNamedCount"}},"errorBreakdown":{"type":"array","description":"The most common errors in the window, grouped by stage and code.","items":{"$ref":"#/components/schemas/ImportStatsErrorBucket"}},"streamChanges":{"$ref":"#/components/schemas/ImportStreamChanges"},"sourceIssues":{"type":"array","description":"The source data does not match what the import process expects during the specified time window. These issues are not failures: the runs succeed, so they do not appear in pass/fail counters.","items":{"$ref":"#/components/schemas/ImportSourceIssue"}}}},"ImportStatsSummary":{"title":"Statistics summary","type":"object","description":"Headline totals for the window. Rates are fractions between 0 and 1.","properties":{"totalRuns":{"type":"integer","description":"The number of runs started in the window."},"succeeded":{"type":"integer","description":"The number of runs that finished successfully."},"partial":{"type":"integer","description":"The number of runs that finished with some records failing."},"failed":{"type":"integer","description":"The number of runs that failed."},"cancelled":{"type":"integer","description":"The number of runs that were cancelled."},"recordsRead":{"type":"integer","description":"The number of source records read."},"created":{"type":"integer","description":"The number of target objects created."},"updated":{"type":"integer","description":"The number of target objects updated."},"skipped":{"type":"integer","description":"The number of records skipped because nothing had changed."},"deleted":{"type":"integer","description":"The number of target objects deleted."},"failedRecords":{"type":"integer","description":"The number of records that could not be imported."},"successRate":{"type":"number","format":"double","description":"The share of runs that finished successfully."},"failureRate":{"type":"number","format":"double","description":"The share of records that failed."},"deletionRate":{"type":"number","format":"double","description":"The share of processed records that resulted in a deletion."},"skipRate":{"type":"number","format":"double","description":"The share of records skipped as unchanged."},"avgRunDurationSec":{"type":"number","format":"double","description":"The mean duration of a finished run, in seconds, measured from when the run began executing (`executionStartedAt`). Time spent in the queue is not counted."},"avgCreatedPerRun":{"type":"number","format":"double","description":"The mean number of objects created per run."},"avgUpdatedPerRun":{"type":"number","format":"double","description":"The mean number of objects updated per run."},"distinctEntities":{"type":"integer","description":"The number of distinct target objects currently held by the imports in scope."},"activeRuns":{"type":"integer","description":"The number of runs currently in the `QUEUED`, `RUNNING`, or `RESUMABLE` status. When you filter by `streamId`, queued runs are not counted, because they have not started any stream yet."}}},"ImportStatsPoint":{"title":"Statistics time bucket","type":"object","description":"One bucket of the time series, in UTC.","properties":{"bucket":{"type":"string","format":"date-time","description":"The start of the bucket."},"runs":{"type":"integer"},"succeeded":{"type":"integer"},"failed":{"type":"integer"},"recordsRead":{"type":"integer"},"created":{"type":"integer"},"updated":{"type":"integer"},"deleted":{"type":"integer"},"skipped":{"type":"integer"},"failedRecords":{"type":"integer"}}},"ImportStreamHealth":{"title":"Stream health","type":"object","description":"The health of one stream over the window, and the thresholds the verdict used.","properties":{"streamId":{"type":"string","format":"uuid"},"configId":{"type":"string","format":"uuid","description":"The configuration the stream belongs to."},"name":{"type":"string"},"targetType":{"type":"string","description":"The target type the stream writes to."},"lastRunStatus":{"type":"string","description":"The status of the stream's most recent run."},"lastRunAt":{"type":"string","format":"date-time"},"watermarkAgeSeconds":{"type":"integer","description":"The number of seconds since the stream last detected new data."},"failureRatio":{"type":"number","format":"double","description":"The share of the stream's records that failed in the window."},"health":{"type":"string","enum":["GREEN","AMBER","RED"],"description":"The stream's health verdict."},"thresholds":{"$ref":"#/components/schemas/ImportEffectiveThresholds"}}},"ImportEffectiveThresholds":{"title":"Effective thresholds","type":"object","description":"The threshold values the verdict was actually computed with, after resolving every level.","properties":{"failureRatioAmber":{"type":"number","format":"double"},"failureRatioRed":{"type":"number","format":"double"},"staleAmberHours":{"type":"integer"},"staleRedHours":{"type":"integer"},"failedRunIsRed":{"type":"boolean"},"customised":{"type":"boolean","description":"Whether any level overrides the built-in defaults."}}},"ImportStatsNamedCount":{"title":"Named count","type":"object","properties":{"streamId":{"type":"string","format":"uuid"},"name":{"type":"string"},"count":{"type":"integer"}}},"ImportStatsErrorBucket":{"title":"Error bucket","type":"object","description":"A count of errors sharing the same stage and code.","properties":{"stage":{"type":"string","description":"The pipeline stage the error occurred in."},"errorCode":{"type":"string"},"count":{"type":"integer"}}},"ImportStreamChanges":{"title":"Stream changes","type":"object","description":"The counts of streams added and removed during the time window.","properties":{"added":{"type":"integer"},"removed":{"type":"integer"},"trackingSince":{"type":"string","format":"date-time","description":"When stream tracking began for the tenant. Streams created before this point are not counted, so a window reaching further back is not comparable."},"series":{"type":"array","items":{"type":"object","properties":{"bucket":{"type":"string","format":"date-time"},"added":{"type":"integer"},"removed":{"type":"integer"}}}}}},"ImportSourceIssue":{"type":"object","properties":{"streamId":{"type":"string","format":"uuid","description":"The stream the problem was observed on."},"configId":{"type":"string","format":"uuid","description":"The configuration that owns the stream."},"name":{"type":"string","description":"The stream name."},"duplicateKeys":{"type":"integer","description":"Source rows that repeat a key already imported in the same run. The import keeps the last row of each repeated key and discards earlier rows."},"unresolvedParents":{"type":"integer","description":"Child records that were not imported because their parent could not be found."}}}}}} ``` ## The ImportSourceIssue object ```json {"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"ImportSourceIssue":{"type":"object","properties":{"streamId":{"type":"string","format":"uuid","description":"The stream the problem was observed on."},"configId":{"type":"string","format":"uuid","description":"The configuration that owns the stream."},"name":{"type":"string","description":"The stream name."},"duplicateKeys":{"type":"integer","description":"Source rows that repeat a key already imported in the same run. The import keeps the last row of each repeated key and discards earlier rows."},"unresolvedParents":{"type":"integer","description":"Child records that were not imported because their parent could not be found."}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://developer.emporix.io/api-references/readme/api-reference-33/models.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.