Troubleshooting?

Topics

Introduction

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 to scratch with Jira Automation you will feel right at home with Release Automation. Plus you can connect the two to gain Ultimate Automation.

Successor of “Outcoming WebHooks“

For some time we had (Deprecated) Outcoming WebHooks functionality that our clients successfully used to notify audiences about release status change or trigger certain actions either via Jira Automation or “hook”ing 3rd party system (e.g. CI/CD tools, etc.)

The below is a logical evolution of Outcoming Hooks to

• Add all possible triggers

• Add flexible options for conditions

• Humanize actions via outcoming hooks.

At some point of time we will disable and option to create new “Outcoming WebHooks“ and clone existing to deprecate this functionality after decent transition time as we truly believe that Release Automation is what our clients need for automating their release management use cases.

How to create “former“ WebHooks with “new“ Release Automation

If you want to migrate your old WebHooks or use new functionality the old way meanwhile .. here’s a step by step guide to do so.

Step1. Create automation rule

Open

Step 2. Select Version/Package moved as Trigger

Open

Step 3. Add new Field condition

Step 4. Select status and short list the column(s) as you used to do with Webhooks

Step 5. Add Action were you can see all the actions you used to have in WebHooks. Copy configurations if required.

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.

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.

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)

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.

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.

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

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

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

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

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

Click Add.

Combining conditions

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

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)

• 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)

• 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

• param2 is optional and represent the desirable timezone, 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')

Here’s a link to supported formats https://date-fns.org/v2.30.0/docs/format.

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

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

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.

As of September 14, 2024

Till September 14, 2024

Action>Execute Webhook

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

Summary tab

This tab contains the main properties of the hook

• 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.

Action>Invoke Jira Automation

Step 1: Create Jira Automation rule

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

For the trigger select Integrations and Incoming webhook.

Select “No issues from the webhook“

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.

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.executorName - 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

E.g. use case: Send Email notification

Navigate to Automation Use Cases incl. Integration with Jira Automation | ➡️ Send email upon Release status change section of this documentation.

Action>Update Version/Package

Another type of action you can define is updating your version/package (based on the rule definition - whether it’s for version or package).

Update Tags

Click on Tags toggle and specify Tags you want to add to version/package or replace with those tags

Click Add

Update Description

Click on Description toggle and specify Description you want to add to version/package or replace existing description with new one.

You can also decide if you want to use plain text vs HTML editor.

Click Add

Update Environments

Click on Environments toggle to append version environments with designated one. You can also replace the original list with new one.

Click Add

Add Comment

Click on Add comment toggle to specify what comment you want to add upon executing the automation rule. Very good feature to keep audit trail on all the changes happening.

Click Add

Update Properties

Click on Properties toggle and add version/package properties from the list you want to alter.Depending on the property type you can either replace with a new value or append new value

Click Add

Update .. (more to come)

Our backlog is full of stories for other actions to update most of version/package details. We take it according to the priority. If you want to us to prioritize smth please reach out to our support.

Action>Send Slack message

If you select Send Slack message action we will pre-populate webhook URL and Body so you can amend it with your org details.

How to get URL for Slack integration?

Step 1. Navigate to https://api.slack.com/apps?new_app=1 to create an app “From scratch“

Step 2. Choose the name of the App (integration) and a space to send notifications

Step 3. Enable “Incoming Webhooks”

Step 4. Activate it and add new Webhook

Step 5. Allow integration and choose the destination channel from the selected space

Step 6. Copy URL for Slack integration

Tips and Tricks on “How to construct Slack Message“

We are using Slack Block Kit to construct the messages.

Plan B: Use Jira Automation

If you have any difficulties with above or find it easier to configure in Jira because you already have such actions configured there .. feel free to configure Slack Notifications in Jira and use Release Automation Explained | 🤖 Action>Invoke Jira Automation (coming soon) to setup a bridge.

Action>Send Teams message

If you select Send MS Teams notification action we will pre-populate webhook URL and Body so you can amend it with your org details.

How to get URL for Teams integration?

Step 1. Go to the channel where you want to add the webhook and select ••• More options from the top navigation bar.

Step 2. Select Connectors from the dropdown menu:

Step 3. Search for Incoming Webhook and select Add.

Step 4. Select Configure, provide a name, and upload an image for your webhook if required:

Step 5. The dialog window presents a unique URL that maps to the channel. Copy and save the Teams integration URL, to send information to Microsoft Teams and select Done:

Plan B: Use Jira Automation

If you have any difficulties with above or find it easier to configure in Jira because you already have such actions configured there .. feel free to configure Teams Notifications in Jira and use Release Automation Explained | 🤖 Action>Invoke Jira Automation (coming soon) to setup a bridge.

Action>Create Jira Issue

Another action you can define is Creating Jira issue. There could be multiple use cases for it, but what we have heard from the clients the most is the following:

• Ticket for end-to-end regression

• Ticket for CAB approval (Change Management Board)

• Ticket for DevOps to deploy for lower or production environment

• Ticket for Marketing Team to start experiment

• etc.

To make one click on Add action pull up to choose Create Issue

Create issue dialog will show up where you can specify

• Project where you want to create issue (projects will be filtered by your permissions - actor permissions)

• Issue type

• Issue parent (for subt-tasks only)

• Issue summary

• Issue description

• Additional fields (see below)

• Actor upon which Create issue will run (permissions will be verified)

In all - summary, description & additional fields - you can inject variable of versions/packages and change related items.

Creating sub-tasks

If you select sub-task issue type the App will automatically suggest you to select parent standard issue type from the selected project

Additional issue fields (multiple use cases)

There are certain limitations, namely

• we can't show you standard Issue Creation dialog to specify other standard and custom fields

• we do not know what are the mandatory fields you heave setup for your issue type

To overcome this we created a possibility to add additional fields in JSON format. Thus you can specify mandatory fields and/or any other fields you would like to setup upon issue creation.

Plan B: Use Jira Automation

If for some reason you are missing smth in the App and can’t create issues you need please reach out to our support. Meanwhile you can do a work around via Jira Automation bridge - trigger a hook there, pass over the payload you need from the App and create/update issue via one of the Actions in Jira Automation. Read more details about our Examples of Release Automation (also via Jira Automation).

More actions

Execution history

You can see the history of all the automation rules execution. To do so click on any of the rules and navigate to History tab.

Click Show more the execution you are interested it to receive the details about Trigger, Action (both Request and Response).

Troubleshooting Automation Rules

Tips: How to troubleshoot?

Typical failed cases