Migrating from Comala to Aura

Aura ships with a migration feature that transfers your existing workflow assignments from Comala Document Management — both Cloud and Data Center — into Aura Workflows. Each page’s current state is preserved, so content keeps moving from where it left off after the switch.

The importer reads a JSON file describing which page was running which workflow and what state it was in. The Comala migration script generates this file for you; if you’re moving from a different workflow app, the same JSON shape can be produced by any tool that knows your data. Reach out to support before starting a non-Comala migration so we can help shape the file.

What gets migrated

Migration brings two things across: the link between a page and its workflow, and the page’s current state. Aura looks up the page by space key and title, finds the workflow by name, finds the matching state by name, and applies the workflow with that state set as current.

Approval history, prior reviewers, comments on past reviews, and the record of transitions in the legacy app do not come across — those stay in the source tool’s storage. A page halfway through an approval lands in that state cleanly in Aura, with no pending reviewers and no in-flight approval; anyone who needs to act starts fresh.

Prerequisites

You’ll need Site Admin permissions in Confluence to access the migration UI. The target workflows must already exist in Aura before you migrate, ideally with state names that match what you used in Comala. We provide the migration script bundle on request — ask support and you’ll receive a small archive containing:

migration-bundle.js    # The migration script
.env.example           # Template for your configuration
README.md              # Quick-start instructions

Note

Recreate your Aura workflows before migrating. The importer matches by workflow name and state name. If a workflow has no counterpart in Aura, the page is skipped. If a state name doesn’t match, the page falls back to the workflow’s initial state.

Step 1: Prepare your workflows in Aura

1. Create the corresponding workflows in Aura — global or space-scoped, matching your Comala setup.
2. Use the same state names you had in Comala wherever possible. Any state name that doesn’t match drops the page into the workflow’s initial state.

Step 2: Run the migration script

The script connects to your Comala instance, extracts every active workflow assignment, and writes a JSON file. Aura never talks to Comala directly — credentials stay on the machine that runs the script.

Comala Data Center

1. Copy .env.example to .env and fill in your Data Center credentials:

   DC_BASE_URL=https://your-confluence-dc.example.net
   DC_USER=your_username
   DC_PASSWORD=your_password

2. Run the script:

   node migration-bundle.js

3. The script generates json/comala-workflow-instances.json.

Comala Cloud

1. Run the script:

   node migration-bundle.js

2. The script generates json/comala-cloud-workflow-instances.json.

Cloud only

The Comala Cloud API does not expose workflow names directly. The generated JSON contains placeholders like "<workflowId>-name" and "<workflowId>-scope". You must replace each one with the matching Aura workflow name and scope before uploading.

Step 3: Review the JSON

Each entry in the generated file describes one page or blogpost and the workflow assignment it should land on:

[
  {
    "contentTitle": "Project Plan Q4",
    "contentType": "page",
    "currentStateName": "In Review",
    "spaceKey": "PROJ",
    "workflowName": "Approval Workflow",
    "workflowScope": "space"
  }
]

Field	Description
contentTitle	Title of the Confluence page or blogpost.
contentType	Either "page" or "blogpost".
currentStateName	The current workflow state in Comala.
spaceKey	The Confluence space key.
workflowName	The name of the target workflow in Aura.
workflowScope	"global" for global workflows, "space" for space-scoped workflows.

Before uploading, confirm three things: workflowName matches an existing Aura workflow exactly, workflowScope reflects whether it’s global or space-scoped, and currentStateName matches a state in the target Aura workflow. Anything that doesn’t match falls back to the initial state, or — for unmatched workflows — fails the entry outright.

The format is general. Any export tool that produces this shape can feed the importer; this is how migrations from other workflow apps work in practice. The Comala script is the supported path, but the JSON is the contract.

Step 4: Upload and start the migration

1. Open Aura Workflows in Confluence and navigate to the Migration section under Administration (Site Admins only).
2. Drag the JSON onto the upload area or click to select it, then click Start upload. Large files are uploaded in chunks automatically.
3. Once the upload completes, click Start migration to begin processing.

Step 5: Monitor progress

The migration UI shows live counts of applied pages, failed pages, and elapsed time. Pages are processed in batches in the background, so you can close the page and come back later. Stop migration halts the run cleanly and leaves unprocessed entries in place; Continue picks up from where you left off.

Every migrated page records a “migrated” event in its workflow history, attributed to the app rather than a user. This distinguishes pages that came through the importer from those started by hand.

How matching works

Workflows are looked up by name and scope. Global workflows are matched across all global workflows in Aura. Space workflows are matched within the specified spaceKey. If no matching workflow is found, the entry fails.

States are matched by currentStateName against the names in the target workflow. An exact match places the page in that state; no match falls back to the workflow’s initial state.

Pages are matched by exact title within the specified space. Pages that have been renamed or deleted since the JSON was generated are skipped.

After the migration

Successfully migrated pages have the Aura workflow applied with the correct state. The migration history event is visible in the page’s workflow history. If some pages failed, Retry reruns the failed entries — already-applied entries are skipped automatically, so retry only touches what’s left. For a small leftover, applying the workflow from the page’s Aura panel and picking the right state takes seconds.

Troubleshooting

Issue	What to do
Many pages show as failed	Check that workflow names and scopes in the JSON match your Aura configuration exactly.
Pages are in the wrong state after migration	Verify that your Aura state names match the Comala state names. Unmatched states fall back to the initial state.
Upload fails or is very slow	Ensure a stable network connection. Large files are uploaded in chunks; cancel and restart if needed.
Migration seems stuck	Migrations process in batches. For large jobs, the run can take a while — check that the progress counter is advancing.
Cloud JSON has placeholders	Expected. Replace every "<workflowId>-name" and "<workflowId>-scope" with the matching Aura workflow name and scope before uploading.

FAQ

Can I run the migration multiple times? Yes. The migration is idempotent — if a workflow is already applied to a page, it’s replaced with the migrated state.

Will the migration affect pages that aren’t in the JSON? No. Only pages listed in the uploaded file are touched.

Do I need to remove Comala before migrating? No, but disabling Comala workflows after a successful migration is recommended to avoid conflicts.

What permissions do I need? Site Admin permissions in Confluence. Anyone with less can run individual workflow apply actions but not the migration UI.