On this page:

How to migrate your automation rules to Forge

Once Didit runs fully on Atlassian Forge, automation rules that start Didit by setting the didit.action issue property stop working: Forge apps aren’t notified when an issue property is set (Atlassian ticket FRGE-55). Migrate these rules to the Didit actions, which come with the Connect on Forge version 5.x of Didit.

Old rules fail silently

After the full Forge release, these rules still run and report success in their audit log, but Didit does nothing. Migrate them before then.

Everything else keeps working

Only rules that set didit.action need migrating. Didit custom fields in rules (for example, checking whether a checklist is complete), workflow validators and post functions, and Didit for Confluence keep working as they are.

Before you start

  • Make sure you have the Didit actions. Search for “checklist” in a rule’s actions: you should see the three Didit actions under Other apps. If not, update Didit to the latest version 5.x.
  • Check your permissions. As a Jira administrator, you can migrate the rules of all projects at once, including global rules, with the script or by hand. Project admins can only migrate their own projects’ rules, by hand. The script, the Forge readiness tab, and the export of all rules need a Jira administrator.
đź’ˇ

Rules or flows?

Jira now calls automation rules flows and projects spaces. This guide uses rules and projects, like Didit.

Migrate your rules

With more than about 10 rules to migrate, we recommend the script: it migrates all your rules at once. With fewer, migrating them manually is usually quicker.

In every rule that sets didit.action, including global rules, the script swaps the old action for the matching Didit action and connects it in your name. The rest of the rule stays as it is. The script runs on your computer with your own account, writes a backup first, and sends nothing to Didit.

What you need

  • A Jira administrator account and Node.js 18 or later.
  • An API token for your account, with a short expiry date.
  • One rule that already uses a Didit action, so the script can read your site’s Didit details.

  1. Export all your rules: in Jira settings (⚙), select System → Automation flows, then More actions (…) → Export flows. Click Next, then Done.

  2. Download the migration script into the same folder, and open a terminal there.

  3. Set your email address and API token.

    On macOS or Linux:

    export ATLASSIAN_EMAIL=you@example.com
export ATLASSIAN_API_TOKEN=your-api-token

    On Windows, in PowerShell:

    $env:ATLASSIAN_EMAIL = "you@example.com"
$env:ATLASSIAN_API_TOKEN = "your-api-token"

  4. Do a dry run with your export file and your Jira site. It lists the rules it would change, and changes nothing.

    node migrate-automation-rules.mjs api automation-rules-202610051200.json --site your-site.atlassian.net

  5. If the list looks right, run it again with --apply.

    node migrate-automation-rules.mjs api automation-rules-202610051200.json --site your-site.atlassian.net --apply

    To try one rule first, add --rule and the rule’s name, like --rule "Add DOD". If some rules fail, run the same command again with --only-failed and the results file the script wrote.

  6. Rebuild the rules marked âš  manually.

    The script skips values it doesn’t recognize. It also doesn’t connect rules that have other connections, like Slack: open these rules, click the Didit action, and click Connect.

  7. Delete the API token, and keep the backup file until you’ve tested your rules.

    To undo the changes, run restore with the backup file. Without --apply it’s a dry run that lists what it would restore. Run it again with --apply to restore. It skips rules you’ve changed since.

    node migrate-automation-rules.mjs restore didit-rules-backup-1791275303544.json --site your-site.atlassian.net

Test your rules

  1. Trigger the rule on a test work item, for example by creating one.

  2. Check that the checklist appears or the metadata is set, and that the rule’s audit log shows a successful run.

Then confirm you’re done: export all your rules again and drop the file on Check if you’re all set in the Forge readiness tab. Projects with no old rule left drop off Impacted projects, and if no rule uses the old trigger, the tab says All good, as described in How to check if your site is ready for Forge (opens in a new tab).

Frequently asked questions

When do I have to finish?
Why can’t Didit migrate my rules itself?

Need help? Reach out to our support team or chat with us.