Zendesk

Introduction

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

Install the Integration

From All Clients, select a client.
Go to Setup > Account.
Select the Integrations and Apps tab.
The Installed Integrations page, where all the installed applications are displayed. Note: If there are no installed applications, it will navigate to the Available Integrations and Apps page.
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.
Search for Zendesk using the search option available.
Note: Alternatively, you can use the All Categories option to search.
Click ADD on the Zendesk tile. The Inbound tab is displayed.

Configure the Integration

Based on your requirements, you can configure Inbound, Outbound or both.

Configure the Inbound (From Zendesk to OpsRamp)

BMC Remedy Inbound and Outbound configuration

To configure the inbound, follow these steps:

Authentication:
- OAUTH2. Select OAUTH2 from the Authentication Type dropdown and click Generate Key to generate the Key and Secret.
  Note: Keep a copy of the token as the information will not appear again. Read information about the Access Key.
- WEBHOOK: Choose “WEBHOOK” as the authentication method, then select the required entity type from the dropdown. Click the Generate Key button to create the Key and Secret pair.
Map Attributes: Map OpsRamp entity attributes with Zendesk attributes.
1. Click +Add from the Map Attributes section.
2. From the Add Map Attributes window, enter the below information:
  - OpsRamp Entity: Select the OpsRamp entity from dropdown.
  - OpsRamp Property: Select the OpsRamp property from dropdown. It will change based on entity selection.
  - Zendesk Entity: Enter the Zendesk entity.
  - Zendesk Property: Enter the Zendesk property.
3. Click +Property Value in the Property Values section, and enter Zendesk Property Value and OpsRamp Property Value and click Save.
  Note:
  - The Property values section appears based on the OpsRamp Property selected.
  - To add property values, click +Property Value.
  - To map more attributes, click +Entity.
Properties:
1. Click +Properties from the Properties section.
2. Enter the values for the Properties and Value fields and click Save.
  Note: To add properties, click +Properties
3. Click Add Map Attributes.
4. Click Next. The Outbound tab is displayed.

Configure the Outbound (From OpsRamp to Zendesk)

To configure the outbound, follow these steps:

Configuration: The notification details to trigger integration events are displayed.
1. Base URI: https://{subdomain}.com/arsys/services/ARService?server=onzendesk-s&webService=OpsRamp_CreateIncident
2. Notification Type: Select the Notification Type. Available options are REST API and SOAP API.
3. Authentication Type: Based on the Notification Type selected, the Authentication Type differs. Available options are Basic, OAuth2, JWT, None.
Map Attributes: From the Map Attributes window, enter the below information:
1. OpsRamp Entity: Select the Opsramp entity from dropdown.
2. OpsRamp Property: Select the Opsramp property from dropdown. It will change based on entity selection.
3. Zendesk Entity: Enter the Zendesk entity.
4. Zendesk Property: Enter the Zendesk property.
5. Click +Property Value in the Property Values section, and enter Zendesk Property Value and OpsRamp Property Value and click Save.
  Note:
  - The Property values section appears based on the OpsRamp Property selected.
  - To add property values, click on +Property Value.
  - To map more attributes, click on +Entity.
- Click Add Map Attributes .
Events: Events are for sending notifications when an action is performed on OpsRamp entities.
1. Click Add in the Events section.
2. Enter a name for the event.
3. Select the Entity, Entity Type, and Entity Type Event from the drop-down lists.
4. (Optional) Under Advanced Settings, enter the values for Property, Operator, and Value and click Save.
5. From Actions:
  1. Select Use Parent Configuration checkbox to inherit parent configuration.
  2. Enter Endpoint URL.
  3. Select the Notification Type. Available options are REST API and SOAP API.
  4. Select the Authentication Type. Based on the Notification Type selected, the Authentication Type differs. Available options are Basic, OAuth2, JWT, None.
  5. Select the web method.
6. Headers:
  1. Click +Add and enter/select the header name and value.
  2. Click Save to save the header name.
  - (Optional) Click +Add to add more _headers
  - Enter the Payload.
7. Response:
  1. Click +Add and enter/select the response name and value.
  2. Click Save to save the response name.
  - (Optional) Click +Add to add more responses.
    Note:
    - The event is created, only if you provide the response properties.
    - You cannot enter more than four responses.
8. (Optional) Attachment: In the Attachment section, provide inputs in the Process Type, Attachment Endpoint URL, and Web Method fields.
9. Attachment Headers: In the Attachment Headers section, provide inputs in the Name and Value fields and click on Save.
  1. Enter the payload in the Attachment Payload box.
  2. Enter the Key and Value in the Attachment Response section.
10. Click Add Event. The event is added.
  There are some actions you can perform on the Events.
  See here for more details.

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:

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
sample response payload to mapping the id in response mapping:
```
{
"result":{
"id":"INC0001",
"type":"incident",
"tool":"servicedesk"
    }
}
```
external ticket id = $result.id

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

sample response payload to mapping the Incident Number in response mapping

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

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

Failures: In the case of failure in integration, an Email is sent to the user about the failure in integration.
To configure failure notification:
1. Click add from the Failures section.
2. Select notification type as Email.
3. Enter the email address(es) in the To and CC fields
4. Click Add Failure Notifications. The details are added.
5. Click Finish. The integration is installed.

Actions on Integration

You can perform actions on an integration.

See here for more information.

Actions on Event

Follow these steps to perform actions on the events:

Click on the integration name.
Navigate to Outbound tab > Events section.
Hover over the event name.
Click the actions (three dots) menu. A popup appears with options.
- Copy Id: To copy an event Id.
- Edit: To edit the event details.
- Save as: To save an event name.
- Validate: Validate if the event is successful.
  - Select Json or Form.
    - Json: Enter the payload and click on Validate.
    - Form: Enter the property and value in the fields and click on Validate.
      A green tick appears if the event is successful
- Remove: To remove an event.

Audit Logs

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

Field Values

Fields	Values
Notification Type	REST API
Base URI	https://opsramp.zendesk.com
Authentication	OAUTH2
Grant Type	Password Credentials
Access Token URL	https://{subdomain}.com/oauth/tokens
Key	Unique Identifier configured in OAuth client in Zendesk.
Secret	Secret in OAuth client in Zendesk.k-0
Username	Zendesk username
Password	Zendesk password
Scope	tickets:write

Integration Event Payloads

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

Fields	Values
Endpoint URL	https://{subdomain}.com/api/v2/tickets
Headers	Accept: application/json Content-Type: application/json
Method	POST

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:

Fields	Values
Endpoint URL	https://{subdomain}.com/api/v2/tickets
Headers	Accept: application/json Content-Type: application/json
Method	POST

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:

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

Prerequisite: Configure OAuth Client

Log into Zendesk, click the Admin icon.
Go to Channels API > OAuth Clients and click the Add icon to create a new client.
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.

Log into Zendesk and click the Admin icon.
Go to Settings > Extensions > Targets and click add target.
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.

Click the Admin icon, go to Business Rules > Triggers.
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}}"
}