Create a MS Teams template

MS teams template is currently available only for the ARNR Cloud app.

Navigate to the Templates tab >> click on Create button.

Select the MS Teams template

This launches the the template builder/editor page where you can customize the template.

MS Teams template fields

Template type
- Here, MS Teams option is selected since we are creating an MS Teams type of template
Template name
- This is for internal reference & doesn’t show up in the actual release notes in MS Teams.
Level
- Local or Global - Determines whether the MS Teams template is available to be used in other projects across Jira.
- Cross-project - For cross-project templates (which can be managed only from the cross-project ARNR screen), this field is disabled from editing & is set to cross-project by default.
ARNR branding - To define whether you wish to show ARNR branding in release notes.
- For Free ARNR app it is default and cannot be unchecked

Customise the MS Teams template

MS Teams uses adaptive card blocks to build messages with text, images, buttons, and more. We have provided the same structure here. You can customize the order and appearance of each block, including elements within them. Below are some blocks that are supported to design MS Teams template in ARNR.

Reach out to our Service desk if you want us to add support for any specific block in the MS Teams template.

Ms teams template builder allows you to customize the template using different blocks like Header, Texbox, and JQL. You can use variables and custom variables in these blocks to fetch different data points from Jira issues. Let us see more details about these blocks -

Header

Add image - You can add a thumbnail image in the header of the release notes message
Image URL - Paste the URL of the image
Header text - Add the header text, this is typically the project name, heading of the announcement, etc.
Description - Description of the header

In the Header and Description text, you can use ARNR’s variables and custom variables.

Textbox

In the block, users can insert plain text along with ARN variables and custom variables.

JQL Section

JQL section

JQL section in different ARNR templates

Introduction

The JQL functionality in MS Teams template operates uniquely compared to other templates such as Email,HTML, etc.

Below, we elaborate on the process of incorporating a JQL section for creating release notes and reports in MS Teams template.

The JQL section in MS Teams template has three tabs -

Section
Fields
Layout

Section

In the section tab you will find below fields to define the content that will be posted in the release notes.

Title - This text will be shown as a section header of the Jira issue list fetched using the given JQL section.
Description - This fields can contain the description of your given JQL section.
JQL - This field is where you add the JQL to fetch the relevant issues to your release notes
Hide section (checkbox) - Check if you wish to hide the JQL section when given JQL does not return any Jira issues
- Message - When the checkbox is unchecked, write a message that needs to be displayed when no issues are returned from the given JQL.

Fields

This tab is to display what all Jira issue fields/custom fields that are to be added to your release notes and reports. These fields be added as columns if you are using a table layout or selected fields will be listed in the sequence you have designed in the layout tab when sequential layout is selected.

As shown in the below image, ⚙️ icon in front of each selected field would show some extra settings -

Display as text -
- If checked, value will be displayed as text
- In case of Description field, if this setting is checked, the value of this field will be displayed as text ignoring any media files and links in the content fetched from the Jira issue content.

Currently, MS Teams template does not support images from the Jira issue content.

Hide field label variable when the field value is empty -
- When checked, if the field value is empty, the field label variable shall also be kept empty in the sequential layout.

Layout

Table layout

This layout is fairly straightforward & does not need any additional configurations. All the fields that are selected in Feilds tab (as shown in the above image), will be displayed as table columns from left to right.

Sequestial layout

Selecting equential layout presents the selected fields (from the Fields tab) in a sequenced format. The desired layout needs to be designed within the area highlighted below.

In above image, the design is simply a sequence of Key, Priority, and Status fields from Jira issues, . These fields are displayed based on what fields you have chosen on the Fields tab.

Any fields that you have selected to be used, can be arranged in any order you wish. For every field that is configured under Fields tab on the left, there will be two variables on the right. One that will fetch the field value & other to fetch its display label. e.g. for the Priority field, there are two variables - {priority} & {priorityLabel}.

Required condition is, you have to add fields & their configurations before they can be used in the Layout section. The layout created will be repeated for every issue that is returned by your section JQL. For example, layout in the above screenshot will generate data that looks like the below screenshot.

Variables

These are the data points used to bring the values from Jira to your release notes content. The variables will be replaced by actual values for given data points. Some examples are projectName, fixVersion, userName, etc.

When you use such variables, upon execution of the template, variables are replaced with actual values.

List of supported output variables

Variables (Users)	Syntax
userName userEmail versionDriver versionApprovers	[userName] [userEmail] [versionDriver] [versionApprovers]
Variables (Project)	Syntax
projectName projectld projectKey	[projectName] [projectld] [projectKey]
variables (Version)	Syntax
version Name versionDesc release Date versionld versionURL startDate	[version Name] [versionDesc] [release Date] [versionld] [versionURL] [startDate]
Variables (Sprint)	Syntax
sprintName sprintId sprintGoal sprintStartdate sprintEnddate sprintCompletedate sprintState	[sprintName] [sprintId] [sprintGoal] [sprintStartdate] [sprintEnddate] [sprintCompletedate] [sprintState]
Variables (Date & Time)	Syntax
timestamp currentDate currentDatetime	timestamp currentDate currentDatetime
Variables (Confluence)	Syntax
confluenceURL confluencePageId	[confluenceURL] [confluencePageId] This variable works similarly to the Confluence URL variable. For example - There are two actions in the rule. First action has to be Confluence action, second action could be any template action like Email, PDF, etc. that has the [ConfluencePageId] variable. When the first action is executed, its page ID is parsed in the second action and the id variable is replaced with the page ID created from the first action
releasePageURL (only available in Release page notification* and LinkedIn announcement template type)*	[releasePageURL]

Custom variables

Apart from the default variables that are typically the default fields, users may want to create custom fields and fetch that data to release notes. In such a case one can map the ARN custom variables with their Jira fields and bring the values of those fields to release notes.

All the custom variables created in ARN are global. It means, that irrespective of the projects they are created from, all non-deleted custom variables will be visible across all the projects.

In below image, notice the way ARN custom variable is used.

When executing the template, this is how the preview will asks for the value of the custom fields.

This just one simple use case, Read how to Manage & use ARN custom variables with more examples.

Preview MS Teams template

Once done with all the editing, you can preview the template to make sure everything is in place and Release notes are accuratly created before sending them to the end user.

Clicking on Preview, brings you to the preview page. Choose inputs based on variables, custom variables used JQL/s or template body & click Preview. This will generate the template preview.

Click on Copy to Clipboard and paste the code into MS teams adaptive card builder to see the exact preview of your template in MS Teams.

In MS teams adaptive card builder click on +CARD PAYLOAD EDITOR at the bottom of the screen and paste the code copied from preview screen.

Verify the release note content and make necessary changes if needed. Once the template is all set it's time to set Rules and Actions. Rules are the same as it is for any other template. In case of the action read https://amoeboids.atlassian.net/wiki/spaces/ARN/pages/edit-v2/304807972#Send-to-MS-teams for more details.

In below image -

1 - Containt coming Header block
2 - Content coming from Text box block
3 - Content fetched based on JQL section’s configurations with a tabular layout.

On this page