What you'll learn

  • How to configure Jira Automation to define periodic actions
  • How to configure Jira Automation to gather Test Plan data through the Xray API
  • How to configure Jira Automation to send formatted data through email


Prerequisites


For this example we will use Jira Automation built-in capabilities and Xray API to gather Test Plan progression information and send a formatted email with that information.


You'll need:

  • a Jira instance with Xray installed and configured

Jira Automation

Jira Automation is flexible enough to be used as a no-code or low-code rule builder, where you can create automation rules to take care of everything from the most simple repetitive tasks to the most complex scenarios - all in a few clicks.

Automation rules consist of three parts: triggers that initiate the rule, conditions that refine the rule and identify when it's applicable, and actions that perform tasks on your site.

Triggers, conditions, and actions are the building blocks of automation. Combine these components to create rules that can do anything from auto-closing old issues to notifying specific teams when a release has been shipped. You can find some automation templates to help you get started within the product library.

Create a new rule

The first step is to create a new automation rule. To do so, access the Project Automation option in the Project Settings section and press the Create Rule button.


A new page is opened and now you can start by defining the trigger of this new rule.

Define the trigger

There are multiple ways to define triggers for Jira Automation rules. 

For this example, we configure the "scheduled" trigger, which can be selected in the search box by searching with the term scheduled and pressing the Scheduled trigger.


Notice that once pressed a configuration form for the rule is shown. There we define that this rule will be executed once per day and we have chosen to run a specific JQL query to fetch the required Test Plan (using the project key and Test Plan issue id).


And press "Save" to add another component, that in our case is a component that allows making a web request to the Xray API.

Define Xray API requests

Now that we have selected the Test Plan issue from which we want more information, we need to define what other information we want to obtain, namely the key of each Test and the status of the latest run. 

To obtain this information, we are using API requests. The first step is to fetch the Test Plan data using a web request component of the Jira Automation rules.


Fetch Test Plan data

We use the "Send web request" component to send a request to the Xray API to extract information of a given Test Plan.

The "Send web request" component is configured with the following options:

  • Web request URL: https://<your-server>/rest/raven/1.0/api/testplan/{{issue.key}}/test
  • HTTP method: GET
  • Web request body: Empty
  • Choose "Delay execution of subsequent rule actions until we've received a response for this webhook" option; this option allows the subsequent requests to access the response through smart values like: {{webhookResponse.headers}}
  • Define a new header to pass the "username:password" encoded in Base64 in a key/value pair format: 
    • Key: Authorization
    • Value: Bearer {{webResponse.headers.x-access-token}}

Format data and send email

The information retrieved from the previous request is in Json format so we need to reformat it to be useful if we want to send it as an email.

Jira Automation has a "Send email" component that allows you to define the Subject line and body of the email.

The last step is to add this component to our rules. To do so, we choose the "Send email" component from the component list.

The "Send email" component has three required fields that need to be defined:

  • The destination user(s): To - The destination recipient of the email.
  • The Subject: Subject - The email subject where you can use smart values if needed.
  • The Content of the email: Content - The actual email content, that can be plain text or HTML depending on your goals.


For our example we are defining the destination user with an email but you can define your own or use some smart values available.

In the Subject we want to include the Key of the TestPlan to be easily identified in the inbox, so we use: "Test Plan {{issue.key}} Status Report" where the smart value {{issue.key}} will be replaced by the Test Plan issue key.

In the Content field we have defined an HTML content as we can see below:

Formatted Email 
<html>
<head>
<style type="text/css">
.container{
margin: auto;
width: 60%;
padding: 10px;
font-family: Arial;
}
a {
text-decoration: none;
}
img {
height: 35px;
float: right;
}
</style>
</head>
<body>
<div class="container">
<h1>
<p><strong>Test Plan {{issue.key}} Status Report (id: {{issue.id}})</strong></p>
</h1>
<hr style="border:1px solid red">
<h2>Summary: <a href="{{issue.toUrl}}" style="color: #1963d1;">{{issue.summary}}</a></h2>
<strong>Description: </strong> {{issue.description}}
<br>
{{#webhookResponse.body}} 
<p>
<strong>Test: </strong>{{key}} 
{{#if(equals(latestStatus, "PASS"))}}
<strong>Status: </strong> <strong style="color:#95c160">{{latestStatus}}
</strong>
{{/}}
{{#if(equals(latestStatus, "FAIL"))}}
<strong>Status: </strong> <strong style="color:#d45d52">{{latestStatus}}
</strong>
{{/}}
{{#if(equals(latestStatus, "TODO"))}}
<strong>Status: </strong> <strong style="color:#696969">{{latestStatus}}
</strong>
{{/}}
</p>
{{/}}
<hr style="border: 1px solid red">
</div>
</body>
</html>


Notice that we are using several smart values that will be replaced when the email is sent, such as:

  • {{issue.toUrl}} - Fetches the issue URL so that the users can click on the Test Plan link on the email and be redirected to the Jira issue.
  • {{issue.summary}} - That is replaced by the summary field of the Test Plan issue.
  • {{issue.description}} - That is replaced by the description of the Test Plan issue.


We also use the ability to apply a rule to all the elements of a list (more information here) using: {{#}} and {{/}}.

These special tags will apply what is between them to all the elements of the list, in our case it replaces the summary, key, status color, and status name of each Test in the Test Plan:

Apply to all elements of the list
{{#webhookResponse.body}} 
<p>
<strong>Test: </strong>{{key}} 
{{#if(equals(latestStatus, "PASS"))}}
<strong>Status: </strong> <strong style="color:#95c160">{{latestStatus}}
</strong>
{{/}}
{{#if(equals(latestStatus, "FAIL"))}}
<strong>Status: </strong> <strong style="color:#d45d52">{{latestStatus}}
</strong>
{{/}}
{{#if(equals(latestStatus, "TODO"))}}
<strong>Status: </strong> <strong style="color:#696969">{{latestStatus}}
</strong>
{{/}}
</p>
{{/}}


Notice that we have added some conditionals to color the test status, so depending on the latestStatus field content (PASS, FAIL, TODO, etc) we have defined different colors.

Apply to all elements of the list
{{#if(equals(latestStatus, "PASS"))}}
<strong>Status: </strong> <strong style="color:#95c160">{{latestStatus}}
</strong>
{{/}}
{{#if(equals(latestStatus, "FAIL"))}}
<strong>Status: </strong> <strong style="color:#d45d52">{{latestStatus}}
</strong>
{{/}}
{{#if(equals(latestStatus, "TODO"))}}
<strong>Status: </strong> <strong style="color:#696969">{{latestStatus}}
</strong>
{{/}}


The generated email will look like this:


Tips

  • The Send web request component has a Validate option that will perform the request and show the result; this is very helpful for testing your rule while creating the automation rules.
  • Take advantage of smart values to use responses from previous components of the automation rule to enrich your automation.
  • The email accepts plain text or HTML content; use the one that better suits your needs.

References




  • No labels