The Zendesk Resource API allows developers to build Zendesk widgets that push data into external sources, and optionally pulls data from external sources back into ticket events. The external sources are URLs that act as REST resources.

The Resource API works exclusively through Javascript. If your sources are REST enabled, all you need is javascript in your widget to utilize the Resource API.
The API itself is a javascript library (/javascripts/push/zd_resource.js) that HTTP GETs and POST/PUTs your REST resources through a Zendesk server proxy. The server proxy is necessary due to cross-site scripting restrictions present in most browsers. The Javascript library uses the Prototype Framework.

To illustrate how the Resource API is used, we will recreate the Harvest widget as a custom widget. The Harvest widget allows agents to register time spent on a ticket through Harvest:

Upon submit of the time registration form, values associated with the time registration are pushed back to the ticket as an event:

The contents of the Harvest widget is:

<div id="harvest-time-tracking" domain="yourharvestaccountname.harvestapp.com"
    use_ssl="true">
  <h3 id="title"></h3>
  <div id="content"></div>
</div>
<script src="/javascripts/push/harvest.js" type="text/javascript"></script>

The div with ID “harvest-time-tracking” includes Harvest domain definitions and content placeholders for the widget. Following the Harvest div is the javascript for the widget. This could be inline, but in this example it resides on the Zendesk server. It could just as easily reside on a server of your own choosing.

The following will be a walk-though of the Harvest widget javascript.

Resource initialization

At the bottom of the javascript code file for the Harvest widget (/javascripts/push/harvest.js) you’ll find the initialization of the API’s Resource object:

harvest_resource = new Zendesk.Resource(
  {title: 'Harvest time tracking',
   anchor: 'harvest-time-tracking',
   domain: $('harvest-time-tracking').readAttribute('domain'),
   use_ssl: $('harvest-time-tracking').readAttribute('use_ssl') || 'false',
   login_content: login,
   application_content: application,
   application_resources: [ {resource: 'daily', on_success: projects_selector} ]
  }
);

Let’s go to trough each of the objects initialization parameters:

title

The title of the widget. Appears on the widget form.

anchor

DOM ID of the element where the widget will be placed.

domain

The resource domain. In this example, the value is read from the “domain” attribute in the widget div ID – i.e. yourharvestaccountname.harvestapp.com.

use_ssl

If you need to communicate with your resource domain through SSL, set this attribute to true. In this example, the value is read from the “use_ssl” attribute in the widget div ID.

cache_gets

Caches the content of the application part (see section “The application function”).

login_content

References the function in your javascript that generates the login form (if any). See section “The login function”.

application_content

References the function in your javascript that generates the application part. See section “The application function”.

application_resources

An array of resources that needs to be consulted in order for the application part of the widget to be displayed correctly. Typically values for form elements. In our Harvest example we have one application resource, “daily” that generates the values used to populate the “Select project” and “Select task” parts of the widget form.

{resource: 'daily', on_success: projects_selector}

Thus, the application resource is yourharvestaccountname.harvestapp.com/daily. The resource is processed asynchronously, and the result is sent as a JSON object to the projects_selector function on success. This functions traverses the JSON object, picking the project and tasks values on your Harvest account, and dynamically inserts those in the widget application dropdowns.

The Login function

Your widget might need to capture login credentials for the agent, if your resource(s) require authentication. These login credentials are subsequently passed on to the resources, when e.g. populating the application part of the widget (see next section) or pushing data to the resource.

The login function for our example widget is trivial, and can be found at the top of the javascript code file for the Harvest widget (/javascripts/push/harvest.js). It simply writes out the login form html:

When an agent submit the login form, the login credentials will be cached by the Resource API. Subsequently, the widget will no longer display the login form, but the application part of the widget.

The application function

The application function in the Harvest example generates the time registration form – the application part of the widget. Have a look at the application form in the javascript. First the function defines placeholders for the tasks and projects dropdowns and the notes and hours text fields. These are all parameters that is required for the Harvest time registration. When the form is submitted, request[field] values are POST’ed to a defined resource. Secondly, various hidden form fields that are not directly associated with the time registration are defined. The value of these instructs the Zendesk proxy what to do with the form content – e.g. which resource to POST to.

Let’s take a closer look at each of the hidden parameters:

resource

The resource to POST the form parameters to. In this case, yourharvestaccountname.harvestapp.com/daily/add

media_type

application/xml or application/json. Use the latter if the resource returns JSON when GET’ing.

event_reference

Title on the ticket event we will be logging.

event_log

Values to log to the ticket event. These values correspond to values in the answer from the POST to the resource. In this case the result from POSTing the form parameters to yourharvestaccountname.harvestapp.com/daily/add. The result will always be delivered from the proxy as JSON, regardless of the original format of the resource’s return.

pluck_param

Defines the form fields to pass on to the resource. In this example fields prepended with “request” – e.g. request[notes]