> 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-documentation/api-guides/utilities/import-service/api-reference/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."},"targetDeleteSubscriptionEnabled":{"type":"boolean","description":"Whether the stream reacts to its target objects being deleted outside the import."},"onTargetReappear":{"type":"string","enum":["IGNORE","READD"],"description":"What happens when a record deleted in the target is seen in the source again."},"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.","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","SUCCEEDED","PARTIAL","FAILED","CANCELLED"],"description":"The run status."},"mode":{"type":"string","enum":["FULL","DELTA"],"description":"The run mode."},"startedAt":{"type":"string","format":"date-time","description":"When the run started."},"finishedAt":{"type":"string","format":"date-time","description":"When the run finished."},"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."}}}}}} ``` ## 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"],"description":"The stream's status within the run."},"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.","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","SUCCEEDED","PARTIAL","FAILED","CANCELLED"],"description":"The run status."},"mode":{"type":"string","enum":["FULL","DELTA"],"description":"The run mode."},"startedAt":{"type":"string","format":"date-time","description":"When the run started."},"finishedAt":{"type":"string","format":"date-time","description":"When the run finished."},"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."}}},"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"],"description":"The stream's status within the run."},"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.","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","SUCCEEDED","PARTIAL","FAILED","CANCELLED"],"description":"The run status."},"mode":{"type":"string","enum":["FULL","DELTA"],"description":"The run mode."},"startedAt":{"type":"string","format":"date-time","description":"When the run started."},"finishedAt":{"type":"string","format":"date-time","description":"When the run finished."},"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."}}}}}} ``` ## 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 may be active at once for the tenant. A run requested beyond this limit is rejected with `429`."},"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."},"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 progress."}}}}}} ``` ## 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."},"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 progress."}}},"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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developer.emporix.io/api-documentation/api-guides/utilities/import-service/api-reference/models.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.