| Document Status | DRAFT |
|---|---|
| Planned Release Date | TBD |
| Jira Ticket |
ATEAM-42
-
Getting issue details...
STATUS
|
Functions
- When user changes Jira field 'Create ServiceNow?' from 'No' to 'Yes' a ServiceNow incident will be created and updates will be synchronized.
- Will NOT create Jira tickets off of ServiceNow. This functionality will be different per project/group which will require its own requirements.
Conditions
- This integration can support any additional Jira projects with same use case through editing lookup tables. Workato recipes will be untouched.
- All Jira users associated must also have Yale email accounts for mapping purposes
Field Mappings (JIRA -> SN)
The trigger for creating a ServiceNow incident from a new or existing Jira issue is by selecting 'Yes' under the Jira field called 'Create ServiceNow?'. If Jira Issue Key already exists in a ServiceNow Incident's Internal Ticket ID field then it will just update.
| Jira Field Name | SN Field Name | Description | Notes and Workato Behavior |
|---|---|---|---|
Reporter | Client Contact | *Only maps during creation since clients and contacts will not always be the same as reporter. Users will manually change on ServiceNow if that is the case. Reporter maps to Client and Contact. Call back number and Location are pulled from the contact. If null then defaults to "N/A". | Workato searches the sys_user table on ServiceNow for Active users using the Reporter's email address to find the matching record. This gives the User ID, Business phone, and Location values needed. Our Client and Contact are ServiceNow users so as long as email is associated with them this should work. In the past, we did not include call back number and location mapping even though they are required field that should autopopulate. This still creates the ServiceNow ticket while those two required fields are blank so we have decided to pull those two fields from the client through the process. |
| Call Back Number | Call Back number will be pulled from the client by Workato. | In the past, we did not include call back number and location mapping even though they are required field that should autopopulate. This still creates the ServiceNow ticket while those two required fields are blank so we have decided to pull those two fields from the client through the process. | |
| Location | Location will be pulled from the client by Workato. | In the past, we did not include call back number and location mapping even though they are required field that should autopopulate. This still creates the ServiceNow ticket while those two required fields are blank so we have decided to pull those two fields from the client through the process. | |
| Contact type | Defaults to 'Jira' | This option cannot be selected in ServiceNow. The contact type option is only selectable via the integration. This will need to be a task on the change ticket as this functionality needs to be created in ServiceNow. | |
Assignee | Assigned To | Assignee on Jira and ServiceNow are people from our team so they will exist in both instances. Email will be added on both instances to use as means of mapping. | Workato searches the sys_user table on ServiceNow for Active users using the Assignee's email address to find the matching record. This gives the User ID values needed. |
Linked Status | State | Jira Workflow can have many statuses. Each status however can only be associated with 3 different linked statuses: To Do, In Progress, and Done. Mapping:
*CLOSED status is a special status that users won't be able to manually change to or even see. Only Workato service account can change to that. This status stops the ticket from being editable. This will disable reopening of closed ServiceNow incident. |
Example: ANALYZE QUEUE, INTAKE, AND QA has the linked status of To do IN PROGRESS has linked status of In Progress RESOLVED and CLOSED has linked status of Done |
Description | Description | Maps word for word. ServiceNow Description character limit is 3500. | Overwrites the field |
Summary | Short Description | Maps word for word. ServiceNow Short Description character limit is 160. | Overwrites the field |
Comments | Work Notes | Jira comments will be mapped in ServiceNow as Work Notes. Takes the commenter's full name and message from Jira. The user entering the comment is JIra Integration and the work note entry will display <Commenter's Full Name>: <comment> *On incident creation, Will post a Work Note with the link to the Jira ticket. |
|
Project Key | Business Service (Service Offering) Assignment Group | Jira project key maps to one ServiceNow business service and one assignment group through a lookup table. The business service and assignment groups are defined using their sys ids. | Lookup Table:
|
Issue Type | Category | Category is defined by Jira Project Key and Issue Type through a lookup table. *Only maps during creation due to issue types having different workflows and difference in behavior for some categories for both Jira and ServiceNow. This means if an issue type (JIRA) or category (SN) is changed, it will not update. | Lookup Table:
|
| Priority | Impact Urgency | Priority cannot be manually set on ServiceNow but is determined by Impact and Urgency. The business rule which sets Priority is not triggering currently. This issue is currently being investigated by Tom Hughes
| By using a lookup table, we map Jira Priority to different combinations of Impact and Urgency to get the priority we want on ServiceNow
Example: Jira priority is set to Medium, Workato will set ServiceNow Impact to 4 - Individual and Urgency to 3 - Work not Affected. |
Attachments | Attachments | New uploads will also be uploaded on ServiceNow with the same file and name. We are currently not handling deletions or name changes. *uploading a file with the exact same name will get uploaded onto servicecnow with some code inside parenthesis. | Deletions will need to be manually done. |
| Close code | Close code | Field appears when transitioning to Resolve status on Jira. It behaves just like ServiceNow and is a dropdown with same selection. | maps exactly |
| Close notes | Close notes | Field appears when transitioning to Resolve status on Jira. It is a required text field that maps word for word. ServiceNow close notes character limit is 4000 | maps exactly |
| Issue Key | Internal Ticket ID | On ServiceNow incident creation, the Jira Issue Key is entered into ServiceNow Internal Ticket ID. The Internal Ticket will = true and Internal Ticket System will say "Jira". | This is what Workato uses to know which ticket/incident to update. |
Form Fields (SN -> JIRA)
ServiceNow Account: s_jira
Updates to ServiceNow will follow the mappings below.
| SN Field Name | Jira Field Name | Description | Notes and Workato Behavior |
|---|---|---|---|
Email on Assigned To User Record | Assignee | Maps by email | Workato maps using Assignee email. Since Jira api doesn't allow you to find user using email we actually truncate the@yale.edu and match with Jira User ID which is also the email without the @yale.edu *Jira announced it will be changing their user id system and Workato will adjust to that when the time comes. The ServiceNow team will be notified when this change happens for future state testing. |
State | Status | Workato uses the ServiceNow State value and searches a lookup table to find the corresponding Jira Status Transition. If the Jira ticket already exists it will search the current Jira Status Category along with the State value in the lookup table. If it returns something then Workato will do nothing. This is because we actually want it to map by Linked Status but Jira api forces us to use transitions instead when updating status. *CLOSED status transition makes the Jira ticket uneditable which is mapped to ServiceNow Closed state. | For creating Jira tickets, Workato looks for the associated status transition to the state number:
for updating Jira tickets, Workato will only update using the table above if the changed ServiceNow State and current Jira status color does not match. Green are 'done' statuses, Grey are 'To Do' statuses, and Yellow are 'In Progress' statuses. 6 = green 17 = grey 15 = yellow This is because we want to map States to Status Category instead of the transition but when updating Jira, we can only update it by using transitions. This is a workaround that accomplishes what we want. |
Description | Description | maps word for word. Character Limit of 3500. | Overwrites field. |
Summary | Short Description | maps word for word. Character Limit of 160. | Overwrites field. |
Priority | Priority | Workato uses ServiceNow priority value to search a lookup table for the corresponding Jira priority. If the ServiceNow priority value is a 4 then it will do an extra search for the impact and urgency. |
|
Additional Comments/Work Notes | Comments | Additional comments and Worknotes both gets posted as a Jira comment. Sample: The system will map the following: In production Jira the service account user name is 'Workato Service Account' For Additional Comments: Workato Service Account added a comment - <time since updated> comments: <user who entered the comments netid>: <comment entered> For Work Notes: Workato Service Account added a comment - <time since updated> work_notes: <user who entered the work notes netid>: <work notes entered> |
|
| Attachments | Attachments | attachments gets uploaded to Jira with same file and name. Currently not handling deletions. Will need to delete manually on both instances. *Uploading files with the same name from SN will not get uploaded onto Jira | |
| Close code | Close code | Maps the same. Also a dropdown on Jira. | |
| Close notes | Close notes | Maps word for word. Character limit of 4000. |
Additional Requirements:
| Requirement Name | Requirement |
|---|---|
Notifications |
|