Prerequisites

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 are made up of three parts: triggers that kick off 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. Simply 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 thing to do is to create a new automation rule. To achieve that, access the 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 of defining triggers for Jira Automation rules. 

For this example we configure the "scheduled" trigger, that can be selected in the search box by searching with the term scheduled and press 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 at 09:00 AM 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 "Next" to add another component, that in our case is a component that allows making a web request to the GraphQL API.

Define GraphQL requests

Now that we have selected the Test Plan issue we want to extract more information about, we need to define what other information we want to obtain, namely the number of tests that are part of the Test Plan and the status of the latest run.

To obtain this information we are using GraphQL queries, the first step is to authenticate using a web request component of the Jira Automation rules.

Authentication

A web request must be done at the authentication endpoint of Xray because all accesses to the Xray APIs are only possible after authentication.

The authentication is performed using an action component called Send web request that will execute a web request to a specific endpoint and retrieve the corresponding results.

We configure the web request as follows:

• Web request URL: https://xray.cloud.getxray.app/api/v2/authenticate (Xray API endpoint)
• HTTP method: POST
• Web request body: Custom data
• Custom data: { "client_id": "CLIENTID","client_secret": "CLIENTSECRET" } (Client Id and secret to authenticate against your Xray API instance)
• Choose "Delay execution of subsequent rule actions until we've received a response for this web request" option; this option allows the subsequent requests to access the response through smart values like: {{webResponse.body}}

The "Send web request" component allows the validation of the request configuration before setting it, to do so use the "Validate your web request configuration" option and press "Validate". This will execute the request and show you the result.

Fetch Test Plan data

Now that we are authenticated we are going to use the token retrieved from the last request and perform a request to the GraphQL endpoint requesting information about the Test Plan.

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

• Web request URL: https://xray.cloud.getxray.app/api/v2/graphql
• HTTP method: POST
• Web request body: Custom data
• Custom data: 
  • GraphQL query

    {
        "query": "{ getTestPlan(issueId: \"{{TestPlanId}}\") { issueId projectId jira(fields: [\"key\", \"summary\",\"url\",\"description\"]) tests(limit: 100) { total results { status { name description final color } testType { id name kind } jira(fields: [\"key\", \"summary\"])}}}}"
    }

  • To obtain information from the Test Plan we are using the getTestPlan query and define that we want to receive information about (as we can see above):
    • Test Plan issueId
    • Test Plan projectId 
    • Test Plan Key
    • Test Plan summary
    • Test Plan issue url
    • Test Plan description
    • Test Plan List of Tests
      • total number of tests that are part of the Test plan
      • status of each Test (with the name of the status, description, and final color)
      • testType of each Test (with id, name, and kind)
      • Test key
      • Test summary
• Choose "Delay execution of subsequent rule actions until we've received a response for this web request" option; this option allows the subsequent requests to access the response through smart values like: {{webResponse.headers}}
• Define a new header to pass the authentication token 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 the definition of the Subject and of the 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:

<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 {{issue.id}}</strong></p>
</h1>
<hr style="border:1px solid red">

<h2>Summary: <a href="{{issue.toUrl}}" style="color: #1963d1;">{{webResponse.body.data.getTestPlan.jira.summary}}</a></h2>
<strong>Description: </strong> {{webResponse.body.data.getTestPlan.jira.description}}
<br>
<strong>Total number of Tests: </strong>{{webResponse.body.data.getTestPlan.tests.total}}
<br>

{{#webResponse.body.data.getTestPlan.tests.results}} 
<p>
<strong>Test: </strong>{{jira.summary}} - {{jira.key}} 
<br>
<strong>Type: </strong> {{testType.name}} 
<br>
<strong>Status: </strong> <strong style="color:{{status.color}}">{{status.name}}</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.
• {{webResponse.body.data.getTestPlan.jira.summary}} - That is replaced by the summary field of the Test Plan issue.
• {{webResponse.body.data.getTestPlan.jira.description}} - That is replaced by the description of the Test Plan issue.
• {{webResponse.body.data.getTestPlan.tests.total}} - That is replaced by the total number of tests present in the Test Plan issue in Jira.

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, test type name, status color, and status name of each Test in the Test Plan:

{{#webResponse.body.data.getTestPlan.tests.results}} 
<p>
<strong>Test: </strong>{{jira.summary}} - {{jira.key}} 
<br>
<strong>Type: </strong> {{testType.name}} 
<br>
<strong>Status: </strong> <strong style="color:{{status.color}}">{{status.name}}</strong>
</p>
{{/}}

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 to test your rule while you are 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

• Jira Automation Documentation
• Jira Automation smart values
• Xray GraphQL
• Xray GraphQL getTestPlan schema