:grey-exclamation: Available in the Enterprise version

A common Salto use case is documentation. You may decide to document your production business application changes due to:

  • SOX compliance - teams in publicly traded companies are required to meet certain financial processes, including documenting all of their financial related changes, e.g., changes in Salesforce (financial related objects), Netsuite or Zuora. This is needed to prove to the auditors that the company is following all of the requirements correctly.
  • Best practice - proper documentation helps debugging production issues / root cause analysis and onboarding new team members.

Initial Setup

First, make sure to set up a scheduled fetch so that your Salto production environment is regularly updated with changes in the relevant business applications.

Second, please make sure you have a git provider integrated with your Salto org. Step-by-step instructions on how to complete this flow can be found here

Then, you will need to connect your production environment to a git repository and branch. To do so, go to the Audit tab at the top and click on the ‘Connect Git’ CTA.

🚧

Please make sure that you have write permissions to the connected git branch (aka not ‘push protected’)

Lastly, make sure to connect your Git provider with your ticketing provider, e.g., Jira or Zendesk. Doing this will allow any documented change from Salto with a ticket-id mention to appear in the mentioned ticket in your ticketing system, along with a link to the changed code in Git. This is helpful in documenting your changes from request (the ticket) throughout the change in production.

Documentation

You may decide on a process where the whole team meets on a weekly basis to document the changes together (typically fits smaller teams) or to document your changes as they happen / end of day by the person who made the change (typically fit larger teams). Either way, you will start from the Audit tab where you can see:

  1. At the top, the pending changes that should be documented. Click on the ‘Preview Push’ CTA to document these changes.
  2. Below, under the ‘Commit History’ headline you can see the previously documented changes. Each change includes the name of the user who documented the change and the commit (documentation) message. Below the vertical 3-dots menu you have a link to the code change in your Git provider.

Preview Push

This is where the actual documentation takes place. On the left, you can see each of your configuration files that contains a change. The +, - & M symbols indicate whether the change is an addition, e.g., a new field, a deletion, or a modification, e.g., a value change. Files with multiple different changes, e.g., additions and deletions will appear with an M symbol.

Clicking on a file will allow you to see the exact change by comparing the file version before the change and after it.

You can select one or more files or all of them via the ‘Select All’ CTA at the bottom.

On the right side you can document the nature of the change via the title and message boxes. Selecting at least one file and adding a title enables the ‘Push’ button. Clicking the button will commit your message, along with the code change to Git.

Make sure to mention your ticket number, e.g., in Jira that would be your project name and the ticket number: name-3754, so that your comment and link to the code change in Git will appear in the relevant ticket in your ticketing system.

You can mention multiple tickets within one Push event if your code change addressed multiple tickets. Similarly you can select multiple files with one ticket and Push event, if your ticket was addressed by changes in multiple files.

Salto supports Jira ‘Smart Commits’. This feature allows actions such as commenting on or closing a ticket in Jira, directly from Salto. Enabling this feature in Jira also allows you to automatically add a list of all of your documented file names by adding {{fileNames}} to your commit message.


What’s Next
Did this page help you?