> For the complete documentation index, see [llms.txt](https://docs.frends.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.frends.com/reference/frends-6.3.0/process-development/process-variables.md). # Process Variables Process-specific variables that initialize and set default values within a Process. Process Variables are variables defined on a Process that are initialized at the start of the Process execution. They allow you to define values once and reuse them throughout the Process flow, and to adapt a Process to different users and environments. Process Variables are referenced using the `#var` prefix. ## What are Process Variables? Process Variables are Process-specific variables that are expanded during Process startup. They are initialized right after the Process is triggered and the Trigger has executed, and before anything else in the Process has been done. As a result, the Process Variable values are available to use in the Process right after the Trigger, but not within the Trigger itself. Process Variables provide the `#var` reference value, which can be used in expressions throughout the Process flow. A Process Variable is referenced by its name, for example `#var.MyVariable`. Process Variables are also used with Templates to provide initial or default values to variables within the Process, and they behave the same way inside Subprocesses. ### Process Variables and Variables Frends uses the `#var` reference for two related but distinct kinds of data: Process Variables and Variables. They differ in where and when they are defined, and in how they are managed. | Aspect | Process Variable | Variable | | -------------- | -------------------------------------------------------- | ---------------------------------------------------- | | Definition | Defined on the Process, in the Process Variables tab | Defined during the Process flow, in a shape | | Initialization | Initialized at Process startup, after the Trigger | Created at the point in the flow where it is defined | | Management | Managed externally, from the Process list or via the API | Managed within the Process flow | | Reference | `#var.VariableName` | `#var.VariableName` | Both kinds are currently referenced with the same `#var` prefix. ### Process Variable Lifecycle Process Variables follow a defined lifecycle within each Process execution: 1. The Trigger executes and starts the Process. 2. Process Variables are initialized with their defined default values. 3. The Process flow runs, and Process Variables can be read throughout the flow. Variables created in the flow can be read and modified by Assign Variable and Code Task shapes. 4. The Process execution completes. {% hint style="info" %} Because initialization happens after the Trigger, Process Variable values cannot be used within Trigger parameters. {% endhint %} ## Defining Process Variables Process Variables are defined in the Process Variables tab, located in the Parameter Editor of the Process Editor. It is where you define variables that are available throughout the entire Process execution. Each Process Variable has the following properties: * **Name:** The name used to reference the variable, for example `#var.MyVariable`. * **Type:** The variable type, expressed as a C# type such as `string`, `JObject`, or `List`. * **Value:** The initial value, which can be a static value or an Environment Variable. * **Description:** An optional description of the variable. Process Variables defined in this tab cannot contain C# expressions or Handlebars. Environment Variables are translated directly into their value, while Handlebars and C# expressions are not evaluated. Because Process Variables are defined on the Process, they can be managed outside the Process Editor and are used to configure Templates. ## Creating Variables in the Flow Variables can also be created during the Process flow. Unlike Process Variables, these Variables are internal to the Process execution and are not managed outside the Process Editor. ### Assign Variable Shape The Assign Variable shape assigns the result of a single C# expression to a variable during Process execution. Variables created this way are available for use in subsequent steps of the Process. ### Code Task Shape A Code Task shape can create a variable when the **Assign variable** parameter is enabled. This allows custom C# code to produce a value that is stored in a variable. ## Using Variables ### 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. ### Accessing Object Properties 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. ## Editing Process Variables Outside the Process Editor After creating a Process Variable through the Process Variables tab, it is possible to edit the variable values from the Processes view. Select **Edit Process Variables** from the Process Actions menu to access the values outside the Process Editor. Process Variables are deployment-specific: each Process Variable is scoped to an Agent Group and a Process version. A Process Variable is defined with a default value, and that default can be overridden separately for each Agent Group and Process version where the Process is deployed. This makes it possible to run the same Process in multiple Agent Groups while using a different value for the same Process Variable in each, without modifying the Process itself. To override a Process Variable for a specific deployment, deploy the Process to the target Agent Group and set the value using **Edit Process Variables** in that Agent Group. The following behavior applies to Process Variables across deployments: * **Deploying a Process:** Existing Process Variables for the Process in the target Agent Group are not overwritten. * **Reconfiguring a Process:** The Process Variables defined for the Process in its respective Test or Production Agent Group are used, rather than only the default values. * **Updating from a Template:** The Process Variables defined on the Process are retained. New keys from the Template are added with their default values, and keys that are no longer present in the Template are removed. * **Overrides are remembered:** When a new version of the Process is deployed to the same Agent Group, the previously set override continues to be used by default, so each override only needs to be set once per Process, per target Agent Group, per variable. ## Process Variables in Templates Process Variables deserve special attention in the context of Templates. The recommended approach is to store configurable values as Process Variables on the Process, so that the values can be filled in when the Template is taken into use instead of relying on Environment-specific values. When creating a Process from a Template, the Process Variables are set for the specific use case. It is then up to the Template user to provide the Process Variables their values as Environment Variables. The default value for the Process Variables can also be set as Environment Variables, providing information to the Template's user that it might be a good idea to do that as well. ## Process Variables in Subprocesses Process Variables can also be used to initialize and set default values to be used within Subprocesses. The variables are initialized right after the Subprocess is triggered and the Trigger has been executed, and before anything else in the Subprocess has been done. As such, the Process Variable values are available to use in the Subprocess right after the Trigger, but not within the Trigger. All variables created within a Subprocess are scoped to that execution. They are not shared with the calling Process and are cleaned up when the Subprocess completes. ## Managing Process Variables via the API Process Variables can be listed and updated through the Process Deployments API. The API provides endpoints to list Process variables for Processes in an Agent group and to update Process variables for a specific Process. Each Process Variable is described by its name, value, secret flag, mode, and description. ## Error Handling with Process 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. ## Reference Values ### #var Represents a variable in Frends Processes. A `#var` reference value can be a Process Variable, defined in the Process's general parameters, or a Variable created during the Process flow using the Assign Variable or Code Task shapes. It is accessed using the syntax `#var.VariableName`. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.frends.com/reference/frends-6.3.0/process-development/process-variables.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.