Skip to navigation
API ReferenceData Ingestion & ExtractionExtractions

Read an extract configuration

This endpoint retrieves the extract configuration by name: the caller’s own draft under that name if they have one, and otherwise the submitted configuration that is still active. The response carries status of the extract configuration, whether it is a draft, active or inactive, and version, which may be sent back on an update as a precondition.

Permissions for nested calls. This endpoint calls other Fynapse services with your token. Depending on the request, the token also needs:

  • data_structure_read, when the configuration names an entity.

Authentication

AuthorizationBearer

OAuth authentication of the form <token>.

Path parameters

namestringRequired
The name of the extract configuration.

Response

OK
extractConfigurationNamestring<=200 characters
Business key of the configuration. Unique among the configurations that are submitted and still active.
startDatestringformat: "date-time"
When the configuration starts producing extracts.
extractTypeenum

Format of the extracted data. Which values are allowed depends on uploadSpace.

Allowed values:
uploadSpaceenum
Where the extracted data is delivered.
Allowed values:
statusenumOptional

On a read, what the configuration is doing. On a write, the status it should be in: DRAFT keeps it a draft, and anything else submits it. The values a read returns are accepted on a write, so a configuration can be read, changed and sent back without translating them, and SUBMITTED is accepted as well because that is what submitting is called everywhere else. On an update, omitting it leaves the configuration in the status it is in; a status this API does not know is refused with 400 rather than ignored.

Allowed values:
versionlongOptionalRead-only

The version the configuration is on. Send it back as expectedVersion on an update to fail safely when someone else has changed it in the meantime.

descriptionstringOptional
Free text describing what the configuration is for.
endDatestringOptionalformat: "date-time"
When the configuration stops. Absent means it does not stop.
balanceQueryNamestringOptional
Saved balance query the extract draws from, where it draws from one rather than from an entity.
d365ConfigNamestringOptional
D365 configuration that shapes the data, for a D365 extract.
dimensionSetNamestringOptional
Dimension set the extract reports against.
excludedDimensionslist of stringsOptional
Dimensions of that set to leave out.
incrementalbooleanOptional
Whether each run extracts only what has arrived since the last one.
holdLateDataUntilNewGroupIsFoundbooleanOptional

Whether late-arriving data is held back until a new group begins.

chunkSizeintegerOptional
Maximum number of records per produced file.
queryobjectOptional

What is selected - the entity and namespace, the fields, filters, aggregations and clustering. The same shape the bulk configuration document uses for an extract configuration’s query.

schedulerobjectOptional

When the extract runs - a frequency or a cron expression, or disabled. Validated when the configuration is submitted, not while it is a draft.

splitByobjectOptional
How produced data is split across files, by attribute.
kafkaTargetConfigobjectOptional
Target topic and entity name, for an extract delivered to Kafka.
dynamicFilteringobjectOptional
Filtering resolved at run time rather than fixed in the query.

Errors

401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
429
Too Many Requests Error
5XX
Server Error