How to create, map and configure fields in a work item/task template

When a user is creating tasks from issues identified in the Siteimprove platform, they will be presented with a modal containing fields and options. Siteimprove provides a template to determine what fields and options are presented to the user. This article discusses how to create and configure the task/work item template.

Note: For the purpose of this article we have used screenshots for mapping an Azure DevOps work item but the configuration is similar for Jira connection fields.

More information on creating tasks/work items is available in the articles How to create Jiras from within the Siteimprove platform and "How to create Azure DevOps work items from within the Siteimprove platform".

Example of work item form

Creating new templates

You need to create new templates for each work item, task, or project that is to be available for users to create tasks or work items.

Typically this will be done after the connection is configured to make tasks/work items available for use in the Siteimprove platform. New templates can be set up and configured at a later date as required. To create a template follow these steps:

1. Go to Integrations > Task Management > Connections.
2. Select the tab of your task management system (Jira connections or Azure DevOps organizations).
3. Click on "View details"  (For Jira connections you also click on the Field Setups tab)
   
   
4. Select “+ Add field setup” (Azure DevOps)or “+ Add work item template” (Jira connections)
5. Adding JIRA field setup
   a) Select the user - This is the user that was used to set up the task management connection.
   b) Select the Project – The projects available are those that the connection user has read/write access to.
   c) Select the Field Setup – This is the task type. For example, bug, epic, story, sub-task, task, or a custom task type available under the project.
   Adding Azure DevOps work item template a) Select Project - The projects available are those that the connection user has read/write access to.
   b) Select Work item template – This is the task type. For example, bug, epic, story, sub-task, task, or a custom task type available under the project.
6. Select the “Continue” button.
7. See details on configuring fields in the template below.

Editing Work Item/Task templates

You have the option to configure fields when creating a new template. You can also edit the configuration afterward if required:

1. Go to Integrations > Task Management > Connections.
2. Select the tab of your task management system. (Jira connections or Azure DevOps organizations).
3. Click on "View details"  (For Jira connections, click on the Field Setup tab) 
4. Use the edit icon. 

Configuring fields in the template

When configuring the task template, you have the possibility to map fields. This means you can customize the template if required. In this article, we explain the options available to map fields in the template.

Note: Related information is available in "Siteimprove’s Azure DevOps connector" and "Siteimprove’s Jira Connector".

Field Types

Unsupported fields

Unsupported fields will not be displayed in the modal in the Siteimprove platform if nothing is done, but if there are unsupported fields in your template (denoted by the info “i” in a circle icon), you have the following options: 

• Hide unsupported optional fields
• Make any remaining unsupported fields “optional” in your task management tool and reimport the template

Visible and Hidden Fields

When configuring fields, you are presented with two tables:

• Visible fields - contains the fields that will be displayed in the modal when the user creates a new work item/task.
• Hidden Fields - contains the fields that will not be shown in the modal when creating a work item/task. This may be because they are either not required or incompatible.

Required Fields

These fields are denoted by an asterisk (*) and are required by the task management system and cannot be hidden.

Note: Please check your task management project to see what fields are required and make sure that they are included in the template as the required status may not translate from the task management software here.

Visible fields table

Ordering fields

You can drag and drop the order of the fields in the Visible field area. This order is the order they will appear in the modal users are presented with when creating work items/tasks in the Siteimprove platform.

Mapping/Configuring fields

Here we focus on the mapping and configuration of the Visible fields table.

The Action column on the Visible fields table includes two buttons, one for hiding a field, and one for editing the mapping for that field.

When you click on the "Edit field" button, you are presented with a pop-up component containing information about the field: i.e. Field name, Field type, and Value type.

The Value type section contains a dropdown, where you can change the type of mapping used. That is, you can change the type of value that will be inserted in the field when the user creates a new work item.

The dropdown has three options for Value type:

Value type - No value

The field will use the default value. The default value can be a number, a string, or the current date. This is dependent on the field being edited.

Value type - Fixed

This option allows you to define a fixed value to be used each time a task is created. The value will remain the same unless re-edited.

When you chose Fixed in the Value type dropdown, you can write (or select) a value to be used each time the user opens the create work item modal.  The option to either write or select a value is dependent on the type of field.

Value type - Dynamic

This option means you choose from a list of values predefined by Siteimprove. The values will be used to generate the content for the field based on a user's location within the Siteimprove platform when creating the work item.

The dynamic values available are:

• Module - represents the name of the module being used when the work item is created (e.g. Policy, Accessibility)
• Issue type - represents the name of the issue in the platform (e.g. Policy match, Accessibility issue)
• Title - represents the generated title (e.g. for Policy, it can be Policy broken links)
• Issue description - represents the description for the work item, and it can be composed of a link to where the issue can be viewed in the platform, the number of occurrences, etc.
• Count - represents the number of issue or matches, depending on the location in the platform
• Detection date - represents the date when the issue or the match was detected
• Issue details URL - represents a link to a detailed view of the issue or policy in the platform (e.g. It could be the Page report link for Policy)
• Issue source URL - direct link to the source of the issue
• Issue source name -  the name of the issue (e.g. for a policy called broken links in the Policy module, the source name will be broken links)

Learn more

More information on creating tasks/work items is available in the articles How to create Jiras from within the Siteimprove platform and "How to create Azure DevOps work items from within the Siteimprove platform".

Siteimprove is happy to help with questions regarding configuring the integration. Siteimprove does not provide support or product help for the third-party software with which you are connecting.