Skip to main content
System StatusContact Support Agility Community

Step 2—Create the Field Mapping


Field mapping is not restricted to fields of the same type. You can map fields of different types too.

  • The Field Mapping page lets you map the fields of the assets (Stories, Epics, etc.) from the two applications that are being integrated. 
  • There are two drop-down lists, one each to the left and right-hand sides of the forward/backward mapping arrows. 
  • When a field is forward-mapped (clipboard_ee88c3097e3cec411e5a88a0cc57d0094.png), any changes to the field on the left are synced with the field on the right.
  • When a field is backward-mapped (clipboard_e3b0990920c2fe8ecbd1ceb6014b7e075.png), any changes to the field on the right are synced with the field on the left.
  • Selecting both the arrows syncs the fields bi-directionally.
  • You can map as many fields as you want. Just add a new field mapping row (Add Field button), select the fields to map, and select the mapping direction.

Date fields, if mapped, must comply with the following format: YYYY-MM-DD.


You can either choose to automatically map the fields or you can do it manually.

Auto Map

The fields that are auto-mapped are predefined in Agility Connect for each asset type.

Auto-mapping of fields is not defined for TeamForge/Azure asset types and so you cannot automatically map TeamForge/Azure fields with other tools.


  • Click Auto Map to create a bidirectional automatic mapping of the default mandatory fields as defined in Agility Connect.
  • Once the fields are auto-mapped, you can manually map more fields (click Add Field), if required.
  • Auto-mapping of fields is only available when you create field mappings. It is not available when you edit a mapping.

Here's an example of the auto-mapped fields of Agility and Jira.


Field Value Mapping

You can create a value-level mapping of certain field types such as the Single-Select Drop-down. For example, the Status field has three values that are mapped as shown in the following illustration.

  1. Click Show Mapping/Hide Mapping toggle link. 
  2. Click Add Value
  3. Select the values from the drop-down lists to map the values of the two applications.
  4. Select the mapping directions using the map arrows. 
  5. Repeat steps 2 through 4 to map more values. 
  6. You can also select one of the values as the default value. Select the option button from the Default column. 


  1. You can also set default values for text-type fields. After mapping text-type fields, click the Default Value link and type the default value for the text field. 


8. You can also configure Conflict Resolution settings for field values. 

Value Mapping Settings

You may or may not have mapped all of the values in single-select drop-down lists. In such cases, the sync operation may fail as Agility Connect cannot figure out what to do when a single-select drop-down field is updated with an unmapped value. You can use the Value Mapping Settings to resolve such conflict situations arising out of unmapped values.

Here's an illustration that shows the field value mapping for the Priority field—Medium being the default value. As you can see, the Default Value option has been selected for both Jira and Agility under Value Mapping Settings, which means that you are instructing Agility Connect to go with the default value, which is Medium, whenever an unmapped value is passed along for syncing.



You can also select the other options:

  • Skip Data Sync—Agility Connect skips syncing the single-select drop-down field when updated with an unmapped value and proceeds with the data sync.
  • None—Agility Connect throws an error for any incoming unmapped value. 

Mapping Agility Team's Storyboard Statuses

In addition to workitem statuses, Agility Team's Storyboard statuses are also available for mapping.


Mapping Iteration/Sprints

When you create a mapping, you can map the Iteration and Sprint fields of Agility and Jira respectively, to have these fields synced when you create or update a workitem in Agility or Jira. 


Filter Fields by Type

You can filter the fields by type (Mandatory, Read-Only, and Optional) to have just the fields you want to map readily available from the drop-down lists.


  • You can hover over a field to view its type—for example, Text, Number, Date, Single-Select drop-down, etc.
  • Field names in the drop-down list are prefixed with a color-coded dot.


The legends at the top right (click Legend) can assist you in identifying the different types of fields you select from the drop-down lists.


For example,

  • Mandatory fields are marked with a red dot.
  • Optional fields are marked with a blue dot. 
  • Read-only fields are marked with a grey dot

Tags recommended by the template: article:topic