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.

The topic provides creating custom metadata records for custom fields for Jira Issue to PSA Project Task and vice-versa mode. The created custom metadata supports mapping for PSA Project Task to Jira Issue workflow and vice-versa and PSA Project to Jira Issue mode workflow.

Notes:
  • 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.
  • 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, is of array type. That is, they can contain multiple values. In Certinia Help, there is the capability to handle this using the arrayFirst and arrayAll operators. These are part of Certinia Help and not the mapping system, so they are unavailable elsewhere. Only arrayFirst is currently implemented. arrayFirst takes the first element of the array and uses that to map from.

  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 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 MultiPicklist.
  8. Next to Owning Type. For example, enter fields.
  9. Next to Jira Datatype. For example, enter customfield_10909.arrayFirst when the field type is MultiPicklist.
    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.
  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, enter customfield_10909.arrayFirst.
    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:

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