Import

The workspace has six tabs — Overview, Profile, Preview, Apply, Reconcile, History. Four of those are the stages of a run; Overview tells you which stage you are at and what the next safe action is, and History holds previous runs. The workspace states the discipline plainly: one profile, one preview, one approved apply, then one reconciliation — stop when a step reports blockers. It also shows your step-up expiry inline, so you can see before starting whether the mutation steps will still be available.

Import brings records in from a file, in four stages: profile, preview, apply, reconcile. This page covers all four and how to read the result when only part of a run succeeded.

Import Operations at /admin/import-operations needs SystemAdmin and a recent step-up.

Import creates records; it does not roll back

Two facts shape everything below.

Import is create-oriented. Apply creates records. It does not update, delete, or reactivate them, and it is not a synchronization tool. Running the same package twice does not reconcile the second run against the first.

Rerunning is guarded, with two exceptions. Apply keeps a record of every row it has already created, keyed by profile, entity type, and source row. A rerun of the same row reports AlreadyMaterialized and creates nothing; if the same source key arrives with different content, the row fails with SourceKeyPayloadConflict. Department, User, Group, DepartmentAccess, Service, and TicketParticipantWatcher rows are checked against the existing record as well, and report AlreadyExists. Ticket and TicketComment rows have no such check — for those two, a rerun under a new source key does create duplicates.

Apply processes rows in batches, and it can stop partway. There is no automatic whole-run rollback. If row 800 fails, rows 1 to 799 stay created. Getting back to where you started after a partial run is manual work you plan for in advance, per entity type.

Before you start

• An active import profile and template version that your organization approved.
• A package of 5 MB or less, within the configured row guardrail — 5,000 rows by default.
• Ticket rows carrying requesterEmail, and TicketComment rows carrying participantEmail. Guided templates require their equivalent mapped aliases.
• A private place for the package and the run evidence. Import files carry real people's data; keep them out of shared drives and out of version control.

Supported entity families are Department, User, Group, DepartmentAccess, Service, Ticket, TicketComment, and TicketParticipantWatcher. Package actions are create, skip, or preview-only.

Attachment references in a package are metadata only. Nothing fetches the files.

Select the profile

1. Open Import Operations and select Profile.

2. Under 1. Template setup, read the standard template version and the entity, action, and mapping contract it supports.

3. Create, update, or activate the approved profile definition.

4. Confirm which entities and actions remain unsupported, so nobody expects them later.

Run preflight

Preflight validates the file before anything is staged.

1. Select Preview. Download the CSV template and column guide if you need them.

2. Choose a CSV or JSON file up to 5 MB, or paste rows directly.

3. Select Run preflight.

4. Read the result: rows checked, blocking findings, warnings, temporal findings, and the overall gate — Ready or Blocked.

5. Fix what it found: unsupported formats, objects, or actions; duplicates; missing fields, including requester and comment-author identity; missing references; and temporal blockers.

Ready means preflight found no blocking finding of any kind — not just identity fields. Format problems, unsupported entities or actions, duplicate source keys, values that look like disclosed secrets, and attachment URLs all block as well.

Ready does not mean apply will succeed. Apply requires each supplied email to match exactly one active user, and that check happens later, against the state at that moment.

Do not reinterpret a blocked row as approved. Fix it or remove it.

Run the dry run

1. With preflight ready, select Run preview.

2. Read the staged row counts and the ready, warning, and blocked categories.

3. Resolve every blocker and read every warning deliberately before considering apply.

4. Note the preview run identifier. You need it to apply. Keep it inside the private workspace.

The dry run changes no target records — no department, user, group, access, service, ticket, comment, or participant record. It does persist the staged source rows so the preview can be reloaded. That is the only thing it writes.

A successful dry run does not promise that apply will succeed. State can change between the two.

Apply

Apply changes real records. Do not start it without your organization's change approval.

1. Confirm the preview run is apply-eligible, and separately check that the profile is still active. Apply does not prove the profile still matches what the preview ran against.

2. Complete a recent step-up and confirm product use is allowed. See Licence problems.

3. Select Apply.

4. Under 3. Apply approved changes, enter the reviewed Preview run ID to apply.

5. Enter your Execution idempotency key, or select Generate a new key. Keep it in the protected workspace — it is how you safely retry.

6. Select Apply approved rows once.

7. Read rows considered, applied, and failed, plus the replay, resume, and checkpoint status.

The configured guardrails default to 5,000 rows per run, 500 rows per batch, 30 seconds of runtime, and 5 resumes. They are limits that stop a run. They are not promises about how long a run takes or that it will finish.

Reusing the exact same key for the exact same request returns the completed run rather than importing twice. Reusing the same key with a different request is refused. Failed or in-progress work resumes only within the guardrails above.

Read the ledger

The ledger records three different things. Read them separately.

Row status is one of exactly two values.

Outcome code sits on each row alongside the status and says what actually happened. It appears in the exported evidence.

Run-level results describe the run, not any one row.

The reconciliation summary also shows an unattempted count. That is not a stored row status — it is the rows considered minus the rows attempted, which is what a guardrail or checkpoint stopping the run leaves behind.

Reconcile and close

1. Select Reconcile.

2. Under 4. Confirm outcomes and reconcile, enter the Apply run ID to reconcile.

3. Select Load reconciliation summary.

4. Read the Applied, Failed, and Unattempted counts and the recommendations.

5. Download the CSV or JSONL evidence into your approved private location only.

6. Use History to see the preview, import, replay, and guardrail timeline for the run.

7. For each applied row that needs correcting, assign the correction to whoever owns that entity type. There is no bulk undo.

8. For each identity-resolution failure, confirm the intended active user and fix either the source file or the user state, then rerun deliberately with a new key. Do not guess between two matching users.

Worked example: importing a ticket

The BareBones standard template profile (Ticket import rules 1.2.0) maps all eight entity families listed above, so one package can create a department, the users and groups that go with it, a service, and then the tickets that reference them. The sample rows in the downloadable template are laid out in that order for exactly that reason, and apply works through rows in dependency order rather than file order.

What it will not do is invent a reference. A ticket's departmentKey and requesterEmail must resolve to a department and an active user that either already exist or are created by an earlier row in the same package. Point either at something that is neither, and preflight blocks the row, or apply fails on identity resolution.

The example below imports a single ticket into a department that already exists, so it carries no Department or User row of its own.

The smallest useful run is a single ticket. This example creates one ticket in an existing Laundry Services department (key LAUNDRY), requested by an existing user:

1. Profile. On Import Operations → Profile, choose source Generic ticket package, package Tickets, comments, and participants CSV/JSON, and the BareBones standard template … Ticket import rules 1.2.0 (Active) profile. Select Continue to template.

2. Template. Select Download CSV template and Download column guide. The template's columns are, in order: entityType, sourceRowKey, title, description, departmentKey, departmentName, serviceName, category, requesterEmail, ownerEmail, ticketExternalId, body, participantEmail, participantRole, groupName, accessLevel, plannedAction, plannedTargetKey, notes. A ticket row needs entityType=Ticket, a unique sourceRowKey, a title, an existing departmentKey, an existing active requesterEmail, and plannedAction=Create. Leave the columns that do not apply blank.

   entityType,sourceRowKey,title,description,departmentKey,requesterEmail,plannedAction
   Ticket,TICKET-LNDRY-01,Floor 3 linens bulk wash,Weekly bulk wash for floor 3 linens,LAUNDRY,requester@example.com,Create

   (The real file keeps every template column, filling only the ones above.)

3. Preflight. On Preview, upload the file and select Run preflight. A well-formed ticket row reports Ready with, at most, non-blocking warnings for a blank service or status. A blank or unknown departmentKey or requesterEmail is what blocks here — those two fields are required.

4. Preview. Select Run preview. It reports "Preview complete with no blocking rows" and stages the row for apply without changing anything.

5. Apply. On Apply, select Apply approved rows. Apply reports Completed and issues a run id. The ticket now exists — for this example it was created as LAUNDRY-1, "Floor 3 linens bulk wash," in Laundry Services.

6. Reconcile. On Reconcile, close out the run. Confirm the applied count matches what you intended before calling the migration complete.

Reaching this workspace requires step-up, and so does the apply itself.

If it does not work

The gate says Blocked. Read the blocking findings. Fix the file. Do not try to apply a preview that did not pass.

Apply returned Conflict. The key you used belongs to a different request. Work out which run you actually meant, then generate a deliberate new key. Do not replay blindly.

Apply stopped partway. Keep the ledger. Reconcile it before you run anything else. A second run against the same package reports the rows that already succeeded as AlreadyMaterialized and does not create them again — except for Ticket and TicketComment rows, which are not checked against existing records and can be duplicated.

A row failed on identity. The email in the file does not match exactly one active user right now. It may be absent, deactivated, or shared by two accounts. Fix that through your normal identity process, not by editing the database.

Something went in that should not have. Correct it through the ordinary workspace for that entity type. Do not run update or delete against the database outside an approved procedure.

Related pages

• Audit and evidence
• Change control
• Licence problems
• Limits and scope