> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kayanos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Export jobs

> Create, monitor, download, and retire organization data exports with clear purpose, time boundaries, value format, and temporary-file controls.

An export job is a governed movement of organization data. It is not a reporting shortcut for ordinary members and it does not make a dataset safe to share. The current export controls are available only to the organization owner, who remains accountable for the selected entities, date range, recipient, storage location, and deletion of the downloaded file.

For the Directorate of Citizen Services, use an export only when the service purpose, recipient, and data-minimization decision are known. A monthly aggregate review may need a narrow request dataset; an ad hoc request to “export everything” is not a sufficiently defined purpose.

## Goal

Create a small, reviewable export job; understand exactly what the format and dates mean; monitor its asynchronous result; download it only during the retention window; and record or remove the resulting file under the organization’s data-handling policy.

## Access and export boundary

Only the current organization owner can open the export-entity list, create a job, inspect jobs, or request a download link. A member who can view an entity, build a dashboard, or administer another setting is not automatically authorized to export it.

Before an export, the owner should confirm:

1. **Purpose:** What decision, statutory report, migration, or approved analysis needs the data?
2. **Minimum data:** Which entity or entities are necessary? Do not use a broad export to discover what might be useful.
3. **Recipient and location:** Who receives the archive, how will they access it, and where will it be held?
4. **Date basis:** Does the requested interval mean records **created** in the period or records **updated** in the period?
5. **Format:** Does the recipient need readable labels or raw stored values for a controlled technical process?
6. **Retention and destruction:** When will the downloaded copy be removed, and who will confirm it?

An export preserves organization data outside the live application. Treat the archive and every copied spreadsheet inside it according to the same—or stricter—access and retention controls as the source records.

## What an export job contains

The export dialog selects entities, not individual fields. For each selected entity, the job creates a spreadsheet inside a ZIP archive. It includes the entity’s non-deprecated fields and the system columns **ID**, **Label**, **Created**, and **Updated**. Review the entity design and classification before creating a job; do not assume an individual sensitive field can be excluded from this workflow.

| Choice             | What it controls                                                                                                        | When to choose it                                                                           |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| Entity selection   | Which available organization entities receive a workbook in the ZIP                                                     | Select the smallest set that supports the approved purpose                                  |
| Created date basis | Filters records by creation time                                                                                        | Use for intake volume, newly registered requests, or a period’s new work                    |
| Updated date basis | Filters records by last update time                                                                                     | Use for changed records, reconciliation, or a review of work touched in a period            |
| From / To dates    | Optional inclusive-looking business date boundary normalized in the organization’s default time zone                    | State the time-zone assumption in the request, especially around month-end                  |
| Readable values    | Converts options, relations, localized labels, durations, times, and ranges into display-friendly values where possible | Use for supervised analysis, operational review, or a human-readable report                 |
| Raw values         | Preserves stored representations; arrays and objects can appear as JSON                                                 | Use only for an approved technical reconciliation or migration that needs stored structures |

Readable output is easier for people to interpret but is not a lossless technical interchange format. Raw output can expose identifiers and structured values that are less obvious in the application. Choose the format deliberately and protect it accordingly.

## Before creating a job

1. Confirm you are the current organization owner in the correct organization. If ownership has changed, resolve that before starting; a job will not proceed if the requester is no longer the owner when it runs.
2. Write the export purpose, recipient, selected entities, date basis, date range, format, and deletion date in the approved request or change record.
3. Open each selected entity and check its active fields, system fields, and any sensitive relations. The export includes system columns and current non-deprecated fields.
4. Decide whether **created** or **updated** answers the question. For example, “requests received in June” normally uses created; “requests changed in June” normally uses updated.
5. Confirm the organization’s default time zone. Date-only boundaries are normalized using that time zone, so a boundary near midnight can change which records belong to the period.
6. Start with one entity and a short controlled interval when validating a new report. Use synthetic or approved non-production data where that is available.
7. Prepare a secure destination. Do not download to a shared desktop, a public cloud folder, a personal email account, or an unapproved removable drive.

## Create a controlled Citizen Service Request export

Suppose the Directorate needs a service-owner review of requests updated in the first week of a month. The owner wants a readable review workbook, not a technical archive of raw field structures.

1. Open **Administration → Export jobs** and select **New export job**.
2. Select **Citizen Service Request** only. Do not include inspections, members, documents, or unrelated service entities unless the approved purpose requires them.
3. Choose **Updated** as the date basis. Enter the approved first-week From and To dates, with the organization default time zone recorded in the change request.
4. Choose **Readable** values. This presents status options and relations in a form service reviewers can understand.
5. Create the job and note its purpose and job time in the change record. Creating the job queues work; it does not immediately create a downloadable archive.
6. While the status is pending or processing, monitor the job table. The page refreshes running jobs automatically every ten seconds; use **Refresh** when investigating a result.
7. When the status becomes completed, compare the listed entities, row count, file size, and expiry with the original request. A zero or unexpectedly large count is a reason to stop and investigate before download.
8. Download the archive only to the approved location. Open the workbook in a controlled environment and verify its columns and a small number of synthetic/authorized rows.
9. Share only through the approved recipient channel, record the handoff if required, and remove the local/archive copies at the approved deletion date.

Expected result: one ZIP archive containing a workbook for the selected entity, with the approved date basis and value representation. The job does not publish records, change them, or grant its recipient access to KayanOS.

## Job states, downloads, and retention

| State or condition     | Meaning                                                                     | Administrator action                                                                  |
| ---------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| Pending                | The background job is waiting to run                                        | Wait and monitor; do not create duplicate jobs merely because a file is not immediate |
| Processing             | The job is building the archive                                             | Keep the request context; the interface continues periodic refresh                    |
| Completed              | The archive was produced and metadata such as row counts/size are available | Review the result before downloading                                                  |
| Failed                 | The job did not produce a usable archive and may show an error message      | Read the error, correct the cause, and create a new deliberate job if appropriate     |
| Expired/deleted result | The temporary file can no longer be downloaded                              | Do not attempt a bypass; create a new approved job if the data is still needed        |

Completed export results are retained for a limited period—currently fifteen days—and the issued download URL is itself short-lived—currently five minutes. The download control is available only when the job is completed, the result remains retained, and its storage record is available. Downloading the file does not extend its retention.

Do not treat the temporary KayanOS result as your retention plan. Once downloaded, the organization must manage every copy and derivative according to its own approved classification, access, and destruction controls.

## Readable and raw examples

For a **Citizen Service Request** record, a readable export can render a status such as **Ready for inspection**, a member relation as the member’s label, and a duration or range in a display-friendly form. A raw export can preserve an option value, relation structure, or array/object as stored data, often represented as JSON.

Use readable mode for a service manager reviewing a bounded queue. Use raw mode only when an approved technical owner needs to reconcile stored values or migrate data and has a secure process for identifiers and structured fields. Never use raw simply because “more detail might be useful.”

## Safe validation

| Test                     | Expected result                                                                                                                                    |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| Owner boundary           | A non-owner cannot create, list, or download organization export jobs                                                                              |
| Minimal entity selection | A test job contains only the selected entity’s workbook, not unrelated entities                                                                    |
| Date-basis check         | A controlled record created but not updated in the interval behaves differently from a record updated in the interval, matching the selected basis |
| Time-zone check          | A boundary-date record is included or excluded according to the organization’s documented default time zone                                        |
| Readable/raw comparison  | A known option/relation is rendered as a label in readable mode and as its stored representation in raw mode                                       |
| System column check      | The workbook includes ID, Label, Created, and Updated alongside active non-deprecated fields                                                       |
| Download/retention check | Download is enabled only after completion and before result expiry; a past-expiry result is not downloadable                                       |
| Failure handling         | A failed job is investigated and recreated deliberately, not retried by duplicating unknown exports                                                |

## Troubleshooting

| Symptom                                        | Check first                                                                          | Safe response                                                                                                      |
| ---------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| Export jobs page is unavailable                | Whether you are the current organization owner and in the correct organization       | Ask the owner to perform or authorize the export; do not share an owner account                                    |
| Create button is disabled or entity is missing | Loading state, available organization entities, and selected-entity validity         | Refresh and confirm the entity belongs to the organization; do not substitute a different dataset without approval |
| Job remains pending/processing                 | Current status, active-job workload, and the job table after refresh                 | Allow the asynchronous job to progress; avoid duplicate submissions                                                |
| Job failed                                     | Error text, entity configuration, date range, owner status, and requested purpose    | Correct the documented cause, then create one new controlled job                                                   |
| Download is unavailable                        | Completed status, file expiry, and retained result availability                      | Do not attempt to reuse an old link; create a new approved export if still necessary                               |
| Result count is surprising                     | Date basis, dates/time zone, entity selection, active fields, and known test records | Stop distribution and validate with a small controlled range before sharing                                        |
| Raw values look complex                        | Whether raw rather than readable was selected                                        | Use readable output for human review, or keep raw in the approved technical workflow                               |
| Owner changed while a job ran                  | Current organization ownership and job error                                         | Reconfirm purpose and have the current owner create a new job; do not alter background-job data                    |

## Related guides

* Design and classify entity fields before exporting them in [Entity fields and layouts](/build/entity-fields-and-layouts).
* Protect export authority through [Organization settings](/admin/organization-settings) and [Roles and scopes](/admin/roles-and-scopes).
* Build safer operational analysis in [Dashboards](/build/dashboards).
* Review access boundaries in [Permissions and availability](/reference/permissions-and-availability).

![KayanOS export-job status for the Directorate of Citizen Services.](https://kayanos.app/docs-images/en/admin/export-jobs.png)