Zendesk Application Engineer Jeremiah Currier has been with Zendesk for three years. Two of those were on the Support team where he was the Subject Matter Expert for Zendesk Apps & the REST API. He is a Podiatry School drop-out.

Part 1, 8 am: On the Apps Framework and how apps work

The Zendesk Apps Framework (ZAF) is part of the Zendesk platform and is actually its own development environment inside Zendesk. Zendesk created ZAF to enable developers to extend Zendesk beyond its core “out-of-the-box” feature set. This is helpful if you want to add new functionality or allow interaction with data from third-party systems.

There are three important things to understand about the ZAF:

It protects the rest of the Zendesk instance from errant code.

It simplifies customizing Zendesk. For example, you can install and update apps instead of copying and pasting code.

It provides tools to the developer / designer.

The ZAF provides all sorts of tools to the designer/developer (Data APIs & Interface APIs) that allow the Zendesk app they're building do things. This includes getting data from Zendesk, manipulating data on behalf of the user, and giving complete control over manipulating the user's own interface in the app.

The ZAF provides tools for structured access for manipulating certain elements of the Zendesk user interface. In addition to these APIs, another great tool included in the ZAF is Handlebars, which is a templating system. With Handlebars, multiple templates can be combined with a data model to yield a result document(s). Moreover, conditional logic (if/then statements, loops, etc.) can be added to data passed between templates displayed in apps.

“You can do a lot of really cool stuff with the ZAF.” - Me, Jeremiah Currier

The ZAF was launched a couple of years ago, with far fewer options for developers than exist now. The current ZAF is incredibly robust, and affords the developer many options to take Zendesk to the next level.

"I think it's very important to have a feedback loop, where you're constantly thinking about what you've done and how you could be doing it better." - Elon Musk

So who is it for?

Primarily, the ZAF was created for any Zendesk customer who wanted to integrate Zendesk with their own third-party tools or other integrations. Also, it empowers users who are looking to add features that don’t currently exist in Zendesk to help satisfy unique workflows.

How apps work within the ZAF

When Zendesk is loaded in your browser, two JavaScript files are served containing (1) the ZAF and (2) the installed apps for the given Zendesk account. In that second file each app’s app.js code can be thought of as a self-executing, anonymous function (that is, each app is its own function inside of the whole file of installed apps).

You can place apps in various locations in your Zendesk agent UI, so you control where your agents interact with the features of any given app. For example, if an app needs to display customer information to the agent while working on a ticket, then a good location for the app would be within the ticket.

Or it might be appropriate to have the app display directly on a user’s profile or organization profile. If the app needs a lot of screen real estate, then consider the navigation bar on the left side of the agent UI.

When choosing the location for your app, think about what the app needs to do, then place it accordingly.

Apps can talk to each other. To do so, combine the ~/api/v2/notify.json API endpoint from our REST API with the .popover() method in an app located in the Top Bar apps location. Then you can, for example, send out a message to all of your agent’s saying, “Great work today - everyone go home to your families now!”

Here’s an example:

So…..do you want to build an app yet!? If you’re ready to get started with the ZAF, begin with the app developer documentation on developer.zendesk.com. For working code examples that demonstrate everything that’s possible with the ZAF, feature by feature, check out the suite of demo apps.

Don’t forget to post your questions/comments/anecdotes in this article’s comments section for live feedback!

Part 2, 11 am: Using your own tool inside a Zendesk app

Many Zendesk customers are already using a tool external to Zendesk that they need to use simultaneously with Zendesk. This scenario is very common, so I’m including this section to discuss the considerations.

Sometimes customers like the look and feel of their existing third-party tool and they just want it displayed within an app in Zendesk. And sometimes customers want to completely port over their tool to turn it into its own Zendesk app.

Embedding an existing tool into a Zendesk app using an iFrame

This can be the route to go with when there’s an existing tool hosted on your website external to Zendesk. That tool can have the ZAF SDK added into its code, and the UI can be embedded inside of a Zendesk app using an iFrame. Adding the ZAF SDK to the Zendesk app lets the external tool send and receive messages via an iFrame to the app.

While the SDK is technically the ZAF SDK, often it’s also referred to as simply the ‘iFrame SDK’ in the context of embedding web apps inside Zendesk apps using an iFrame.

The postMessage API is part of the ZAF SDK that is added to the external customer tool. This API allows the Zendesk app (into which the tool is embedded) to send and receive messages.

Security considerations (for Zendesk apps in general)

For a hacker to see the SSL request details (API calls from Zendesk apps travel over SSL) they will have to compromise the victim's browser. If the web browser is compromised, or if the "Bad Certificate" warning is ignored, then SSL is no longer of any protection. The security of a customer's network is entirely external to their Zendesk instance and its apps.

Security considerations (for embedding a third-party tool in a Zendesk app using an iFrame)

When a customer adds the ZAF SDK to an external tool, it makes all events that are normally available to any Zendesk app available to that external tool too. So you should ensure that the tool embedded via an iFrame into a Zendesk app is a tool hosted at a trusted URL.

Design considerations

The nav bar is a good location to use for full page apps, but sometimes a tool needs to be available while agents are working on tickets or accessing user/organization profiles. Tickets and user/organization profiles have an apps tray on the right-hand side that is a fixed width. Keep this in mind when considering embedding an existing tool into a Zendesk app using an iFrame. Some customers recognize that there is a fixed width, and build for height, as there’s no fixed height in this area.

If the tool needs to be used by agents when on the ticket, user, or organization profile, then building a new UI into the Zendesk app might be the better way to go. If a UI is being built into the app from scratch, don’t worry. The Bootstrap Framework included with the ZAF makes the UI building process easier.

Don’t forget to post your questions/comments/anecdotes in this article’s comments section for live feedback!

Part 3, 2 pm: Tips & tricks for using the Apps Framework

Would you be interested to know some of the cool ideas that come up in meetings with customers who are planning to build Zendesk apps? Well, look no further.

A must-have for every Zendesk apps developer

These tools let the developer create all the app files at once, validate the code at any point in development, and test all the code locally by running a local server on the developer’s machine.

Create all files at once as seen below:

Testing apps when secure requests / app requirements are involved adds an additional level of complexity. There is existing documentation that covers the limitations of the ZAT server.

Test changes with the ZAT server running as seen below:

No template apps

Sometimes an app doesn’t need a UI. In that case, you can use an app without any template. To do this, simply add a “noTemplate” key to the manifest.json file in the app’s folder and a value of true. Taking this a step further, the developer can choose, in certain locations of the app, to hide the app initially and then display the app based on some event.

ngrok is a service that lets the developer expose a local service behind IP restrictionor a firewall to the internet including the feature of HTTPS requests.

Showing and hiding apps

In the ticket, user, and organization sidebar app locations, the app tray can have a number of apps running it. The real estate, so to speak, in these locations can become expensive. There are several ways to solve this problem, one of which being adding HTML containers around elements in an app, or the entire app itself, to show/hide the elements.

Showing and hiding an app displayed below:

Secure requests with HTTP basic authentication

Note: This is going to be useful only if the credentials are constant (i.e. the username & password to authenticate can be static), they are base64 encoded, and they are stored in the app settings.

The ZAF interpolation of secure settings does not account for the need to Base64 encode when using HTTP basic authentication. The developer needs to account for this when a set of authentication credentials is needed in the settings of the app that is used to authenticate some third-party API via HTTP basic authentication.

This tip assumes an understanding of Secure Requests as a feature of the ZAF, which hides sensitive information client-side from support agents using a given Zendesk app that has Secure Requests built into requests made by the app.

Here’s an example of how to write a function in an app to make a request using a secure setting and HTTP basic authentication. This example shows the credentials stored in the app settings already Base64 encoded:

username:password

Base64 encoded becomes:

dXNlcm5hbWU6cGFzc3dvcmQ=

So that value directly is stored in the secure setting:

manifest.json (excerpt)

...

"location": "ticket_sidebar",

"version": "1.0",

"frameworkVersion": "1.0",

"domainWhitelist": "api.domain.com",

"parameters": [

{

"name": "base64_encoded_credentials",

"type": "text",

"required": true,

"default": "dXNlcm5hbWU6cGFzc3dvcmQ=",

"secure": true

}

]

...

The Authorization header with the secure setting is formatted as follows using an example URL:

app.js (excerpt)

...

exampleFunction: function() {

return {

url : 'https://api.example.com/api/v1/users.json',

type : 'get',

dataType : 'json',

secure : true,

headers : {

"Authorization" : 'Basic ' + '{{setting.base64_encoded_credentials}}'

}

};

},

...

That’s all for now :)

Don’t forget to post your questions/comments/anecdotes in this article’s comments for live feedback!

Great stuff. I love the simplicity of the apps framework, and the zat tool. The Data API and the Interface API is really powerful.

Being able to test your app code locally using zat server, where changes are immediately deployed into Zendesk, so greatly simplifies development.

When we started with Zendesk, the Interface API and the locations didn't fully support the user sidebar or the organization side bar, but I discovered you have added support here, through your public apps changelog, which is awesome (I follow that changelog now, to keep up to date of any new additions to your framework).

When I started out with the apps framework, one source of confusion was interaction inside the app with the object

this.$

which is not a jQuery object, but a object with subset of some of it's features.

In the beginning, I tried to access jQuery functions like this.$.trim(), with no success. I have learnt since then, but I think we should improve on the documentation here. Maybe we could the capabilites of this object better?

When I started out with the framework, I sometimes added custom fields to the left sidebar (where ticket data and forms live), because this location is always visible, and it sometimes makes more sense from an UX perspective

Since then I have learned that when developing an app for the ticket sidebar, it's usually better to consider having your app's interface solely in the right (apps) ticket sidebar.

When I started installing apps in our Zendesk, I reflected over how much space each app takes in the ticket sidebar.

To remedy this, I'd love to see some built-in support for controlling the real estate of the app, specifically being able minimize apps, and remembering their toggle state. This is totally doable already, but it adds a lot of boilerplate code to the app, and it does require some consideration so the apps collapse state is tracked properly. Which is why is most apps in the marketplace today doesn't seem to offer this.

Basically, if it would be great to add support for changing the state of the app like below (example):

I can explain by using an example, let's say you have a container in an app that you need to hide using the JQuery .hide() method. You would do that this way:

this.$('#container-name-here').hide();

...where 'this' means the scope of the entire app and the rest is using JQuery to call the '.hide()' method on the DOM element you've specified, in this case that's the example ID 'container-name-here'.

Hopefully that helps.

2. "What I also like to be able to do within the apps framework, is to drop in some custom js libraries"

The documented best practice is to use our Interface API to hide & show ticket fields.

4. App real estate

There's a lot of ways to solve this problem but none of them are by a build-in method with ZAF that let's someone easily hide/show an entire app/etc.

Here is my response to this question already posted elsewhere in the forums including my working code examples. Again, this is just one way to collapse/expand an app.

5. "I'd love to be able to interact with the central column to the left of the right ticket sidebar (where the comments live).Is this on the roadmap yet?"

I'm afraid accessing elements of the DOM not built into what's possible with the aforementioned Interface API would not be supported. I can certainly appreciate the use cases you've described and regrettably it doesn't seem this is a feature coming soon.

6. "We use automations to auto remind requesters on certain pending tickets, or to reassign tickets where support agents are inactive. Would be great to be able to selectivly choose to display such events in the comment stream..."

This could be solved by using a trigger + target combination. It would operate like an application of a macro after ticket update using a target.

At one point, I'd love to be able to interact with the central column to the left of the right ticket sidebar (where the comments live).Is this on the roadmap yet?

I have lots of use cases, like

We use light agents (who don't work in Zendesk), so cannot use Internal Notes to make internal work notes on the ticket, since those are visible and set out with agent notifications. It would make perfect sense to put those notes in the comment stream instead.

We use automations to auto remind requesters on certain pending tickets, or to reassign tickets where support agents are inactive. Would be great to be able to selectivly choose to display such events in the comment stream

We have conversations where agents and customers are added and removed from CC. It would be great to hook into the comments audits to add some select extra info above the comment updates, showing which users where on the CC or notified for specific updates, and the source of a ticket update (e.g. the sender's email address)