3.5 Custom Issue Templates

We recommend that a developer with JavaScript experience create the custom issue template.

When creating an issue, the RTC Git Connector plugin takes various work item attributes and uses them to set equivalent fields on the new issue.

Here is a list of the mappings that are performed when creating a new issue:

Work Item Attribute	Git Issue Equivalent
Summary	Title
Description	Body/Description
Tags	Labels

Additionally, the label from-rtc-work-item is added to the new issue.

Most other work item attributes don't have a directly equivalent field. To solve this, they are instead added to the description and formatted with Markdown. A template is used to decide which attributes are used and how they will be formatted.

An issue created using the default template will look something like this:

When created from a work item that looks like this:

We can see that the description and acceptance criteria were taken over including formatting. The rich text editor in RTC uses HTML to format text. For a nicer display and easier editing, we convert the HTML formatting into Markdown. That way the formatting isn't lost and it even looks the same as the original.

A few other attributes are added to a table displaying their name and value. In this case, we have Owned By, Filed Against, Planned For, and Tags.

Here is the default template:

### Description

{{#if attributes.description.content}}
{{{turndown attributes.description.content}}}
{{else}}
Please add a description
{{/if}}

{{#if attributes.[com.ibm.team.apt.attribute.acceptance]}}
### Acceptance Criteria

{{#if attributes.[com.ibm.team.apt.attribute.acceptance].content}}
{{{turndown attributes.[com.ibm.team.apt.attribute.acceptance].content}}}
{{else}}
Please add some acceptance criteria
{{/if}}

{{/if}}
### Other Attributes

| Attributes | Values |
| --- | --- |
| Owned By | [{{{attributes.owner.name}}}](mailto:{{{attributes.owner.emailAddress}}}) |
| Filed Against | {{{attributes.category.label}}} |
| Planned For | {{{attributes.target.label}}} |
{{#if attributes.internalTags.content}}
| Tags | {{{attributes.internalTags.content}}} |
{{/if}}

If you would like to customize how new issues created by the plugin will look, you can create your own custom template. One way to start is by copying the template above and customizing it how you like. Alternatively, you can create one from scratch.

In order for the plugin to know that it should use a custom template, you need to place it in a specific location. If you're using GitLab, place it in your default branch under the path .gitlab/issue_templates/rtc-work-item-v1.md. For GitHub repositories the path is .github/ISSUE_TEMPLATE/rtc-work-item-v1.md. It's important that the file is named rtc-work-item-v1.md otherwise, it won't be used. If the plugin finds a file with this name in this location it will use it instead of the default template for creating the issue.

The template uses normal Markdown for formatting and Handlebars.js for logic. Using Handlebars syntax you have access to all work item attributes making the template very configurable. To access the value of a work item attribute you need to know what it's called (in JavaScript). The plugin provides a dump of the work item object that you can use to see the names of the attributes.

Simply navigate to the "Create a new issue" item and click on it to view its details. In the details, you should see a button with the text "Copy work item details to clipboard".

Click the button and then paste (CTRL + V) the result into a text editor (like Notepad++). You should now see a JSON representation of the work item attributes. This object might be very large so you may wish to use CTRL + F to find the attributes that you are looking for.

Here are some important tips to pay attention to when creating your custom issue template:

• Use triple brackets when outputting attributes that contain HTML content. Otherwise, the HTML will be encoded and not used for formatting.
• Use the flag turndown to convert HTML to Markdown. Just place the string "turndown" in the brackets before the attribute. This uses the turndown package internally.
• Pay close attention to the Handlebars.js syntax for attributes that contain dots in the name. For example to get the acceptance criteria in JavaScript: attributes["com.ibm.team.apt.attribute.acceptance"].content and in Handlebars.js: attributes.[com.ibm.team.apt.attribute.acceptance].content. Note the added preceding dot and the lack of the double quotes.
• All of the helpers in the just-handlebars-helpers package are available to be used in custom issue templates.

Once you have successfully created and saved a custom issue template in the correct location with the correct file name, the RTC Git Connector plugin will always use that template when creating issues in that Git repository.

If you find the instructions to be unclear or are having problems creating your own issue template, please contact us and we will do what we can to help out.