JIRA is used for bug tracking, issue tracking, and project management.

This collaboration integration supports the webhook-based inbound calls with different types of service management requests. For example, you can select one or multiple Entity Types from Incident, Service Request, Problem, and Change.

OpsRamp configuration

Step 1: Install the integration

  1. From All Clients, select a client.
  2. Go to Setup > Integrations > Integrations.
  3. From Available Integrations, select Collaboration > JIRA.
  4. Click Install.

Step 2: Configure the integration

Configure the following:

  • Inbound
  • Outbound
  • Monitoring of Integration
  • Audit Logs

Inbound

  1. In Authentication, configure the authentication to call Freshservice APIs.
    1. Select Webhook as Authentication Type.
    2. Select an Entity Type.
    3. Click Save.
      Copy URL details. These values are used for creating and updating tickets in JIRA.
  2. In Map Attributes, map Freshservice attributes with OpsRamp entity attributes.
    1. Select the OpsRamp entity from the drop-down menu.
    2. Click Map against the respective attribute, enter the mapping details, and click Save.

The following table shows the attribute mappings:

Third-Party EntityOpsRamp EntityThird-Party PropertyOpsRamp Property
IssueIncidentissue.fields.summarySubject
IssueIncidentissue.fields.descriptionDescription
IssueIncidentFor worklogs: worklog.comment
For Comments on Issue: comment.body
Latest comment description
IssueIncidentissue.fields.priority.name
Third-Party Property ValueOpsRamp Property Value
HighestUrgent
HighHigh
MediumNormal
LowLow
LowestVery Low
Priority mappings depends upon the Jira settings.
Priority
IssueIncidentissue.fields.status.name
Third-Party Property ValueOpsRamp Property Value
TO DONew
IN PROGRESSPending
DONEClosed
Status mappings depends upon the Jira settings. By default, Jira provides three statuses as mentioned above.
Status
  • You can modify the attributes at any time.
  • You need not follow the same mappings.
Create Issue Payload sample sent from Jira
{
    "timestamp": 1584872075428,
    "webhookEvent": "jira:issue_created",
    "issue_event_type_name": "issue_created",
    "issue": {
        "id": "10000",
        "self": "https://test-jira-opsramp.atlassian.net/rest/api/2/10000",
        "key": "TEST-1",
        "fields": {
            "issuetype": {
                "self": "https://test-jira-opsramp.atlassian.net/rest/api/2/issuetype/10001",
                "id": "10001",
                "description": "Functionality or a feature expressed as a user goal.",
                "iconUrl": "https://test-jira-opsramp.atlassian.net/secure/viewavatar?size=medium&avatarId=10315&avatarType=issuetype",
                "name": "Story",
                "subtask": false,
                "avatarId": 10315
            },
            "timespent": null,
            "project": {
                "self": "https://test-jira-opsramp.atlassian.net/rest/api/2/project/10000",
                "id": "10000",
                "key": "TEST",
                "name": "test",
                "projectTypeKey": "software",
                "simplified": false
            },
            "priority": {
                "self": "https://test-jira-opsramp.atlassian.net/rest/api/2/priority/3",
                "iconUrl": "https://test-jira-opsramp.atlassian.net/images/icons/priorities/medium.svg",
                "name": "Medium",
                "id": "3"
            },
            "customfield_10023": null,
            "status": {
                "self": "https://test-jira-opsramp.atlassian.net/rest/api/2/status/10000",
                "description": "",
                "iconUrl": "https://test-jira-opsramp.atlassian.net/",
                "name": "To Do",
                "id": "10000",
                "statusCategory": {
                    "self": "https://test-jira-opsramp.atlassian.net/rest/api/2/statuscategory/2",
                    "id": 2,
                    "key": "new",
                    "colorName": "blue-gray",
                    "name": "New"
                }
            },
            "components": [],
            "timeoriginalestimate": null,
            "description": "test"
        }
    }
}
Worklog
{
   "timestamp":1584872198443,
   "webhookEvent":"worklog_created",
   "worklog":{
      "self":"https://test-jira-opsramp.atlassian.net/rest/api/2/issue/10000/worklog/10000",
      "author":{
         "self":"https://test-jira-opsramp.atlassian.net/rest/api/2/user?accountId=5dd517ec9def2a0ee974d920",
         "accountId":"5dd517ec9def2a0ee974d920",
         "displayName":"<name>",
         "active":true,
         "timeZone":"Asia/Calcutta",
         "accountType":"atlassian"
      },
      "updateAuthor":{
         "displayName":"<name>",
      },
      "comment":"test",
      "id":"10000",
      "issueId":"10000"
   }
}

Outbound

  1. In Integration Basic Configuration, configure notification details to trigger integration events.
    • Notification Type: REST API
    • BASE URI: https://{subdomain}.com/rest/api/2/issue/
    • Authentication Type: BASIC
    • Provide username and password and click Save.
      For JIRA cloud, using passwords is deprecated in REST API calls. Create an API token from the Atlassian account and use it as the password. To create the token,
  2. Log into https://id.atlassian.com/manage/api-tokens.
  3. Click Create API token.
  4. In Map Attributes, map OpsRamp entity attributes with JIRA attributes.
    1. Select the attribute, click Map, and Create Integration Mapping window is displayed.
    2. Enter the values and click Save.
  5. In Integration Events, specify the event. An action performed on an entity is defined as an event. When an event is triggered, notifications are sent to the respective users.
    1. Click Add.
    2. Enter a name for the integration event.
    3. Select Service Desk, select an entity and select the action.
    4. Select Parent Configuration to assign basic integration configuration details to the event.
    5. Select the web method and enter the header name and value.
    6. Enter the payload for the respective action.
      • A custom field that is already configured as a response payload attribute for a given integration is not available for configuration in any other integrations. You need to remove the existing mapping from the integration to make the custom field available to map on the response payload of any other integration.
      • To add more tokens to the payload, click the token in the Place Holder list.
      • To parse the properties returned in the response, select the property from the drop-down and enter the value.
        For example, To parse issue key $key of JIRA with OpsRamp, select the property as EXT_ENTITY_ID (external entity ID) in OpsRamp.
        Add Integration Event
  6. Verify Integration, validate if the integration is successful.
    1. Select the event from the drop-down and select the payload type.
    2. Enter the payload values and click Verify.
  7. For Integration Failures, select the notification type Email, enter the email address, and click Save.

Integration event payloads

FieldsValues
Endpoint URLhttps://{subdomain}.com/helpdesk/tickets
Headers
  • Accept: application/json
  • Content-Type: application/json
MethodPOST
Authentication typeBASIC
UsernameJIRA username
PasswordJIRA password
Request with hard-coded values
{
 "fields" : {
  "project" : {
   "key" : "IT"
  },
  "summary" : "Test ticket from OpsRamp integration REST API plugin",
  "description" : "Creating of an issue using OpsRamp  integration REST API plugin",
  "issuetype" : {
   "name" : "Bug"
  },
  "priority" : {
   "name" : "Critical"
  },
  "components" : [
   {
    "name" : "Component-1"
   }
  ]
 }
}
Request with event tokens
{
 "fields" : {
  "project" : {
   "key" : "IT"
  },
  "summary" : "$incident.subject",
  "description" : "$incident.impact",
  "issuetype" : {
   "name" : "$incident.customFields.clientCustomFieldValues.values_1_25.value_1"
  },
  "priority" : {
   "name" : "[@$incident.priority.name@]"
  },
  "components" : [
   {
    "name" : "$incident.customFields.clientCustomFieldValues.values_1_25.value_2"
   }
  ]
 }
}
Response
{
 "id" : "27999",
 "key" : "IT-1",
 "self" : "https://jira.opsramp.net:443/rest/api/2/issue/27999"
}

Update JIRA issue

FieldsValues
Endpoint URL
  • Hard-coded issue key: https://{subdomain}.com/helpdesk/tickets
  • Replaced key with token: https://{subdomain}.com/rest/api/2/issue/${incident.extTicketId}
Headers
  • Accept: application/json
  • Content-Type: application/json
MethodPOST
Authentication TypeBASIC
UsernameJIRA username
PasswordJIRA password
Request with event tokens
{
 "fields" : {
  "priority" : {
   "name" : "[@$incident.priority.name@]"
  }
 }
}
Response

Status code 204 No Content is displayed.

Update JIRA issue with attachment

FieldsValues
Endpoint URL
  • Hard-coded issue key: https://{subdomain}.com/helpdesk/tickets/attachments
  • Replaced key with token: https://{subdomain}.com/rest/api/2/issue/${incident.extTicketId}/attachments
Headers
  • Accept: application/json
  • Content-Type: multipart/form-data
  • X-Atlassian-Token : no-check
MethodPOST
Authentication TypeBASIC
UsernameJIRA username
PasswordJIRA password
Request with event tokens
{
    "file":"$utils.attachmentMultipart($incident.latestResponse.resourceList,$incident.client.uniqueId,$installedAppId,$incident.uniqueId,$incident.latestResponse.id,$entity)"
}
Response
[
    {
        "self": "https://jira.atlassian.net/rest/api/3/attachment/10000",
        "id": "10000",
        "filename": "file.txt",
        "created": "2021-03-31T09:02:00.991+0530",
        "size": 181,
        "mimeType": "text/html",
        "content": "https://jira.atlassian.net/secure/attachment/10000/file.txt"
    }
]

Update JIRA issue status

FieldsValues
Endpoint URL
  • Hard-coded issue key: https://{subdomain}.com/helpdesk/tickets/transitions
  • Replaced key with token: https://{subdomain}.com/rest/api/2/issue/${incident.extTicketId}/transitions
Headers
  • Accept: application/json
  • Content-Type: application/json
MethodPOST
Authentication TypeBASIC
UsernameJIRA username
PasswordJIRA password
Request with event tokens
{
    "transition": {
    "id": "[@$incident.status.name@]"
    }
}
Response

Status code 204 No Content is displayed.

Add comment to JIRA issue

The following parameters provide values for adding comments to a JIRA issue.

FieldsValues
Endpoint URL
  • Hard-coded issue key: https://{subdomain}.com/rest/api/2/issue/IT-3/comment
  • Replaced key with token: https://{subdomain}.com/rest/api/2/issue/${incident.extTicketId}/comment
Headers
  • Accept: application/json
  • Content-Type: application/json
MethodPOST
Authentication TypeBASIC
UsernameJIRA username
PasswordJIRA password
Request with hard-coded values
{
 "body" : "Test comment added"
}
Response

Status code 201 is displayed.

Configuration in JIRA

Configure JIRA to add the webhook URL copied during OpsRamo configuration.

  1. Log into JIRA.
  2. Navigate to Settings, System WebHooks.
  3. Configure the New Webhook Listener with the Webhook Url generated during OpsRamp configuration and click Save.

If no external ticket ID Mappings are provided, add &extTicketId=${issue.id} at the end of webhook URL copied from OpsRamp.

Example URL: https://opsramp.com/integrations/incidentWebhook/client_4/incidents?vtoken=Zj8MYUDD8BQhMEstAMxhvPXq5deyNwTV&extTicketId=${issue.id}