Zendesk

Describes how to setup an integration for viewing OpsRamp incident and service requests in Zendesk and vice versa.

Leave Feedback

Introduction

Zendesk provides a cloud-based customer support platform tool. OpsRamp provides two-way integration between OpsRamp and Zendesk for service requests.

OpsRamp configuration

Configuration involves:

  1. Installing the integration.
  2. Configuring the integration.

Step 1: Install the integration

To install:

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

Step 2: Configure the integration

Configure the following: - Inbound - Outbound - Monitoring of Integration - Audit Logs

Inbound

Inbound configurations send events from Zendesk to OpsRamp.

To configure inbound communications:

  1. In Authentication, configure the authentication to call Zendesk APIs.
    1. Select authentication type as HTTP Basic and click Save.
    2. Take note of the Tenant Id and Token. These values are used while configuring the trigger and target in Zendesk.
      Inbound Configuration

      Inbound Configuration

  2. In Map Attributes, map Zendesk attributes with OpsRamp entity attributes.
    1. Select OpsRamp entity from the drop-down menu.
    2. Click Map against respective attribute, provide the mapping details and click Save.
      Mapping Attributes

      Mapping Attributes

Outbound

Outbound configurations send events from OpsRamp to Zendesk.

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

To configure outbound communication:

  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. Provide the field values and click Save.
      Integration Event

      Integration Event

  2. Map Attributes: Map OpsRamp attributes with Zendesk attributes.
    1. Select OpsRamp entity and then click Map against the required attribute.
    2. Provide the mapping values and then click Save.
      Outbound Configuration

      Outbound Configuration

  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.Add Integration Event page appears.
    • Provide a name for the integration event.
    • Select Service Desk, select an entity and then 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 then click Save.
      • To add additional tokens to the payload, click on the token in the Place Holders list.
      • A custom field that is already configured as 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 response payload of any other integration.
        Add Integration Event

        Add Integration Event

  4. In Verify Integration, validate if the integration is successful.
    1. Select the event from the drop-down and then select the payload type.
    2. Provide the payload and then click Verify. A 200- OK success response is generated if the integration is successful.
  5. Integration Failures: In the case of failure in integration, a message is sent to the user about the failure.
    1. Select notification type Email.
    2. Provide email.
    3. Click Save.

Field values

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.

Field Values
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,
		"via" : {
			"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 via 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"
		]
	}
}

Update Zendesk ticket

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

Field Values
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

Configuring Zendesk to send Zendesk events to OpsRamp involves:

  1. Configuring targets
  2. Configuring triggers

Prerequisite: Configure OAuth Client

To configure OAuth client to call Zendesk APIs:

  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. Provide information for the client and click Save. Use Unique Identifier as key and Secret as secret to call Zendesk APIs.
Configure OAuth Client

Configure OAuth Client

API OAuth Client

API OAuth Client

Step 1: Configure targets

A target is a part of an extension and is a notification type to external systems. To get notifications of Zendesk events, define HTTP target to invoke OpsRamp APIs. Zendesk events are create ticket, update ticket, and add comment to a ticket. Unique targets should be created for each event.

  • Create incident target
    • Title: OpsRamp Incident Create Target
    • URL: https://<api-url>/api/basic/tenants/{tenantId}/incidents?vtoken={token}
  • Update incident target
    • Title: OpsRamp Incident Update Target
    • URL: https://<api-url>/api/basic/tenants/{tenantId}/incidents/{{ticket.id}}?vtoken={token}&idType=external
  • Add response to incident Target
    • Title: OpsRamp Incident Add Response Target
    • URL: https://<api-url>/api/basic/tenants/{tenantId}/incidents/{{ticket.id}}/responses?vtoken={token}&idType=external

To create a target:

  1. Log into Zendesk and click the Admin icon.
  2. Go to Settings > Extensions > Targets and click add target.
  3. Click HTTP target and provide the values for the target.
    Considering Create Incident Target as an example, the following screenshot show sample values.
Configure HTTP Target

Configure HTTP Target

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, then an event is triggered and sent as an email.
  • Unique triggers are created for each event.

To create a trigger:

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

Configure Triggers

Example: Create incident trigger

The following example generates a create incident trigger:

  1. Provide a title for the trigger.
  2. Select condition Ticket is: Created.
  3. To notify OpsRamp of the event, select Notifications: Notify Target and select the target created. Example: OpsRamp Incident Create.
  4. Provide JSON payload and edit the values in the payload.
  5. Click Create trigger, the created trigger is visible in triggers list. JSON payload to create trigger for creating incident target
{
	"subject" : "{{ticket.title}}",
	"description" : "{{ticket.description}}",
	"priority" : "{{ticket.priority}}",
	"cc" : "{{ticket.cc_names}}"
}
Configure Incident Trigger

Configure Incident Trigger

Example: Update Incident Trigger

The following example generates an update incident trigger:

  1. Provide a title for the trigger.
  2. Select conditions Ticket is: Updated.
  3. To notify OpsRamp of the event, select Notifications: Notify Target and select the target created. Example: OpsRamp Incident Update.
  4. Provide JSON payload and edit the values in payload.
  5. Click Create trigger, the created trigger is visible in triggers list. JSON payload to create trigger for update incident target
{
	"priority" : "{{ticket.priority}}",
	"status" : "{{ticket.status}}"
}
Update Incident Trigger

Update Incident Trigger

Example: Add Response to Incident Trigger

  1. Provide a title for the trigger.
  2. Select condition Ticket: Comment is: Present (Public or Private).
  3. To notify OpsRamp of the event, select Notifications: Notify Target and select the target created.
    For example: OpsRamp Incident Add Response Target.
  4. Provide the JSON payload and edit the values in the payload.
  5. Click Create trigger, the created trigger is visible in triggers list. JSON payload to create trigger for Add Response to Incident target
{
	"description" : "{{ticket.latest_public_comment_formatted}}"
}
Add Response to Incident Trigger

Add Response to Incident Trigger