Systemset Technical Overview

Systemset enhances the aspects of the standard Zendesk User Interface, therefore providing additional services to the user.

Systemset Enhancements

UI Components

Systemset can be configured to affect the following Zendesk screen types :

• Agent ticket page
• Agent user page
• Agent organization page
• End-User My Activities page (views)

Services

There are several service types from the simple hiding of fields (in the Agent Interface) to the full re-implementation of Ticket Request Views (in the End-User Interface).

Configurator

An Administrator uses the Systemset Configurator to specify rules and conditions to be applied to different parts of the Zendesk User Interface and to specify the Cloudset Role.

Systemset App Locations

Navbar Location

The Systemset Configurator runs in the Navbar location of the app.
 

Background Location

The configuration data is stored by Cloudset and delivered to a Background Systemset app.

The Background Systemset app uses an instance.created handler to detect when an agent is focused on one of the following:

• a ticket
• a user
• an organization
  
  

The handler reads the context.location to determine the page type and runs the appropriate tailoring logic for that screen according to the supplied rule definitions.

Systemset Configurator

Agent Interface Buttons

Click one of the following buttons to focus the Configurator to a particular area of interest:

These buttons lead to their respective pages in the agent interface.

The Background Systemset app reads and applies the configuration data defined within the screen opened according to the button selected by the Agent.

An Agent's ticket screen can be tailored to: 

• hide fields
• manipulate tags when fields change
• map system fields to show different values

Click the Tickets button to display these three sub-tabs which control each of these functional areas.

A candidate list of fields is presented in a column:

The Systemset Configurator finds these by querying the Zendesk API for the account's ticket fields. This illustrates why the app requires an OAuth token with administration rights before it can proceed. Without an OAuth token the API ticket field query would fail with an authentication error and the field list cannot be shown.

Click on the icon to the left of one of these fields and a drop-down list appears:

If you select a field to be hidden and click Save  the system writes the corresponding ticket field IDs to the configuration data.

The Background Systemset app uses services provided by the Zendesk Applications Framework Version 2  (ZAF V2) to hide the fields with IDs that match those in the configuration data.

NOTE: Existing ticket pages may need to be refreshed to pick up the latest changes.  

Tag fields

This feature is similar to Hide Fields as a candidate list of ticket fields is presented in a column.

If you select a ticket field, the icon to the left of it changes to a purple tick  and three tag values can be defined for when the ticket value changes in the Agent Interface.

These are:

• Set tag
• Update tag
• Clear tag

Click Save  to write the tag value definitions for the corresponding ticket field IDs to the configuration data.

At run-time, the Background Tailoring app uses the configuration data to record the initial values of the relevant fields.

When the Agent clicks Submit, a Save hook handler compares the latest value of these fields with their originals. If they have been set, updated or cleared, the corresponding tag value from the configuration data is added to the ticket using the ZAF V2 service, before the ticket is submitted.

Map fields 

Tailoring allows alternative values to be used to represent the Zendesk system fields : 

• type
• priority
• status

These alternative values closely reflect the terminology used by the Support Team. (There is more than one term corresponding to a particular system value).
Tailoring creates mappings between alternative values and their system equivalents. It applies these transparently at run-time.

Configuration Prerequisites

Before mappings can be created in the Systemset Configurator, dropdown custom fields containing the alternative values must first be defined using the standard Zendesk Administrator Ticket Field Screen.

Mapping Definition

The Systemset Configurator reads all the account's custom field types using the Zendesk API.

It presents the dropdown field types as candidates for selection in each of the three combinations for:

• Custom Type
• Custom Priority
• Custom Status

Select the appropriate custom field in each combination to present a panel to the right.

Each of the custom field values can be mapped here to its corresponding system value.

Different custom field values can map to the same system value if so desired.
Click Save  to write the mappings to the configuration data.

Background Application

On a ticket screen, the Background Systemset app reads the mapping configurations and for each one uses the ZAF V2 to: 

• hide the corresponding system field
• read the current value of its alternative custom field
• set the hidden system field to the mapped value of the alternative field

The app uses the ZAF V2 to add a listener for changes to the alternative custom field values. When this happens steps 2 and 3 in the bullet list above are reapplied to keep the hidden system value in sync.

Click the Users button to display the Hide Fields sub-tab. 

In a similar way to tickets, Tailoring can be configured to hide custom fields when focused on a user. A candidate list of user fields is presented in a column.

The Systemset Configurator finds these by querying the Zendesk API for the account's user custom fields. 
If you select a field to be hidden and click Save  the system writes the corresponding ticket field IDs to the configuration data.

The Background Systemset app uses services provided by the Zendesk Applications Framework Version 2  (ZAF V2) to hide the fields with IDs that match those in the configuration data.

NOTE: Existing ticket pages may need to be refreshed to pick up the latest changes.

Click the Organizations button to display the Hide Fields sub-tab.

In a similar way to tickets, Tailoring can be configured to hide custom fields when focused on an organization. A candidate list of organization fields is presented in a column.

The Systemset Configurator finds these by querying the Zendesk API for the account's user custom fields. 
If you select a field to be hidden and click Save  the system writes the corresponding ticket field IDs to the configuration data.

The Background Systemset app uses services provided by the Zendesk Applications Framework Version 2  (ZAF V2) to hide the fields with IDs that match those in the configuration data.

NOTE: Existing ticket pages may need to be refreshed to pick up the latest changes.

Supplementary Buttons - Views, Roles

Tailoring Views enables changes to the Zendesk End User Interface, Help Center (Guide).

The standard Help Center My Activities page shows ticket requests raised by a user and/or their organization(s), but the column layout is fixed.

The Systemset Configurator enables new views to be defined for the My Activities page with many different column types to display additional ticket field values.

A full description of how to configure views is outside the scope of this Technical Overview but to learn more please see the separate topic: Basic View Definitions.

Apps do not exist for the Help Center/Guide, but it can still run third party Javascript that has been inserted into the pages.

The Tailoring run-time code, for the replacement My Activities page, and its configuration data, is delivered to the Help Center by snippet code. The snippet must be inserted manually into the document head template by a Help Center Administrator, using the Zendesk Theme Editor.

The App generates the snippet for you when you click the Help Center Code Snippet button at the top right-hand side of the screen. 

The generated code is small but acts as a bootstrap loader to pull all the other required code for end user views onto the page.

Follow the instructions and paste the snippet into your custom theme. Afterwards click OK.

Cloudset Roles are independent of Zendesk roles.

• When defined, Cloudset Roles control the behaviour of Systemset and other apps in the Cloudset product suite, based on the current user.
• Cloudset Roles can be defined for Agents (via their Groups) and for End-Users (via their organizations). 

Configuration

Agent Roles can be created, renamed and deleted freely in the left-hand column. 

Selecting an Agent Role presents a list of Zendesk Groups in the right-hand panel.  

• Select one or more groups to associate them with the selected Agent role in the left-hand column.
• Deselect a group to disassociate it from the role.
• Any previously associated groups are shown pre-selected when the role is selected in the left-hand column.

Click Save  to write the agent role/organization mappings to the configuration data.

Once created, Formset and Flowset can reference the roles in their own configurators.

NOTE: The App looks up the current groups in Zendesk by querying the Zendesk API using the supplied OAuth token for authentication.

Cloudset App Runtime

At run-time, Formset and Flowset evaluate which Cloudset roles are associated with the current Agent. They do this so they can decide whether to apply any role-controlled logic defined in their configuration data.

To do this they look up the Agent's groups and compare them with the Agent role mappings in the configuration data.

Any Cloudset roles that contain one or more of the Agent's groups are considered to be valid roles for the Agent.

Configuration

End-User Roles can be created, renamed and deleted freely in the left-hand column. 

Selecting an End-User Role presents a list of Zendesk Organizations in the right-hand panel. 

• Select one or more organizations to associate them with the selected End-User role in the left-hand column.
• Deselect an organization to disassociate it from the role.
• Any previously associated organizations are shown as pre-selected when the role is selected in the left-hand column.

Click Save  to write the end user role/organization mappings to the configuration data.

Once created, Systemset can reference them to restrict the visibility of End-User views by role.

NOTE: The App looks up the current organizations in Zendesk by querying the Zendesk API using the supplied OAuth token for authentication. If there are several organizations the interface switches to use a search-based GUI.

Help Center / Guide Runtime

At run-time, the Javascript for End-User views, loaded into the page via the snippet, looks up the End-User Roles for the current user, to determine whether they can see any role-restricted views.

To do this the system finds the end-users's organizations using an Ajax call to the me.json Zendesk API endpoint. It compares the users' organizations with those in the End-User Role mappings. Any Cloudset roles that contain one or more of the End-User's organizations are considered to be valid roles for that End-User.