Atlassian Asset Migrator

01What do I need before I start?

Node 18 or newer, Assets enabled on the Cloud target, REST access to Data Center, and bash + curl + jq for the extraction scripts. Plus two credentials most people get wrong on the first try.

Requirements

02How do I get the token and the workspace id?

The token is base64 of email:api_token — not the raw token. The workspace id is a UUID you read from a REST endpoint in your browser.

Both credentials, in order

1. 1Create an API token at id.atlassian.com/manage-profile/security/api-tokens.
2. 2Base64-encode it with your email: echo -n "you@example.com:your-api-token" | base64. The result — not the raw token — is CLOUD_API_TOKEN. Missing the email and the colon is the single most common setup error, and it presents as a 401 that looks like an expired token.
3. 3Read the workspace id by opening https://your-domain.atlassian.net/rest/servicedeskapi/assets/workspace in a browser where you are logged in. The workspaceId field is the UUID you need for WORKSPACE_ID.

The minimum viable .env

cd asset-migration-script
cp .env.example .env

CLOUD_BASE_URL=your-domain.atlassian.net    # no https://
CLOUD_API_TOKEN=<base64 of email:api_token>
WORKSPACE_ID=<uuid from the endpoint above>
DATACENTER_PATH=                            # defaults to ../datacenter_assets

03How do I get the data out of Data Center?

Four shell scripts in standalone-utilities/get_datacenter, run behind the firewall. They write JSON into datacenter_assets/ at the project root, which is what the engine reads.

Extraction is deliberately shell rather than Node, because it usually has to run on a machine inside the network that can reach Data Center — often not the machine that will run the migration. Configure it once in main/datacenter_common.sh, then run whichever extracts you need.

The extraction scripts

Run the core extract

cd standalone-utilities/get_datacenter
# Edit main/datacenter_common.sh with your DC base URL and credentials first.
bash main/get_datacenter_assets.sh

# -> creates ./datacenter_assets/ at the project root

04What is the correct run order?

Dry run, one schema, verify in the UI, then widen. Never the whole workspace on the first attempt — and never with attachments and tickets enabled before objects are proved.

The order that works

1. 1`node main.js --dry-run` — validates the configuration and shows what would be created. Nothing is written. Read the log, not just the summary line.
2. 2One schema, objects only. node main.js --schema "Hardware" --limit 25 with UPLOAD_ATTACHMENTS=false and CONNECT_TICKETS_TO_OBJECTS=false. Twenty-five objects is enough to expose an attribute-type mismatch and small enough to clean up by hand.
3. 3Open Assets in the Cloud UI and look at those objects. Check the attributes, then check a reference actually points somewhere. A created object with an empty reference is the failure mode that survives every API-level check.
4. 4The whole schema. Drop --limit. Re-verify a sample.
5. 5Then attachments, then tickets — one at a time, each verified before the next is enabled. Combining them means a failure tells you nothing about which subsystem produced it.
6. 6Then the remaining schemas, one at a time via --schema.

05What is the engine actually doing?

Seven phases. The two that matter for correctness are dependency analysis, which decides creation order, and reference resolution, which runs after every object exists.

The seven phases

1. 1Schema discovery — read the exported schemas and analyse their structure.
2. 2Type mapping — map DC object types to Cloud-compatible shapes. Fuzzy name matching handles underscores, case differences, partial matches and pipe patterns, because the two instances rarely agree on naming exactly.
3. 3Dependency analysis — build the dependency graph and topologically sort it, so an object is never created before something it references.
4. 4Object creation — create objects in Cloud in that order, with their attribute values.
5. 5Reference resolution — a second pass that fills in references, after every object exists. This is why circular references are survivable at all.
6. 6Attachment upload — download from DC, upload to the created objects.
7. 7Ticket connection — link Jira tickets to the migrated objects through their custom fields.

06Which flags and settings actually matter?

Every setting has both a CLI flag and an environment variable; the flag wins. These are the ones that change what the run does, rather than how fast it does it.

The settings that change behaviour

07What is in standalone-utilities, and when do I need it?

Six utilities. Two do jobs the main engine can also do inline — run them separately when you want to retry that job alone, without re-running the migration.

The six utilities

08How do I migrate attachments without the run falling over?

Extract them first, cap the size, and treat attachments as a separate pass once objects are proved correct.

The attachment pass

1. 1bash main/get_datacenter_attachments.sh in get_datacenter — attachments have to be extracted before anything can upload them.
2. 2Set MAX_ATTACHMENT_SIZE_MB (default 100) and MAX_ATTACHMENTS_PER_OBJECT (default 10) deliberately. The defaults are conservative; raise them knowingly.
3. 3Run with --upload-attachments, or run upload_attachment_assets standalone against objects that already exist.
4. 4Check a handful of objects in the Cloud UI. An object with a correct attachment count and zero downloadable files is a real outcome, and only the UI shows it.

09get_datacenter — how do I run the extraction?

Five bash scripts, one shared config file, run behind the firewall. Only the first is always required; the rest are prerequisites for specific features.

Configure once, then run what you need

cd standalone-utilities/get_datacenter
# Edit main/datacenter_common.sh: DC base URL and credentials. No .env here.

bash main/get_datacenter_assets.sh                 # ALWAYS — the core export
bash main/get_datacenter_attachments.sh            # if UPLOAD_ATTACHMENTS=true
bash main/get_datacenter_ticket_associations.sh    # if CONNECT_TICKETS_TO_OBJECTS=true
bash main/get_datacenter_comment_visibility.sh     # for sync_comment_visibility
bash main/generate_automation_mapping.sh           # for automation-service

10upload_attachment_assets — how do I run it, and why separately?

The retry path. The main engine can upload attachments inline; this uploads them to objects that already exist, so a failed subset can be re-run without repeating object creation.

Diagnose, then upload

cd standalone-utilities/upload_attachment_assets
# Uses standalone-utilities/.env

node check_config.js                     # confirm credentials and workspace id
bash diagnose_attachment_upload.sh       # probe the endpoint end to end
bash find_valid_attachments.sh           # what is actually present in the extract
node upload_attachments_to_existing_objects.js --dry-run
node upload_attachments_to_existing_objects.js --confirm

Flags

11connect_assets_tickets — how do I run it, and how do I recover it?

Links Jira tickets to Assets objects that already exist. It ships more recovery tooling than any other utility here, because ticket connection is the step that most often half-finishes.

Run, then recover

cd standalone-utilities/connect_assets_tickets
# Uses asset-migration-script/.env

node index.js --dry-run --limit 50
node index.js --confirm

# When it half-finishes:
node overall_progress.js                       # where did it get to
node analyze_failures.js                       # why did rows fail
node analyze_field_errors.js                   # which custom fields rejected the write
node fix_stuck_processing.js                   # release rows wedged in "processing"
node reset_failed_ticket_connections.js        # flip failed rows back to pending

The recovery scripts

12sync_comment_visibility — how do I run it?

Two steps by design: a bash extract that runs behind the firewall, and a Node updater that can run anywhere.

Extract, then apply

# 1. Behind the firewall, against Data Center:
cd standalone-utilities/get_datacenter
bash main/get_datacenter_comment_visibility.sh

# 2. Anywhere, against Cloud:
cd ../sync_comment_visibility
node sync_comment_visibility_to_cloud.js --dry-run
node sync_comment_visibility_to_cloud.js

13automation-service — how do I run it?

CLI arguments only, no .env. Migrates automation rules between instances with the object ids remapped.

Run it

cd standalone-utilities/automation-service

node index.js \
  --source-site-url source.atlassian.net --source-cloud-id <id> \
  --source-username you@example.com --source-token "$SRC" \
  --target-site-url target.atlassian.net --target-cloud-id <id> \
  --target-username you@example.com --target-token "$TGT" \
  --mapping-file mappings.json --rules-file rules.json

Flags

14src_misc — what is in it, and when would I use it?

Admin helpers for during and after a migration. cleanup_objects.js is the destructive one — read this before running it.

Object cleanup

cd standalone-utilities/src_misc
# Uses standalone-utilities/.env

node cleanup_objects.js --dry-run --schema "Hardware"
node cleanup_objects.js --schema "Hardware" --confirm

The TEST_OBJECT_IDS environment variable scopes several of these helpers to a handful of known objects, which is the right way to prove a destructive helper behaves before pointing it at a schema.

15It crashed at object 8,000 of 20,000. What now?

Re-run it. Migration state is checkpointed in logs/migration_plan.json, and already-created objects are skipped — no duplicates.

The plan file is the source of truth for what has been done. Every object carries a status, and every created object's DC-to-Cloud id mapping is tracked separately in created_objects_mapping.json, which is what makes reference resolution possible across a restart.

The recovery scripts

16What do the common failures actually mean?

Four causes account for almost everything: the token encoding, the Assets admin permission, an attribute type mismatch, and a reference to something that does not exist yet.

Symptom to cause

401 immediately

The token is not base64 of email:api_token. Re-encode with echo -n — a trailing newline from plain echo also breaks it.

403 partway through the run

Authentication is fine; the account is not an Assets admin on the target workspace. Fix the permission, then reset the failed rows.

Object creation fails on one attribute

Type mismatch, or a required attribute with no value. check_cloud_attrs.js shows the Cloud side; the intelligent-migration mode converts what it safely can and truncates over-length text, but it will not invent a required value.

References not resolved

The referenced object was not created, or the referenced object type does not exist on Cloud. Check the creation status of the target first — an unresolved reference is usually a symptom of an earlier failure, not its own problem.

429 rate limited

Lower MAX_CONCURRENT_REQUESTS, wait, and consider MULTI_TOKEN_MODE. Retries use exponential backoff, but sustained over-concurrency outruns it.

Attachment upload fails

The file is missing from the extract, over the size limit, or the target object was never created. Check in that order.

17How do I prove the migration actually landed?

In the Assets UI, on objects you chose in advance — not from the run summary. An object created with empty references passes every API-level check there is.

The verification that counts

1. 1Pick the objects before the run. Choose ten that matter — the deepest hierarchy, the one with cross-schema references, the one with attachments — and write down what each should contain. Deciding what to check afterwards means checking what is easy.
2. 2Open them in the Assets UI. Every attribute, not the first one. Then click a reference and confirm it lands on the right object.
3. 3Count per object type, DC against Cloud. A whole type missing is easy to overlook when the total looks plausible.
4. 4Open a ticket that referenced an asset and confirm the custom field points at the migrated object, not at an empty value.
5. 5Download an attachment. A correct attachment count with an unreadable file is a real and common outcome.
6. 6Re-run with `--dry-run`. If it now reports nothing left to create, the plan agrees with reality. If it wants to create objects again, something is wrong with the mapping.