# SailPoint Generic Service Desk Connector Documentation > Generic Service Desk Connector Documentation # Documentation # Configuring Generic Service Desk Configure the following items for your Generic Service Desk. On the Summary page, you can review the general settings and parameters for the connectivity and authentication. ## Ticket Creation The information provided in this section is used to create a ticket on the Generic Service Desk. These tickets contain information that can be used by IT, compliance auditors, and executive management. > [!NOTE] > > **Screenshot** > > [![Ticket Creation]()]() The contents of a ticket define the components of the SailPoint provisioning task that are added to the ITSM ticketing system ticket. SailPoint recommends that you include the Apache Velocity variables as needed to meet your specific use cases. SailPoint provides a **Sample Description** field, however you will add required fields based on your target ITSM system, and then delete this sample field. 1. To add a field, select **Add Field**. Select the field type and enter the required information based on the type. Options are Single Value, Number, Multi Valued Field, Grouped Key-Value Pair, and Raw JSON. 2. To add additional fields, select **Add Another**. 3. Once completed, select **Save**. Select the trash can icon to remove fields that are not needed. #### Advanced Properties To add advanced properties, select **View Advanced Properties**. > [!NOTE] > > **Screenshot** > > [![Advanced Properties]()]() 1. Enter the Velocity Expression in **Process Response Element Expression**, which provides parsing logic to fetch the ticket number from the response. For example: ```text $response.substring($StringUtils.lastIndexOf($response, '/') + 1) ``` > **Note** > > Applicable only if the ticket creation API returns a URL containing the ticket number. Not applicable if only the ticket number itself is returned. 2. Enter the basic JSON root element of the request ticket in **Request Root Element**. ```text values ``` 3. Enter the **Request Root Element Type** of JSON Request. For example: ```text JSONObject ``` 4. Enter the **Resource** used for the request ticket. This is ticket creation REST endpoint. Do not provide the base url in the value. Base URL would be appended to this endpoint value. Provide only remaining endpoint URL. For example: ```text /api/x_sap_sdim/sailpoint_cart_js_api/create_ticket ``` 5. Enter the JSON path expression that indicates the location of the ticket number in **Response Element**. For example: ```text $.values.['Incident Number'] ``` **Request:** > [!NOTE] > > **Screenshot** > > [![Example request]()]() **UI fields:** > [!NOTE] > > **Screenshot** > > [![Example UI]()]() > [!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](). #### Velocity Objects to Corresponding Java Objects | Object | Description | | --- | --- | | `$plan.requests` | List of `ProvisioningPlan.AccountRequest` objects | | `$request.id` | Account native identity | | `$request.items` | List of `ProvisioningPlan.AttributeRequest` objects | ## Status Mapping > [!NOTE] > > **Screenshot** > > [![Status Mapping]()]() Map the status of the tickets in SailPoint to the corresponding status of the ITSM ticketing system. Select **Add Status** to add new rows, or the trash can icon to remove those that are no longer needed. For the Identity Security Cloud Status, select from the drop-down list, Failed, Committed, or Queued. The **Generic SDIM Status** can be whatever is required based on your target ITSM system. #### Advanced Properties To add more details to the status mapping, select **View Advanced Properties**. > [!NOTE] > > **Screenshot** > > [![Advanced Properties]()]() **Resource**: REST endpoint used to read the ticket. Do not provide the base URL in the value, the base URL is appended to this endpoint value. ```text /api/arsys/v1/entry/HPD:IncidentInterface?q='Incident+Number'=%22$ticketId%22 ``` **Response Element**: A JSON path expression that identifies the ticket number in the response from the REST endpoint. For example: ```text $.entries[0].values.Status ``` ## Requester Source > [!NOTE] > > **Screenshot** > > [![Requester Source]()]() In the **Requester Source** dropdown list, select the source name through which the ITSM ticketing system's users are aggregated. # Connecting SailPoint and Generic Service Desk The Generic Service Desk Integration Module (SDIM) helps to perform effective and efficient service management for SailPoint services offered to the organization in the ITSM ticketing system and enables customers to create and manage any type of ticket. You can integrate a SailPoint source with an ITSM ticketing system for access request and monitor it. **To create the connection:** 1. Sign in to **SailPoint \> Admin interface**. 2. Select **Connections \> Service Desk**. The Service Desk connections page displays. 3. Select **Create**, and then provide the required information on the [General Settings](<#general-settings>) page. 4. Select **Continue**. The Configure page appears. 5. Provide the [Connectivity and Authentication](<#connectivity-and-authentication>) information on the Configure page. 6. Provide the [Ticket Creation]() information on the Configure page. 7. Provide the [Status Mapping]() information on the Configure page. 8. Provide the [Requester Source]() information on the Configure page. 9. Select **Continue** to save the configuration and review the Summary of the configuration. If the Summary is satisfactory, select **Create**. ## General Settings > [!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 are synchronized in SailPoint. 1. Enter a descriptive **Name** for the connection. 2. Enter the **Description** of the connection. 3. Select **Integration Type** Generic SDIM from the drop-down list. 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 Generic 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 Generic Service Desk integration. ## Connectivity and Authentication SailPoint's Generic Service Desk SDIM supports Basic, OAuth2, and API Token as Authentication Types. > [!NOTE] > > **Screenshot** > > [![Connectivity and Authentication]()]() 1. In the **URL** field, enter the URL of the ITSM ticketing system you want to integrate with. 2. Select Basic, OAuth2, or API Token for Authentication Type. 3. Complete the authentication steps: - [Basic Authentication](<#basic-authentication>) - [OAuth2 Authentication](<#oauth2-authentication>) - [API Token Authentication](<#api-token-authentication>) ### Basic Authentication > [!NOTE] > > **Screenshot** > > [![Basic Authentication]()]() 1. Select Basic as the **Authentication Type**. 2. Enter the Service Account username in the **Username** and Service Account user's Password in the **Password**. ### OAuth2 Authentication For OAuth2 authentication, there are three grant types: - Password - Refresh Token - Client Credentials In the **Grant Type** drop-down list, select the grant type. > [!NOTE] > > **Password Grant Type** > > [![Password Grant Type]()]() > > 1. In the **Token URL** field, enter the location of the token endpoint that the instance uses to retrieve token. > 2. In the **Username**, **Password**, **Client ID**, and **Client Secret** fields, enter the respective values for OAuth2 authentication. > [!NOTE] > > **Refresh Token Grant Type** > > 1. In the **Grant Type** drop-down list, select **REFRESH\_TOKEN**. > 2. In the **Token URL** field, enter the URL required for OAuth2 authentication. > 3. In the **Refresh Token** field, enter the refresh token for OAuth2 authentication. > 4. In the **Client ID** and **Client Secret** fields, enter the values for OAuth2 authentication. > > > **Note** > > > > To configure OAuth2, refer to the Managed System documentation for detailed instructions. > [!NOTE] > > **Client Credentials Grant Type** > > [![Client Credentials Grant Type]()]() > > 1. In the **Grant Type** drop-down list, select **CLIENT CREDENTIALS**. > 2. In the **Token URL** field, enter the location of the token endpoint that the instance uses to retrieve token. > 3. In the **Client ID**, and **Client Secret** fields, enter the respective values for OAuth2 authentication. ### API Token Authentication > [!NOTE] > > **Screenshot** > > [![API Token Authentication]()]() 1. Select API Token as the **Authentication Type**. 2. Enter the Base64 Encoded value in the **API Token** field. # Integrating SailPoint Generic Service Desk with Any ITSM Ticketing System SailPoint's Generic Service Desk Integration Module (SDIM) enables customers to integrate easily with any Help Desk Solution. The new service desk functionality provides an easy way to: - See a list of integrations - View summaries of the integrations - Create new integrations - Edit/Update existing integrations - Delete integrations This document describes how to configure a Generic Service Desk Integration Module. > [!NOTE] > > To view the latest features, enhancements, and fixes for all SaaS connectors, refer to the [SaaS Release Notes]() page. ## Supported Features - Creation of tickets for manual provisioning operations. - Check status of tickets. - Synchronization of ticket status between the Generic Service Desk Integration Module (SDIM) and ITSM ticketing system. - Retry Mechanism for check ticket status failure. > [!NOTE] > > The Generic Service Desk Integration can be configured as a [SaaS Connection Type]() for SaaS connectivity that doesn't require a Virtual Appliance Cluster. ## Prerequisites > [!IMPORTANT] > > For Service Desk Integration Module to function properly, ensure that the feature flag `GOV_DISABLE_PLAN_INITIALIZER` is set to `true` for your organization. For more information, reach out to [Professional Services/Expert Services](). - 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](). - Know the authentication option (Basic, OAuth 2.0 Authentication, or API Token) to use to authenticate into the ITSM ticketing system. ## Required Permissions - The minimum permissions required for a Service Account user to create and get the status of the ticket using Generic Service Desk varies according to the target ITSM system you want to configure. Refer to the relevant ITSM system documentation for further details. - Admin user level permissions are required to access the Generic Service Desk Integration Module. ## System Requirements - An IT Service Management System with an appropriate REST API for Ticket creation deployed either in your IT environment or in the cloud. - 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: - **ITSM Ticketing System Details:** You can create an integration for your company's ITSM ticketing system if it 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 the ITSM ticketing 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 Generic Service Desk Integration Module. - **Generic Service Desk Integration Module Statuses:** Make a list of each possible status in the ITSM ticketing 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 ITSM ticketing system so that the related provisioning task is also treated as complete. For more information about mapping statuses, refer to your ITSM ticketing system's documentation. - **Requests:** Identify each type of provisioning action in SailPoint that you want to create a ticket for in the ITSM ticketing system, along with the information from those actions that should be included in the related ticket. For more information, refer to your ITSM ticketing system's documentation and API reference. # Retry Configurations > [!IMPORTANT] > > Add a list of retryable error messages to the attributes map of the source configuration. The value must be specified as a list or array even when only a single error string is provided. ## Provisioning Retry Errors > [!NOTE] > > For more information on SailPoint's REST APIs, refer to [Best Practices: REST API Authentication]() and [REST API - Update Source (Partial)]() in the SailPoint Developer Community. SailPoint connectors that support provisioning operations have the ability to retry a failed operation based on configurable error messages. The `retryableErrors` entry in the connector configuration is a list of strings that the connector searches for in the error message received from the managed source. If any of the configured error strings are found in the error message, the connector will attempt to retry the provisioning operation. Add a list of retryable error messages to the attributes map of the source configuration. The value must be specified as a list or array even when only a single error string is provided. If the error message contains one of the specified strings, the connector will initiate a retry attempt. However, if the configured error string is not present in the error message, the connector will consider the operation as failed and will not attempt a retry. Add the following entry in the source XML using the SailPoint REST APIs: For example, Use the SailPoint API by sending a PATCH request to the /v3/sources/{id} endpoint: `PATCH https://{orgName}.api.identitynow.com/v3/sources/:id` In the body of the PATCH, enter the retryable errors as follows: ```json [ { "op": "add", "path": "/connectorAttributes/retryableErrors", "value": [ "", "" ] } ] ``` > [!NOTE] > > Error messages containing very specific information about date/time, sequence ID and so on must be avoided. Error codes or error message substrings would be good candidates for inclusion. # 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]() ## Unable to set custom headers during the creation of a ticket or check the status **Resolution**: You need to manually add the required headers in the request using the REST APIs and update the source. Following are the steps to include headers in the API request: 1. Use [GET]() API to get to the particular SDIM using its Id. 2. Add the header you want under the `provision` to create a ticket or else add the header under the `checkStatus` to check the status of a ticket. For example, to create a ticket add the custom header under `provision` as shown in the body of the request: ```text "id": "8863a433fec3", "name": "xyz Generic SDIM", .... "provision": { .... "headers": { "Accept": "application/json", "Content-Type": "application/json" } } ``` To check status of a ticket add the custom header under `checkStatus` as shown in the body of the request: ```text "generic": { "checkStatus": { .... headers": { "Accept": "application/json", "Content-Type": "application/json" } }, ``` 3. Update the Source using [PUT]() API. ## Unable to pass an empty array through the provisioning plan during ticket creation **Resolution**: The steps to add an empty array so the connector can pass it to the managed system are as follows: 1. Request to enable feature flag on SailPoint: `CON_SDIM_EMPTY_ARRAY_SUPPORT`. 2. Go to **Integration Edit** page. You can enable this feature in two ways: Option 1: Add a Multi-Valued Field in Ticket Creation - Create a multi-valued field with any field name. - Assign a single value with `null` as its value. > **Screenshot** > > [![Multi-valued field with null value]()]() Option 2: Add a Raw JSON Field - Add a raw JSON field with the following value `[null]`. > **Screenshot** > > [![Raw JSON field with null value]()]()