3.5 Custom Issue Templates

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.

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