---
sidebar_label: 'Overview'
sidebar_position: 1
---

# Building a data import job

Data import jobs in Future Ordering are responsible for creating import entities that later jobs in the same flow can process. Each job gathers or transforms source data and uploads entities for downstream jobs to consume.

<!-- ## Overview -->

<!-- For your endpoint to take part in a run, there are some requirements on how it all comes together. For details on data models and their requirements, see [Menus](./importing-menus) and [Stores](./importing-stores). This is an asynchronous operation — you must respond immediately to the initial HTTP request with `200 OK` or `202 Accepted`.

## Requirements and best practices

1. **Authentication** — Basic Authentication is the only supported external authentication method. Provide the credentials to Future Ordering when your job is created.
2. **Asynchronous response** — Respond immediately to confirm the job has been accepted, then process asynchronously.
3. **Dynamic data structure** — If your job is not the first in a flow, use a dynamic data model. You cannot predict what metadata earlier jobs have added.
4. **Upload everything** — When your job is done, upload all data to the orchestrator, including anything you did not change (unless you are intentionally removing that entity, e.g. removing a store from the store import).
5. **Report progress** — Report at key milestones (start, critical steps, completion) so administrators can monitor the run.
6. **Send error reports** — If your application encounters an unrecoverable error, send an error report with all available diagnostic information.
7. **Keep error reports safe** — Error reports are visible in the Navigator application. Do not include personal or secret data.
8. **Compress uploads** — GZIP data when uploading if possible.
9. **Treat SAS URLs as temporary** — Fetching data from the initial request URLs does not require a token. The URLs are temporary SAS URLs. -->

## Import job flow

```mermaid
sequenceDiagram
    participant fo as Future Ordering
    participant int as Data Import Job

    note over fo : An import flow is started
    fo->>+int: The orchestration system calls the job's configured endpoint
    int-->>-fo: 202 Accepted
    note over int : The job starts processing the request and gathers data to upload
    int->>fo: Progress report
    note over int : The job finishes processing the request
    int->>+fo: Upload entities
    fo-->>-int: SAS URL
    int->>fo: Complete report
    note over fo: The import continues with subsequent jobs in the flow
```

<!-- The initial request contains all the information needed to start your job.
```json
{
	"runId": "some-example-run-id",
	"flowId": "some-example-flow-id",
	"jobId": "your-job-id",
	"data": {
		"<entityId>": {
			"references": ["some-reference-name-for-entity"],
			"dataSources": ["datasources-that-contributed-to-model"],
			"route": "https://example-sas-endpoint.com/1/url-route?query-params=true"
		},
		"<otherEntityId>": {
			"references": ["some-other-reference-name"],
			"dataSources": ["some-datasource"],
			"route": "https://example-sas-endpoint.com/2/url-route?query-params=true"
		}
	},
	"timeOut": "00:30:00",
	"configuration": {
		"skipOnStuff": true
	},
	"payload": {
		"countries": [
			"Sweden"
		]
	},
	"reportConfiguration": {
		"progress": "https://api.futureordering.com/orch/reports/progress",
		"complete": "https://api.futureordering.com/orch/reports/complete",
		"error": "https://api.futureordering.com/orch/reports/error",
		"entity": "https://api.futureordering.com/orch/runs/some-example-run-id/jobs/your-job-id/entities/"
	}
}
``` -->
<!-- ### Payload

The `payload` field contains run-specific configuration set when a run starts. The `configuration` field contains static configuration, set once when the job is created. The example above uses the country configurator — when starting a run, an operator can specify which countries the import covers.

![Country Selector](./../assets/images/country-selector.png) -->

<!-- ## Next steps

For details on sending progress updates, completion reports, error reports, and uploading entity data, see [Reports and entities](./reports-and-entities). -->