Automation Rule Management API is now Generally Available!

[#1]

Hi Atlassian Community,

In our previous post we announced our new Rule Management APIs available for testing. Today we’re excited to announce that the Automation Rule Management API has graduated from Early Access and is now Generally Available (GA) for all customers! 🎉

This release brings new capabilities for managing automation at scale, making it easier than ever for admins and developers to programmatically control rule configurations across your Jira sites

What’s new in GA?

• Developer documentation updated: Find the latest API details, usage patterns, and best practices in our developer documentation.
• Create connections via API: You can now create connections directly through the API, enabling more seamless integration with external systems.
• Create new labels on the fly: When creating or updating rules, you can now specify new labels that will be created automatically if they don’t already exist.
• Specify rule UUIDs: When creating a rule, you can provide a UUID. If it’s not already taken, it will be used for your new rule, making migrations and imports much simpler.

How does it work?

Here are some practical API use cases and examples to help you get started:

Import/Export a Rule

Export a rule using the “get a rule by UUID” API:

curl --request GET \
  --url '{baseSiteURL}/gateway/api/automation/public/jira/{cloudid}/rest/v1/rule/{ruleUuid}' \
  --header 'Accept: application/json' \
  --header 'Authorization: {authorisationToken}'

To import (clone) a rule, remove the uuid field from the payload if importing into the same site, then use:

curl --request POST \
  --url '{baseSiteURL}/gateway/api/automation/public/jira/{cloudid}/rest/v1/rule' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: {authorisationToken}' \
  --data '{ ... }'

Bulk Update Rule Scope

To update the scope of multiple rules (e.g., after creating a new project):

Search for rules by scope:

curl --request POST \
  --url '{baseSiteURL}/gateway/api/automation/public/jira/{cloudid}/rest/v1/rule/summary' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: {authorisationToken}' \
  --data '{ "scope": "ari:cloud:jira:{cloudId}:project/10001" }'

Update rule scope for each rule:

curl --request PUT \
  --url 'https://api.atlassian.com/automation/public/{product}/{cloudid}/rest/v1/rule/{ruleUuid}/rule-scope' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: {authorisationToken}' \
  --data '{ "ruleScopeARIs": [ "ari:cloud:jira:{cloudId}:project/10001", "ari:cloud:jira:{cloudId}:project/{newProjectId}" ] }'

Update Rules in Bulk

To update a set of rules (e.g., after a field rename):

Search for rules by trigger:

curl --request POST \
  --url '{baseSiteURL}/gateway/api/automation/public/jira/{cloudid}/rest/v1/rule/summary' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: {authorisationToken}' \
  --data '{ "trigger": "jira.incoming.webhook" }'

For each rule, fetch details, edit as needed, and update:

curl --request PUT \
  --url 'https://api.atlassian.com/automation/public/{product}/{cloudid}/rest/v1/rule/{ruleUuid}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{ "rule": {updatedRuleConfig} }'

Get Started

Check out the developer documentation for how to get started.

We want your feedback!

Have questions or want to share how you’re using the API? Drop your thoughts in the comments below. Your feedback helps us shape future improvements.

Thanks for being part of the Atlassian Community!

[Bill Sheboy]

Hi @Scott Bell 

Thank you for the updated information.  I have a couple of questions:

What can you share on progress to create endpoints and webhooks for accessing automation audit logs?

While there is some older documentation for Data Center on component types and structure in rule JSON, there is nothing newer or for Cloud's Jira, Confluence, and JSM automation.  As a result, customers must first create many example rules and analyze them to identify the content to use for endpoints to create / update rules.  What can you share on plans to create such documentation to support using the endpoints?

Kind regards,
Bill

[Scott Bell]

@Bill Sheboy thanks for the reply and apologies for the late response.

We’re looking at the Audit Log soon. I don’t have concrete dates, but I want to make sure we have API endpoint coverage. If you can share your top audit use cases, we’ll add them to our requirements.

For the rule structure, I spoke with the engineering team. The public API documents the top-level rule object and data types. The tricky bit is component configs. Each component has its own payload and the component value field is component-specific. There are hundreds across Jira, Confluence and JSM, so we can’t publish a complete, stable schema right now.

The best method today is to create a sample rule with the component you need and review the export JSON to see the exact config. I know that’s not ideal at scale, and your feedback is noted.

[Bill Sheboy]

Thanks for the updates, @Scott Bell 

And, I did much of that component analysis you describe when I created my own rule parser outside of Jira, and I agree it is a moving target due to the excellent, continuing improvements the team makes to automation :^)

For some audit log endpoint and webhook scenarios, I expect many are to add instrumentation to cover gaps in the rule list for monitoring and documentation.  For example:

• increase the history duration for available logs when read using the endpoints
• improve the audit log details to add a "verbose" setting which shows all changes made to a rule for updates (This was one of my original automation suggestions in JAC, but it was replaced by team member edits :^)
• given a set of rules filtered-by criteria (e.g., Status, enabled, scope, project, etc.), return all log entries for a specific timeframe
• given a set of rules filtered-by criteria, return all log entries over a specified execution Duration (excluding stuff like the new Delay() action impacts)
• for the above endpoints, include orderBy parameters
• for the above endpoints, I would want to avoid the problems caused by ornery project admins locking down permissions, and thus add parameters to allow Site / Product Admins to override owner / editor permissions if you anticipate those would impact audit log access
• add events to webhooks for rule creation, rule deletion, rule update, rule enable, rule disable, rule moved, rule scope changed, etc.

Thanks again, and kind regards,
Bill

[Mykenna Cepek]

(wrong account, see below)

[Mykenna Cepek]

I must be missing something. I'm excited about this API, but not finding what I was expecting.

The "previous post" link above (as of today) goes to an article that talks about the orchestration (advanced) components and doesn't mention the automation API. I think it should go here instead.

I understood that this API was to help with rule import and export (among other things). And many of us were particularly interested in doing full backups of all their rules periodically with this API.

But based on what I'm seeing for the API endpoints today, getting a usable full backup of all rules would involve:

• Using GET /rule/summary repeatedly (since it's a paged call) to extract the UUIDs for all currently defined rules.
• Iterating on those UUIDs and calling GET /rule/<UUID> to return the JSON for each rule.
• Reformatting all those results into a single JSON that matches what we get when exporting all rules manually.

Otherwise you end up with a pile of separate rules (in our case, hundreds of them) which can be individually imported, or sent individually to PUT /rule to recreate them.

Instead of making all that extra work for all of us, wouldn't it have made sense to have one more GET endpoint returning all rules in the proper (importable) format, identical to what "export all rules" does today? I was excited. Now I'm just tired.