# SailPoint Atlassian Data Center Jira Service Management Connector Documentation > Atlassian Data Center Jira Service Management Connector Documentation # Documentation # Configuring SailPoint for Atlassian Data Center Jira Service Management In SailPoint, configure the following items for your Atlassian Data Center Jira Service Management Integration Module: - [Ticket Creation](<#ticket-creation>) - [Create Ticket Advanced Properties](<#create-ticket-advanced-properties>) - [Status Mapping](<#status-mapping>) - [Status Mapping Advanced Properties](<#status-mapping-advanced-properties>) - [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 In a centralized approach spanning many users and resources to strengthen IT controls and provide proof of compliance to auditors and executive management, you can create a ticket for your integration, based on your requirement. A ticket has all relevant data filed for further processing. > [!NOTE] > > Atlassian Data Center Jira Service Management Integration Module supports only Service Request, Incident, and Change Request. The contents of a service request, incident, or change request define the components of the SailPoint provisioning task that are added to the Atlassian Data Center Jira Service Management system ticket. SailPoint recommends that you include the Apache Velocity variables as needed to meet your requirements. > [!NOTE] > > **Screenshot** > > [![Ticket Creation]()]() 1. Enter the **Raise On Behalf of** for the ticket you are creating. The default value is: ```text $!{plan.arguments.opened_by|'Default_Jira_Account_ID'} ``` To modify `Default_Jira_Account_ID` do one of the following: - Replace the `Default_Jira_Account_ID` with the service account name for the Jira user from the Requester Source. - Replace the `Default_Jira_Account_ID` with a Jira user's account name that you want to use as the reporter's name for the ticket generated by this integration. 2. Enter the **Service Desk Id** in the Atlassian Data Center Jira Service Management system. To obtain the Service Desk Id, execute the following request from POSTMAN with valid credentials. Use the ID from response and enter it into the Service Desk Id field. If Jira is installed to run in a non-root context path (i.e. it has a context path), the URL also must include this context path. For example, if Jira is running at `http://www.foobar.com/Jira` then the URL must be `GET http://www.foobar.com/Jira/rest/servicedeskapi/servicedesk`. 3. Enter the ID of each request type. For example, `ServiceRequest:1`, `Incident:14`, and `ChangeRequest:15`. Ensure that the Request Type ID belongs to the same project that is used. To obtain the Request Type ID, execute the following request from POSTMAN with valid credentials. For example, if Jira is running at `http://www.foobar.com/Jira` the URL must be `GET http://www.foobar.com/Jira/rest/servicedeskapi/servicedesk/{serviceDeskId}/requesttype`. 4. Complete the following in the **Request Field Values**: 1. In **Description**, enter the main body of the request in the Atlassian Data Center Jira Service Management system that includes the details about the request. 2. In **Summary**, enter the title or summary of the request in the Atlassian Data Center Jira Service Management system. #### Add a 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 - 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 Atlassian Data Center Jira Service Management 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 the Velocity Template Expression. > [!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 Select **View Advanced Properties** to add other details of the ticket. > [!NOTE] > > **Screenshot** > > [![Create Ticket Advanced Properties]()]() 1. Enter the **Resource** used for the request ticket. This is the ticket creation REST endpoint. Do not provide the base URL in the value. The base URL is appended to this endpoint value. Enter only the remaining endpoint URL. For example, `/rest/servicedeskapi/request`. 2. Enter the **Response Element** for the request ticket. This value is the JSON path expression that provides information about where to find a ticket number. For example, `$.issueKey`. 3. Select **Save**. ## Status Mapping You can map the status of the service request to the corresponding status of activity on the Atlassian Data Center Jira Service Management system. Select **Add Status** to add another row for status mapping. > [!NOTE] > > **Screenshot** > > [![Status Mapping]()]() For SailPoint, the status types are: - Committed - Queued - Failed For the Atlassian Data Center Jira Service Management managed system, the types of status are dependent upon request type. ### Status Mapping for Service Request | Entry Key on Atlassian Data Center Jira System | SailPoint Values | | --- | --- | | Canceled | Failed | | Waiting for support | Queued | | Waiting for customer | Queued | | Escalated | Queued | | In Progress | Queued | | Pending | Queued | | Closed | Committed | | Resolved | Committed | ### Status Mapping for Incident | Entry Key on Atlassian Data Center Jira System | SailPoint Values | | --- | --- | | Closed | Committed | | Canceled | Failed | | Work In Progress | Queued | | Open | Queued | | Pending | Queued | | Completed | Committed | ### Status Mapping for Change Request | Entry Key on Atlassian Data Center Jira System | SailPoint Values | | --- | --- | | Planning | Queued | | Implementing | Queued | | Canceled | Failed | | Declined | Failed | | Peer review/ change manager approval | Queued | | Resolved | Committed | | Closed | Committed | | Pending | Queued | | Awaiting CAB approval | Queued | | Awaiting Implementation | Queued | ### Check Status Interval You can add and delete a status as per your organizational needs. The Atlassian Data Center Jira Service Management Integration Module 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 tickets]() - [Updating the time check configuration of queued tickets]() ### Status Mapping Advanced Properties Select **View Advanced Properties** to add other details of the status mapping. > [!NOTE] > > **Screenshot** > > [![Status Mapping Advanced Properties]()]() 1. Enter the **Resource** used for the status mapping. For example, `/rest/servicedeskapi/request/$ticketId`. 2. Enter the **Response Element** for the status mapping. This value is the JSON path expression that has information on the service request status. For example, `$.currentStatus.status`. 3. Select **Save**. ## Customize Ticket Fields > [!IMPORTANT] > > Contact SailPoint Services for setting up a Before Provisioning rule for your integration. You can customize the ticket fields based on your requirements. You can set up a Before Provisioning rule to generate ticket fields. Create a new 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](). ## Requester Source > [!NOTE] > > **Screenshot** > > [![Requester Source]()]() 1. In the **Requester Source** field, enter the source name through which the Atlassian Data Center Jira Service Management system's users are aggregated. 2. Select **Save**. # Connecting SailPoint and Atlassian Data Center Jira Service Management The Atlassian Data Center Jira Service Management Service Desk Integration Module helps to perform effective and efficient service management for SailPoint services offered to the organization in the Atlassian Data Center Jira Service Management system and enables customers to create and manage service requests, incidents, and change requests. You can integrate a SailPoint source with an Atlassian Data Center Jira Service Management system for access request and monitor it. To create an integration, on the **Service Desk Integrations** page: 1. Go to **Admin \> Connections \> Service Desk**. 2. Select **Create**. [![Service desk integration process flow]()]() ## General Settings The following are the steps to set up an 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 are 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 `Atlassian Data Center SDIM` for the **Integration Type**. 4. Select the **Ticket Type**. 5. Select **VA-Based** for the **Connection Type**. > **Note** > > Once you create an integration, you cannot edit the connection type. 6. Select the **Virtual Appliance Cluster** to assign to the integration. 7. Enter the name of the **Integration Owner**. ### VA-Based Connection Type The Atlassian Data Center Jira Service Management integration supports only the VA-based connection type. > [!NOTE] > > **Screenshot** > > [![VA-Based Connection Type]()]() 1. Select **VA-Based** to use a Virtual Appliance Cluster. 2. Select **Save**. ### 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 Atlassian Data Center Jira Service Management system, verify that it is configured for provisioning. > [!TIP] > > Edit the **Description** field for these sources to indicate they are used in the Atlassian Data Center Jira Service Management integration. ## Connectivity and Authentication Following are the steps to connect and authenticate your Atlassian Data Center Jira Service Management system with SailPoint: 1. In the **URL** field, enter the URL of the Atlassian Data Center Jira Service Management system that you want to integrate with. > **Note** > > If Jira is installed to run in a non-root context path (that is, it has a context path), the URL also must include this context path. For example, if Jira is running at `http://www.foobar.com/Jira` then the URL must be `http://www.foobar.com/Jira`. 2. Choose the appropriate **Authentication Type** and provide the information required to connect and interact with the source. - [Basic Authentication](<#basic-authentication>) - [Personal Access Token Authentication](<#personal-access-token-authentication>) ### Basic Authentication > [!NOTE] > > **Screenshot** > > [![Basic Authentication]()]() 1. Select the **Basic** as the authentication type. 2. Enter the **Username** and **Password** to authenticate with the source. 3. Select **Save**. ### Personal Access Token Authentication > [!NOTE] > > **Screenshot** > > [![Personal Access Token Authentication]()]() 1. Select the **Personal Access Token** as the authentication type. 2. Enter the created **Personal Access Token** to authenticate with the source. 3. Select **Save**. > [!NOTE] > > For more information, refer to [Generating a new Personal Access Token in Atlassian documentation](). # Integrating SailPoint with Atlassian Data Center Jira Service Management > [!NOTE] > > **Integration** > > This is an integration and requires additional licensing or subscriptions to utilize it. For more information, contact your customer success manager. Atlassian Data Center Jira Service Management is a software platform that supports IT service management and automates common business processes for requesting and fulfilling service requests across a business enterprise. 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 guide describes how to configure a Service Desk Integration Module. It converts SailPoint provisioning actions into tickets in Atlassian Data Center Jira Service Management system. > [!NOTE] > > - You must have an active SailPoint Atlassian Data Center Jira license to use this integration. Contact your Customer Success Manager (CSM) for more information. > - The Atlassian Data Center Jira Service Management Integration supports only the Service Request, Change Request, and Incident 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. ## Supported Features - Creation of tickets for manual provisioning operations and status check. - Synchronization of ticket status between the Atlassian Data Center Jira Service Management Integration Module and Atlassian Data Center Jira Service Management system. - Retry Mechanism for check ticket status failure. - Populating comments on the Access Request page as a part of Access Provisioning. ## 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](). ## Required Permissions The minimum project role and application access required for a user to create and get the status of a ticket using an IT service management type project are as follows: - Add Service Desk Team as a Project role to an Agent ## System Requirements The connector supports the following managed systems: - Atlassian Data Center Jira Service Management version 10.3.1 - Atlassian Data Center Jira Service Management version 5.15.0 - 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 Atlassian Data Center Jira Service Management 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 Atlassian Data Center Jira Service Management system and the sources used in the connection. - **Atlassian Data Center Jira Service Management Details** - You can create an integration for each Atlassian Data Center Jira Service Management 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 Atlassian Data Center Jira Service Management 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 Atlassian Data Center Jira Service Management Integration Module. - **Atlassian Data Center Jira Service Management Statuses** - Make a list of each possible status in the Atlassian Data Center Jira Service Management 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 Atlassian Data Center Jira Service Management 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 Atlassian Data Center Jira Service Management system, along with the information from those actions that should be included in the related Atlassian Data Center Jira Service Management system ticket. For more information, refer to [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 `Service Request` ticket type:** When the ticket type is `Service Request`, modify the value of the **Description** field to include comments as shown below in bold: ```velocity #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') 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 #else $newline $!req.Operation Account #if ($request.arguments.comments), Comment from SailPoint : $request.arguments.comments #end $newline #end #end ``` **For the `Change Request` ticket type:** When the ticket type is `Change Request`, modify the value of the **Description** field to include comments as shown below in bold: ```velocity #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') 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 #else $newline $!req.Operation Account #if ($request.arguments.comments), Comment from SailPoint : $request.arguments.comments #end $newline #end #end ``` **For the `Incident` ticket type:** When the ticket type is `Incident`, modify the value of the **Description** field to include comments as shown below in bold: ```velocity #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') 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 #else $newline $!req.Operation Account #if ($request.arguments.comments), Comment from SailPoint : $request.arguments.comments #end $newline #end #end ``` # 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]() ## A message appears if provisioning status map is not defined 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 'serviceRequest' ticket type. ``` **Resolution** - Ensure that you configure the mapping of ticket statuses. ## A message appears when a user who is not a Jira member tries to create a ticket The following error message appears when a user who is not a Jira member tries to create a ticket: ```text {"errorMessage":"Your request could not be created. Please check the fields have been correctly filled in. is not a valid email address","i18nErrorMessage": {"i18nKey":"sd.validation.request.creation.failure.required.field","parameters":[" is not a valid email address"]} ``` **Resolution** - Ensure that the user requesting the ticket is a member on Jira Service Management. # Using Integrations ## Listing Integrations To list the SailPoint Atlassian Data Center Jira Service Management 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 Atlassian Data Center Jira Service Management 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 Atlassian Data Center Jira Service Management 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 Atlassian Data Center Jira Service Management 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 Atlassian Data Center Jira Service Management 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. ## Configuring Integration for Jira Project Filtering To assign Jira projects to incoming tickets, configure the following: 1. Modify the Before Provisioning Rule to contain the logic to filter which Jira project the tickets are assigned to. For example, you can have a use case where you create tickets in a Jira project with an ID of `33` where the application is Slack, and a Jira project with an ID of `50` where the application is Okta. Then for all other applications the tickets will be created in a Jira project with an ID of `1`. > **Note** > > In the following example, Slack and Okta are considered to be configured as a Managed Resource for the integration in question. ```java for (AccountRequest accReq : Util.iterate(plan.getAccountRequests())) { if (accReq.getApplicationName().equals("Slack")) { plan.put("serviceDeskId", "33"); plan.put("requestTypeId", "33"); } else if (accReq.getApplicationName().equals("Okta")) { plan.put("serviceDeskId", "50"); plan.put("requestTypeId", "50"); } else { plan.put("serviceDeskId", "1"); plan.put("requestTypeId", "1"); } } ``` 2. Modify the values for **Request Type Id** and **Service Desk Id**, located in the **Ticket Creation** section, to read the modified values from the Before Provisioning Rule rather than the default hard coded values. ```text Request Type Id: $plan.arguments.requestTypeId Service Desk Id: $plan.arguments.serviceDeskId ``` 3. Update the **Identity Security Cloud Status** to **Atlassian Data Center Jira SDIM Status** based on the status mapping you configured in the [Status Mapping]() section, as per the status being received from multiple objects.