Mapping Configuration

Map the fields between Jira and the other system to be integrated to ensure that the data between both the systems synchronizes correctly.

Criteria Configuration

Click Mapping Configuration to learn the step-by-step process to configure mapping between the systems.


Pre-requisite for mapping a field

While mapping a field in Jira, make sure that it is part of both Create and Update screen of all the projects for which this field will be synchronized.

Also it is imperative to map only those fields (both system and custom) that are visible on the screen at the time of creating/editing an issue on Jira UI. This is to avoid erroneous situation later when the integration starts You can ignore the above precaution for ‘Status’ field as it will be accessible by default to the integration user.

If you want to synchronize the Epic Link or Issue in Epic links, then you need to add Epic Link to the create and update screen. For further details on how to add a field to screen refer Adding field to Screen. If you miss this step, you will not be able to see Epic Link and Issue in Epic as part of ‘Link Type’ in the ‘Relationship Configuration’.

Note: In any case you have changed the default name of Epic, the name of link type will change.
Note: Ignore the above precaution for ‘Status’ field as it will be accessible by default to the integration user.

For checking whether the field is accessible by the dedicated integration user, refer Field Helper.


SLA Metric fields mapping

SLA PowerBox is a plugin in Jira that provides the functionality to create SLA Metric fields. SLA Metric fields have different attributes. The SLA Metric Fields table describes the attributes of the SLA Metric fields that can be synchronized. Here in this table, ‘SLA Metric field’ refers to any SLA Metric type of field in Jira.

Sr. No.FieldField typeField Description
1SLA Metric fieldTextIt contains information regarding the raw value that is present in the Jira API response. This can be used to perform advance configuration on the raw SLA Metric field's data.
2SLA Metric field.RemainingTime UnitThis field will contain the 'remaining time'. The value of this field will depend on the state of an entity.
3SLA Metric field.Remaining percentage TextThis field will contain the 'remaining time in percentage' value.
4SLA Metric field.ExceededTime UnitThis field will contain the 'exceeded time'. The value of this field will depend on the state of an entity.
5SLA Metric field.Exceeded PercentageTextThis field will contain the 'exceeded time in percentage' value.
6SLA Metric field.SpentTime UnitThis field will contain the value of the 'time spent'.
7SLA Metric field.Deadline DateThis field will contain the 'deadline' of the entity based on the SLA Metric field configuration.
8SLA Metric field.StateTextThis field will contain information regarding the 'state' attribute of SLA Metric field.
9SLA Metric field.Goal TypeTextThis field will contain information regarding the 'goal type' attribute of SLA Metric field.


Limitations for SLA Metric field:
  • These fields are read-only fields in Jira.
  • There is no history available for these fields. The changes in the attributes of the fields can only be determined if an entry is added in the history of the entity.


Select List (Cascading) fields mapping

    Select List (Cascading) is a field type in Jira that allows users to select multiple values using two select list. This field is supported in OpsHub Integration Manager with advance mapping.

    Advance mapping can be done by following the steps given below:

  • Edit the field mapping for which you need to map such fields.
  • Expand the pop-up by clicking the arrow icon.
  • Click particular field mapping to change the default behavior of a particular field mapping.
  • Place advance mapping in this field (There are some examples given below. Use them as per your needs).
  • Save.
  • This field will be considered as an array of String that holds the primary and child values in ordered position where index 0 will hold the primary value and index 1 will hold the child value.

    Given below is an example for hierarchy (cascade) field to hierarchy (cascade) field mapping: In this example ‘TargetField’ is a hierarchy (cascade) field in the target system that accepts array of String. ‘SourceField’ is a hierarchy (cascade) field of source system that accepts array of String.

    <TargetField xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
      	<xsl:for-each select="SourceXML/updatedFields/Property/SourceField/string">
    		<fieldvalue>
    			<xsl:value-of select="text()"/>
    		</fieldvalue>
      	</xsl:for-each>
     </TargetField>
    

    Given below is an example for hierarchy (cascade) field to text field mapping: In this example ‘TargetField’ is a text field of the target system that accepts String. ‘SourceField’ is a hierarchy (cascade) field of the source system that accepts array of String. Multiple source values will be concatenated using ‘-‘ separator on the target side. You can change the separator as per your needs.

     <TargetField xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
      	<xsl:for-each select="SourceXML/updatedFields/Property/SourceField/string">
    		<xsl:choose>
    			<xsl:when test="position() = 1">
    				<xsl:value-of select="text()"/>
    			</xsl:when>
    			<xsl:otherwise>
    				<xsl:value-of select="concat('-',text())"/>
    			</xsl:otherwise>
    		</xsl:choose>
      	</xsl:for-each>
     </TargetField>
    

    Given below is an example for text field to hierarchy (cascade) field mapping: In this example ‘TargetField’ is a text field of the target system that accepts array of String. ‘SourceField’ is a String field of the source system that accepts String. Multiple source values will be split using ‘-‘ separator from the source side. You can change the separator as per your needs.

     <TargetField xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
     	<xsl:variable name="tokenizedLine" select="tokenize(SourceXML/updatedFields/Property/SourceField, '-')" />
     	<xsl:for-each select="$tokenizedLine">
     		<fieldvalue>
     			<xsl:value-of select="."/>
     		</fieldvalue>
     	</xsl:for-each>
     </TargetField> 
    


Inline attachments synchronization

For fields with Wiki Style Renderer enabled, Jira allows to add inline attachments that can be images or any other type of files. Such content can be synchronized for Jira with the following behavior:

  • For Jira fields, where inline attachments synchronization is being used, Detect Conflict should be kept OFF/Disabled in field mapping.
  • Below is the synchronization behavior:
    • When Jira is the source system

      Images and other type of files are synced to the target system depending on whether the target system supports inline images or not.

      If the target system supports inline images, all inline files, for example, images or other type of files, are added as attachments for the target entity.

      Inline image are directly visible and other type of files are visible as href link in the field content.

    • When Jira is the target system

By default, Jira field comes as a Text type field when generating mapping, even if it has Wiki Style Renderer enabled. So, to synchronize inline images/attachments to Jira from other systems and supporting inline images, an advance mapping is required.

Given below is a sample advance mapping for Jama to JIRA_Custom_Field(Any custom Text type of field in Jira) for synchronization with wiki formatting:

 <JIRA_Custom_Field>
      <xsl:value-of xmlns:xsl="http://www.w3.org/1999/XSL/Transform" select="utils:convertHTMLToWikiKeepImgTag(SourceXML/updatedFields/Property/JamaField)"> </xsl:value-of>  
 </JIRA_Custom_Field>

Above mapping will preserve another wiki formatting as well.


Known limitations:
  • Synchronization for inline attachment is supported for Jira except version < 5.0
  • Inline attachments for Comments are not supported currently
  • If same image is added in more than one field of Jira while creating an entity, it creates duplicate attachments in the target system (if targets system allows multiple attachments with the same name)
  • Such inline attachment synchronization is not supported for configurations when both – source and target – end points are Jira.
  • While synchronizing inline images from Jira to another system, images are visible with their actual size in target synchronized field content, irrespective of their size visible in Jira field content.
  • While synchronizing inline images from other systems to Jira, images are visible with their actual size in Jira synchronized field content, irrespective of their size visible in source field content.

Integration Configuration

Set a time to synchronize data between Jira and the other system to be integrated. Also, define parameters and conditions, if any, for integration.

Click Integration Configuration to learn the step-by-step process to configure integration between two systems.

Integration Configuration
Criteria Configuration

If you want to specify conditions for synchronizing an entity between Jira and the other system to be integrated, you can use the Criteria Configuration feature.

Go to Criteria Configuration section on Integration Configuration page to learn in detail about Criteria Configuration.

To configure criteria in Jira, integration needs to be created with Jira as the source system. Set Query as per Jira JQL Format. For Example, ‘Priority=”Must”.

  • To know more about JQL query in Jira refer this link: [JQL in Jira]
  • See the sample snippets below of how the JQL queries can be used as criteria in OpsHub Integration Manager
Sr. No.Field typeCriteria DescriptionCriteria snippet
1LookupSynchronize all entities which have certain value in LookupPriority = 'Critical'
2DateSynchronize all entities created after certain datecreated >= 2018-04-14
3TextSynchronize all entities which contains 'UI' in Summary fieldsummary ~ 'UI'
4UserSynchronize all entities which was created by user 'Robert'creator = 'Robert'
5User and LookupSynchronize all entities which was created by user 'Robert' and also has 'Priority' as 'Critical'creator = 'Robert' and Priority = 'Critical'
6Lookup or TextSynchronize all entities which has Priority as 'Critical' or has 'UI' as text in 'Summary' fieldPriority = 'Critical' or summary ~ 'UI'


Appendix

Field Helper
  • You can use the Field Helper to help you determine why a custom or a system field is not appearing on a specific screen.
  • You can log in with the dedicated integration user in Jira.
  • Now try to create an entity of the specific issuetype in the project for which the custom or system field is not appearing on a specific screen.
  • Then on the create issues page you can select Where is my field?.
  • Here you can type the field name for which integration user doesn’t have the access and the Field Helper will guide you through the steps to add the field.
Integration Configuration
Integration_Configuration
Integration limitations
  • Jira allows users to translate issue types or fields name through Jira UI or using external plugins. However, there are certain behavioral limitations with such translations, which are listed below :
    • History synchronization will not be maintained for the changes done prior to the last translation, for the translated fields/Link type.
  • Jira does not support these characters space (” “) + . , ; ? | * / % ^ $ # @ [ ] for project names and issue types.
Adding field to Screen

Follow these steps for adding a field to screen associated with a project

  • Select Project from the top navigation bar and then select ‘View All Projects’ Project.
  • View All Projects
  • Search and select the project for which the fields needs to be added in the screen.
  • Select File:JIRA project settings icon from the left navigation bar
  • Now select Screens from the sub-left navigation bar
  • Here you can see the screen association with the issue type for Create, Edit and View operations.
  • JIRA project
  • Select the screen for the issue type for which you want to add the field.
  • Now scroll down to the end of the screen configuration and then add the field as shown below:
  • JIRA project