How do you document your automation rules?

[Charlie Misonne]

Hi Community!

I'm wondering how other Jira administrators document their more complex automation rules.

When working with several Jira admins or when you have a lot of automation rules it can get difficult to remember why something was configured that way.

Here is how my team deals with this:

• We have a Confluence page template with a page property table that includes info like: URL to the rule, short description, purpose, complexities, ...
• For every rule we create a page with this template. Using the page property macro we have a nice overview of all rules on the parent page
• We put the URL of the page in the description of the rule

It's a fine way of working but it is still difficult to document specific parts of a rule. Why are we setting a variable somewhere, why are we doing a "fetch issue data", why are we calling this specic API with a http request, ...

A suggestion for Atlassian: it would be great to have a "comment" field on each component (action, condition, trigger, ...) where we can put some explanation about the specific component.

What do you think?
Feel free to share how you deal with this in your team :-)

[Laurie Sciutti]

Hi @Charlie Misonne ~ I create automation rules based on Jira requests in our backlog so when I create the rule, I ensure to add the Jira issue # to the Rule Description along with an overview of what the rule does (along with a linked Confluence page if needed).  It's not great but at least I can get more information from the Jira issue.  Though it sounds like this is essentially equivalent to what you're doing by documenting in Confluence. 

I agree with you that some type of comment field for each component of the rule would be helpful.

[Rick Westbrock]

A comment attribute for each step would be great. I suppose a kludgy workaround would be to put a log action just before or after any step which might require explanation.

I would also love to see a Name attribute for all steps since that would make it easier to document externally and to collaborate i.e. if I'm working with you on a rule I can ask you to explain step XYZ instead of "the lookup step that is sixth from the top".

[Charlie Misonne]

yes great idea too. Naming or even numbering the steps would be great.

We already number the rules manually but putting a number in front of the title. It's easier to reference a rule when talking to a colleague.