# SailPoint ServiceNow Service Desk Connector Documentation > ServiceNow Service Desk Connector Documentation # Documentation # Additional Information Be sure to close all open access requests before starting the following scenarios: - When migrating from an Integration config-based Service Desk Integration Module to an Application-based Service Desk Integration Module. - When switching from one ticket type to another ticket type. ## Workflow Customization for Task Configuration in a Service Request You can modify the workflow of the task configuration in the ServiceNow managed system. > [!IMPORTANT] > > You must have the workflow\_admin role to make changes in the workflow. To modify the workflow of the task configuration: 1. Go to the ServiceNow application **\> Settings**. A pop-up window for System Settings appears. 2. Select the **Developer** tab. In **Application**, ensure SailPoint for Service Desk is selected. > **Screenshot** > > [![Developer application settings]()]() 3. Search for and select **Workflow Editor** from **Filter Navigator**. Then, select the SailPoint Access Request name. > **Screenshot** > > [![Workflow Editor]()]() 4. Select **Checkout** from the left-hand side of the **Workflow Actions** list. > **Screenshot** > > [![Checkout workflow action]()]() 5. Double-click **Catalog Task**. A pop-up window for **Activity Properties: Catalog Task** appears. > **Screenshot** > > [![Catalog Task activity properties]()]() 6. Scroll down to the **Script** section and select **Advanced**. This allows you to edit the **Advanced Script**. You can map as many catalog variables as you want as part of the script, and the mapping is reflected on the Task. Select **Update** to save the workflow changes. > **Screenshot** > > [![Advanced script]()]() Task-level changes are reflected on the ServiceNow ticket as shown below: > [!NOTE] > > **Screenshot** > > [![Task-level changes on the ServiceNow ticket]()]() ## Upgrade Considerations This section lists points to consider when upgrading from any previous version to v1.1.0, or through v1.1.0. > [!NOTE] > > This section does not capture changes to the product in other versions. If both the **SailPoint for Service Catalog** and **SailPoint for Service Desk** store applications are installed on the same ServiceNow instance, you can link the tickets created by both of these applications. For more information, refer to [Linking with SailPoint Service Catalog](). By default, this setup links these tickets using the **parent** field on tickets created by **SailPoint for Service Desk**. This means you can use out-of-the-box related lists (Requests \> Parent) to display linked records on requested items created by **SailPoint for Service Catalog**. Because this linking uses the **parent** field, you must remove existing transform map entries for the **parent** field. # 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]()]() # Configuring ServiceNow for a Service Request In the ServiceNow managed system, perform the following steps: 1. For each source that you want to integrate with, either identify the existing catalog items associated with that source, or create catalog items in ServiceNow. You can use the default catalog item named SailPoint Access Request. > **Screenshot** > > [![ServiceNow catalog items]()]() 2. Copy the `sys_id` for each catalog item so that you can use it while defining the integration, as described in [Catalog Mapping for Service Requests](). > **Screenshot** > > [![ServiceNow catalog item sys\_id]()]() 3. Create and publish a workflow based on the default workflow. The default example is the SailPoint Access Request workflow. > **Screenshot** > > [![ServiceNow workflow]()]() 4. Attach the workflow to the respective catalog item to handle the Requested Item (RITM) and Service Request. The workflow must be able to create a Catalog Task. 5. Repeat the previous steps for each ServiceNow instance you want to integrate with. > [!NOTE] > > To customize the existing workflow, refer to [Workflow Customization for Task Configuration in a Service Request](). # Connecting SailPoint and ServiceNow Service Desk The ServiceNow Service Desk Integration Module helps to perform effective and efficient service management for SailPoint services offered to the organization in the ServiceNow Service Desk managed system and enables customers to create and manage Service Requests or Incidents. > [!NOTE] > > ServiceNow Service Desk SDIM supports Incident and Service Request ticket types. You can integrate a SailPoint source with ServiceNow Service Desk for access requests and to monitor it. To create an integration, on the **Service Desk Integrations** page, go to **Admin \> Connections \> Service Desk**, and select **Create**. > [!NOTE] > > **Screenshot** > > [![Service Desk Integrations landing page]()]() ## General Settings The following are the steps to set up your ServiceNow Service Desk integration: > [!NOTE] > > **Screenshot** > > [![General Settings]()]() > [!NOTE] > > Ensure that the name and description of each connection are unique. Because you can configure multiple source types to use this connection, you should specify the sources in the description. The tickets for those sources will be processed on the managed system while the status of the tickets is synchronized in SailPoint. 1. Enter a unique **Name** for the integration that you are setting up. 2. Enter a unique **Description** for the integration. The description will help you identify the associated sources and tasks associated with an integration. 3. Select ServiceNow Service Desk for the **Integration Type**. 4. Select **Incident** in the **Ticket Type** dropdown list. 5. Select the Connection Type: - [VA-Based Connection Type](<#va-based-connection-type>) - Select the **VA-Based** connection type if you want to use a Virtual Appliance Cluster. - [SaaS Connection Type](<#saas-connection-type>) - Select the **SaaS** connection type if you want to create a SaaS application without using a Virtual Appliance Cluster. > **Notes** > > - SaaS Connection types don't support Credential Providers. > - Once you create an integration, you cannot edit the connection type. 6. (Optional) If Credential Providers are supported for this integration, you can select **Use a Credential Provider** to use a credential provider configured in your tenant. 7. Enter the name of the **Integration Owner**. ### VA-Based Connection Type > [!NOTE] > > **Screenshot** > > [![VA-Based Connection Type]()]() 1. Select **VA-Based** connection type if you want to use a Virtual Appliance Cluster. 2. Select **Save**. ### SaaS Connection Type > [!NOTE] > > **Screenshot** > > [![SaaS Connection Type]()]() 1. Select **SaaS** connection type if you want to create a SaaS application without using a Virtual Appliance Cluster. > [!NOTE] > > When you select the SaaS connection type, the [Enable Debug Logging](<#administrator-settings>) feature is available. It is only supported for Service Desk SaaS integration. #### Administrator Settings > [!NOTE] > > **Screenshot** > > [![Administrator Settings]()]() 1. Select the **Enable Debug Logging** checkbox to enable the integration to create and send debug log files to SailPoint Support to help troubleshoot issues. 2. If the **Enable Debug Logging** feature is needed, please contact SailPoint. > **Note** > > **Enable Debug Logging** should not be enabled without SailPoint guidance. ### Sources > [!NOTE] > > **Screenshot** > > [![Sources]()]() In the **Sources** dropdown list, select sources to configure from the available sources. For each source you want to integrate with the ServiceNow Service Desk system, verify that it is configured for provisioning. > [!TIP] > > Edit the **Description** field for these sources to indicate they are used in the ServiceNow Service Desk integration. ## Connectivity and Authentication 1. In the **URL** field, enter the URL of the ServiceNow instance that you want to integrate with. For example, `https://.service-now.com`. 2. Select **Basic** or **OAuth2** in **Authentication Type**. 3. Complete the authentication steps: - [Basic Authentication](<#basic-authentication>) - [OAuth2 Authentication](<#oauth2-authentication>) ### Basic Authentication > [!NOTE] > > **Screenshot** > > [![Basic Authentication]()]() For the **Basic** authentication type, enter the **Username** and **Password** in the respective fields. ### OAuth2 Authentication > [!NOTE] > > **Screenshot** > > [![OAuth2 Authentication]()]() For OAuth2 authentication, there are two grant types: - Password - Refresh Token > [!NOTE] > > For the most current information about using OAuth2 authentication, refer to [OAuth API Request Parameters]() in the ServiceNow documentation. In the **Grant Type** drop-down list, select either **Password** or **Refresh Token** grant type. #### Password Grant Type > [!NOTE] > > **Screenshot** > > [![Password Grant Type]()]() 1. In the **Token URL** field, enter the location of the token endpoint that the instance uses to retrieve the token. For example, `https://.service-now.com/oauth_token.do`. 2. In the **Username**, **Password**, **Client ID**, and **Client Secret** fields, enter the respective values for OAuth2 authentication. #### Refresh Token Grant Type > [!NOTE] > > **Screenshot** > > [![Refresh Token Grant Type]()]() 1. In the **Token URL** field, enter the location of the token endpoint that the instance uses to retrieve the token. 2. In the **Refresh Token** field, enter the refresh token for OAuth2 authentication. Refer to the ServiceNow documentation for information about [creating an endpoint for a client to access a ServiceNow instance](). Use the following curl command to create a refresh token: ```text curl -d "grant_type=password&client_id=&client_secret=&username=admin&password=admin" POST https://instancename.service-now.com/oauth_token.do ``` 3. In the **Client ID** and **Client Secret** fields, enter the values for OAuth2 authentication. # Frequently Asked Questions This section provides answers to the most commonly asked questions about the ServiceNow Service Desk Integration Module (SDIM). ## My organization uses multiple ServiceNow instances. Can I connect them all? **Answer**: Yes. A single SailPoint instance can connect to multiple ServiceNow instances using the ServiceNow Service Desk Integration Module (SDIM). Create a Service Desk Integration for creating requests to each ServiceNow instance. Ensure that each ServiceNow Service Desk Integration has a distinct set of sources to manage. For more information, refer to [Connecting SailPoint and ServiceNow Service Desk](). # Getting Started with ServiceNow [![SailPoint and ServiceNow]()]() Give your users a seamless employee experience with SailPoint apps on ServiceNow, when your de-facto application for requesting and approving requests is ServiceNow. The SailPoint apps on ServiceNow provide an easy-to-implement, out-of-the-box Identity and Access Management interface with ServiceNow. The SailPoint apps are published in the ServiceNow store and provide multiple integration options, based on your business case. ## Identity Governance Sync user data between SailPoint and ServiceNow. - Users with a Virtual Appliance can refer to [Integrating SailPoint with ServiceNow Identity Governance]() for detailed information. - Users without a Virtual Appliance (also referred to as a SaaS connector) can refer to [Integrating SailPoint with Identity Governance SaaS]() for detailed information. ## Service Desk Raise ServiceNow requests for disconnected applications from SailPoint. Requests can be configured according to your organization's policies and to the features available in ServiceNow. Refer to [Integrating SailPoint with ServiceNow Service Desk]() for detailed information. ## Service Catalog Users can raise requests from ServiceNow, and approvers can approve requests within ServiceNow. Requests for access can be raised for requestable roles, access profiles, and entitlements after Separation of Duties checks, and according to the approval process defined within ServiceNow. Provisioning is initiated in SailPoint, and the status is updated against the request once completed. Refer to [Integrating Identity Security Cloud with ServiceNow Service Catalog]() for detailed information. ## SailPoint Service Catalog AI Assistant Enables users to interact with AI-powered agents to request, manage, and track access through the SailPoint Service Catalog. It provides the conversational AI layer with a chatbot-based experience powered by ServiceNow Now Assist. ### Process Diagram for Catalog App [![Process diagram for the SailPoint Service Catalog AI Assistant]()]() ## Accessing SailPoint Apps [![SailPoint apps on the ServiceNow Now Platform]()]() SailPoint apps for ServiceNow are developed in partnership with ServiceNow on the Now Platform. They are published and available for ServiceNow customers in the [ServiceNow store](). Purchases must be coordinated with your Customer Success Manager or account manager. You can request trials from the ServiceNow store according to [ServiceNow's store policy](). Refer to [Entitlement Process for SailPoint Apps on ServiceNow]() for the detailed entitlement process for SailPoint customers. The ServiceNow store [Help]() page provides generic information about buying, installing, uninstalling, and managing the app. ## Release Information SailPoint continually works to extend the rich experience of core features in apps for ServiceNow. New versions of these apps are regularly released, ensuring compatibility with the latest versions of ServiceNow and SailPoint. ServiceNow also supports deleting accounts. Refer to [What's New in ServiceNow]() for details about recent and upcoming releases for all of SailPoint's ServiceNow solutions. ## Compatibility and Support Matrix SailPoint continually updates support for the apps published in the ServiceNow store to match the ServiceNow support policy and SailPoint releases. SailPoint's ServiceNow team works to announce support for the latest versions within 2 weeks of the General Availability (GA) release of ServiceNow, as well as SailPoint releases. The supported ServiceNow applications and store versions are as follows: | Application | Australia | Zurich | Yokohama | | --- | --- | --- | --- | | Identity Governance | Supported
Store Version 1.0.6 (December 2022) | Supported
Store Version 1.0.6 (December 2022) | Supported
Store Version 1.0.6 (December 2022) | | Service Desk | Supported
Store Version 1.2 (July 2024)
Store Version 1.1 (March 2024) | Supported
Store Version 1.2 (July 2024)
Store Version 1.1 (March 2024) | Supported
Store Version 1.2 (July 2024)
Store Version 1.1 (March 2024) | | Service Catalog | Supported
Store Version 5.2 (May 2026)
Store Version 5.1 (Oct 2025)
Store Version 5.0 (Jul 2025)
Store Version 4.1 (Jan 2025)
Store Version 4.0 (Nov 2024)
Store Version 3.2 (May 2024) | Supported
Store Version 5.2 (May 2026)
Store Version 5.1 (Oct 2025)
Store Version 5.0 (Jul 2025)
Store Version 4.1 (Jan 2025)
Store Version 4.0 (Nov 2024)
Store Version 3.2 (May 2024)
Store Version 3.1 (Dec 2023) | Supported
Store Version 5.2 (May 2026)
Store Version 5.1 (Oct 2025)
Store Version 5.0 (Jul 2025)
Store Version 4.1 (Jan 2025)
Store Version 4.0 (Nov 2024)
Store Version 3.2 (May 2024)
Store Version 3.1 (Dec 2023) | | SailPoint Service Catalog AI Assistant | Supported
Store Version 1.0 (May 2026) | Supported
Store Version 1.0 (May 2026) | \- | # Integrating SailPoint with ServiceNow Service Desk > [!NOTE] > > **Integration** > > This is an integration and requires additional licensing or subscriptions to utilize it. For more information, contact your customer success manager. ServiceNow Service Desk is a software platform that supports IT service management and automates common business processes for requesting and fulfilling service requests across a business enterprise. This guide helps you configure the ServiceNow Service Desk Integration Module (SDIM). It converts SailPoint provisioning actions into tickets (Service Requests or Incidents) in the ServiceNow managed system. > [!NOTE] > > **Notes** > > - Currently, the ServiceNow Service Desk integration supports only the Service Request and Incident ticket types. > - You must have an active SailPoint ServiceNow Service Desk license to use this integration. Contact your Customer Success Manager for more information. > [!NOTE] > > To view the latest features, enhancements, and fixes for all SaaS connectors, refer to the [SaaS Release Notes]() page. ## Supported Features The SailPoint ServiceNow Service Desk Integration Module (SDIM) supports the following features: - Creation of tickets for manual provisioning operations and status check. - Synchronization of ticket status between the ServiceNow Service Desk Integration Module (SDIM) and the ServiceNow Service Desk managed system. - Retry Mechanism for check ticket status failure. - The supported operations for the ServiceNow Service Desk Integration Module: - List - View - Create - Edit/Update - Delete > [!NOTE] > > The ServiceNow Service Desk Integration can be configured as a [SaaS Connection Type]() for SaaS connectivity that doesn't require a Virtual Appliance Cluster. ## Prerequisites - Configure the virtual appliance cluster only when using a VA-based connection type. For instructions, refer to the [Virtual Appliance Reference Guide](). > **Note** > > This requirement doesn't apply to SaaS connections. - Configure at least one source to generate manual tasks for Provisioning. For more information, refer to [Configuring Source Account Provisioning](). - Be familiar with Apache Velocity scripting. For more information, refer to [Apache Velocity Engine - Getting Started](). - A source must be set up between ServiceNow and SailPoint to aggregate and correlate ServiceNow users with SailPoint identities. - Have at least one ServiceNow instance that is an established part of your IT environment. Refer to [Connecting SailPoint and ServiceNow Service Desk]() for more information. - Know the authentication option ([Basic Authentication]() or [OAuth2 Authentication]()) to authenticate into ServiceNow. For token generation and OAuth Client setup on the ServiceNow instance, refer to [Create an endpoint for clients to access the instance]() in the ServiceNow help. > [!NOTE] > > To track RITM status for service requests, it is mandatory to install **SailPoint for Service Desk (version 1.0.8 or higher)** from the ServiceNow store. By default, the existing application supports REQ status only. ## Required Permissions - A Service Desk Administrator must be assigned the `x_sap_sdim.admin` role on the ServiceNow instance. - In SailPoint, the Admin user level permissions are required to access the ServiceNow Service Desk UI integration. ## System Requirements - For supported ServiceNow releases, refer to [SailPoint for Service Desk]() on the ServiceNow Store. - The virtual appliance must be able to connect to the ITSM system when using a VA-based connection type, typically using outbound access for port 443 (HTTPS). > **Note** > > This requirement doesn't apply to SaaS connections. ## Best Practices Before you start the configuration process, you should make decisions about the following components of this integration: - **Identify** - Find the ServiceNow Service Desk system and the resources that will be used in the connection. Use the **Name** and **Description** fields in **General Settings** to clearly identify the specific ServiceNow Service Desk system and the sources used in the connection. - **ServiceNow Details** - You can create an integration for each ServiceNow Service Desk system your company uses. If the integration meets the prerequisites, you need to identify the URL for each instance you want to integrate with. You also need to identify the administrator details and the applicable authentication requirements. - **Sources** - For each source you want to integrate with an ServiceNow system, verify that it is configured for provisioning. For more information, refer to [Prerequisites](<#prerequisites>). > **Tip** > > Edit the **Description** field for these sources to indicate they are used in the ServiceNow Service Desk Integration Module. - **ServiceNow Statuses** - Make a list of each possible status in the ServiceNow Service Desk system that you want to map to a status in SailPoint. This will help you track tickets as they're worked. Most importantly, SailPoint uses this mapping to determine when a ticket is closed in the ServiceNow Service Desk system so that the related provisioning task is also treated as complete. For more information about mapping statuses, refer to [Status Mapping](). - **Requests** - Identify each type of provisioning action in SailPoint that you want to create a ticket for in the ServiceNow Service Desk system, along with the information from those actions that should be included in the related ServiceNow Service Desk system ticket. For more information, refer to [Ticket Creation](). - **Catalog Items** - Make note of the Catalog Items in ServiceNow associated with the sources you want to integrate with. - **Attribute Synchronization** - For the ServiceNow UI Integration, attribute synchronization is not recommended because it depends on aggregation operations. If attribute synchronization is not managed correctly, it can cause excessive ticket creation. # Managing Comments on Access Request As a part of Access Provisioning, you can populate comments on the Access Request page. The comment is included out-of-the-box as a **Description** field for the ticket type during **Ticket Creation**. ## Upgrade Considerations For an existing Service Desk Integration configuration, you must modify the **Description** field in the [Ticket Creation]() section to include the comments for Access Request as explained below for each of the following ticket types: **For the `serviceRequest` ticket type:** When the ticket type is `serviceRequest`, modify the value of the **Description** field to include comments as shown below: ```text #if($request.operation == 'Create') Create Account on application $request.resource #elseif($request.operation == 'Delete') For $request.id in application $request.resource : Requested action from SailPoint : Delete Account #if ($request.arguments.comments), Comments : $request.arguments.comments #end #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') Requested action from SailPoint : Disable Account #if ($request.arguments.comments), Comments : $request.arguments.comments #end $newline #elseif ($item.name == '*disabled*' && $item.value == 'false') Requested action from SailPoint : Enable Account #if ($request.arguments.comments), Comments : $request.arguments.comments #end $newline #elseif ($item.name == '*locked*' && $item.value == 'false') Requested action from SailPoint : Unlock Account #if ($request.arguments.comments), Comments : $request.arguments.comments #end $newline #else $!item.Operation $item.name: $item.value #if ($item.arguments.comments), Comment from SailPoint : $item.arguments.comments #end $newline #end #end #end ``` > [!NOTE] > > For information on handling special characters in the comment, refer to [Ticket creation fails when Access Request comments contain special characters](). ## To Populate Ticket Resolution Comments on the Identity Request You can populate resolution comments from ServiceNow on the Identity Request. The resolution comments from the ServiceNow ticket (Service Request or Incident), listed as **Close Notes**, are fetched and shown on the Identity Request page as an Errors and Warnings message. The **Close Notes** for any ticket type can be fetched based on the tracking status you're interested in. For more information, refer to [Status Mapping Advanced Properties](). # Troubleshooting If you encounter any of the following issues or errors, SailPoint recommends that you follow the guidance provided below to resolve the error before contacting SailPoint Support. For issues or errors that are not addressed in this connector guide, refer to the following resources for troubleshooting information: - [SailPoint Identity Services Documentation]() - [SailPoint Support Knowledge Base]() - [SailPoint Developer Community]() ## Ticket creation fails with ticket number not found in response error - WashingtonDC specific Ticket creation fails with the incident type of ticket when using ServiceNow WashingtonDC. The error message is: ```text sailpoint.connector.InvalidConfigurationException: [ InvalidConfigurationException ] [ Possible suggestions ] a) Check the response for the ticket number. b) Ensure that provision 'responseElement' is correctly configured for the 'incident' ticket. [ Error details ] Ticket number not found in the response. Response: {"import_set":"ISET0010034","staging_table":"x_sap_sdim_incident","result":[{"transform_map":"Incident","table":"incident","status":"error","error_message":"Target record not found"}]} ``` **Resolution**: Ensure the **sn\_incident\_read** role is added explicitly to the Service Desk Administrator created in [Required Permissions](). ## While creating any ticket or checking status, an error is displayed **Resolution**: To review and assess, enable logging at the debug level. It is set at the error level by default. [![Enabling debug-level logging]()]() ## SailPoint intermittently creates duplicate accounts for an identity on a CSV source integrated with ServiceNow SIM, creating duplicate tickets for the user in ServiceNow It's possible the identity is refreshed from two different sources at the same time (for example, aggregations from two different sources running at the same time). Under the right conditions, this can cause two "create account" requests to the CSV source since the user is assigned to the same entitlement twice. **Resolution**: Ensure aggregations from two different sources don't run at the same time to avoid refreshing an identity twice at the same time. ## Ticket creation fails when the request includes escape characters (`\\`) Ticket creation fails because the request includes escape characters (`\\`). The system produces the following error message: ```text Ticket creation failed. com.google.gson.stream.MalformedJsonException: Invalid escape sequence at line 3 column 49 path $.description ``` **Resolution**: Update the value of the **Description** attribute by using the `StringEscapeUtils` string in the [Ticket Creation]() section as shown below: ```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: $StringEscapeUtils.escapeJava($StringEscapeUtils.escapeJava($item.value.toString())) $newline #end #end #else $newline $!request.Operation Account #end ``` ## Ticket creation fails when Access Request comments contain special characters Ticket creation fails because the Access Request comments contain special characters. The system produces the following error message: ```text Request completed sailpoint.connector.ConnectorException: [ ConnectorException ] [ Error details ] Request execution failed. {"error":{"message":"Ensure valid catalog items details provided for catalog item: 8053818edbffb300e90690b3db9619c4 (sys_ws_operation.f1f3898edbffb300e90690b3db961966.operation_script; line 38)","detail":""},"status":"failure"}. Status: 500 ``` or ```text sailpoint.connector.InvalidRequestException: [ InvalidRequestException ] [ Error details ] Invalid request received to IT Service Desk System. Status: 400, Output: {"error":{"message":"Exception while reading request","detail":"The payload is not valid JSON."},"status":"failure"} ``` **Resolution**: When the ticket type is `serviceRequest`, update the value of the **Description** attribute by using `StringEscapeUtils` through the [Ticket Creation]() section, as shown below in bold: ```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') **Requested action from SailPoint :** Disable Account $newline #elseif ($item.name == '*disabled*' && $item.value == 'false') **Requested action from SailPoint :** Enable Account $newline #elseif ($item.name == '*locked*' && $item.value == 'false') **Requested action from SailPoint :** Unlock Account $newline #else $!item.Operation $item.name: $item.value **#if ($item.arguments.comments), Comment from SailPoint :** **$StringEscapeUtils.escapeJava($StringEscapeUtils.escapeJava($item.arguments.comments.toString())) #end** $newline #end #end #else $newline $!request.Operation Account #end ``` ## Ticket creation fails with ticket number not found in response error When configuring a custom catalog item in ServiceNow with SDIM integration and the `track_ritm` flag set to `true` for the Service Request ticket type, the following error occurs: ```text sailpoint.connector.InvalidConfigurationException: [ InvalidConfigurationException ] [ Possible suggestions ] a) Check the response for the ticket number. b) Ensure that provision 'responseElement' is correctly configured for the 'serviceRequest' ticket. [ Error details ] Ticket number not found in the response. Response: {"result":{"items":[]}} ``` **Resolution**: Update the **Tracking ID** field on the custom catalog item configuration in ServiceNow. [![Updating the Tracking ID field]()]() ## Source name on the Service Desk ticket differs from the name in SailPoint You rename a source in SailPoint. The UI shows the new name. The Service Desk ticket still shows the original name. Example: ```text Name in SailPoint: Payroll Access Name on the Service Desk ticket: Payroll Test ``` The Service Desk ticket uses the source name from the provisioning plan. That name is set when the source is created. You cannot change it. When you rename the source, SailPoint updates the display name only. The UI shows the display name. The ticket continues to show the original name. **Resolution**: This is expected. There is no setting that makes the ticket use the display name. Do not edit the source XML to make the names match. ## Timeout error occurred A timeout occurred while performing a provisioning operation. To resolve this, a connection reset is required. 1. Ensure that the IT Service Desk System is up and running. 2. Ensure that the connection between the Identity Server and IT Service Desk System is stable. **Resolution**: Add the following entry to the application XML using debug mode: ```xml ``` # Using Integrations ## Listing Integrations To list the SailPoint ServiceNow Service Desk integrations in the card-view format, perform the following: > [!NOTE] > > **Screenshot** > > [![Listing Integrations]()]() > [!NOTE] > > All your Service Desk integrations are displayed based on: Name, Description, and Integration Type. 1. Go to **Admin \> Connections \> Service Desk**. 2. On the **Service Desk Integrations** page, the integrations will be sorted by name in alphabetical order. The ServiceNow Service Desk integrations are listed accordingly. ## Viewing Integrations > [!NOTE] > > **Screenshot** > > [![Viewing Integrations]()]() 1. Go to **Admin \> Connections \> Service Desk**. 2. On the **Service Desk Integrations** page, select a card for the ServiceNow Service Desk integration to view the corresponding details. 3. Scroll down to view the values of the UI fields. 4. To exit, select the **X**. ## Editing an Integration > [!NOTE] > > **Screenshot** > > [![Editing an Integration]()]() 1. Go to **Admin \> Connections \> Service Desk**. 2. On the **Service Desk Integrations** page, select a card for the ServiceNow Service Desk integration to view the corresponding details. 3. Scroll down to view the values of the UI fields. 4. Select **Edit**. The integration details with the previous values are displayed. Change the UI field values as per your requirement. 5. Select **Continue** on the dialog boxes to proceed to the **Summary** page. 6. Select **Update** to save the changes. ## Deleting an Integration > [!NOTE] > > **Screenshot** > > [![Deleting an Integration]()]() 1. Go to **Admin \> Connections \> Service Desk**. 2. On the **Service Desk Integrations** page, select a card for the ServiceNow Service Desk Integration to view the corresponding details. 3. Select **Delete**. A warning message is displayed. Select **Delete** if you're sure you want to delete the integration.