Export jobs - KayanOS Documentation

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:

Purpose: What decision, statutory report, migration, or approved analysis needs the data?
Minimum data: Which entity or entities are necessary? Do not use a broad export to discover what might be useful.
Recipient and location: Who receives the archive, how will they access it, and where will it be held?
Date basis: Does the requested interval mean records created in the period or records updated in the period?
Format: Does the recipient need readable labels or raw stored values for a controlled technical process?
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

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.
Write the export purpose, recipient, selected entities, date basis, date range, format, and deletion date in the approved request or change record.
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.
Decide whether created or updated answers the question. For example, “requests received in June” normally uses created; “requests changed in June” normally uses updated.
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.
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.
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.

Open Administration → Export jobs and select New export job.
Select Citizen Service Request only. Do not include inspections, members, documents, or unrelated service entities unless the approved purpose requires them.
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.
Choose Readable values. This presents status options and relations in a form service reviewers can understand.
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.
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.
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.
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.
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

Design and classify entity fields before exporting them in Entity fields and layouts.
Protect export authority through Organization settings and Roles and scopes.
Build safer operational analysis in Dashboards.
Review access boundaries in Permissions and availability.

KayanOS export-job status for the Directorate of Citizen Services.

​Goal

​Access and export boundary

​What an export job contains

​Before creating a job

​Create a controlled Citizen Service Request export

​Job states, downloads, and retention

​Readable and raw examples

​Safe validation

​Troubleshooting

​Related guides