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 > Integrations > Integrations.
  3. From Available Integrations, select Collaboration > Zendesk.
  4. 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:

Third-Party EntityOpsRamp EntityThird-Party PropertyOpsRamp Property (non-editable)
EventIncidentstatus
Third-Party Property Value
OpsRamp Property Value
NewNew
PendingPending
SolvedResolved
OpenOpen
incident.status.name
EventIncidentpriority
Third-Party Property Value
OpsRamp Property Value
NormalNormal
HighHigh
LowLow
UrgentUrgent
incident.priority.name
EventIncidentdescriptionincident.latestResponse.description
EventIncidentsubjectincident.subject
EventIncidentdescriptionincident.impact
EventIncidentextTicketIdincident.extTicketId

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.
    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.
  4. In 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 and click Verify.
      A 200- OK success response is generated if the integration is successful.
  5. Integration Failures, a message is sent to the user about the failure.
    1. Select Email as the notification type.
    2. Enter an email address.
    3. Click Save.

Field values

FieldsValues
Notification TypeREST API
Base URIhttps://opsramp.zendesk.com
AuthenticationOAUTH2
Grant TypePassword Credentials
Access Token URLhttps://{subdomain}.com/oauth/tokens
KeyUnique Identifier configured in OAuth client in Zendesk.
SecretSecret in OAuth client in Zendesk.k-0
UsernameZendesk username
PasswordZendesk password
Scopetickets:write

Integration event payloads

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

FieldsValues
Endpoint URLhttps://{subdomain}.com/api/v2/tickets
Headers
  • Accept: application/json
  • Content-Type: application/json
MethodPOST

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 modify 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:

FieldsValues
Endpoint URLhttps://{subdomain}.com/api/v2/tickets
Headers
  • Accept: application/json
  • Content-Type: application/json
MethodPOST

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}}"
    }