Salto

Salto Documentation

Welcome to the Salto docs!

You'll find comprehensive guides and documentation to help you start working with Salto as quickly as possible, as well as deep dive into Salto topics and ideas you find interesting.

Let's get started!

Get Started

NaCl in detail

Introduction

A formal language specification is coming soon. In the interim we will gradually add more information about NaCl to this page.

:mag: Eager to dive deeper? The basic syntax is mostly HCL2 with some minor deviations.

Configuration elements

At its core, Salto fetches the configuration of business system accounts and builds an hierarchy of configuration elements where each element is represented by a unique Salto Element ID.

A Salto Element ID conforms with the following schema:

<adapter>.<type>.attr.<name>[.<key>...]
<adapter>.<type>.field.<name>[.<key>...]
<adapter>.<type>.instance.<name>[.<key>...]

A few configuration element id examples:

# salesforce object 
salesforce.MyCustomObj__c

# salesforce object's field
salesforce.MyCustomObj__c.field.MyField__c

# apex class
salesforce.ApexClass.instance.MyApexClass

Using element IDs

Element IDs are used as references, encoding meaningful relationships between config elements. Element IDs are also used as filters or selectors in several commands, including:

  • Searching for elements
  • Moving elements to/from Common Config
  • Cloning elements from one env to another
  • Restoring elements from their env's state

Below are some examples of using element IDs in Salto-IDE and the open source CLI.

Salto-IDE

Salto-IDE aspires to make these element commands as accessible and useful and possible. Editing commands are generally accessed by right-clicking an element definition line, while element search is available on the workspace level.

Search

  • To access, click the magnifying glass at the top of the workspace's file tree. Search has two modes: Files and Elements; make sure to switch to Elements
  • To search, enter any part of the ID you have in mind, for example:
    • salesforce.Account.field. will suggest all the fields defined under the Salesforce Account object
    • salesforce.Account.field.SLA__c will find the specific SLA field under Account
    • Just typing SLA is a great option, since it will suggest the exact field, as well as other elements that have the word SLA in their IDs, and might be relevant

Editing

  • To access editing commands, find the element in question, and right-click its definition line; in the right-click menu you'll find options like Move Element to Common, Clone Element to Another Env, Restore Element from State and a few more
  • Clicking one of these commands opens a preview screen presenting the NaCl change that will happen if you approve the command

Command line interface

Salto's CLI (command line interface) is a key component is Salto's open source project, and many decisions on Salto's SaaS interface come after deciding on the CLI solution first. To learn more about the CLI, visit the open source project on GitHub.

The CLI supports several commands for moving, copying, comparing and manipulating configuration elements. These commands usually accept an element-id-selectors input parameter that enables the user to provide a list of element ID patterns represented by regular expressions.

For example, all custom fields of the Salesforce Lead object can by represented by:

salesforce.Lead.field.*__c

:information-source: For a full guide on how to use the CLI visit the user guide on GitHub.

Salto core annotations

Salto supports various annotations whose semantic is enforced by the tool itself, independent of the business application the relevant configuration element is mapped to.

  • _required A boolean specifying whether the specific field value must be set or if it may be omitted when defining an instance or using it as a field in another type. Adapters may use this annotation whenever their target service supports the feature of required/optional fields.
  • _default A default value that will be used in instances that do not explicitly define a value for the specific field.
  • _restriction Can be used to define acceptable values for a particular field or type, accepts a complex value with (some of) the following fields:
    • values A list of allowed values for the field
    • min For number fields, the smallest allowed value
    • max For number fields, the greatest allowed value
    • enforce_value A boolean specifying whether the restriction should be enforced. when set to true, restriction violations will create warnings (this is the default behavior), when set to false a violation of this restriction will be ignored (the restriction is essentially disabled)
    • regex A regular expression that the value should match (e.g. "^[a-z]*$" for lowercase values)
  • _depends_on Can be used to explicitly define dependencies between blocks. Its value is a list of references, each reference marks that this block depends on the reference target
  • _parent Can be used to explicitly define a relationship between blocks. Its value is a list of references, each reference marks that this block is a child of the reference target, unlike _depends_on, a parent relationship means the child block is assumed to be deleted automatically (by the service) when the parent is removed
  • _generated_dependencies System-generated list of additional references besides the ones already covered elsewhere. Should not be modified manually - use _depends_on instead

Built-in types

The following types are supported in the language:

Name

Example field definition

Example value

Description

string

string name {}

"me"

'''
Multiline
String
'''

Use " to define single line string.

Use ''' to define a multiline string.

number

number age {}

12

boolean

boolean isOpen {}

true
false

json

json value {}

"{ "a": 12 }"

A string value that expects the value to be in JSON format.

serviceid

serviceid myid {}

"ID"

A string value that denotes an ID in the service (used by adapters to distinguish ID fields from other fields).

list

"list<string>" listField {}

["a", "b", "c"]

A list of values. contains values of a specific type.

map

"map<string>" mapField {}

{
a = "A"
b = "B"
c = "C"
}

A map/dictionary with string keys, and values of the specified type

set

Coming soon!

Coming soon!

unknown

unknown anyType

anything

A field value which is not validated, and can hold any type of data.

References

In some cases, it is useful to reference one element from another. Such references can be introduced by the adapter, or by the user when manually editing NaCl files.

A reference is done to a Salto Element ID.

For example, if we want to define that the value of a certain field will reference the value of another field, we could write :

valueSet = salesforce.StandardValueSet.instance.LeadSource.standardValue

In the case you need to reference a specific element in a list, you should use the index as an additional key, e.g. salesforce.Lead.field.MyField__c.valueSet.2.fullName would access the fullName attribute of the 3rd element in the list valueSet under the custom field MyField__c which is part of salesforce.Lead

A reference implies a creation dependency between a source and a target element. Meaning that when element A references element B it also implies that Salto will make sure to create element B before element A is created.

Variables

Variables let you define a primitive value, give it a name, and then use it multiple times. Variables are defined using a vars block:

vars {
    secondsPerDay = 86400
    daysPerYear = 365
    firstMonth = "January"
}

Variables can be defined anywhere in the NaCl files, and there can be many vars blocks. The scope of a variable is always global, so any variable can be referenced from any NaCl file.

A variable is referenced using the following schema: var.<name>. For example, we can set:

salesforce.CompanySettings {
    fiscalYear = {
        fiscalYearNameBasedOn = "endingMonth"
        startMonth = var.firstMonth
    }
}

Static Files

Static files allows you to store content in an external file referenced in the NaCl file.

This simplifies viewing and editing the content in separate files instead of a huge string block inside a NaCl file.

salesforce.Text ApexFileForProfile {
    content = file("salesforce/classes/ApexFileForProfile.cls")
}

Those files are stored in the static-resources folder inside your workspace (see more at How Multi-env works).

E.g. for the ApexFileForProfile class above, the content will be saved to static-resources/salesforce/classes/ApexFileForProfile.cls.

The files are validated and hashed (MD5) for comparison to see if there are any changes.

This allows you to rename the files as long as the path mentioned in the NaCl file is relative to the static-resources folder.

For example you can create the folder static-resources/ProfileClasses and move the ApexFileForProfile.cls there, and update the NaCl file to point to ProfileClasses/ApexFileForProfile.cls.

If the file function points to a non existing file, the deploy operation will warn and stop.

NOTE: If you remove the static file usage (remove the file(...)), the referenced static file is not deleted.

Updated 3 months ago

NaCl in detail


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.