Introduction
Zendesk provides a cloud-based customer support platform tool.
Note
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
Configuration involves:
- Installing the integration
- Configuring the integration
Step 1: Install the integration
To install:
- From All Clients, select a client.
- Go to Setup > Integrations > Integrations.
- From Available Integrations, select Collaboration > Zendesk.
- 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:
- In Authentication, configure the authentication to call Freshservice APIs.
- Select Webhook as Authentication Type.
- Select an Entity Type.
- Click Save.
Note: Copy URL details. These values are used for creating and updating tickets in Zendesk.
- In Map Attributes, map Zendesk attributes with OpsRamp entity attributes.
- Select the OpsRamp entity from the drop-down menu.
- Click Map against respective attribute, provide the mapping details, and click Save.
- Select the OpsRamp entity from the drop-down menu.
The following table shows the property mappings:
Third-Party Entity | OpsRamp Entity | Third-Party Property | OpsRamp Property (non-editable) | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Event | Incident | status
| incident.status.name | ||||||||||
Event | Incident | priority
| incident.priority.name | ||||||||||
Event | Incident | description | incident.latestResponse.description | ||||||||||
Event | Incident | subject | incident.subject | ||||||||||
Event | Incident | description | incident.impact | ||||||||||
Event | Incident | extTicketId | incident.extTicketId |
Note
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
To configure outbound communication:
- Integration Basic Configuration: Configure basic notification details to trigger integration events.
- Notification type: REST API
- Base URI:
https://{subdomain}.zendesk.com/api/v2/tickets
- Authentication type: OAUTH2
- Provide the field values and click Save.
- Map Attributes: Map OpsRamp attributes with Zendesk attributes.
- Select OpsRamp entity and then click Map against the required attribute.
- Provide the mapping values and then click Save.
- 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 more tokens to the payload, click 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.
- Click Add.
- In Verify Integration, validate if the integration is successful.
- Select the Event from the drop-down and then select the Payload type.
- Provide the payload and then click Verify.
A 200- OK success response is generated if the integration is successful.
- Integration Failures, a message is sent to the user about the failure.
- Select Email as the notification type.
- Provide an email address.
- Click Save.
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 |
|
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 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"
]
}
}
Note
Read the ticket ID of Zendesk and save it into the external entity ID of 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 |
|
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
Configuring Zendesk to send Zendesk events to OpsRamp involves:
- Configuring targets
- Configuring triggers
Important
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
To configure OAuth client to call Zendesk APIs:
- Log into Zendesk, click the Admin icon.
- Go to Channels API > OAuth Clients and click the Add icon to create a new client.
- 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:
- Log into Zendesk and click the Admin icon.
- Go to Settings > Extensions > Targets and click add target.
- 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:
- 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}}" }