# SailPoint BMC Helix ITSM Service Desk Connector Documentation > BMC Helix ITSM Service Desk Connector Documentation # Documentation # Configuring SailPoint for BMC Helix ITSM Service Desk In SailPoint, configure the following items for your BMC Helix ITSM Service Desk integration: - [Ticket Creation](<#ticket-creation>) - [Status Mapping](<#status-mapping>) - [Requester Source](<#requester-source>) 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 managed BMC Helix ITSM system. You can customize this information by adding fields as required. These tickets contain information that can be used by IT, compliance auditors, and executive management. **Supported Ticket Types:** - Incident - Change Request - Service Request - DWP Service Request (Supported only for BMC Helix ITSM version 21.3) ### Incident > [!NOTE] > > **Screenshot** > > [![Incident ticket creation]()]() Incident Ticket creation requires the following attributes: 1. Enter the **Impact** of the ticket being created. For example: `3-Moderate/Limited`. 2. Provide the default **Status** for the newly created ticket. For example: `New`. 3. Provide the **Description** of the requirement that generated the ticket. 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 ``` 4. Enter the **First Name** and **Last Name** of the user to whom the ticket is assigned. 5. Enter the **Value** of Incident type that generated the ticket. For example: `User Service Request`. 6. Enter the type of source through which this ticket is reported. For example: `Direct Input`. 7. Specify the **Urgency** of this ticket. For example: `3-Medium`. 8. To add a field, select **Add Field**. Select the field type and enter the required information based on the type. Options are Single Value, Multi Valued Field, or Grouped Key-Value Pairs. #### Incident Advanced Properties To add advanced properties to the details of the ticket, select **View Advanced Properties**. > [!NOTE] > > **Screenshot** > > [![Incident advanced properties]()]() 1. Enter the basic JSON root element of the request ticket in the **Request Root Element** field. For example: `values`. 2. Enter the type Request Root Element. For example: `JSONObject`. 3. Enter the resource used for the request ticket in the **Resource** field. Do not include the base URL for the instance in the value. Provide only the remaining directories for the endpoint. For example: `/api/arsys/v1/entry/HPD:IncidentInterface_Create?fields=values(Incident+Number)`. 4. Enter the JSON path expression that indicates the location of the ticket number in the **Response Element** field. For example: `$.values.['Incident Number']`. ### Change Request > [!NOTE] > > **Screenshot** > > [![Change Request ticket creation]()]() Change Request Ticket Creation requires the following fields: 1. The **First Name** and **Last Name** of the user to whom the ticket is assigned. 2. Enter the **Impact** of the ticket being created. For example: `3-Moderate/Limited`. 3. Enter the **Risk Level** of the ticket. For example: `Risk Level 1`. 4. Provide the default **Status** for the newly created ticket. For example: `Draft`. 5. Provide the **Description** of the request that generated the ticket. 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 ``` 6. Specify the **Urgency** of this ticket. For example: `3-Medium`. 7. Enter the **Location Company** as the company name listed on the BMC Helix ITSM portal. For example: `Calbro Services`. > **Note** > > This field is required for Change Request tickets. #### Change Request Advanced Properties To add advanced properties to the details of the ticket, select **View Advanced Properties**. > [!NOTE] > > **Screenshot** > > [![Change Request advanced properties]()]() 1. Enter the basic JSON root element of the request ticket in the **Request Root Element** field. For example: `values`. 2. Enter the type Request Root Element. For example: `JSONObject`. 3. Enter the resource used for the request ticket in the **Resource** field. Do not include the base URL for the instance in the value. Provide only the remaining directories for the endpoint. For example: `/api/arsys/v1/entry/CHG:ChangeInterface_Create?fields=values(Infrastructure+Change+Id)`. 4. Enter the JSON path expression that indicates the location of the ticket number in the **Response Element** field. For example: `$.values.['Infrastructure Change Id']`. ### Service Request > [!NOTE] > > **Screenshot** > > [![Service Request ticket creation]()]() > [!NOTE] > > For more information on Service Request tickets and the Sr Type fields, refer to [Service Requests](). Service Request Ticket creation requires the following attributes: 1. Provide the default **Status** for the newly created ticket. For example: `In Review`. 2. Enter the **First Name** of the user to whom the ticket is assigned. 3. Enter the **Last Name** of the user to whom the ticket is assigned. 4. Specify the service attributes that are used in the fulfillment process. 5. **Z1 D Action** defines what action is performed by the SRM Request Interface REST API. `CREATE` is the only supported option. 6. **Source Keyword** defines the type of ticket that is created by the SRM Request Interface REST API. `Service Request` is the only supported option. 7. Specify the service attributes that are used in the fulfillment process. 8. Provide a value for the **Title Instance Id** for the Service Request Definition. You must also provide different Service Request Fields as entry key parameters into the service desk application, so that those can be passed on to populate the service attributes defined in the **Sr Type Field 1** and **Sr Type Field 14** fields. 9. To add a field, select **Add Field**. Select the field type and enter the required information based on the type. Options are Single Value, Multi Valued, or Grouped Key-Value Pairs. #### Service Request Advanced Properties To add advanced properties to the details of the ticket, select **View Advanced Properties**. > [!NOTE] > > **Screenshot** > > [![Service Request advanced properties]()]() 1. Enter the basic JSON root element of the request ticket in the Request Root Element field. For example: `values`. 2. Enter the type Request Root Element. For example: `JSONObject`. 3. Enter the resource used for the request ticket in the Resource field. Do not include the base URL for the instance in the value. Provide only the remaining directories for the endpoint. For example: `/api/arsys/v1/entry/SRM:RequestInterface_Create?fields=values(Request+Number)`. 4. Enter the JSON path expression that indicates the location of the ticket number in the **Response Element** field. For example: `$.values.['Request Number']`. ### Digital Workplace (DWP) Service Requests > [!NOTE] > > **Screenshot** > > [![DWP Service Request ticket creation]()]() > [!NOTE] > > For more information on DWP Service Request tickets and other fields, refer to [Digital Workplace (DWP) Service Requests](). DWP Service Request Ticket creation requires the following attributes: 1. Enter the login ID of the user for whom the ticket is created. For example: `$!plan.arguments.loginId`. 2. Provide the payload of all the required input **Questions** defined in the Service Definition. Values can be provided for Description and Summary Given from the Service Catalog. You need to add the Question-input IDs based on the Questionnaire Defined in the Service Catalog. To add input values for the question-answer pair, add another `{}` entry to the Questions list. For example: ```json [ { "questionId": "QUESTIONAIRE INPUT ID", "answers": [ "#foreach($req in $plan.requests) #if($req.operation == 'Create') Create Account on application $req.resource #else For $req.id in application $req.resource #end #if($req.items) $newline #foreach($item in $req.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 $!req.Operation Account #end #end" ] }, { "questionId": "QUESTIONAIRE INPUT ID", "answers": [ "SailPoint Access Request $!plan.arguments.identityRequestId #if($plan.arguments.identityName) for the user $plan.arguments.identityName #end" ] } ] ``` 3. Enter the ID of the Service Definition. 4. If required, select **Add Field** to add more fields. Select the field type and enter the required information based on the type. Options are Single Value, Multi Valued, or Grouped Key-Value Pairs. #### DWP Service Request Advanced Properties To add advanced properties to the details of the ticket, select **View Advanced Properties**. > [!NOTE] > > **Screenshot** > > [![DWP Service Request advanced properties]()]() 1. Enter the basic JSON root element of the request ticket in the **Request Root Element**. For example, `JSONObject`. 2. Enter the resource used for the request ticket in the **Resource**. Do not include the base URL for the instance in the value. Provide only the remaining directories for the endpoint. For example, `/api/myit-sb/requests`. 3. Enter the JSON path expression that indicates the location of the ticket number in the **Response Element**. For example, `$.requests[0].['requestId']`. 4. Enter the URL required to submit the DWP Service Request to the BMC Helix ITSM System in the **Submit Order Resource**. For example, `/api/myit-sb/orders`. > [!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](). ## Status Mapping Map the status of the tickets in SailPoint to the corresponding BMC Helix ITSM status. Customize the status map to meet your needs by adding or deleting as needed. 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 BMC Helix SDIM Status** can be whatever is required. > [!NOTE] > > The Status Keys vary by Ticket Type selected. ### Incident Status Keys > [!NOTE] > > **Screenshot** > > [![Incident status mapping]()]() #### Incident Advanced Properties To add more details to the status mapping, select **View Advanced Properties**. > [!NOTE] > > **Screenshot** > > [![Incident status mapping 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. BMC Helix ITSM Service Desk: ```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 ``` ### Change Request Status Keys > [!NOTE] > > **Screenshot** > > [![Change Request status mapping]()]() #### Change Request Advanced Properties To add more details to the status mapping, select **View Advanced Properties**. > [!NOTE] > > **Screenshot** > > [![Change Request status mapping 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. BMC Helix ITSM Service Desk: ```text /api/arsys/v1/entry/CHG:ChangeInterface?q='Infrastructure+Change+ID'=%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.['Change Request Status'] ``` ### Service Request Status Keys > [!NOTE] > > **Screenshot** > > [![Service Request status mapping]()]() #### Service Request Advanced Properties To add more details to the status mapping, select **View Advanced Properties**. > [!NOTE] > > **Screenshot** > > [![Service Request status mapping 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. BMC Helix ITSM Service Desk: ```text /api/arsys/v1/entry/SRM:RequestInterface?q='Request+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 ``` ### DWP Service Request Status Keys > [!NOTE] > > **Screenshot** > > [![DWP Service Request status mapping]()]() #### DWP Service Request Advanced Properties > [!NOTE] > > **Screenshot** > > [![DWP Service Request status mapping 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. For example: ```text /api/myit-sb/services/requests/$ticketId ``` **Response Element**: A JSON path expression that identifies the ticket number in the response from the REST endpoint. For example: ```text $.status.status ``` ## Requester Source > [!NOTE] > > **Screenshot** > > [![Requester Source]()]() In the Requester Source dropdown, select the source name through which BMC Helix ITSM Service Desk system's users are aggregated. # Connecting SailPoint and BMC Helix ITSM Service Desk The BMC Helix SDIM connection performs effective and efficient service management for SailPoint services offered to the organization in BMC Helix ITSM Service Desk and enables you to create and manage tickets reported from other SailPoint sources. > [!NOTE] > > BMC Helix ITSM Service Desk SDIM supports Incident, Change Request, Service Request, DWP Service Request ticket types. **To create the connection:** 1. Sign in to **SailPoint \> Admin interface**. 2. Go to **Connections \> Service Desk**. The Service Desk connections page displays. 3. 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. ## 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. From the **Integration Type** drop-down list, select **BMC Helix ITSM SDIM**. 4. Select the ticket type you want to create from the **Ticket Type** drop-down list. The options are: Incident, Change Request, Service Request, and DWP Service Request. 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 BMC Helix ITSM 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 BMC Helix ITSM Service Desk integration. ## Connectivity and Authentication BMC Helix ITSM supports AR-JWT and OAuth2 as Authentication Types. > [!NOTE] > > **Screenshot** > > [![Connectivity and Authentication]()]() 1. Enter the URL of the REST API endpoint for BMC Helix ITSM server. For example, `https://{serverName}-restapi.onbmc.com`. 2. Select **AR-JWT** or **OAuth2** for Authentication Type. 3. Complete the authentication steps: - [AR-JWT Authentication](<#ar-jwt-authentication>) - [OAuth2 Authentication](<#oauth2-authentication>) ### AR-JWT Authentication > [!NOTE] > > **Screenshot** > > [![AR-JWT Authentication]()]() 1. Enter the **Username** and **Password** of the BMC Helix ITSM user. 2. Enter the Token URL required to generate an access token. The Token URL is the REST API endpoint for BMC Helix ITSM server. For example, AR-JWT for BMC Helix ITSM will be `https://{serverName}-restapi.onbmc.com/api/jwt/login`. ### OAuth2 Authentication > [!NOTE] > > **Screenshot** > > [![OAuth2 Authentication]()]() 1. Select REFRESH\_TOKEN as the **Grant Type**. 2. Enter the Token URL required for OAuth2 authentication. The Token URL is the RSSO endpoint for the BMC Helix ITSM server. For example, `https://{serverName}-rsso.onbmc.com/rsso/oauth2/token`. 3. Enter the required value for **Refresh Token**. 4. Enter the **Client ID** and **Client Secret** values of the connected app. # Digital Workplace (DWP) Service Requests BMC Helix SDIM is certified for BMC Helix ITSM version 21.3 and now supports Digital Workplace (DWP) Service Request. ## Prerequisites For more information on the BMC Helix Digital Workplace Catalog REST APIs, see the [Endpoints in the BMC Helix Digital Workplace Catalog REST API]() page. - Create a Service Request Definition / Catalog or use an existing one, create a Workflow, and create a Questionnaire based on the workflow as a part of Service Request Definition. - Create a dummy Service Request to get the IDs of the questionnaire associated with a particular ServiceId. - Execute the following REST APIs to get the values for the Service Request Payload: - Use the following API to fetch the serviceId (service/definition IDs) in the BMC Helix ITSM 21.3 environment: `GET https://{{server}}/api/myit-sb/services`, where `myit-sb` is the default scope. - Use the following API to initiate a Service Request: `POST https://{{server}}/api/myit-sb/requests`, where `myit-sb` is the default scope. Request Body: ```json { "serviceId": "", "requestForUserIds": [ "User ID" ] } ``` - The Service request Id received in "Get Services List" API should be added as "serviceId" in "Initiate a Service Request" API. `GET https://{{server}}/api/myit-sb/requests//questionnaire`. The response contains the question IDs, type, and label. This provides the details for the service request payload. # Integrating SailPoint with BMC Helix ITSM 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. > [!NOTE] > > **Notes** > > - The configuration of BMC Helix ITSM Service Desk requires SailPoint Services hours or Partner involvement. For more information, contact SailPoint Customer Support. > - The BMC Helix ITSM Service Desk Integration supports Incident, Change Request, Service Request, and DWP Service Request ticket types. > - All activity on the Service Desk source appears as events in Search and on the Activity tab of an identity. For more information, refer to [Using Search - Events](). > [!NOTE] > > To view the latest features, enhancements, and fixes for all SaaS connectors, refer to the [SaaS Release Notes]() page. SailPoint's BMC Helix ITSM Service Desk connector integrates with BMC Helix ITSM for service to bring the BMC Helix ITSM experience to SailPoint where the users can raise and track service desk tickets to their logical closure without leaving SailPoint. > [!NOTE] > > For support, SailPoint requires the organization to provide access to its BMC sandbox or development environment. [![Service desk integration process flow]()]() 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 ## Supported Features SailPoint's BMC Helix ITSM Service Desk Integration Module (SDIM) supports the following features: - Creation of tickets for manual provisioning operations and status check. - Synchronization of ticket status between SailPoint's BMC Helix ITSM Service Desk Integration Module (SDIM) and the BMC Helix ITSM Service Desk system. - The supported operations are: - List - View - Create - Edit/Update - Delete - Digital Workplace (DWP) Service Requests when using BMC Helix ITSM Version 21.3 or later. For more information, refer to [DWP Service Request](). > [!NOTE] > > The BMC Helix ITSM Service Desk Integration can be configured as a [SaaS Connection Type]() for SaaS connectivity that doesn't require a Virtual Appliance Cluster. ## System Requirements The BMC Helix ITSM Service Desk Integration Module (SDIM) supports the following BMC products: - For Cloud Environments: - BMC Helix ITSM 22.1 - BMC Helix ITSM 21.3 - 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. ## 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](). - Configure a Delimited File connector to aggregate all the People records (BMC Helix ITSM Users) from the BMC Helix ITSM system and use it as a **Requester Source** during configuration. For more information, refer to [Requester Source](). Following is the list of attributes you need for the Delimited File connector in addition to any other attributes that are marked as mandatory within the BMC Helix ITSM system: - RemedyLoginID - FirstName - LastName - Company - InternetEmail - PersonID - Determine the authentication option (AR-JWT or OAuth2 Authentication) you want to use to authenticate to the BMC Helix ITSM system. The BMC Helix ITSM Service Desk uses Remedy Single Sign-On (Remedy SSO) for OAuth2 authentication. For more information about installation and setup, refer to [Installing Remedy SSO](). ## Required Permissions The BMC Helix ITSM Service Desk Integration Module (SDIM) service account requires the following application permissions: - Incident Master Application permission for Incident Management application. - Infrastructure Change Master application permission for Change Management application. - SRM Administrator application permission for Service Request Management application. - SailPoint Admin user level permissions to create and configure BMC Helix ITSM Service Desk connections. See [Granting and Removing User Level Permissions]() for more information about setting user level permissions. - BMC Helix Digital WorkPlace (BMC DWP) Administrator application permission for DWP Service Request Management application. ## Best Practices Before you start the configuration process, you should make decisions about the following components of this integration: - **Identify** - Find the BMC Helix ITSM 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 BMC Helix ITSM Service Desk system and the sources used in the connection. - **BMC Helix ITSM Details** - You can create an integration for each BMC Helix ITSM 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 BMC Helix ITSM 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 BMC Helix ITSM Service Desk Integration Module. - **BMC Helix ITSM Statuses** - Make a list of each possible status in the BMC Helix ITSM 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 BMC Helix ITSM 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 BMC Helix ITSM Service Desk system, along with the information from those actions that should be included in the related BMC Helix ITSM Service Desk system ticket. For more information, refer to [Ticket Creation](). # Service Requests When you want to create Service Request ticket types in the BMC Helix ITSM Service Desk system, create a new service offering (for example, SailPoint Access Request) represented by a service request definition (SRD) on the BMC Helix ITSM side. For more information, refer to [Creating Services](). ## Service Request Designer and Service Request Definitions The Service Request Designer leads you through the process of defining and deploying a service, which can be requested by users, and is then fulfilled using the selected fulfillment process. Defining the service entails the following: - Describing the service to the users - Setting service attributes related to the turnaround time, and price - Selecting a process to fulfill the service request (for example, "Generic - Create Incident") - Defining the questions to pose to the users - Defining the service attributes that are used in the fulfillment process (e.g. 'SR Type Field 1' or 'SR Type Field 14' or any other custom attributes) - Defining which users are entitled to request the service - Defining who will approve the service request - Setting the user display and notification preferences - Deploying the service For more information on creating Service Request Definitions (SRD), refer to [Creating service request definitions: Basic configuration](). You need to provide the value of `InstanceID` for the Service Request Definition into the `Title Instance Id` parameter on the [Ticket Creation]() panel. You also need to provide different Service Request Fields as entry key parameters into the service desk application, so that those can be passed on to populate the service attributes defined in the fulfillment process on the Service Request Definition. > [!NOTE] > > Different Service Request Fields have different character limits, so ensure that you have mapped them accordingly for the payload data you want to send. For example, for SR Type Field 1: ```text SailPoint Access Request $!plan.arguments.identityRequestId #if($plan.arguments.identityName) for the user $plan.arguments.identityName #end ``` For example, for SR Type Field 14: ```text #foreach($req in $plan.requests) #if($req.operation == 'Create') Create Account on application $req.resource #else For $req.id in application $req.resource #end #if($req.items) $newline #foreach($item in $req.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 $!req.Operation Account #end #end ``` # Enable Connector Logging This topic provides the steps needed to enable logging on SailPoint using REST APIs. > [!NOTE] > > This topic only applies to VA-based integrations. > [!NOTE] > > The examples provided might not match your configuration. Use the logging levels and logging classes reference at the bottom of the topic to configure your API responses to match your connector. This process is broken up into four steps: 1. Identify the Virtual Appliance (VA) cluster on which you want to enable logging. 2. Get the logging configuration for the existing VA cluster. 3. Update the VA cluster to enable logging levels. 4. Observe logging changes to the logging levels. ### Identify the Virtual Appliance Cluster Select the VA on which you need to enable logging using REST API. If you already know the VA application's `id`, proceed to [Get the Logging Configuration](<#get-the-logging-configuration>). 1. Make the following call to the REST API to return a list of available VA clusters: GET /v3/managed-clusters The REST API returns a response that looks similar to the following: ```json [ { "id": "2c9180866166b5b0016167c32ef31a66", "name": "Development Cluster", "description": "Development Cluster", "clientType": "CCG", "ccgVersion": "373_535_70.2.0", "pinnedConfig": true, "logConfiguration": null }, { "id": "2c9180846a93ce60016ab29f039944de", "name": "Cloud Cluster", "description": "Cloud Cluster", "clientType": "CCG", "ccgVersion": "373_535_70.2.0", "pinnedConfig": true, "logConfiguration": { "clientId": null, "durationMinutes": 60, "expiration": "2020-12-15T19:13:36.079Z", "rootLevel": "DEBUG", "logLevels": { "sailpoint.connector.ADLDAPConnector": "DEBUG" } } } ] ``` > **Note** > > The previous example code shows two VA clusters. One VA cluster has a log configuration and the other does not (refer to the `logConfiguration` value in each returned VA cluster). This is because one of the clusters already has logging enabled. This is just an example configuration, and your environment may not have logging enabled on a cluster. 2. Identify the VA cluster that you want to enable logging on by its name or description and record its `id` attribute. ### Get the Logging Configuration Get your selected VA's cluster logging configuration and identify the values you need to update. 1. Make the following call to the REST API to return the VA cluster's logging configuration. Replace `{id}` with the VA cluster's `id` attribute value recorded earlier. GET /v3/managed-clusters/{id}/log-config - If the VA doesn't have a logging configuration currently set, it returns `204 No Content` as a response. - If the VA has an existing logging configuration, it returns something similar to the following: ```json { "clientId": null, "durationMinutes": 60, "expiration": "2020-12-15T19:13:36.079Z", "rootLevel": "DEBUG", "logLevels": { "sailpoint.connector.ADLDAPConnector": "DEBUG" } } ``` You'll need to configure the following information in the response: - `durationMinutes` is the number of minutes logging should remain enabled. - `rootLevel` is the default level for all logs. For more information, refer to [Logging Levels](<#logging-levels>). - `logLevels` is a map object with logging classes as keys and logging levels as values. - For keys, refer to [Logging Classes](<#logging-classes>) for commonly used logging classes. - For a list of available values, refer to [Logging Levels](<#logging-levels>). ### Update Logging Configuration Update the VA cluster configuration returned by the REST API to update the logging settings as needed. 1. Make the following call to the REST API to update the VA cluster's logging configuration. Replace `{id}` with the VA cluster's `id` attribute value recorded earlier. PUT /v3/managed-clusters/{id}/log-config 2. Submit your configuration changes to the REST API in a JSON body. - If the VA cluster did not already have a logging configuration and you received a `204 No Content` response, you can create a new one. - If the VA returned a configuration, you can edit it to include the changes. The JSON body should be as follows: ```json { "durationMinutes": 60, "rootLevel": "DEBUG", "logLevels": { "sailpoint.connector.ADLDAPConnector": "DEBUG" } } ``` Consider the following as you edit the JSON: - `durationMinutes` is the number of minutes logging should remain enabled. - `rootLevel` is the default level for all logs. For more information, refer to [Logging Levels](<#logging-levels>). - `logLevels` is a map object with logging classes as keys and logging levels as values. - For keys, refer to [Logging Classes](<#logging-classes>) for commonly used logging classes. - For a list of available values, refer to [Logging Levels](<#logging-levels>). If the update was successful, the REST API should return a response similar to the following: ```json { "clientId": null, "durationMinutes": 60, "expiration": "2020-12-15T19:13:36.079Z", "rootLevel": "DEBUG", "logLevels": { "sailpoint.connector.ADLDAPConnector": "DEBUG" } } ``` ### Observe Logging Changes Approximately five minutes after you update the configuration, the VA cluster starts generating log files you can review. You can view the log files in **ccg.log**. ### References The tables in this reference section list information that can be helpful when creating the JSON body you'll use to configure the VA cluster's configuration file. #### Logging Levels | Logging Level | Description | | --- | --- | | ERROR | Designates error events that might still allow the connector to continue. | | WARN | Designates potentially harmful situations. | | INFO | Designates information messages that highlight process at a coarse-grain level. | | DEBUG | Very verbose. Fine grain logging levels used for development and debugging. | | TRACE | Most verbose. Finer grain logging levels than debugging. | #### Logging Classes | Connector | Logging Class | | --- | --- | | Active Directory | sailpoint.connector.ADLDAPConnector sailpoint.connector.LDAPConnector | | AIX | openconnector.connector.unix.AIXConnector openconnector.connector.unix.UnixConnector | | Amazon Web Services | logger.aws.name=openconnector.connector.aws logger.aws.level=trace logger.aws.additivity = false logger.aws.appenderRef.rolling.ref = STDOUT | | Atlassian Suite Cloud | sailpoint.connector.OpenConnectorAdapter openconnector.connector.atlassian.AtlassianConnector | | Atlassian Data Center | sailpoint.connector.OpenConnectorAdapter openconnector.connector.atlassian.AtlassianDataCenterConnector | | Microsoft Entra ID | sailpoint.connector.AzureADConnector | | Box | openconnector.connector.BoxNetConnector sailpoint.connector.OpenConnectorAdapter | | Cerner | openconnector.connector.CernerConnector sailpoint.connector.OpenConnectorAdapter | | Delimited File | logger.DelimitedFileConnector.name = sailpoint.connector.DelimitedFileConnector logger.DelimitedFileConnector.level = debug logger.DelimitedFileConnector.additivity = false logger.DelimitedFileConnector.appenderRef.rolling.ref = STDOUT | | Dropbox | openconnector.connector.DropBoxConnector sailpoint.connector.OpenConnectorAdapter | | Epic | openconnector.connector.EPICConnector sailpoint.connector.OpenConnectorAdapter | | GE Centricity | openconnector.connector.GECentricity sailpoint.connector.OpenConnectorAdapter | | Google Apps / G Suite | openconnector.connector.GoogleAppsDirect sailpoint.connector.OpenConnectorAdapter | | IBM i | openconnector.connector.IBMiConnector | | Lotus Domino | sailpoint.connector.LotusDomino | | JDBC | sailpoint.connector.JDBCConnector | | Sun One LDAP | sailpoint.connector.LDAPConnector | | Linux | openconnector.connector.unix.LinuxConnector sailpoint.connector.OpenConnectorAdapter sailpoint.connector.UnixConnector | | Microsoft Office365 | sailpoint.connector.Office365Connector | | Microsoft SQL Server | sailpoint.connector.mssql.serviceimpl.MSSQLServerConnectorV2 | | Okta | logger.openconnector.name = openconnector.connector.okta.OktaConnector logger.openconnector.level = debug logger.openconnector.additivity = false logger.openconnector.appenderRef.rolling.ref = STDOUT | | Oracle Database | sailpoint.connector.OracleDBConnector sailpoint.connector.JDBCConnector | | Oracle E-Business | sailpoint.connector.OracleEBSConnector sailpoint.connector.JDBCConnector | | Oracle Fusion HCM | openconnector.connector.oraclefusionhcm.OracleFusionHCMConnector sailpoint.connector.OpenConnectorAdapter | | Oracle HCM Cloud | sailpoint.connector.oraclehcmcloud.OracleHCMCloudConnector | | Oracle HRMS | sailpoint.connector.OracleAppsHRMSConnector sailpoint.connector.JDBCConnector | | Oracle Netsuite | openconnector.connector.netsuite.NetsuiteConnector | | PeopleSoft ERP | openconnector.connector.PeopleSoftConnector sailpoint.connector.OpenConnectorAdapter | | PeopleSoft HRMS | sailpoint.connector.PeopleSoftHRMSConnector | | RemedyForce | sailpoint.connector.ForceConnector | | RSA Authentication Manager | openconnector.connector.RSAConnector openconnector.connector.rsa.RSAHTTPClient sailpoint.connector.OpenConnectorAdapter | | Salesforce | sailpoint.connector.ForceConnector | | SAP Concur | openconnector.connector.sapconcur.SAPConcurConnector | | SAP - Direct | sailpoint.connector.SAPConnector sailpoint.connector.SAPInternalConnector | | SAP GRC | logger.SAPGRCConnector.name = sailpoint.connector.sapgrc logger.SAPGRCConnector.level = debug logger.SAPGRCConnector.additivity = false logger.SAPGRCConnector.appenderRef.rolling.ref = STDOUT | | SAP HR/HCM | sailpoint.connector.SAPHRInternalConnector | | SCIM 1.1 | openconnector.connector.SCIMConnector sailpoint.connector.OpenConnectorAdapter | | SCIM 2.0 | openconnector.connector.scim2.SCIM2Connector sailpoint.connector.OpenConnectorAdapter | | ServiceNow | openconnector.connector.servicenow.ServiceNowConnector openconnector.connector.servicenow.ServiceNowRestClient sailpoint.connector.OpenConnectorAdapter | | ServiceNow Service Desk Integration | openconnector.connector.servicedesk.ServiceNowServiceDeskConnector sailpoint.connector.OpenConnectorAdapter | | Siebel | openconnector.connector.SiebelConnector sailpoint.connector.OpenConnectorAdapter | | Snowflake | openconnector.connector.snowflake.SnowflakeConnector sailpoint.connector.OpenConnectorAdapter | | Solaris | openconnector.connector.unix.SolarisConnector openconnector.connector.unix.UnixConnector sailpoint.connector.OpenConnectorAdapter | | SuccessFactors | sailpoint.connector.SuccessFactorsConnector | | Sybase | sailpoint.connector.SybaseDirectConnector sailpoint.connector.JDBCConnector | | Webex | openconnector.connector.Webex sailpoint.connector.OpenConnectorAdapter | | Workday | openconnector.connector.WorkDay sailpoint.connector.OpenConnectorAdapter | | Workday Accounts | openconnector.connector.workdayaccounts openconnector.connector.workdayaccounts.WorkdayAccountsConnector sailpoint.connector.OpenConnectorAdapter | | Web Services | sailpoint.connector.WebServices | | XML | openconnector.connector.XMLConnector sailpoint.connector.OpenConnectorAdapter | | Yammer | openconnector.connector.YammerConnector sailpoint.connector.OpenConnectorAdapter | | Zoom | openconnector.connector.zoom.ZoomConnector sailpoint.connector.OpenConnectorAdapter | # 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]() ## The following error message appears if the provisioning status map is not defined ```text InvalidConfigurationException ] [ Error details ] SailPoint Identity Platform provisioning status is not defined against the IT Service Management status 'Resolved' in the check status configuration 'statusMap' for the 'incident' ticket type. ``` **Resolution**: Ensure that you configure the mapping of ticket statuses under the Status Mapping section. ## The following error message appears if the InstanceID for the given Service Request Definition (SRD) does not exist ```text sailpoint.connector.ConnectorException: [ ConnectorException ] [ Error details ] Request execution failed. [{"messageType":"ERROR","messageText":"No item matches filter conditions --\nthis operation has been defined so that \"No Match\" generates an error.","messageAppendedText":null,"messageNumber":380}]. Status: 500 ``` **Resolution**: Provide the correct value of `InstanceID` for the given Service Request Definition (SRD) is present for the `Title Instance Id` parameter. # Timeout Errors and Settings Timeout errors might occur when SailPoint is waiting for a response from the Virtual Appliance (VA). These errors are applicable to all connectors and tend to occur during the setup of sources or when sources are down. This document is designed to give specific information that can be used to resolve these errors. Each timeout attribute has a default time value that is listed in seconds or minutes. Increasing the time value may resolve the error as it will allow for longer communication time between the two systems, thus avoiding the timeout error. > [!IMPORTANT] > > Add the necessary attributes or values before performing the "replace" operation, as missing attributes will cause the operation to fail. To increase the communication time, increase the value of the appropriate timeout attribute. Then submit the change to the VA using the SailPoint REST API. > [!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. ### aggregateTimeout **Description:** This parameter is set for the aggregation timeout, measured in seconds. **Resolution:** Increase the `aggregateTimeout` value gradually to optimize aggregation. Start with 180, then increase to 600, 900, and finally 1800. The maximum value is 3600 seconds. For example: If your current time value is 180 seconds, update the `aggregateTimeout` attribute as follows: ```json [ { "op": "replace", "path": "/connectorAttributes/aggregateTimeout", "value": 600 } ] ``` ### healthCheckTimeout **Description:** This parameter is set for the test connection and health check timeout. **Resolution:** The default value is 30 seconds. If the timeout error continues, increase the value in 15 second increments and try again. For example: If your current time value is 30 seconds, update the `healthCheckTimeout` attribute as follows: ```json [ { "op": "replace", "path": "/connectorAttributes/healthCheckTimeout", "value": 45 } ] ``` ### provisioningTimeout **Description:** This parameter is set for provisioning timeout. **Resolution:** Increase the `provisioningTimeout` value gradually to optimize provisioning. Start with 180, then increase to 360, and finally 600. The maximum value is 600 seconds. For example: If your current time value is 180 seconds, update the `provisioningTimeout` attribute as follows: ```json [ { "op": "replace", "path": "/connectorAttributes/provisioningTimeout", "value": 360 } ] ``` ### timeout **Description:** This parameter is set for pass-through authentication timeout. **Resolution:** The default value is 15 seconds. If the timeout error continues, increase this value in 15 second increments and try again. For example: If your current time value is 15 seconds, update the `timeout` attribute as follows: ```json [ { "op": "replace", "path": "/connectorAttributes/timeout", "value": 30 } ] ``` ### apiTimeout **Description:** This parameter is set for API time tracking; customers can check it using an external tool. **Resolution:** The default value is 60 seconds. If the error continues, increase the value by 15 second increments and try again. For example: If your current time value is 60 seconds, update the `apiTimeout` attribute as follows: ```json [ { "op": "replace", "path": "/connectorAttributes/apiTimeout", "value": "75" } ] ``` ### timeoutInSeconds **Description:** This parameter helps prevent the VA from waiting indefinitely for an API response, ensuring efficient handling of API requests. For example: If your current time value is 30 seconds, update the `timeoutInSeconds` attribute as follows: ```json [ { "op": "replace", "path": "/connectorAttributes/timeoutInSeconds", "value": "15" } ] ```