Creating Custom Metadata Records to Support Different Jira Custom Fields

Every Jira instance is unique with custom Issue Types, Worklogs, and Fields. Most users want some custom Jira fields to be mapped to custom fields on their Project Tasks in PSA. Jira only supports custom fields on Issues and not on Projects or Worklogs.

These topic explains how to create custom metadata records for Jira Issue to PSA Project Task and vice-versa. The created custom metadata supports mapping of two-way PSA Project Task to Jira Issue workflow and PSA Project to Jira Issue mode workflow.

Notes:
  • [Optional By default, Certinia Help contains Epic Link, Epic Name, and Parent Link with the package that needs to be customized based on the Jira custom fields.
  • [Optional] Before creating new custom metadata records, ensure that you have created Jira custom fields for the different types in Jira. For more information on creating custom fields in Jira, see the Atlassian documentation.
  • The supported field types include String, MultiPicklist, Email, Picklist, TextArea, and URL.

Once you have created a custom field in Jira, we recommend creating custom metadata records to define objects for custom fields in Jira.

Example 1 - For Scalar Custom Field

A Scalar field in Jira is a text, date, or number entry. But not a dropdown or picklist, even if the values on that picklist are text, date, or numbers.

Note: To work, the custom field type must be a Date Picker, Date Time Picker, Number Field, Text Field (multi-line or single-line), or URL Field. Other field types configured in this way will result in JSON being written into the field, depending on the PSA field type.

We assume that a custom text field in Jira with the label My Text Field and key customfield_10202 is set up. To enable this for mapping, we need to configure Certinia Help to know that this field exists.

  1. In Setup, click Custom Code | Custom Metadata Types.
  2. Next to PSA to Jira Issue Field, click Manage Records. A list of existing mappings is displayed.
  3. Click New. The new custom record page displays to create a custom field.
  4. In the Label field, enter Fields - My Text Field.
  5. Once you move to the next field, the PSA to Jira Issue Field Name automatically populates.
  6. In the Jira Field ID field, enter customfield_10202.
  7. In the Jira Field Name field, enter My Text Field.
  8. Next to Owning Type, enter fields.
  9. Next to Jira Datatype, enter string.
  10. Select the Is Available for Mapping checkbox to make this custom Jira field available for mapping.
  11. Select the Override Field Mapping checkbox to allow users to override the mapping for this field. By default, it is selected.
  12. Click Save. The new custom metadata record mapping field is now created.

The following image displays the metadata record.

Example 2 - For Non-Scalar Custom Field

A scalar field is like a summary represented as a value. But a picklist field in Jira is represented as an object. The value that we actually want to map is the value inside the object.

The first record is very similar to the scalar case in setting up a field within fields. The key difference is the datatype, which is set to the same as the Jira Field ID by convention. As this is not a recognized scalar datatype Certinia Help will treat this as a custom object type.

The following image displays the parent metadata record.

  1. In Setup, click Custom Code | Custom Metadata Types.
  2. Next to PSA to Jira Issue Field, click Manage Records. A list of existing mappings is displayed.
  3. Click New. The new custom record page displays to create a custom field.
  4. In the Label field, enter fields-Linked PSA Project.
  5. Once you move to the next field, the PSA to Jira Issue Field Name automatically populates.
  6. In the Jira Field ID field, enter customfield_10201.
  7. In the Jira Field Name field, enter Linked PSA Project.
  8. Next to Owning Type, enter fields.
  9. Next to Jira Datatype, enter customfield_10201.
  10. Select the Is Available for Mapping checkbox to make this custom Jira field available for mapping.
  11. Select the Override Field Mapping checkbox to allow users to override the mapping for this field. By default, it is selected.
  12. Click Save. The new custom metadata record mapping field is now created.

The following image displays the parent metadata record.

The image displayed the child metadata record.

Now create a new custom record for a field that sets up the value within this custom object type. This is again similar to the scalar setup, but the owning type is set to customfield_10201, indicating that this field is in the custom object.

Note: You can set up any depth of objects required to match the Jira hierarchy and any number of children within the custom objects.
  1. In the Label field, enter Linked PSA Project-Value.
  2. Once you move to the next field, the PSA to Jira Issue Field Name automatically populates.
  3. In the Jira Field ID field, enter Value.
  4. In the Jira Field Name field, enter Value.
  5. Next to Owning Type, enter customfield_10201.
  6. Next to Jira Datatype, enter string.
  7. Select the Is Available for Mapping checkbox to make this custom Jira field available for mapping.
  8. Select the Override Field Mapping checkbox to allow users to override the mapping for this field. By default, it is selected.
  9. Click Save. The new custom metadata record mapping field is now created. You can now use the custom metadata records for mapping.

Example 3 - For Array Types Custom Field

Some fields like the built-in Components field, are of array type, meaning they can contain multiple values. In Certinia Help, there is the capability to handle this using the arrayFirst and arrayAll operators. The arrayFirst takes the first element of the array and uses that to map from. The arrayAll takes all the elements of the array and uses them to map.

  1. In Setup, click Custom Code | Custom Metadata Types.
  2. Next to PSA to Jira Issue Field, click Manage Records. A list of existing mappings is displayed.
  3. Click New. The new custom record page displays to create a custom field.
  4. In the Label field, enter Multipick or any value when the field type is MultiPicklist.
  5. Once you move to the next field, the PSA to Jira Issue Field Name automatically populates.
  6. In the Jira Field ID field, enter customfield_10909.
  7. In the Jira Field Name field, enter the value.
  8. Next to Owning Type. For example, enter fields.
  9. Next to Jira Datatype enter the datatype based on the arrayFirst and arrayAll operators when the field type is MultiPicklist.
    1. If you want to use arrayFirst, enter customfield_10909.arrayFirst.
    2. Or, if you want to use arrayAll, enter customfield_10400.arrayAll.
    Note: This Jira Datatype must be the same as Jira Field ID. If it fails to match, then PSA to Jira synchronization or vice-versa would not work for complex fields from Jira, such as drop-downs. The complex ArrayAll fields only work from Jira to PSA.
  10. Select the Is Available for Mapping checkbox to make the field available for mapping.
  11. Select the Override Field Mapping checkbox to allow users to override the mapping for this field. By default, it is selected.
  12. Click Save. The new custom metadata record mapping field is now created.
  13. Create a new custom record for a field that contains custom values such as drop-downs.
    1. In the Label field. For example, enter Multipick_value when the field type is MultiPicklist.
    2. Once you move to the next field, the PSA to Jira Issue Field Name automatically populates.
    3. In the Jira Field ID field, enter value.
    4. In the Jira Field Name field, enter value.
    5. In the Owning Type field
      1. If the parent was arrayFirst, enter customfield_10909.arrayFirst.
      2. Or, if the parent was arrayAll, enter customfield_10400.arrayAll.
    6. In the Jira Datatype field. For example, enter string.
    7. Select the Is Available for Mapping checkbox to make the field available for mapping.
    8. Select the Override Field Mapping checkbox to allow users to override the mapping for this field. By default, it is selected.
  14. Click Save. The new custom metadata record mapping is now created.

The following images display the Array Types Custom Field metadata record.

Note:

  • The ArrayAll do not support Data Transformation Table but ArrayFirst support the Data Transformation Table.

  • After creating custom metadata records, check whether you want to map the values to the existing field or create a new field for mapping. For more information, see Creating a New Mapping.
  • To support the complex differences between field values in PSA and Jira or vice-versa, the connector transforms the values from one application before syncing them with the other. If the field values differ, you must create a data transformation table.

Example: Here is an example list of mappings for complex field values

Jira to PSA

Jira Issue - Industry Value PSA Project Task - Industry Value
Primary First
Secondary Second
Tertiary Third

PSA to Jira

PSA Project Task - Industry Value Jira Issue - Industry Value
First Primary
Second Secondary
Third Tertiary

For more information, see Creating a Data Transformation Table.

Note that PSA to Jira or vice-versa values will differ between different projects, depending on the values defined. The connector comes with a predefined set of mappings. We recommend customizing the predefined mappings to avoid errors when syncing from one system to another. To create a new mapping from Jira to PSA or vice-versa, see Creating a New Mapping.

For more information on the predefined mappings, see Customizing PSA Direct for Jira Field Mappings.

Depending on how you set up the Certinia Help, your PSA projects might be synchronized to Jira projects or vice-versa. When creating a Jira Issue, manually add the Jira custom field to Jira project and Jira project screens. Select the Jira custom field value, depending on the type of custom field you want to create. For example, select "primary."

The connector automatically creates a PSA project task for the Jira issue or vice-versa. Once the synchronization finishes, the Jira custom field populates with the value of the issue in Jira. For more information, see Synchronizing PSA Information to Jira .