Overview

Expressions are available across multiple Snaps. If the Snap exposes the expressions functionality for a property, then the equals (=) icon appears in front of the text box of the property. Only Snap properties in the Settings category can currently provide expression functionality.

Any field preceded with an equals sign (=) button can handle an expression if that button is toggled on.

To use expressions in a Snap property:

1. Click the equals (=) icon to enable expression mode for that field.
2. Click the down arrow within the field to see the list of functions and properties available.
3. Type within that field to filter the functions displayed.
4. Click the Expand Editor button to have a larger work area to create your expressions.

Dynamic Validation and Output Preview

As you create expressions, they are validated in real-time for syntax and spelling errors and to provide output previews. Expressions are dynamically evaluated at a sub-expression level as they are typed and an output preview shown for each part of the expression—object, method, and arguments.

This is particularly useful in debugging complex expressions as it can be difficult to see the results of sub-expressions within an expression. Preview results of the sub-expression are shown within the yellow curly brace '{' and the result of the whole expression within the green equals sign '='.

Example:

Consider an object 'msg' containing the string "Hello, World". An expression to convert this string to lower case would be:

$msg.toLowerCase()

When the Snap is validated, the expression is also dynamically validated:

• When you click on $msg, it shows the current value of that variable
• When you click on toLowerCase(), it shows the final result of the expression

Expression Output Preview Components:

The final output preview of an expression is shown in parts, one for each block in the expression. For example, the expression Date.now(1,2,3) will display:

• The Date scope with available methods
• Arguments passed to the function (with warnings for ignored arguments)
• The final result of the expression

The expression's evaluation happens in real time:

• As you start typing, SnapLogic shows suggestions from the expression library
• When an object has been typed, it suggests the methods within that object
• When arguments are entered, the expression is validated and a response shown in the Output Preview

File Writer Example

The File Writer Snap provides the ability to toggle the filename into an expression by selecting the equals icon (left of the property box). The content of the text box is interpreted as an expression once the toggle is on.

An example expression would be:

'/out' + Date.now() + '.json'

This would insert the current date as part of the filename.

Accessing Pipeline Parameters

Parameters allow a pipeline to be reused in multiple situations. For example, a File Writer Snap can be configured to write to a file path specified by a parameter, which allows the same pipeline to write to different files.

The parameters for a pipeline can be defined by using the Edit Pipeline properties dialog. The name of each parameter must only contain alpha-numeric characters and the value will be converted to a string. The value for a parameter as defined in the pipeline properties dialog is treated as the default when running the pipeline in Designer.

Parameters can also be passed to a pipeline by a Task or the ForEach Snap. Any parameters that are not passed down from the Task or Snap will use the defaults specified in the properties dialog.

To access a pipeline parameter from the expression language, you must prefix the parameter name with an underscore.

For example, given the following parameters:

The "firstName" parameter can be accessed using _firstName, as in:

"Hello, " + _firstName  // result: Hello, Bob

Converting Parameter Values:

Since the value of a parameter is always a string, you'll need to convert any string to numeric values before operating on them. For example, simply adding two to the "numValue" parameter will append the character "2" to "12" and yield "122":

_numValue + 2   // result: "122"

Instead, you need to use the parseInt or parseFloat functions to parse the string into a value and then add two to it:

parseInt(_numValue) + 2   // result: 14

Using eval() for Parameterized Expressions:

If you need to parameterize your pipeline with an expression, you can use the eval() function to evaluate an expression stored in a string. For example, to read the document field specified by the "path" parameter, you can use:

eval(_path)   // result: <the value of the "age" field in the current document>

Accessing Input View Variables

An input view schema attribute can be used as part of the expression by using the dollar sign ($) prefix.

Example:

The REST Put Snap provides a URL. The URL can be toggled into an expression and the expressions could be created by dynamically substituting the variables from an input view, such as:

'http://someplace:someport/somepart/' + $inputvar + '/somemoreparts'

In this example, $inputvar would be replaced with the value from the input document at runtime.

Accessing Secrets from Secrets Manager

Any expression-enabled authentication field in a Snap or Account can be used with Secrets Management. You can enter an expression that retrieves a secret stored in your secrets manager, such as an access token, a username, or a password.

Steps to use secrets:

1. Create secrets (for example, myaccesskey and mysecretkey) in your Secrets Manager vault.
2. Create or modify the Account and enter an expression in the required fields.
3. Use the expression to reference the secret value.

For more information, see the Secrets Management documentation on configuring accounts to use secrets.

Best Practices

• Validate Early: Validate your Snap to see real-time expression evaluation and output preview.
• Use the Expand Editor: For complex expressions, use the expanded editor for better visibility.
• Test Sub-expressions: Click on different parts of your expression to see intermediate results.
• Quote Strings: Remember to enquote string literals in your expressions.
• Convert Parameter Types: Use parseInt() or parseFloat() when working with numeric pipeline parameters.
• Leverage Autocomplete: Use the dropdown suggestions to discover available functions and properties.