--- title: "Jira Additional Mapping" canonical: "https://docs.perspectium.com/space/earlierReleases/1441954/Jira%20Additional%20Mapping" format: markdown --- For mapping over some of the values Perspectium may need some additional information for customizations. Much of this is already handled by the Update Set. However, depending on the level of customization you have you may have to do some tweaking. ## **Mapping over Custom Fields** For custom fields we will need the unique JIRA identifier for this custom field. We will primarily need this for the “ServiceNow Identifier” custom field. To determine this custom field identifier you can hit the following URL for your JIRA instance. (appending **/rest/api/2/field** to the URL). **https://example.atlassian.net/rest/api/2/field** This will output a JSON Array for all of your fields, out of box and custom. You can then send this entire output to Perspectium so we can map over the custom fields you request. You can also search up your custom column within this output as well. The output is not too readable as is but you can easily pass it into a JSON beautifier tool. Here is an example for the ServiceNow Identifier: ``` { "id": "customfield_11201", "key": "customfield_11201", "name": "ServiceNow Identifier", "custom": true, "orderable": true, "navigable": true, "searchable": true, "clauseNames": [ "cf[11201]", "ServiceNow Identifier" ], "schema": { "type": "string", "custom": "com.atlassian.jira.plugin.system.customfieldtypes:textfield", "customId": 11201 } }, ``` Once Perspectium knows that this is the custom column we can map over this data appropriately, assuming it is passed in through ServiceNow. Then on the Sharing side you will just create an Field Mapping towards this column name (not custom id) and populate it with some value. ## **Mapping over Priority** For priorities we will need the priority name and id values to map to, and how you would like to map ServiceNow priority → JIRA priority. This will require something similar to what we did for the /rest/api/2/field. To determine the priority values you can hit the following URL for your JIRA instance. (appending **/rest/api/2/priority** to the URL). [https://example.atlassian.net/rest/api/2/priority](https://example.atlassian.net/rest/api/2/priority) ``` [ { "self": "https:\/\/example.atlassian.net\/rest\/api\/2\/priority\/1", "statusColor": "#d04437", "description": "This problem will block progress.", "iconUrl": "https:\/\/example.atlassian.net\/images\/icons\/priorities\/highest.svg", "name": "Highest", "id": "1" }, { "self": "https:\/\/example.atlassian.net\/rest\/api\/2\/priority\/2", "statusColor": "#f15C75", "description": "Serious problem that could block progress.", "iconUrl": "https:\/\/example.atlassian.net\/images\/icons\/priorities\/high.svg", "name": "High", "id": "2" }, { "self": "https:\/\/example.atlassian.net\/rest\/api\/2\/priority\/3", "statusColor": "#f79232", "description": "Has the potential to affect progress.", "iconUrl": "https:\/\/example.atlassian.net\/images\/icons\/priorities\/medium.svg", "name": "Medium", "id": "3" } ] ``` This mapping is then controlled on the Perspectium side by using name or id to map through. Then on the ServiceNow side you will send out either the name or the id value to match up to. IE you would want to send 1, 2, or 3 if you are keying off of id or you would send Highest, High, Medium if you are keying off of name. ## **Mapping over Array Types (Components, Labels)** These can be mapped however under the current version there are a few caveats. These are: - These values must be pre-seeded/created in Jira, or the record transaction will fail. - IE if you want to send over the Label “enhancement” that Label must exist in Jira - These values are arrays in Jira, so you can have a list of them. However, currently we can only map to one entry. Please contact [support@perspectium.com](mailto:support@perspectium.com) for assistance in setting this up as it is not a default attribute. However it will primarily be modifying the table map to send in this column to the expected column in Jira. ### Example Mapping In this example I am mapping Contact Type's display value to the components. Then on the Jira side I would expect to see “self-service”, “email”, “phone”, etc under the components. ![image](media://cce82885-115e-4494-b4d1-063102846893) ## **Mapping over State Changes** These can be mapped over however they require a little different handling. In Jira states changes are handled via **transitions**. So they are not handled by setting state=Done but by saying state = 41, where 41 is the transition to done. Much of this is already handled by the default Table Mapping and Transform Mapping of in the included Update Set. ### Example Transitions Jira Here is an example workflow for a given record. You can see there are sets of transitions between states. ![image](media://cd28a76c-6fad-4aae-95d6-3b5b64970522) To determine how to map these transitions you will go to an record and hit a given URL corresponding to its number. The output of this, ie the current available transitions, will differ depending on the current state. Look for the two digit id value above the name. For example for the ticket INC-1234 you would go to: **https://example.atlassian.net/rest/api/2/issue/INC-1234/transitions** Here are some example transitions from “To Do”: ``` { "expand": "transitions", "transitions": [ { "id": "71", "name": "Testing", "to": { "self": "https:\/\/example.atlassian.net\/rest\/api\/2\/status\/10100", "description": "The fix is being tested", "iconUrl": "https:\/\/example.atlassian.net\/images\/icons\/statuses\/generic.png", "name": "Testing", "id": "10100", "statusCategory": { "self": "https:\/\/example.atlassian.net\/rest\/api\/2\/statuscategory\/2", "id": 2, "key": "new", "colorName": "blue-gray", "name": "To Do" } }, "hasScreen": false }, { "id": "11", "name": "Start Progress", "to": { "self": "https:\/\/example.atlassian.net\/rest\/api\/2\/status\/3", "description": "This issue is being actively worked on at the moment by the assignee.", "iconUrl": "https:\/\/example.atlassian.net\/images\/icons\/statuses\/inprogress.png", "name": "In Progress", "id": "3", "statusCategory": { "self": "https:\/\/example.atlassian.net\/rest\/api\/2\/statuscategory\/4", "id": 4, "key": "indeterminate", "colorName": "yellow", "name": "In Progress" } }, "hasScreen": false }, { "id": "21", "name": "Done", "to": { "self": "https:\/\/example.atlassian.net\/rest\/api\/2\/status\/10000", "description": "", "iconUrl": "https:\/\/example.atlassian.net\/images\/icons\/statuses\/closed.png", "name": "Done", "id": "10000", "statusCategory": { "self": "https:\/\/example.atlassian.net\/rest\/api\/2\/statuscategory\/3", "id": 3, "key": "done", "colorName": "green", "name": "Done" } }, "hasScreen": true } ] } ``` Here are some example transitions from “In Progress”: ``` { "expand": "transitions", "transitions": [ { "id": "71", "name": "Testing", "to": { "self": "https:\/\/example.atlassian.net\/rest\/api\/2\/status\/10100", "description": "The fix is being tested", "iconUrl": "https:\/\/example.atlassian.net\/images\/icons\/statuses\/generic.png", "name": "Testing", "id": "10100", "statusCategory": { "self": "https:\/\/example.atlassian.net\/rest\/api\/2\/statuscategory\/2", "id": 2, "key": "new", "colorName": "blue-gray", "name": "To Do" } }, "hasScreen": false }, { "id": "31", "name": "Stop Progress", "to": { "self": "https:\/\/example.atlassian.net\/rest\/api\/2\/status\/10001", "description": "", "iconUrl": "https:\/\/example.atlassian.net\/images\/icons\/statuses\/open.png", "name": "To Do", "id": "10001", "statusCategory": { "self": "https:\/\/example.atlassian.net\/rest\/api\/2\/statuscategory\/2", "id": 2, "key": "new", "colorName": "blue-gray", "name": "To Do" } }, "hasScreen": false }, { "id": "41", "name": "Done", "to": { "self": "https:\/\/example.atlassian.net\/rest\/api\/2\/status\/10000", "description": "", "iconUrl": "https:\/\/example.atlassian.net\/images\/icons\/statuses\/closed.png", "name": "Done", "id": "10000", "statusCategory": { "self": "https:\/\/example.atlassian.net\/rest\/api\/2\/statuscategory\/3", "id": 3, "key": "done", "colorName": "green", "name": "Done" } }, "hasScreen": true } ] } ``` ### Example Mapping On the ServiceNow side you will map over these state values to these transition values appropriately. If the transition supplied is invalid it will not change state. If the current state is In Progress and the transition value passed in is (To-Do → In Progress), it will not change state. Here is the current OOB state transition mapping. | **ServiceNow** | **Jira** | | --- | --- | | 1 - New | To Do | | 2 - Active | In Progress | | 3 - On Hold | In Review | | 4 - Awaiting | In Review | | 5 - Awaiting | In Review | | 6 - Resolved | Done | | 7 - Closed | Done | Here is the current OOB state transition field mapping you will see in your Transform Map: ``` answer = "11"; // default to To Do if (current.state == "2") { answer = "21"; // In Progress } if (current.state == "3" || current.state == "4" || current.state == "5") { answer = "31"; // In Review } if (current.state == "6" || current.state == "7") { answer = "41"; // Done } ``` ## **Mapping Over Epic** The “Epic Link” field on Jira is stored/processed in a different way relative to some of the other fields. The Epic Link is a custom field which may vary between Jira instances. So you will want to check first to verify what this field is. You can do this by pulling up the fields from the REST API, similar to the custom fields. You do this by appending **/rest/api/2/field** to your URL, (**https://example.atlassian.net/rest/api/2/field**). If you take the output of that and put it through a JSON Formatter you should see something like the following: ``` { "id": "customfield_10008", "key": "customfield_10008", "name": "Epic Link", "custom": true, "orderable": true, "navigable": true, "searchable": true, "clauseNames": [ "cf[10008]", "Epic Link" ], "schema": { "type": "any", "custom": "com.pyxis.greenhopper.jira:gh-epic-link", "customId": 10008 } }, ``` Where the id **customfield_10008** represents the field name for Epics. Similarly if you have two records where TEST-100 is the Epic and TEST-101 is a Story of this Epic - you should be able to access the REST API for TEST-101 (**https://example.atlassian.net/rest/api/2/issue/TEST-101**). This shows (amongst all the other fields) your issue, the epic issue, and the corresponding field name. ``` { "id": "49021", "self": "https://perspectium.atlassian.net/rest/api/2/issue/49021", "key": "TEST-101", "fields": { . . . "customfield_10008": "TEST-100", } } ``` So when mapping to this field you will want to update your SIAM Mapping to write to this field and pass in the corresponding issue number of the Epic (example: TEST-100). You will need to pass the issue number of the epic, *not* the unique identifier (49022).