Zendesk Support plugin
For more information about what this plugin does and the data streams it retrieves, see:
Zendesk Support or check out our sample Zendesk dashboards.
The Zendesk support plugin allows you to easily visualize data from Zendesk to see how agents and support teams are performing, find bottlenecks in your process and get a handle on KPIs.
To add a data source click on the + next to Data Sources on the left-hand menu in SquaredUp. Search for the data source and click on it to open the Configure data source page.
Before you start
SquaredUp can be configured to access Zendesk by either clicking the Sign-in button to log in using your Zendesk login credentials or by supplying a Zendesk username and API key.
If you want to authenticate using a username and API key, you will need to generate both of these before getting started. API keys can only be generated by a Zendesk admin, so make sure you login to Zendesk with Admin credentials.
Once generated, they can be used in conjunction with a specific user account, and it is the role of the user account that sets the permissions granted.
Generating API keys and adding users (called Team Members by Zendesk) are performed in the Admin center. To access the Admin center, log in to Zendesk with an account that has the Admin role, then click the apps icon in the top-right corner and select Admin Center.
Generating an API key
Generic instructions on how to generate an API key are provided by Zendesk here, or you can follow the below steps:
- In Zendesk, click Apps & Integrations and select Zendesk API.
- Ensure that Token Access is enabled then click Add API token.
- Enter a name for the token in the API token description field.
- Click Copy next to the API token.
Make sure you have correctly copied the token as you won't be able to access it again.
- Click Save to create the token.
Creating a Zendesk user with required permissions
The API key generated earlier can be used with any user account, the permission level that is granted is dependent on the user account specified.
The Zendesk data source requires a permissions level of Agent or higher. To use the Customer Satisfaction (CSAT) data stream the user must be an Admin user.
To create a user account for this purpose, Zendesk provides generic documentation here, or follow the below steps:
- From the Zendesk Admin Center navigate to People > Team > Team Members.
- Click Create Team Member in the top corner of the window.
- Enter the Name and Email address of the user.
- In the Assign role section, select a role of Agent or higher.
- Click Save.
- Navigate to the inbox of the created user and verify their email address as valid before attempting to use it.
Configuring the data source
Display Name:
Enter a name for your data source. This helps you to identify this data source in the list of your data sources.- Organization name:
Enter the organization name found in your Zendesk URL<organization>.zendesk.com
. Don't enter the.zendesk.com
part, just the organization name. - Authentication:
Select how you want to authenticate the plugin's connection to Zendesk. Choose from the following:- Sign-in button:
Click the Sign in with Zendesk button to authenticate using OAuth 2.0. You are redirected to the Zendesk sign-in page, where you are required to log in using your Zendesk credentials. You must then click Allow when the Allow SquaredUp to access your Zendesk account? prompt displays.
Once authenticated, you are returned to the SquaredUp plugin configuration page. - Authenticates the connection using the API token you previously generated. You must complete the following fields:
- Username:
Zendesk calls its users Team members. Enter the team member’s email address that you would like the data source to use the permissions of. If you want to use the Customer Satisfaction (CSAT) data stream then this user must be an Admin level user. - API Token:
Enter the API Token. This is used in place of a password and can only be generated by a Zendesk admin. An API token can be used by any user regardless of which account generated it.
- Username:
- Sign-in button:
- Import Organizations:
Select to import your Zendesk organizations as objects. Zendesk organizations are typically collections of your end users, but they can also include team members. - API Token:
Enter the API token you previously generated. The API token is used in place of a password and can only be generated by a Zendesk admin. An API token can be used by any user regardless of which account generated it - Import Organizations:
Select to import your Zendesk organizations as objects. Zendesk organizations are typically collections of your end users, but they can also include team members. - Import Organizations with Personal Email Addresses:
Select to import your Zendesk organizations not linked to specific domains as objects. Typically these are organizations based around a single email address and can exist in great numbers. - Import Specific Tags:
By default, SquaredUp only automatically imports tags that have been used in the last 60 days. If you would like to always import particular tags (even if they have not been used recently), then select this checkbox and specify those tags in the dropdown. Restrict access to this data source:
You can enable this option if you only want certain users or groups to have access to the data source, or the permission to link it to new workspaces. See data source access control for more information.Install Sample Dashboards:
Select whether you would like to install sample dashboards with the data source. By default, this is set to on.Click Test and add to validate the data source configuration. SquaredUp will now attempt to connect to SquaredUp using the provided authentication method. If this process fails, see Testing and troubleshooting for assistance with the corresponding errors.
Testing and troubleshooting
The following errors or warnings may be displayed while using the data source. If you encounter an error, refer to the guidance below or contact [email protected] for assistance.
Next Steps
Once you have successfully connected to the Zendesk data source, we will setup the data source by configuring data streams, the method we use to pull real time data back from Zendesk, install sample dashboard (if you chose to do so) and index objects which are used by data streams for scoping.
You must allow this process to complete before you use the data source. Closing the popup and then creating dashboards means there is a high chance that indexing will not have completed, resulting in errors and blank dashboards.
To check whether indexing has completed, click on the data source name and look at the data source status in the top left corner. If it says connected then indexing has completed.
Data source states
There are several states that all data sources can be in:
- Connected: The last data source index was successful. Indexing happens automatically every 12 hours
- Running: Indexing is in progress, if this is the first time the data source has connected to the source platform you should wait for this to complete to ensure all dashboards work without issues
- Warning: When something went wrong but that wasn’t terminal for the data source, meaning indexing was successful for some of the objects the data source and some data sources should work. If you hover over Move info you will be shown the reason for the warning
- Failed: The last graph index failed. If you hover over Move info you will be shown why. Note that each time a data source runs object indexing.
Data source capabilities
SquaredUp provides a high-level list of the data streams and object types for each data source, but once you have the data source connected then the data source overview page shows you more. You will then see each object type within your environment, in addition to the data streams available to the plugin.Click an object to see the applicable data streams - for example, you can click the drilldown for a Zendesk user Adam to see the relational data:Alternatively, you can click a data stream to see where it can be scoped to and the sorts of data it returns (which can then be saved to a dashboard if you so choose).
Modifying data source settings and connection details
You can modify your data source settings and connection details by clicking the Manage button on the data source overview page.
Graph imported objects
This data source imports the following objects.
Data streams
Data streams standardize data from all the different shapes and formats your tools use into a straightforward tabular format. While creating a tile you can tweak data streams by grouping or aggregating specific columns. Depending on the kind of data, SquaredUp will automatically suggest how to visualize the result, for example as a table or line graph.
Data streams can be either global or scoped:
- Global data streams are unscoped and return information of a general nature (e.g. Get the current number of unused hosts).
- A scoped data stream gets information relevant to the specific set objects supplied in the tile scope (e.g. Get the current session count for these hosts).
Scoped data streams
Global data streams
Unlike with scoped data streams, no objects are required for data to be returned.