Designing an integration
This article provides some design guidelines for creating the installation and configuration experience for admins managing your integration. We recommend following these guidelines so you can provide admins with a consistent experience by leveraging our existing design patterns and elements.
In the future, it will be possible to submit your integration to the Marketplace. Part of the acceptance criteria will be that it meets certain visual and experience standards. Use these guidelines to ensure your integration looks, feels, and acts as it should.
Zendesk Garden is an open-source design system providing a common baseline of styles and components such as buttons, icons, and colors. Use Zendesk Garden to match the Zendesk look and feel for your integration.
For private integrations, you upload the integrations ZIP file to your Zendesk account. To learn more building an integration app with OAuth flow, see the Zendesk app as an admin interface tutorial series.
The installation and OAuth process should occur when the end user sets up the integration for the first time.
During the installation process of an integration, you’ll need to allow the user to give you permission to access one or multiple systems. This includes authenticating with Zendesk and other systems.
If your integration only requires a single authentication with Zendesk, you should aim to keep the user within the Zendesk product, without redirecting them anywhere else. This ensures a smooth and consistent experience for your user.
A majority of integrations will have at least two systems which require connection such as Zendesk and a third-party system. In this instance you should design your flow to authenticate with Zendesk first before authenticating with other systems.
A few things to keep in mind:
- Do not send your users to any more locations than they need
- Do not ask users to provide authorization for systems which are not part of the integration
Some integrations require multiple external connections to the one Zendesk instance, such as connecting multiple Shopify storefronts to one Zendesk subdomain. In this instance, users must be able to connect and manage multiple connections.
The installation flow consists of three steps.
Step 1: Connect
Depending on the system, you may need to ask for different values. For example, you would provide a link to the third-party account.
Multiple connections to single Zendesk instance
If your integration allows for multiple connections to one Zendesk subdomain, you should provide extra steps to allow those connections. For example, multiple Slack workspaces connecting to one Zendesk account.
We recommended allowing the user to name each connection so they can easily identify it.
Step 2: Allow Zendesk permissions
Assuming the Zendesk user is logged in, they should be redirected to give permission for your integration to access Zendesk.
Step 3: Allow third-party permissions
After providing Zendesk permissions, you should then prompt the user to allow your integration to access the third-party application. This will redirect the user to the other system to authenticate and allow access. Wherever possible, you should do this in a new browser window rather than navigating away from Zendesk in the primary window.
Use Zendesk Garden base components to produce the configuration pages. The configuration page should contain the following components:
- Header - The header contains information helping the Zendesk Admin contextualize their location within Admin Center
- Navigation - The navigation within your integration will help an admin contextualize their location within your integration. When setting up the structure for your integration configuration, first consider your navigation and the complexity of your configuration. See the design templates below
- Configuration workspace - This is the screen that you should leverage as your configuration workspace. Any configuration you need to surface should be shown within this area
The design templates provided below accommodates a variety of navigation use cases.
Use this template when your integration doesn’t require multiple levels of hierarchy. This is the simplest type of configuration.
This is the recommended approach in most cases. This provides a simple and easy way for your users to see different content and settings relating to your integration.
With more complex use cases, vertical tabs can be used as they are more scalable when adding in five or more features.
When a user uninstalls your integration, make sure they know what’s going to happen next. It’s important that your Zendesk admin is informed about when Zendesk and other data is being deleted.
The flow for uninstalling an integration should consist of the following components.
Step 1: Uninstall page
The uninstall option should be placed behind an Actions menu to make it less accessible to the user.
Step 2: Confirmation modal
A confirmation modal needs to be shown to the user when a destructive action occurs such as uninstalling an integration. Make sure you clearly tell the user the consequences of the action and inform them on what will happen next regarding data and permissions.
If you have any questions, contact Zendesk Customer Support.