Zendesk

Zendesk provides a cloud-based customer support platform tool.

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.

Prerequisites

• Credentials to access Zendesk
• Credentials to access OpsRamp

OpsRamp configuration

Step 1: Install the integration

1. From All Clients, select a client.
2. Go to Setup > Account.
3. Select the Integrations and Apps tab.
4. The Installed Integrations page, where all the installed applications are displayed. Note: If there are no installed applications, it will navigate to the ADD APP page.
5. Click + ADD on the Installed Integrations page. The Available Integrations and Apps page displays all the available applications along with the newly created application with the version.
   Note: You can even search for the application using the search option available. Also yu can use the All Categories option to search.
6. Click ADD in the Zendesk application and click Install.

Step 2: Configure the integration

Configure the following:

• Inbound
• Outbound
• Monitoring of Integration
• Audit Logs

Inbound

Inbound configurations capture all the details required to call OpsRamp APIs in Zendesk. Inbound configurations send events from Zendesk to OpsRamp.

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 Zendesk.
2. In Map Attributes, map Zendesk 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 property mappings:

Mapping can be modified at a later time.

Outbound

Outbound configurations send events from OpsRamp to Zendesk.

Prerequisites Before configuring outbound configuration, configure the OAuth client in Zendesk. See Prerequisite: Configure OAuth client

1. Integration Basic Configuration: Configure basic notification details to trigger integration events.
   1. Notification type: REST API
   2. Base URI: https://{subdomain}.zendesk.com/api/v2/tickets
   3. Authentication type: OAUTH2
   4. Enter the field values and click Save.
2. Map Attributes: Map OpsRamp attributes with Zendesk attributes.
   1. Select OpsRamp entity and click Map against the required attribute.
   2. Enter the mapping values and click Save.
3. In Integration Events, click Add.[0-9.]*
   An action performed on the entity is triggered as an event. When an event is triggered, a notification is sent to the respective user.
   • Click Add.
   • Provide a name for the integration event.
   • Select Service Desk, select an entity and select the action.
   • Select Parent Configuration to assign basic integration configuration details to the event.
   • Provide end point URL.
   • Select the web method, provide headers and payload, and click Save.
     • To add more tokens to the payload, click the token in the Place Holders list.
     • 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.
       Remove the existing mapping from the integration to make the custom field available to map the response payload of any other integration.
     • To parse the properties returned in response for the configured API payload, select the property from the drop-down menu and enter the value.
   • Response: Select a response and enter a value. The event is created, only if you provide the response properties.
     Integration response mapping configuration:
     Response mapping configuration is mainly based on the response payload that is received in third party payload; below are a few examples for response mapping configuration -

     

     1. sample response payload to mapping the id in response mapping:

        {
        "id":"INC0001",
        "type":"incident",
        "tool":"servicedesk"
        }
        

        external ticket id = $id
        We need to append $ to the value

     2. sample response payload to mapping the id in response mapping:

        {
        "result":{
        "id":"INC0001",
        "type":"incident",
        "tool":"servicedesk"
            }
        }
        

        external ticket id = $result.id

     3. Sample response payload to mapping the id in response mapping

        {
               "result":[
                  {
                     "ticketDetails":{
                    "id":"INC0001",
                    "type":"incident",
                    "tool":"servicedesk"
              },
                 "Description":{
                    "display_value":"testing description",
                    "value":"validating"
                 }
              }
           ]
        }
        

        external ticket id = $result[0].ticketDetails.id

     4. sample response payload to mapping the Incident Number in response mapping

                {
              "result": {
              "Incident Number": "INC0001",
              "type": "Incident"
                  }
            }
        

        external ticket id = $result[‘Incident Number’]

Verify integration

To validate if the integration is successful, do the following:

1. Select the event from the drop-down menu and select payload type.
2. Enter the payload and click Verify. A 200-OK success response is generated if the integration is successful.

Integration failures

In case of a failure in integration, a message is sent to the respective user. Select notification type Email, enter the email address, and click Save.

Monitoring of Integration

Assign a template from the Monitoring of Integration tab, if you want to monitor integration failures. See monitoring integration failures for more information.

Audit Logs

View logs from the Audit Logs tab. You can view if the event was successful or not.

Field values

Integration event payloads

The following field values and payloads are used to generate events:

Request with hard-coded values

{
 "ticket" : {
  "type" : "incident",
  "subject" : "Test ticket subject",
  "description" : "Test ticket description",
  "priority" : "Low",
  "status" : "New",
  "tags" : "development"
 }
}

Request with tokens in integration event

{
 "ticket" : {
  "type" : "incident",
  "subject" : "$incident.subject",
  "description" : "$incident.impact",
  "priority" : "[@$incident.priority.name@]",
  "status" : "[@$incident.status.name@]",
  "tags" : "development"
 }
}

Response

{
 "ticket" : {
  "url" : "https://{subdomain}.com/api/v2/tickets/23608",
  "id" : 23608,
  "external_id" : null,
  "using" : {
   "channel" : "api",
   "source" : {
    "from" : {},
    "to" : {},
    "rel" : null
   }
  },
  "created_at" : "2016-12-14T11:57:51Z",
  "updated_at" : "2016-12-14T11:57:51Z",
  "type" : "incident",
  "subject" : "**Test ticket to verify OpsRamp  integration.",
  "raw_subject" : "**Test ticket to verify OpsRamp  integration.",
  "description" : "This is a test of using the API to create a ticket using POSTMAN. The hope is to learn how this works so as to be able to change the XSL script to implement this on generated web pages.",
  "priority" : "normal",
  "status" : "new",
  "recipient" : null,
  "requester_id" : 2814922763,
  "submitter_id" : 2814922763,
  "assignee_id" : null,
  "organization_id" : null,
  "group_id" : null,
  "collaborator_ids" : [],
  "forum_topic_id" : null,
  "problem_id" : null,
  "has_incidents" : false,
  "is_public" : true,
  "due_at" : null,
  "tags" : [
   "development"
  ]
 }
}

Read the ticket ID of Zendesk and save it into the external entity ID of the OpsRamp incident using the token $ticket.id.

Update Zendesk ticket

The following table provides field values for updating tickets and adding comments to a ticket in Zendesk:

Request with hard-coded values

{
 "ticket" : {
  "comment" : {
   "body" : "Test comment."
  },
  "status" : "open"
 }
}

Request with tokens in integration events

{
 "ticket" : {
  "comment" : {
   "body" : "$incident.latestResponse.description"
  },
  "status" : "[@$incident.status.name@]"
 }
}

Response

{
 "ticket" : {
  "id" : 35436,
  "subject" : "Test subject",
  "status" : "Solved"
 },
 "audit" : {
  "events" : []
 }
}

Zendesk configuration

Before configuring targets and triggers in Zendesk:

1. Configure the OAuth client. The OAuth authentication type is required to call Zendesk APIs.
2. Configure the OpsRamp Integration - Inbound Configuration.

Prerequisite: Configure OAuth Client

1. Log into Zendesk, click the Admin icon.
2. Go to Channels API > OAuth Clients and click the Add icon to create a new client.
3. Enter information for the client and click Save. Use Unique Identifier as key and Secret as the secret to call Zendesk APIs.

Step 1: Configure targets

A target is a part of an extension and serves as a notification type to external systems. To get notifications about the Zendesk ticket to create/update/add comments, define HTTP target to invoke OpsRamp APIs. Zendesk events are create ticket, update ticket, and add comment to a ticket. Create a unique target to create/update/add comments.

1. Log into Zendesk and click the Admin icon.
2. Go to Settings > Extensions > Targets and click add target.
3. Click HTTP target and enter the following values for the target:

• Title: Incident
  • URL: https://{api-url}/integrations/incidentWebhook/{tenantId}/incidents?vtoken={token}
    Example URL: https://api.opsramp.com/integrations/incidentWebhook/client_4/incidents?vtoken=rxBqvWns3jX3ufyksYYV6H
    Copy the webhook URL that provides the complete URL with Tenant ID and token. To copy, navigate to Setup > Integrations > Integrations > Select client > My Integrations > Webhook tab > Copy Webhook URL.
    • Method: POST
    • Content type: JSON

Step 2: Configure triggers

Triggers take actions when a ticket is created or updated. Define conditions for the triggers and when the conditions are met, the trigger executes the configured actions.

• An action can be a notification sent to an email or notify target. For example, when a user creates a ticket with high priority, an event is triggered and sent as an email.
• Unique triggers are created for each event.

1. Click the Admin icon, go to Business Rules > Triggers.
2. Click Add trigger, provide values for the trigger, and click Create trigger.

Example Create incident trigger

The following example generates a create incident trigger:

• Title: Create Incident

• Conditions Ticket is: Created.

• To notify OpsRamp of the event, select Notifications: Notify Target and select the target created.
  For example: OpsRamp Incident target.

• Provide JSON payload and edit the values in the payload.

  {
  "subject" : "{{ticket.title}}",
  "description" : "{{ticket.description}}",
  "priority" : "{{ticket.priority}}",
  "cc":"{{ticket.cc_names}}",
  "extTicketId":"{{ticket.id}}"
  }
  

• Click Create trigger.
  The created trigger is visible in the triggers list.

Example Update Incident Trigger

The following example generates an update incident trigger:

• Trigger Title: Update Incident

• Conditions

  • Ticket is: Updated.
    • Comment: is… Present(Public or Private)

• To notify OpsRamp of the event, select Notifications: Notify Target and select the target created. For example, OpsRamp Incident target.

• Provide JSON payload, edit the values in payload, and save the updates.

  {
  "priority" : "{{ticket.priority}}",
  "status":"{{ticket.status}}",
  "description":"{{ticket.latest_public_comment_formatted}}",
  "extTicketId":"{{ticket.id}}"
  }