# Configuring SailPoint for ServiceNow Service Desk In SailPoint, configure the following items for your ServiceNow Service Desk Integration: - [Ticket Creation](<#ticket-creation>) - [Catalog Mapping for Service Requests](<#catalog-mapping-for-service-requests>) - [Status Mapping](<#status-mapping>) - [Requester Source](<#requester-source>) On the Summary panel you can review the general settings and parameters for the connectivity and authentication. > [!NOTE] > > All activity on the Service Desk connector appears as [events in Search]() and on the Activity tab of an identity. ## Ticket Creation A ticket contains the relevant data required for further processing. You can create a ticket for your integration for a centralized approach spanning many users and resources to strengthen IT controls and provide proof of compliance to auditors and executive management. > [!NOTE] > > Currently, ServiceNow Service Desk UI Integration only supports Service Request and Incident ticket types. ### Service Request The contents of a service request define the components of the SailPoint provisioning task that are added to the ServiceNow ticket. SailPoint recommends that you include the Apache Velocity variables, as needed, to meet your specific use cases. For each ticket created by the integration, a request is created that includes the approval flow along with an RITM (request item) as a child of the request to be completed in a ServiceNow managed system. > [!NOTE] > > **Screenshot** > > [![Service Request ticket creation]()]() > [!NOTE] > > The default setting tracks REQ tickets. To track RITM, go to [Add Field](<#add-field>) settings to add a new field to track RITM. 1. Enter the **Short Description** for the ticket that you are creating. For example, `SailPoint Access Request $!plan.arguments.identityRequestId`. 2. Enter the **Opened By** with the `sys_id` for the ServiceNow user from the Requester Source on SailPoint. The default value is `$!{plan.arguments.opened_by|'Default_ServiceNow_Account_Sys_ID'}`. In the default value provided above, replace `Default_ServiceNow_Account_Sys_ID` with the actual service account's `sys_id`. 3. Enter the **Req Description** of the requirement that generated the ticket. For example, `Service Request created by Service Desk Integration Module (SIM)`. 4. Enter additional details in the **Description** field. For example: ```text #if($request.operation == 'Create') Create Account on application $request.resource #else For $request.id in application $request.resource #end #if ($request.items) $newline #foreach ($item in $request.items) #if ($item.name == '*disabled*' && $item.value == 'true') Disable Account. $newline #elseif ($item.name == '*disabled*' && $item.value == 'false') Enable Account. $newline #elseif ($item.name == '*locked*' && $item.value == 'false') Unlock Account. $newline #else $!item.Operation $item.name: $item.value $newline #end #end #else $newline $!request.Operation Account #end ``` 5. Enter the **Requested For** with the `sys_id` of a ServiceNow account for creating a ticket. Alternatively, you can use the existing variable. An admin can create a ticket for an employee or request a ticket for themselves. For example, `$!plan.arguments.requested_for`. #### Add Field To add a field in ticket creation, select **Add Field** and enter the relevant details for the new field. The field types are: - Single Value - Multi Valued Field - Grouped Key-Value Pair For example, if you want to add a Single Value custom attribute such as `custom_attr` in the request to the ServiceNow managed system, add the **custom\_attr** field using the Single Value type. The corresponding value can be either static or dynamic. For the dynamic value, use a Velocity Template Expression. On the ServiceNow managed system, ensure that the Catalog Item has the `custom_attr` variable. ##### Track RITM Select **Single Value**. Add the following details: - Name = `track_ritm` - Value = `true` > [!NOTE] > > The ticket number generated on the Service Desk system for the corresponding provisioning action can be seen under **Search \> Account Activity** details of the identity. For more information, refer to [Account Activity Using Search](). ### Incident > [!NOTE] > > **Screenshot** > > [![Incident ticket creation]()]() 1. Enter the **Description** for the Incident that you are creating. For example: ```text #foreach($req in $plan.requests) #if($req.operation == 'Create') Create Account on application $req.resource #elseif($req.operation == 'Delete') Delete Account on application $req.resource For $req.id #if($req.arguments.comments) Comments: $req.arguments.comments #end #else For $req.id in application $req.resource #if($req.arguments.comments) Comments: $req.arguments.comments #end #end #if($req.items) $newline #foreach($item in $req.items) #if($item.name == '*disabled*' && $item.value == 'true') Requested action from SailPoint: Disable Account #elseif($item.name == '*disabled*' && $item.value == 'false') Requested action from SailPoint: Enable Account #elseif($item.name == '*locked*' && $item.value == 'false') Requested action from SailPoint: Unlock Account #else $!item.Operation $item.name: $item.value #if($item.arguments.comments) Comment from SailPoint: $item.arguments.comments #end #end $newline #end #end #end ``` 2. Enter the **Caller ID** with the `sys_id` for the ServiceNow user from the Requester Source on SailPoint. The default value is `$!plan.arguments.requested_for`. 3. Enter the **Short Description** of the raised Incident ticket. For example, `SailPoint Access Request $!plan.arguments.identityRequestId`. 4. Enter the **Assignment Group** (the group of users that are responsible for the Incident record). The default value is `Service Desk`. 5. Enter the **Impact** level of the ticket. The default value is `3`. 6. Enter the **Contact Type** (the type of contact that created the ticket). The default value is `email`. 7. Enter the **Opened By** with the `sys_id` for the ServiceNow user from the Requester Source on SailPoint. For example, `$!{plan.arguments.opened_by|'Default_ServiceNow_Account_Sys_ID'}`. In the provided default value, replace `Default_ServiceNow_Account_Sys_ID` with the actual service account's `sys_id`. 8. Enter the **Urgency** for the Incident. The default value is `3`. #### Add Field To add a field in ticket creation, select **Add Field** and enter the relevant details for the new field. The field type is: - Single Value - Multi Valued Field - Grouped Key-Value Pair For example, if you want to add a Single Value custom attribute such as `u_custom_attr` in the request to the ServiceNow managed system, add the `u_custom_attr` field using the Single Value type. The corresponding value can be either static or dynamic. For the dynamic value, use a Velocity Template Expression. On the ServiceNow managed system, ensure that the `x_sap_sdim_incident` transform table has the `u_custom_attr` variable. > [!NOTE] > > The ticket number generated on the Service Desk system for the corresponding provisioning action can be seen under **Search \> Account Activity** details of the identity. For more information, refer to [Account Activity Using Search](). ## Create Ticket Advanced Properties ### Service Request Select **View Advanced Properties** to add other details of the ticket. > [!NOTE] > > **Screenshot** > > [![Service Request advanced properties]()]() 1. Enter the basic element of the request ticket in the **Request Root Element** field. The value represents the JSON root element in a request. 2. Enter the resource used for the request ticket in the **Resource** field. This is the ticket creation REST endpoint. Do not provide the base URL for the instance in the value. The base URL is appended to this endpoint value. Enter only the remaining endpoint URL. For example, `/api/x_sap_sdim/sailpoint_cart_js_api/create_ticket`. 3. Enter the response code for the request ticket in the **Response Element** field. This value is a JSON path expression that provides information about where to find a ticket number. For example: - For REQ: `$.result.request_number` - For RITM: `$.result.items` ### Incident Select **View Advanced Properties** to add other details of the ticket. > [!NOTE] > > **Screenshot** > > [![Incident advanced properties]()]() 1. Enter the resource used for the incident in the **Resource** field. This is the ticket creation REST endpoint. Do not provide the base URL for the instance in the value. The base URL is appended to this endpoint value. Enter only the remaining endpoint URL. For example, `/api/now/import/x_sap_sdim_incident`. 2. Enter the response code for the incident in the **Response Element** field. This value is a JSON path expression that provides information about where to find a ticket number. For example, `result[0].display_value`. ## Catalog Mapping for Service Requests A catalog item defines how a provisioning action item on a source produces a ticket for a specific ServiceNow catalog item. It defines the mapping between the sources in the source parameter and the related item at the ServiceNow managed system. A provisioning action item and catalog item have unique codes. > [!NOTE] > > **Screenshot** > > [![Catalog Mapping]()]() 1. The **SailPoint Source** value is auto-populated from **Settings \> General Settings \> Sources** directly. 2. Enter the system ID (`sys_id`) of the ServiceNow catalog item in the **Catalog Item** field. For example, `8053818edbffb300e90690b3db9619c4`. ## Status Mapping ### Service Request Tickets You can map the status of the service request to the corresponding status of activity on the ServiceNow Service Desk managed system. > [!NOTE] > > **Screenshot** > > [![Service Request status mapping]()]() Select **Add Status** to add another row for status mapping. For SailPoint, the types of status are: - Committed - Queued - Failed For the ServiceNow Service Desk managed system, the statuses for tracking REQ are: - requested - in\_process - closed\_complete - closed\_incomplete - closed\_canceled - closed\_rejected - closed\_skipped For the ServiceNow Service Desk managed system, the statuses for tracking RITM are `-5`, `1`, `2`, `3`, `4`, and `7`. ### Incident Tickets You can map the Incident status to the corresponding activity status on the ServiceNow Service Desk managed system. > [!NOTE] > > In an Incident ticket, the status map closure code has a higher precedence than the status. > [!NOTE] > > **Screenshot** > > [![Incident status mapping]()]() Select **Add Status** to add another row for status mapping. For SailPoint, the types of status are: - Committed - Queued - Failed For the ServiceNow Service Desk managed system, the statuses for Incidents are `1`, `2`, `3`, `6`, `7`, and `8`. [![Incident status map closure codes]()]() For SailPoint, the types of statuses for closure codes are: - Committed - Failed For the ServiceNow Service Desk managed system, the types of ServiceNow SDIM Closure Codes for Incidents are: - Solved (Work Around) - Solved (Permanently) - Solved Remotely (Work Around) - Solved Remotely (Permanently) - Closed/Resolved by Caller - Not Solved (Not Reproducible) - Not Solved (Too Costly) - Duplicate - Known error - No resolution provided - Resolved by caller - Resolved by change - Resolved by problem - Resolved by request - Solution provided - Workaround provided - User error ### Adding or Removing Statuses You can add or delete statuses in the Status Mapping section as needed for your organization. The ServiceNow SDIM UI Integration checks the status on tickets at regular intervals. The status must have at least one committed value. For more information on status check configuration, refer to the SailPoint Developer Portal: - [Getting the time check configuration of queued SDIM tickets]() - [Updating the time check configuration of queued SDIM tickets]() ## Status Mapping Advanced Properties ### Service Request Tickets Select **View Advanced Properties** to add other details of the status mapping. > [!NOTE] > > **Screenshot** > > [![Service Request status mapping advanced properties]()]() 1. Enter the ServiceNow ticket field for fetching the resolution comments as closing notes in **Close Notes**. For example, `$.result[0].close_notes`. 2. Enter the resource used for the status mapping in **Resource**. For example: - For REQ: `/api/now/table/sc_request?number=$ticketId&sysparm_fields=request_state,close_notes` - For RITM: `/api/now/table/sc_req_item?number=$ticketId&sysparm_fields=state` 3. Enter the response code for the status mapping in **Response Element**. This value is a JSON path expression that has information on the service request status. For example: - For REQ: `$.result[0].request_state` - For RITM: `$.result[0].state` ### Incident Tickets Select **View Advanced Properties** to add other details of the status mapping. > [!NOTE] > > **Screenshot** > > [![Incident status mapping advanced properties]()]() 1. Enter the ServiceNow ticket field for fetching the resolution comments as closing notes in **Close Notes**. For example, `$.result[0].close_notes`. 2. Enter the response code for the status mapping in **Closure Code Response Element**. This value is a JSON path expression that has information on the incident status. For example, `result[0].display_value`. 3. Enter the resource used for the Incident in **Resource**. This is the check status REST endpoint. Do not provide the base URL value. The base URL is appended to this endpoint value. Provide only the remaining endpoint URL. For example, `/api/now/table/incident?number=$ticketId&sysparm_fields=incident_state,close_code,close_notes`. 4. Enter the response code for the status mapping in **Response Element**. This value is a JSON path expression that has information on the incident status. For example, `$.result[0].incident_state`. ## Customize Ticket Fields You can customize the ticket fields based on your requirements. You can set up a Before Provisioning rule to generate ticket fields. **Moving from Plan Initializer Script Rule to Before Provisioning Rule:** 1. Create a rule with a distinct name that is different from the default rule name (Sample Before Provisioning Rule for SDIM). You can set this new rule for the integration using API. For more information, refer to [Service Desk Integration Update - PATCH API](). If you are using the out-of-the-box PlanInitializerScript in your ServiceNow Service Desk integration, use the [Service Desk Integration Update - PATCH API]() to update the integration to use the out-of-the-box Before Provisioning rule. 2. If you have customized the out-of-the-box PlanInitializerScript in your ServiceNow Service Desk integration, contact SailPoint Services for setting up a Before Provisioning rule for your integration. Then use the [Service Desk Integration Update - PATCH API]() to update the integration to use the new Before Provisioning rule. 3. After completing the previous two steps, raise a support request at [support@sailpoint.com]() to enable the feature flag `GOV_DISABLE_PLAN_INITIALIZER` in your SailPoint instance. ## Requester Source In the **Requester Source** field, enter the source name through which the ServiceNow Service Desk system's users are aggregated. > [!NOTE] > > **Screenshot** > > [![Requester Source]()]() ## Linking with SailPoint Service Catalog If you have both the `SailPoint for Service Catalog` and `SailPoint for Service Desk` store applications installed on the same ServiceNow instance, you can link the tickets created by both applications. The default setup links both tickets using the **parent** field on tickets created by `SailPoint for Service Desk`, so you can use out-of-the-box related lists to show the linked records on requested items created by `SailPoint for Service Catalog`. 1. Sign in to your ServiceNow instance as an administrator, type `sys_properties.FILTER` in the application navigator, and press **Enter** to go to **System Properties**. > **Screenshot** > > [![System Properties]()]() 2. Search for the `x_sap_sdim.relationship_field_name` property name. > **Screenshot** > > [![Relationship field name property]()]() 3. The default value is set to `correlation_id`. Update the value to a different field from the request (`sc_request`) table if you're using `correlation_id` for another integration. If you're using the incident as a ticket type, this field should be from the incident (`incident`) table. > **Note** > > The value in this field is overwritten by the integration, so you must ensure the value is not used by any out-of-the-box or custom code. 4. Select **Save**. Now you must update field mapping in the Service Desk application on SailPoint. **Field Mapping for Service Request Tickets:** 1. Sign in to your SailPoint instance as an administrator, and go to **Connections \> Service Desk**. > **Screenshot** > > [![Service Desk connections]()]() 2. To edit the Service Desk application that you're using to create service requests, select **Configure**. > **Screenshot** > > [![Configure the Service Desk application]()]() 3. Under **Ticket Creation**, select **Add Field**. > **Screenshot** > > [![Add Field for Service Request tickets]()]() 4. Select the **Field Type** as `Single Value`. Copy the same field **Name** that you entered in the property for `x_sap_sdim.relationship_field_name`, and specify the **Value** as `$!plan.arguments.identityRequestId`. > **Screenshot** > > [![Field value for Service Request tickets]()]() 5. Select **Save**. The list of fields displays. > **Screenshot** > > [![Fields list for Service Request tickets]()]() **Field Mapping for Incident Tickets:** 1. Sign in to your SailPoint instance as an administrator, and go to **Connections \> Service Desk**. > **Screenshot** > > [![Service Desk connections]()]() 2. To edit the Service Desk application that you're using to create incidents, select **Configure**. > **Screenshot** > > [![Configure the Service Desk application]()]() 3. Under **Ticket Creation**, select **Add Field**. > **Screenshot** > > [![Add Field for Incident tickets]()]() 4. Select the **Field Type** as `Single Value`. Copy the same field **Name** that you entered in the property for `x_sap_sdim.relationship_field_name`, prepended with `u_`. For example, if the property name is `correlation_id`, add `u_correlation_id` as the name. Specify the **Value** as `$!plan.arguments.identityRequestId`. > **Screenshot** > > [![Field value for Incident tickets]()]() 5. Select **Save**. The list of fields displays. > **Screenshot** > > [![Fields list for Incident tickets]()]()