Troubleshooting?

Topics

Introduction

Release automation is the practice of coordinating the steps that move a release through its lifecycle - status changes, approvals, notifications, hand-offs to other systems - without doing each one by hand. In a Jira context that means reacting to what happens to a version or a package and triggering the right action automatically: a Slack message, a webhook, a new Jira issue for CAB approval, an update through Jira Automation.

Most teams arrive here after outgrowing manual release coordination. Build and release automation, application release automation, release management automation: the labels differ, but the problem is the same. Too many routine release operations are handled by people who should be doing something else. Release Management for Jira applies the trigger, condition, and action model to that problem inside Jira, so the release process runs itself wherever it safely can.

We aim to be “One Stop Shop“ for Release Management in Jira. And Release Automation is one of the key elements on this pathway. With Jira Automation gaining the momentum in optimizing routine operations and improving efficiency of SDLC … we aim to apply it to Release Management process & practices.

Therefore below you will see a similar notion of Automation rules with Triggers, Conditions and Actions. If you are new to Jira Automation you will feel right at home with Release Automation. Plus you can connect the two to gain Ultimate Automation.

Integration with Jira Automation

Conceptually our Automation rules are very similar to Jira Automation - triggers, conditions, actions. They could also be easily integrated - you can call a hook from Release Automation to cause execution of Automation rule in Jira (via Incoming webhook as Trigger).

This opens up an endless opportunity to `do any changes you want in Jira following the change in Release Management.

Examples could be found here - Automation Use Cases incl. Integration with Jira Automation.

Foundations of Release Automation rules

In Release Management you can create multiple automation rules.

To do so click on Board Settings and find Automation section on the left.

Open

To create new rule click on Add rule on top left. to Edit existing one just click on it.

For each rule you need to specify couple of basic parameters

• Name to differentiate your rules

• Status - ACTIVE / SUSPENDED

• Version/Package toggle (Version includes Fix Versions, Epics, Sprints and JQL Versions)

Open

The main essence of the rule is 3 core elements - Trigger, Conditions and Actions. The following sections outline all 3 in details.

Triggers

We support a great variety of triggers.

Open

If you are lacking something we are probably working on it. Just reach out to our support and help us prioritize remaining accordingly.

The aim is to have any possible change to version and/or package as a trigger.

Conditions

by Standard fields

To add condition to your rule click on Conditions drop down to check all the available options. Select the one that suits you most.

Open

Based on condition you will have a configuration dialog to specify other necessary details to be applied

Open

e.g. In example below we what to apply condition for version status change and shortlist a subset of statuses we are interested.

by Properties

You can also add conditions by Custom Properties for Versions and Packages.

To do so select Property condition in Condition look-up

Open

This will allow you to choose from existing Custom properties list for version or package (depending on your automation scope)

Open

Specify the rule and click Add.

By JQL

You can also add conditions by JQL that will be applied to your scope (issues) of version/package (depending of automation scope).

Select JQL condition in Condition look-up

Open

This will allow you to specify JQL and define the rule. You can also inject custom properties in your JQL if required.

Open

Click Add.

Combining conditions

Once you have multiple conditions defined you can switch between OR/AND options for the conditions to be executed.

Open

Actions

Below you will find a list of actions you can execute upon your Tigger and Condition met. But also you can pass on a great deal of version/package data and properties into those actions. Plus you can get a great benefit of some “helpers”, namely formatting capabilities and JS-like functions for data transformations.

Injectable variables

You are able to inject the following variables to the action/hook URL & Request body:

Versions specific

• version id

• version name

• version description

• version start date

• version release date

• link to version (deep link url to navigate to version details)

• project name (the version belongs to)

• project key

• project id

• user name (who is making a change causing the trigger to execute automation rule)

• user id (who is making a change causing the trigger to execute automation rule)

• status id (internal id of the column/status or version workflow)

• status name

• VERSION CUSTOM PROPERTIES

Packages specific

• package id

• package name

• package description

• package start date

• package release date

• link to package (deep link url to navigate to package details)

• package version id’s (versions encompassing the package)

• package project id’s (projects of the versions encompassing the package)

• user name (who is making a change causing the trigger to execute automation rule)

• user id (who is making a change causing the trigger to execute automation rule)

• status id (internal id of the column/status or version workflow)

• status name

• PACKAGE CUSTOM PROPERTIES

CHANGE related variables (for versions and packages)

• change entity name (e.g. version | package | milestone | environment name)

• change entity type

• change entity description

• change property name (property of the entity changed - standard or custom)

• change property old value

• change property new value

TIME functions (or datetime offsets)

You can also insert the following time functions. The App will insert an appropriate Macro that is also editable. Datetime formatting functions are the same as listed in following section.

Previous WEBHOOK response

You can also have access to previous WebHook response data, namely:

• prevWebhookData.headers

• prevWebhookData.body

• prevWebhookData.code

e.g. If your previous webhook returns a list of versions you can access it via

“Helpers“

Datetime formatting

Therefore, we support .formatDate(param1, param2) function where

• param1 is your date/time formatting pattern. Refer to the Java documentation for pattern syntax.

• param2 is optional and represent the desirable time zone, otherwise GMT will be used

Examples:

• .formatDate('MMM dd, yyyy HH:mm:ss', 'GMT+3')

• .formatDate('yyyy/MM:dd HH:mm', 'GMT+4:30')

• .formatDate('yyyy/MM/dd')

Generic String functions

To finetune your web hooks even further you can use JS-like function for injectable variables in URL & Request body sections of the hook. Below is a list of functions that could be used:

concat() - concatenates the string arguments to the calling string and returns a new string

equals() - returns boolean true/false if a calling string matches (exactly) the argument

isEmpty (not exist) - returns boolean true/false if a calling string is empty

split (string regex) - divides a calling string into an ordered list of substrings by searching for the pattern, puts these substrings into an array, and returns the array. So, you can use .split(pattern)[index] to pickup the right element of the array. If used only .split(pattern) it will return a string of comma separated substrings.

slice (int beginIndex, int endIndex) - extracts a section of a string and returns it as a new string, without modifying the calling string

toLowerCase() - returns the calling string value converted to lower case

toUpperCase() - returns the calling string value converted to UPPER case

trim() - removes whitespace from both ends of a string and returns a new string, without modifying the original string

replaceAll (string regex, string replacement) - returns a new string with all matches of regex a replaced by a replacement

Trim HTML tags

Some standard or custom properties might include HTML tags so when used in outcoming hooks not properly received in final destination. e.g. Slack and Teams hooks.

trimHTMLTags() - returns string with erased HTML tags

Open

Convert HTML to Wiki markdown

Instead of trimming HTML tags you might also convert HTML to Wiki markdown and use it elsewhere.

htmlToWiki() - returns string with converted HTML to Wiki markdown

Open

Important (!): IPs whitelisting

Webhooks are outcoming requests from our servers. If you want to receive these requests in your internal network (probably protected by Firewall) you need to while list IPs.

[Action] Execute Webhook

Once you select Execute Webhook in the actions list a dialog will popup to specify the details.

Open

Open

Summary tab

This tab contains the main properties of the hook

• Open

  

  Description to outline the details of what the hook is doing/aiming.

• Method. HTTP method which will be used for the webhook. Available options are:

  • GET

  • POST

  • PUT

  • DELETE

• URL. The URL which will be called from the our server while the webhook execution.

• Request body. The request body which will be used while the webhook execution. For instance, it could contact XML or JSON.

Headers tab

On the headers tab, you can define headers for the webhook HTTP request.

The headers could be added in Key-Value format. Multiple headers are supported.

You can also use variables to define headers keys and values (e.g. use authorization ticket you received with previous request).

To Secure your headers turn on Hidden so the App will hide it and encrypt it.

Open

[Action] Invoke Jira Automation

Step 1: Create Jira Automation rule

Go to your project and click on Automation to create one.

Open

For the trigger select Integrations and Incoming webhook.

Open

Select “No issues from the webhook“

Open

Click Save.

Step 2: Propagate Jira Automation URL into the App

In the App select Invoke Jira Automation from list of Actions and paste the URL you got from Jira Automation of the previous step. Thi is how you create the bridge between Release Automation and Jira Automation.

Step 3: Add Action in Jira Automation you need

Keep creating your new rule in Jira or edit existing one to create the action you need.

Open

Passing Data from Release Management to Jira Automation

You can use the following standard parameters we are sending from Release Automation to Jira Automation:

• webhookData.entityId - version or package ID

• webhookData.entityName - version or package Name

• webhookData.entityDescription - version or package Description

  • webhookData.entityDescriptionPlainText - version or package Description with TrimHTML function applied

• webhookData.startDate - version or package Start Date

• webhookData.releaseDate - version or package Release Date

• webhookData.entityLink - version or package Deep Link so you can access it from any external system

• webhookData.entityJQL - version or package JQL that defines the scope of release (Jira Issues)

• webhookData.projectName - project Name for Fix Versions or Epics, comma separated project names for Cross-Project Versions, empty for Sprints and JQL versions

• webhookData.projectKey - project Key for Fix Versions or Epics, comma separated project keys for Cross-Project Versions, empty for Sprints and JQL versions

• webhookData.projectId - project ID for Fix Versions or Epics, comma separated project ids for Cross-Project Versions, empty for Sprints and JQL versions

• webhookData.epicKey - Epic Key for Epic-based Virtual Versions.

• webhookData.statusId - destination ID of the Column where entity sits post action

• webhookData.statusName - destination Name of the Column where entity sits post action

• webhookData.userName - User Name who triggered Release Automation rule led to executing a hook

• webhookData.userId - User Name who triggered Release Automation rule led to executing a hook

• webhookData.environmentIds - Environment IDs for version or package (all the versions in the package)

• webhookData.environmentNames - Environment Names for version or package (all the versions in the package)

• webhookData.changedEntityName - Name of the entity that changes triggering the rule. See EntityType.

• webhookData.changedEntityType - Type of the entity that changes triggering the rule. Could be: Version, Epic, Sprint, JQL Version, Package, Milestone, Environment, Comment, Custom Property

• webhookData.changedEntityDesription - Description of the entity that changes triggering the rule. See EntityType.

  • webhookData.changedEntityDesriptionPlainText - Description with TrimHTML function applied of the entity that changes triggering the rule. See EntityType.

• webhookData.changedPropertyOldValue - Old Value of the property that changed - standard or custom

  • webhookData.changedPropertyOldValuePlainText - Old Value with TrimHTML function applied of the property that changed - standard or custom

• webhookData.changedPropertyNewValue - New Value of the property that changed - standard or custom

  • webhookData.changedPropertyNewValuePlainText - New Value with TrimHTML function applied of the property that changed - standard or custom

• webhookData.changedPropertyName - Name of the property that changed - standard or custom

• we are also sending a list of custom properties. you can access it via

  • webhookData."Custom Property Name“ - the way you define name in Properties configuration

  • Important: in case of multi select property value comes as comma separated selections

  • Important: in case of multi user property value comes as comma separated user names

Additional Datetime formatting

The following functions are supported: