Skip to main content

Configure field mapping for issue tracking integrations

  • Updated

Who can use this feature?

  • Organization administrators, workspace administrators, and workspace users.
  • Available for the Accelerate and Enterprise packages. Also, for the Essential package with the Integrations add-on.

On this page: 

About field mapping

Field mapping is a process of matching the platform fields to those in an issue tracking software. This facilitates seamless data integration and consistency across the systems. 

  • If you have required fields other than Summary and Description in your issue tracking integration instance, you’ll need to configure them on the platform first. Once they’re configured, you can push tasks to your issue tracking software. Enterprise customers can configure optional fields that the platform supports. For example, Severity. The optional fields vary depending on the configuration of your issue tracking integration project and issue type. Note that the platform doesn't support all issue tracking software fields. For example, JSON items.

  • Fields can contain static values or retrieve values dynamically. Some fields, also known as required fields, must contain either a static or dynamic value.  Otherwise, you cannot save the configuration and will see an error message.

    Note: Only Enterprise customers can configure optional fields. You must configure all the required fields. Required fields are marked with an asterisk and optional fields are not.

Static field mapping

You can define a static value for platform fields. Define the value by typing it. Refer to Configure field mapping (static and dynamic values).

For example, type in a label that represents the field. The label is mapped and shown for that field in the integrated issue tracking software.

Dynamic field mapping

Dynamic field mapping improves how accessibility tasks are pushed to issue tracking tools like Jira, Azure DevOps, and Asana. Based on your configuration, key accessibility details (task details)—such as severity, WCAG success criteria, and identifiers—are automatically populated into dedicated fields when tickets are created. 

Important! Currently, dynamic mapping behavior is supported and validated for tasks originating from scans and monitors findings. However, tasks created from manual findings and design evaluation findings cannot be dynamically mapped, because manual findings data is stored in a different collection and contains a different set of fields.

Benefits of dynamic mapping are:

  • Tickets arrive ready to use, reducing manual cleanup.
  • Teams can filter, query, and triage using existing workflows.
  • Downstream automations and dashboards can rely on accurate accessibility data.
  • The ticket description still includes full task context.

Dynamic mapping is available only for the supported fields. Hover over a disabled toggle to learn why mapping is unavailable.

  • Required fields: Must be populated with either a static value or dynamic mapping. Otherwise, you cannot save the configuration and will see an error message.
  • Optional fields: Can remain unmapped, and you can still save the configuration.

For more information on projects, tasks, and issue tracking integrations, go to Project management. 

Fields that support dynamic mapping 

This section lists the two types of supported fields, issue tracker fields, and platform Task fields.

Field types in your issue tracking integration (Asana, Azure DevOps, JIRA)

  •  Jira Cloud: Short text, Paragraph

  • Jira Data Center: Text (single line), Text (multi-line)

  • Azure DevOps: Text (single line), Text (multiple lines)

  • Asana: Text

Platform Task fields:   

  • Task name

  • Severity

  • WCAG success criteria

  • Priority

  • Rule ID / Rule name

  • Description

  • What is the problem

  • Why it matters

  • What to do

  • Code snippet / HTML element

  • XPath / CSS selector

Configure field mapping (static and dynamic values)

To configure field mapping for an integration: 

  1. Connect a project to Jira, Azure DevOps, or Asana. For details, go to the corresponding topics:  Connect a Jira instance, Connect an Azure DevOps instance, or Connect an Asana instance to a project. 

  2. Select the Projects & Tasks tab. 

  3. Select a project. 

  4. From the three-dot action menu, select Configure Fields.

  5. Select an Issue Type, for example Task.

  6. Select Retrieve all fields. The fields are retrieved, and the field mapping table is displayed. It includes the Elements column and Dynamic mapping column. By default, all dynamic mapping toggles are switched off.

  7. Define static field values. In the Element column, enter default options for each field you want to configure.  

  8. Define dynamic fields. For each field that you want to map dynamically:

    1.  Turn on the Dynamic mapping toggle.  

    2. Select the corresponding platform Field value. The mapping can be established only if the platform fields are compatible with the integration field data type.  

  9. Select Save. The mapping is applied at runtime, when tasks are pushed.

When tasks are pushed to the issue tracking system:

  • Fields configured with dynamic mappings are populated with the corresponding task values. 

  • Fields configured with static values remain unchanged.  

  • If a required dynamic field resolves to a null task value, the platform inserts N/A, to ensure that the ticket creation succeeds. For example, this might occur when certain task data is not present. 

  • The ticket description remains unchanged. It continues to include full task context, regardless of whether you've configured dynamic mapping or not.

Related articles

Comments

0 comments

Article is closed for comments.