Connecting an environment to Salto
The first step to using Salto for configuration management in Zendesk is to create a new environment in Salto.
Salto can connect to one or many Zendesk environments and makes deploying changes from one environment to the next a breeze. Possible environments to add can include Sandbox, Production, and any other Zendesk environment.
Creating a connection between Salto and Zendesk can be done through:
OAuth Salto will create a connection by navigating to Zendesk and allowing a user to log in to Zendesk and approve a connection to Salto. If a user is already logged into Zendesk, the current user information will be used. Note: Salto does not store user credentials and instead relies on the OAuth protocol for the authentication handshake.
API token This approach relies on generating an API token inside of Zendesk, then providing Salto with said API token along with the username used to generate the API token.
Detailed Zendesk environment setup instructions can be found here
Environment settings
Salto provides user with the ability to define settings on an environment-by-environment basis.
These settings sections include:
General - This is where users can update some of the more high-level settings for the environment. This includes the ability to:
Update the environment name to change how it displays inside of Salto
Setup a Scheduled fetch. This determines how often Salto should automatically fetch changes from your environment
Mark an environment as "sensitive" which adds an extra confirmation step before deploying to this environment
Delete the current environment
Application Connections - This displays all applications connected to this Salto environment. For each application you can get a list of credentials used. This documentation article provides more information on how to update these credentials. For each application connection the following can be done:
Edit the Salto adapter configuration file - This can be accessed by pressing the kebab/ellipsis button on the right-hand side and selecting “Edit configuration file”
Update shared credentials - These credentials will be used by the entire team to fetch and even deploy changes to the given environment. Most often this is set to
Fetch, which will allow team members to perform manual fetches or schedule fetches. To allow users to deploy they will need to provide their own personal credentialsUpdate personal credentials - These are specific to the current logged-in user. When provided, these user credentials will be associated with the deployment done by said user. Users can also update the credentials used by Salto to fetch and deploy. This may be useful if the existing account has expired, or a team wants to change the credentials associated with deployments. Note: make sure you have set up "personal credentials" defined for any given environment ahead of starting a deployment*
Delete the current application - This can be accessed by pressing the kebab/ellipsis button on the right-hand side and selecting “Delete application connection”
Note: to fetch Zendesk Guide elements, such as articles, sections, etc., see the Zendesk Guide setup docs
Version Control - This page displays information and configuration options related to connecting a Salto environment to a Git-based repository. For more information refer to the Salto / Git integration overview article. Within the Version Control page the following configuration options are available:
Connect to a repository, navigate the connected repository (using the kebab/ellipsis menu), or disconnect the existing connected repository (using the kebab/ellipsis menu)
Auto push credentials: these credentials are used with changes that are pushed to the underlying repository. Note: team members will be prompted to authenticate with their personal Git account to create and merge deployment Pull Requests.
Manage branch files: this feature is used to add or manage non-application configuration changes in the underlying repository. This is used when updating the readme file of the repository, or any type of update that does not include
.naclfiles. The UI provides instructions for how to select an open Pull Request to merge.Enable pull requests: when enabled, each deployment created in Salto will create a Pull Request in the underlying repository. When a deployment is successful, said Pull Request will automatically be merged by Salto.
Monitor changes - This area lets users define notifications to be alerted when changes are made to the given environment. See below section focusing on monitoring changes for more details.
Impact analysis
Whenever a change needs to be made in Zendesk the actual change itself is just the first step. Understanding how this change may impact other areas of your Zendesk instance, and creating a plan for how do address this impact, is critical to ensure changes do not break something inside of Zendesk.
This type of Impact Analysis is a common use case when using Salto.
The Explore page in Salto is can be used to explore your Zendesk configuration, see dependencies and understand where and how configurations are used. Some commonly-used features include:
Explore and understand a Zendesk configuration represented as Salto
elementsGain a deep understanding of a given Zendesk element via Salto’s AI-assisted “Explain this element” feature. This feature will produce information related to the purpose of the element, an overview of what the element does, and a high-level summary. Can be used with Zendesk automations, triggers, and macros
Immediately see what other areas of Zendesk are dependent on the current element (e.g. if a custom field needs to be deleted, what macros or ticket forms rely on said custom field?)
Quickly understand where the current Zendesk element is being used elsewhere in a Zendesk instance (e.g. when updating a custom field, what triggers and/or macros use this custom field?)
Search for strings within all existing Zendesk elements. Useful when updating all instances of a URL, rebranding, or other find and replace scenarios
Useful impact analysis resources
Monitoring changes
Salto provides highly configurable monitor changes feature to inform users of any type of changes occurring in a given Zendesk environment by sending notifications via email and/or Slack message.
The types of information that can be reported on can range from simple summaries on changes that have happened in an environment on a daily basis to more granular updates whenever a specific type of element is modified in some way.
Common use-cases for monitoring changes include:
Be kept up-to-date by receiving a daily summary of changes that have happened in the sandbox environment
Help ensure a team is adhering to a newly established process by sending a notification when changes are made directly to production rather than the new sandbox → production workflow
Prevent Zendesk macro bloat by creating an alert when macros are modified, deleted, or added
Salto’s monitor changes feature can be customized and tailored to fit most scenarios where regular updates and immediate alerting to updates in Zendesk are needed.
Useful Monitoring changes resources
Compare environments and deploy
Salto’s Compare & Deploy feature allows users to compare two environments (e.g. Sandbox and Production) and deploy changes from one environment to the next.
Changes can be promoted with a few clicks, and if desired Salto can encourage a stricter change management process by allowing only certain team members (release managers) to push changes to production.
Using the compare and deploy feature users can:
Deploy all recent changes done in a sandbox environments and promote them to production
Select a subset of changes like a single Zendesk trigger in sandbox and deploy them to production
Completely refresh a sandbox environment to reflect production, ensuring parity between environments before starting to use a more rigid change management process
Salto offers a few ways to deploy changes between environments:
Compare & Deploy Choose which changes to align between any two environments.
Find environment changes & deploy Choose the changes made during a specific time period to deploy into another environment. Especially useful when deploying from a shared environment.
Promote a deployment Used to promote the same set up changes to another target environment. (ex: after deploying a set of updates to a form in
UAT, promoting those same changes up toProduction)Revert a deployment Revert all changes made in a specific deployment (Note: to revert specific changes, use the restore process mentioned above)
For more information please refer to the compare & deploy documentation article in the Salto help resources.
Useful compare environments and deploy resources
Change log
Salto automatically keeps track of all changes made to any given environment, whether they are made through a Salto deployment or directly from within Zendesk, under the “Change Log” tab.
Within the change log tab users can:
See a complete list of fetch and deployment operations
Quickly understand the nature of changes thanks to meaningful titles and descriptions of the changes made - including changes made outside of Salto such as ticket IDs
Inspect detailed changes for each operation, including what elements were modified, before-and-after values, who was responsible for the changes, and more
Compare the current Zendesk configuration to a previous configuration, with the optional action to restore to a previous configuration
Useful change log resources
Backup and restore
By connecting Salto to a Zendesk instance Salto will automatically backup the configuration of an environment with every fetch operation. Fetching can be done on-demand and will create a snapshot of a Zendesk configuration each time a fetch is performed.
Taking this a step further, Salto can be configured to schedule the fetch operation on a weekly, daily, and even hourly basis, providing organizations with regular snapshots of their Zendesk instance without the need to manually create said snapshot.
If at any point in time there are issues with a Zendesk environment Salto’s restore process can be used to revert changes to any previous snapshot with just a couple of clicks within Salto.
Configuring Salto to create these backup and restore points on a regular basis ensures that only the specific changes which are the root cause of any ongoing issues are reverted, leaving other changes untouched.
Useful backup and restore resources
Configuration issues and environment alignment
When an environment is first connected to Salto, you may see a number of configuration issues, such as identically named elements or permissions issues. Review the Salto ID collisions using this reference as a guide to resolve any ID collisions.
Be aware that Salto uses the names of elements to align them between environments.
For example, if a ticket field is named "Request Reason" in sandbox and "Request Reasons" in Production, Salto will see those as two separate ticket fields, which could lead to unexpected misalignment issues.
If you see these issues, you will have to rename the element(s) and run a fetch in the environment with "regenerate Salto IDs" enabled to re-align the environments.
Common use cases and examples
Using find and replace to perform bulk changes
To make bulk changes (for example, updating a URL to refer to a new URL), you can use Salto's "edit an environment" deployment type to use a text editor (either an in-browser version of VS Code or an external editor of your choice) to do bulk find and replace operations.
Note: this feature requires connecting the Salto environment to Git provider like GitHub. Additionally, the in-browser editor offered by Salto requires one of GitHub, Azure DevOps or Gitlab.
Deploying when a user doesn't exist in the target environment
When deploying elements (such as views, triggers, articles, etc.), they may references users that don't exist in the target environment.