Migrating Support apps to ZAF v2

Before migrating your app, you should have a basic understanding of the new version of the Zendesk Apps framework. If you're new to the framework, see How does it work?

Note: If you used the App Migration Scaffold before November, 2018, the scaffold and its documentation are still available on Github. However, the scaffold was experimental in nature and is no longer part of ZAT. The documentation on Github is for past users.

Understanding the ZAF client

A ZAF v2 app typically consists of HTML displayed in an iframe in a specified location in the Support agent interface. The ZAF SDK v2 provides a ZAFClient global object that allows cross-frame communication between your app and the host Zendesk product.

To create the client

  1. Import the ZAF SDK into the iframe HTML as follows:

    <script src="https://static.zdassets.com/zendesk_app_framework_sdk/2.0/zaf_sdk.min.js"></script>
    
  2. With the SDK in place, you can create a ZAFClient object as follows:

    var client = ZAFClient.init();
    

You can now use the client object to access the framework APIs. Example:

client.get('ticket.requester.name').then(function(data) {
    console.log(data); // { "ticket.requester.name": "Mikkel Svane" }
});

In this example, the client gets the ticket requester's name from the Ticket API. For details, see the next section.

Working with framework APIs

The ZAF client provides get, set and invoke methods (and a few others) to work with framework APIs. Each method returns a JavaScript Promise object with the result of the request.

The following examples compare ZAF v1 and ZAF v2 requests.

Get a property

ZAF v1

var name = this.ticket().requester().name();
console.log(name); // Mikkel Svane

ZAF v2

var client = ZAFClient.init();
client.get('ticket.requester.name').then(function(data) {
  console.log(data); // { "ticket.requester.name": "Mikkel Svane" }
});
Set a property

ZAF v1

this.ticket().type('task');

ZAF v2

var client = ZAFClient.init();
client.set('ticket.type', 'task');
Run a method

ZAF v1

this.comment().appendText('My printer is on fire');

ZAF v2

var client = ZAFClient.init();
client.invoke('comment.appendText', 'My printer is on fire');

To learn more, see Working with framework APIs.

Using the ZAF v2 APIs

As in ZAF v1, the availability of various ZAF v2 APIs depends on the location of your app in Zendesk Support. All the locations in ZAF v1 are included in ZAF v2. See the following ZAF v2 docs for the events, properties, and actions you can use in each location.

Location Description
all locations All listed locations
ticket sidebar Panel on the right side of the ticket
new ticket sidebar Panel on the right side of the new ticket
ticket editor Toolbar on the lower side of the rich-text ticket editor
user sidebar Panel on the right side of the user page
organization sidebar Panel on the right side of the organization page
nav bar Navigation bar on the left side
top bar Right side of the bar on the upper side
background No UI, always running in the background to receive special events
modal Modal dialog

Note: While ZAF v2 aims to support all existing framework features, in some cases some features may be missing or incomplete due to the nature of the new architecture. For more information, see the feature parity status page.

Using third-party libraries

Unlike ZAF v1, ZAF v2 doesn't include third-party libraries like Bootstrap and Underscore.js. The choice of libraries is yours, though you can of course include the same libraries you were using in v1.

Consider including JavaScript libraries from a popular CDN in your migrated app. The following example gets libraries from the jsdelivr CDN:

<script src="https://cdn.jsdelivr.net/g/lodash@4.3.0,handlebarsjs@4.0.5,jquery@2.2.0,momentjs@2.9.0,bootstrap@2.3.2"></script>

In the example, a jsdelivr feature creates a single file containing the specific versions of all the libraries. You can learn more about the feature in the jsdelivr docs.

Using Zendesk Garden CSS

While you can use any CSS stylesheet for your app, Zendesk recommends using Zendesk Garden CSS. Zendesk Garden is designed to be a common baseline of styles and components between all Zendesk products. Use Zendesk Garden CSS classes to ensure the look and feel of your app fits in with the rest of the Zendesk product branding.

You can import Zendesk Garden CSS classes into your app's HTML template from the jsDelivr CDN. See https://www.jsdelivr.com/?query=zendeskgarden. The jsDelivr files are npm packages that can also be installed from npm. See https://www.npmjs.com/search?q=zendeskgarden.

For more information about the CSS classes and React components in Zendesk Garden, see garden.zendesk.com or the demo app.

Updating your manifest file

To update your ZAF v1 manifest to be compatible with ZAF v2:

  1. Update your locations as described below.
  2. Update frameworkVersion property to 2.0.

In ZAF v2, the location object defines URLs that point to HTML files. When migrating, you can point all your locations to the same HTML file.

ZAF v1

{
  "location": ["ticket_sidebar", "new_ticket_sidebar"]
}

ZAF v2

{
  "location": {
    "support": {
      "ticket_sidebar":     "assets/index.html",
      "new_ticket_sidebar": "assets/index.html"
    }
  }
}

For details, see Setting the app location.

Next steps

Even after following these steps, your app might still not work unless you update your code to use the new ZAF SDK v2 APIs. Additionally, you may need to rewrite some functionality that may not be present in ZAF v2. If you get stuck, see the following resources: