Zendesk

Introduction

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

Prerequisites

• Credentials to access Zendesk
• Credentials to access OpsRamp

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 > 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.

To configure inbound communications:

1. In Authentication, select authentication type as Webhook and click Save.
2. Make note of the Webhook URL.
   These values are used while configuring the trigger and target in Zendesk.
3. In Map Attributes, map Zendesk attributes with OpsRamp entity attributes.
   
   1. Select the OpsRamp entity from the drop-down menu.
      
   2. Click Map against respective attribute, provide the mapping details, and click Save.
      

The following table shows the property mappings:

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.
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.
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.
     The 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.
       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 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, a message is sent to the user about the failure.
   1. Select Email as the notification type.
   2. Provide an email address.
   3. Click Save.

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

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.

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.

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 following values for the target:
   • Title: Incident
   • URL: https://{api-url}/integrations/incidentWebhook/{tenantId}/incidents?vtoken={token}
     For example, URL: https://api.vistanet.jp/integrations/incidentWebhook/client_4/incidents?vtoken=rxBqvWns3jX3ufyksYYV6H
     Note: 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, 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.

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