Zendesk Integration

is a popular customer service and communication software. Zendesk can create triggers for customer tickets. By forwarding Zendesk tickets to OpsGenie, you can notify users via iPhone and Android push notifications, email, SMS, and phone calls, track of the alert life cycle, escalate alerts, etc.

What does OpsGenie offer Zendesk users?

OpsGenie provides a powerful two-way integration with Zendesk. When a new ticket is created in Zendesk, a corresponding OpsGenie alert will be automatically created, containing rich information about the ticket. OpsGenie will provide rich notifications with on-call rotation, scheduling etc. features and alert escalations; to ensure the best ticket management for Zendesk customers. As users execute actions on the alerts, like acknowledge, comment or close, the ticket on Zendesk will also automatically be updated with comments about these alert actions.


Functionality of the integration

  • When a ticket is created in Zendesk, it creates an alert in OpsGenie.
  • When a ticket is solved or closed in Zendesk, it closes the alert in OpsGenie.
  • When a comment is added to the ticket in Zendesk, it adds a note to the alert in OpsGenie.
  • If Send Alert Updates Back to Zendesk is enabled, actions for Zendesk will be executed in Zendesk when the chosen action is executed in OpsGenie for alerts which are created by the Zendesk integration.
  • If Create Zendesk Tickets for OpsGenie Alerts is enabled, actions for Zendesk will be executed in Zendesk when the chosen action is executed in OpsGenie for alerts which have a source other than the Zendesk integration.
  • These action mapping features are explained in detail in the Action Mapping Feature section below.

Add Zendesk Integration in OpsGenie

  1. Please create an OpsGenie account if you haven't done already.
  2. Go to OpsGenie Zendesk Integration page,
  3. Specify who should be notified for the Zendesk alerts using the "Teams" field. Auto-complete suggestions will be provided as you type.
  4. Copy the integration URL by clicking on the copy button or selecting.
  5. Click on "Save Integration".

Configuration in Zendesk

  1. In Zendesk, go to the "Admin" page.
  2. Select "Extensions" under "Settings".
  3. Click "add target".
  4. Select "URL target" from the opened list.
  5. Paste the integration URL you copied earlier into "Url". Select POST as "Method". Enter ticket into the "Attribute Name" field.
  6. Select "Create target" and click "Submit".
  7. Now from the admin panel, select "Triggers" under "Business Rules".
  8. Create the triggers following this instructions file.

Alert properties can be configured from Zendesk Integration / Advanced Settings page.

​All set! You can now manage your Zendesk alerts at OpsGenie and leverage its full alerting functionality:

Action Mapping Feature

  • OpsGenie allows customers to define action mappings between OpsGenie actions and Zendesk actions.

  • For alerts created by Zendesk
  • You can use this section to map OpsGenie actions to Zendesk actions when the source of the alert is Zendesk (i.e When the alert is created by Zendesk integration.)
  • You can map different OpsGenie actions to different Zendesk actions. For example, you can add an internal note to Zendesk ticket, when the alert is acknowledged. In order to do this, you should define If alert is acknowledged in OpsGenie, add it as an internal note to ticket in Zendesk. mapping in Send Alert Updates Back to Zendesk section.

  • For other OpsGenie alerts
  • You can use this section to map OpsGenie actions to Zendesk actions when the source of the alert is NOT Zendesk (i.e When the alert is created by another integration.)
  • For this purpose, you can use Create Zendesk Tickets for OpsGenie Alerts section. In order to use this functionality, you need to map one OpsGenie action to create a ticket Zendesk action. The OpsGenie action doesn't have to be alert is created, it can be other actions as well.

  • a tag is added to the alert and a custom action is executed on alert actions differ from other actions. When you select one of these actions, you'll see an extra field to enter for which tags or for which custom action this mapping will work.
  • You can enter multiple tags by separating the tags with a comma. If you enter multiple tags, the mapping will work if the alert has one or more of the specified tags. You can also leave the tags field empty, if you would like the mapping to work for any tag.
  • If you select a custom action mapping, you must specify the name of the custom action that the mapping will work. It cannot be left empty.
  • If you map an OpsGenie action to multiple Zendesk actions, you will get an error except for the a tag is added to the alert and a custom action is executed on alert actions. You can save multiple mappings for these actions, because they will differ by the given tags and the given custom action names.

Integration via Marid (Optional)

Alternatively, you can use OpsGenie's Zendesk integration package to create/update tickets on Zendesk. This will enable you to deploy your own scripts / modify the ones provided and execute customized actions on Zendesk.

To use Zendesk integration package, you need to follow the steps in the sections below through the end.

Download and install Zendesk package

For Red Hat Based Distributions
During upgrades, rpm package does not overwrite your existing configurations. It saves the new default configuration file as opsgenie-integration.conf.rpmnew. You can find more information about rpm upgrade config file handling from here.
For Debian Based Distributions For Windows
  • Download OpsGenie Zendesk (Windows)
  • Unzip opsgenie integration zip file which contains Lamp and Marid packages into a directory (C:\opsgenie-integration is the preferred path. C:\opsgenie-integration\marid will be referred as MARID_HOME in the rest of documentation.)
  • To install Marid as a service:
    • Open a command window
    • Go to <MARID_HOME> directory
    • For 32 bit systems, run marid.exe -install
    • For 64 bit systems, run marid_64.exe -install
    Name of the service will be assigned to "OpsGenie Marid"
To set JAVA_HOME environment variable, refer to Setting JAVA_HOME for more information.
To enable Ruby scripting, you need to download JRuby Complete jar file and put this jar file in lib directory (/var/lib/opsgenie/marid On Linux, MARID_HOME/lib on Windows systems.).
You may need to restart your system after setting JAVA_HOME environment variable for Windows XP/2000/2003 operating systems due to problem reported at http://support.microsoft.com/kb/821761

Configuring Zendesk Integration for Marid

  • In order to use Marid utility, enable Send Via Marid.
  • Other configurations regarding Zendesk can be done either via integration page or Marid configuration file opsgenie-integration.conf. Configuration in integration page will precede the configuration file.

Marid Configuration

The plugin uses Marid utility (included in the plugin) to update tickets on Zendesk when alerts are updated.

  • To start Marid, run the following command:
    /etc/init.d/marid start 
  • To stop Marid, run the following command:
    /etc/init.d/marid stop 

Marid is a JAVA application; therefore requires the JAVA Runtime version 1.6+ Both the Open JDK and Oracle JVMs can be used.

Ensure that JAVA_HOME environment variable is set. If it is not, you may set it by removing the comment at the begining of the following line in /etc/opsgenie/profile file and set JAVA_HOME to your JRE installation directory.
#JAVA_HOME=<path/to/JDK or JRE/install>

To be able to execute actions on Zendesk, Marid gets the configuration parameters from /etc/opsgenie/conf/opsgenie-integration.conf file.

Configuration Parameters
apiKey Copy the API key from the Marid integration you've created above
zendesk.url Your company's Zendesk url; for example https://opsgenie.zendesk.com
zendesk.email Enter an e-mail address and API token for a Zendesk user with agent role.
zendesk.apiToken

According to the action that will be executed in Zendesk, the script to be run can be set here. OpsGenie's script is set by default; you can change the following configuration to run your own custom script if you like.

Action Mappings
mappedActions.createTicket.script zendeskActionExecutor.groovy
mappedActions.addInternalComment.script zendeskActionExecutor.groovy
mappedActions.addPublicComment.script zendeskActionExecutor.groovy
mappedActions.setStatusToOpen.script zendeskActionExecutor.groovy
mappedActions.setStatusToPending.script zendeskActionExecutor.groovy
mappedActions.setStatusToSolved.script zendeskActionExecutor.groovy
mappedActions.setStatusToClosed.script zendeskActionExecutor.groovy

For more information about Marid, see Marid support document.

Zendesk integration package does not support SSL v1.0. If your Zendesk Server has SSL v1.0, we suggest you to upgrade your SSL server.

Sample params sent to Marid

{
  "zendeskUrl":"https://caglaopsgenie.zendesk.com",
  "integrationName":"Zendesk",
  "sendViaMarid":true,
  "zendeskEmail":"cagla.arikan@gmail.com",
  "subject":"test",
  "integrationId"=*********,
  "external_id":"og_d6d3775c-71c3-451f-8e2a-e946ac2d3dd5",
  "body":"[OpsGenie] New alert: \"test\" https://cd94fa71.ngrok.io/i/35,
  "tags":[],
  "apiToken":*********,
  "integrationType":"Zendesk",
  "mappedAction":"createIssue",
  "alias":"d6d3775c-71c3-451f-8e2a-e946ac2d3dd5",
  "action":"Create",
  "alertId":"d6d3775c-71c3-451f-8e2a-e946ac2d3dd5",
  "ticketID":null

}