Reference Values

Variables from different sources in Frends Processes.

Reference values in Frends Processes provide access to dynamic data during execution through a convenient hashtag-based syntax. These values enable you to work with Variables, Trigger data, Environment settings, Task results, and Process information throughout your integration flows.

Frends uses the hashtag (#) prefix followed by a reference type to access different kinds of data within Processes. The main reference value types are #var, #trigger, #env, #result, and #process. Each type serves a specific purpose and provides access to different data contexts during Process execution.

#var (Process Variable)

Variables in Frends Processes are represented by the #var reference type. These variables can be created and modified during Process execution to store and manipulate data as needed.

Creating Variables

Variables can be created in two ways in Frends:

Process Variables are initialized at the start of a Process, defined in the Process's general parameters. These variables are available immediately after Triggers have executed but cannot be used within Trigger parameters themselves. Process Variables allow you to set default values that can be modified during execution.

Variables are created during Process flow using the Assign Variable shape or the Code Task shape with the "Assign variable" parameter enabled. These Variables can be created at any point in your process logic and are available for use in subsequent steps.

Using Variables

When a variable is created, you must define a name for it. The variable can then be referenced using the syntax #var.VariableName, where VariableName is the name you assigned to the variable. For example, if you created a variable named CustomerID, you would access it as #var.CustomerID.

Variables can hold any type of data, including primitive types, complex objects, arrays, and custom classes. When dealing with object properties, you can use bracket notation to access specific fields, such as #var.ObjectVariable["MyField"]. You can also use dot notation, such as #var.ObjectVariable.MyField when the data type is JObject, JToken, anonymous object or dynamic, and the field name does not contain special characters or whitespace.

Variable Typing

Variables in Frends can be explicitly typed by specifying a C# type or class (such as string, JObject, or List) or left dynamically typed, where the type is automatically determined at runtime. Explicit typing helps with IntelliSense and compile-time validation, while dynamic typing provides flexibility.

Error Handling with Variables

A special variable reference #var.error is always available in error handling subprocesses. This variable provides access to exception details when errors occur, including the error message, type, stack trace, and other diagnostic information. The Catch shape uses #var.error by default to access error information, though this name can be customized if needed.

#trigger (Trigger Data)

The #trigger reference provides access to data from the trigger that initiated the process execution. The structure and available data depend on the specific trigger type used.

For detailed information about specific trigger types and their available reference values, see the Trigger reference documentation.

Multiple Triggers

When multiple triggers are present in a process, only one trigger executes for each process instance. The trigger that executes is the one that provides values for the #trigger reference. You can use Decision shapes to check #trigger.name or #trigger.type to determine which trigger initiated the process and act accordingly.

#env (Environment Variables)

Environment variables are centrally managed, globally available configuration values that can have different values for each Environment (such as Development, Test, and Production).

Purpose and Use Cases

Environment Variables are ideal for storing configuration settings that vary across different Deployment Environments. Common use cases include connection strings, API endpoints, credentials, file paths, and other configuration parameters that differ between Environments.

Using Environment Variables promotes good CI/CD practices by allowing you to deploy the same Processes across multiple Environments without modification. Only the Environment Variable values change between Environments, keeping your Process logic consistent.

Creating and Managing Environment Variables

Environment Variables are created and managed through the Environment Variables view in the Frends Control Panel. When you create a variable, you define its name, type, and values for each Environment. Changes to Environment Variable values require saving to take effect, while creating or deleting variables takes effect immediately.

Environment Variables can be used in both Process expressions (with Handlebars syntax or as part of C# code) and directly in Trigger parameters (without Handlebars). This flexibility makes them versatile for various configuration scenarios.

Frends tracks the use and modification of Environment Variables. A changelog is kept for each Variable to show who modified the value and when. The Environment Variable view also shows all the Processes that use a specific variable, allowing you to confirm the scope any changes to the value would have.

Structure and Organization

Environment Variables are organized using groups. For example, you might create a group called CRM containing values like BaseUrl, Username, and Password.

Variables inside groups can be of different types including Text (string values), Number (integer values), Boolean (true/false values), List (arrays of text values), and Secret (string values that are hidden in the UI and encrypted in database).

Accessing Environment Variables

Environment Variables are accessed in Processes using the syntax #env.VarGroup.VariableName. For example, #env.CRM.BaseUrl accesses the BaseUrl variable within the CRM group.

For dynamic access where the variable name is determined at runtime, you can use bracket notation such as #env.MyGroup["MyVariable"]. Accessing the value dynamically does not make the use of the variable visible in Environment Variable view, creating a possibility of breaking the Process in case the Environment Variable's value is modified or deleted.

Environment Variables in Trigger Parameters

Trigger parameters support a special syntax for Environment Variables. You can use #env references directly in Trigger parameter fields without Handlebars syntax. The Environment Variable references are translated directly into their values at runtime, while other text content is not evaluated. For example in a File Trigger, you could use FilePrefix_#env.ExampleGroup.FileName.csv to dynamically construct the filter string FilePrefix_MyFileName.csv for a filename.

#result (Task Results)

The #result reference provides access to the output or return value of preceding shapes within a Process, including both Task shapes and Scope shapes as well as few other shapes.

How Results Work

For Task shapes, the #result is populated directly by the Task when it completes execution. The structure and content of the result depend on the specific Task being executed. For example, an HTTP Request Task returns an object containing properties like Body, StatusCode, and Headers.

For scope shapes (including Scope, Foreach, and While shapes), the result value is specified using a Return shape within the scope. The expression or content defined in the Return shape becomes the scope's result value.

Unnamed vs Named Results

By default, #result reference value references the return value of the last shape that was executed. This unnamed reference is convenient when you only need to access the most recent result.

However, in complex Processes with multiple Tasks and scopes and other logic shapes, you may need to reference specific results. Named #result references allow you to specify which shape's result you want to access using square bracket notation: #result[ShapeName] or #result[TaskName]. For example, #result[HTTP Request].Body accesses the Body property of a Task named "HTTP Request".

When using named results for scope shapes, note that the result is named after the scope shape itself, not the Return shape inside it. If you have a Scope named "Handle elements", you would reference its result as #result[Handle elements], regardless of what the Return shape inside is named.

Results in Iterative Scopes

When a Return shape is used to end Foreach shape, the results from each iteration are collected into an array. This array is accessible through the #result reference after the loop completes, containing the return value from each iteration.

For a While shape, the #result reference will contain only the last iteration's result.

Limitations

In order to be able to use named result reference value, the shape must have been executed before its result can be used.

You also cannot use named result reference value if the targeted shape was executed in a conditional branch or inside another scope shape, because the runtime cannot ensure the execution will happen, leaving the named result undefined in some cases.

To use a result from scenario like this, initialize a Process Variable before the branch or scope shape, and within the branch or scope assign the shape's result into the Variable.

The #result reference value from a shape cannot be used in error handling paths immediately following that Task or Scope, such as within a Catch shape or Exclusive Decision shape connected to the error path. It is only safe to use #result after the execution path has been determined to be successful.

When working with shapes that might fail, consider capturing the result in a variable before the potential error point, or structure your Process so that result access occurs after error handling has completed.

#process (Process Information)

The #process reference provides access to metadata about the current Process Instance and the Process definition itself. These values are set for each Process Instance and remain constant throughout the execution.

You can read more about the Process details and related #process reference values from the Process reference documentation.