Variables in AEM Forms workflows variables-in-aem-forms-workflows

A variable in a workflow model is a way to store a value based on its data type. You can then use the name of the variable in any workflow step to retrieve the value stored in the variable. You can also use variable names to define expressions for taking routing decisions.

In AEM workflow models, you can:

The following video demonstrates how you can create, set, and use variables in AEM workflow models:

Variables are an extension of the existing MetaDataMap interface. You can use MetaDataMap in ECMAScript to access metadata saved using variables.

Create a variable create-a-variable

You create variables using the Variables section available in the sidekick of the workflow model. AEM workflow variables support the following data types:

You require AEM Forms add-on package for Document and Form Data Model data types. Use ArrayList data type to create variable collections. You can create ArrayList variable for all primitive and complex data types. For example, create an ArrayList variable and select String as sub-type to store multiple string values using the variable.

Execute the following steps to create a variable:

When you create variables, consider the following practices:

Set a variable set-a-variable

You can use the Set Variable step to set value of a variable and define the order in which the values are set. The variable is set in the order the variable mappings are listed in the set variable step.

Changes to variable values affect only the instance of the process in which the change occurs. For example, when a workflow is initiated and variable data changes, the changes affect only that instance of the workflow. The changes do not affect other instances of the workflow that were initiated previously or are initiated subsequently.

Depending on the data type of the variable, you can use the following options to set value of a variable:

You can also update specific elements of a JSON or XML type variable using JSON DOT Notation or XPATH notation.

Add mapping between variables add-mapping-between-variables

Execute the following steps to add mapping between variables:

Example 1: Query an XML variable to set value for a string variable example-query-an-xml-variable-to-set-value-for-a-string-variable

Select a variable of XML type to store an XML file. Query the XML variable to set the value for a string variable for the property available in the XML file. Use Specify XPATH for the XML variable field to define the property to store in the string variable.

In this example, select a formdata XML variable to store the cc-app.xml file. Query the formdata variable to set the value for the emailaddress string variable to store the value for the emailAddress property available in the cc-app.xml file.

Example 2: Use an expression to store value based on other variables example2

Use an expression to calculate the sum of the variables and store the result in a variable.

In this example, use the expression editor to define an expression to calculate the sum of assetscost and balanceamount variables and store the result in totalvalue variable.

Use expression editor use-expression-editor

You also use expressions to calculate value of a variable on the runtime. Variables provide an expression editor to define expressions.

Use the expression editor to:

It is based on adaptive forms rule editor with following changes. Rule editor in variables:

For more information, see adaptive forms rule editor.

Use a variable use-a-variable

You can use variables to retrieve inputs and output or save the result of a step. The workflow editor provides two types of workflow steps:

Workflow steps with support for variables workflow-steps-with-support-for-variables

The Go To step, OR Split step, and all AEM Forms Workflow steps support variables.

OR Split step or-split-step

The OR Split creates a split in the workflow, after which only one branch is active. This step enables you to introduce conditional processing paths into your workflow. You add workflow steps to each branch as required.

You can define routing expression for a branch using a rule definition, ECMA script, or an external script.

You can use variables to define the routing expression using the expression editor. For more information on using routing expressions for the OR Split step, see OR Split step.

In this example, before defining the routing expression, use example 2 to set the value for the totalvalue variable. Branch 1 is active if the value of the totalvalue variable is greater than 50000. Similarly, you can define a rule to make the Branch 2 active if the value of the totalvalue variable is less than 50000.

Similarly, select an external script path or specify the ECMA script for routing expressions to evaluate the active branch. Select Rename Branch to specify an alternate name for the branch.

For more examples, see Create a workflow model.

Go To step go-to-step

The Goto Step lets you specify the next step in the workflow model to execute, dependent on the result of a routing expression.

Similar to the OR Split step, you can define routing expression for Goto step using a rule definition, ECMA script, or an external script.

You can use variables to define the routing expression using the expression editor. For more information on using routing expressions for the Goto step, see Goto Step.

In this example, the Goto step specifies the Review Credit Card Application as the next step if the value for the actiontaken variable is equal to Need more info.

For more examples on using rule definition in the Goto step, see Simulating a For loop.

Forms-workflow centric workflow steps forms-workflow-centric-workflow-steps

All AEM Forms Workflow steps support variables. For more information, see Forms-centric workflow on OSGi.

Workflow steps without support for variables workflow-steps-without-support-for-variables

You can use MetaDataMap interface to access variables in workflow steps that do not support variables.

Retrieve the variable value retrieve-the-variable-value

Use the following APIs in the ECMA Script to retrieve values for existing variables based on the data type:

You require AEM Forms add-on package for Document and Form Data Model variable data types.

Example

Retrieve the value of string data type using the following API:

workItem.getWorkflowData().getMetaDataMap().get(accname, Packages.java.lang.String)

Update the variable value update-the-variable-value

Use the following API in the ECMA Script to update the value of a variable:

workItem.getWorkflowData().getMetaDataMap().put(variableName, value)

Example

workItem.getWorkflowData().getMetaDataMap().put(salary, 50000)

updates the value for the salary variable to 50000.

Set variables to invoke workflows apiinvokeworkflow

You can use an API to set variables and pass them to invoke workflow instances.

workflowSession.startWorkflow uses model, wfData, and metaData as arguments. Use MetaDataMap to set value for the variable.

In this API, the variableName variable is set to value using metaData.put(variableName, value);

import com.adobe.granite.workflow.model.WorkflowModel;
import com.adobe.granite.workflow.metadata.MetaDataMap;
import com.adobe.aemfd.docmanager.Document;

/*Assume that you already have a workflowSession and modelId along with the payloadType and payload*/
WorkflowData wfData = workflowSession.newWorkflowData(payloadType, payload);
MetaDataMap metaData = wfData.getMetaDataMap();
metaData.put(variableName, value); //Create a variable "variableName" in your workflow model
WorkflowModel model = workflowSession.getModel(modelId);
workflowSession.startWorkflow(model, wfData, metaData);

Example

Initialize the doc document object to a path (“a/b/c”) and set the value of the docVar variable to the path stored in the document object.

import com.adobe.granite.workflow.WorkflowSession;
import com.adobe.granite.workflow.exec.WorkflowData;
import com.adobe.granite.workflow.model.WorkflowModel;
import com.adobe.granite.workflow.metadata.MetaDataMap;
import com.adobe.aemfd.docmanager.Document;

/*This example assumes that you already have a workflowSession and modelId along with the payloadType and payload */
WorkflowData wfData = workflowSession.newWorkflowData(payloadType, payload);
MetaDataMap metaData = wfData.getMetaDataMap();
Document doc = new Document("/a/b/c");// initialize a document object
metaData.put("docVar",doc); //Assuming that you have created a variable "docVar" of type Document in your workflow model
WorkflowModel model = workflowSession.getModel(modelId);
workflowSession.startWorkflow(model, wfData, metaData);

Store sensitive user data outside JCR using workflow variables jcr-independent-persistance

Data processed using Forms Workflow can contain sensitive user data, such as Personally Identifiable Information and Sensitive Personal Information. Businesses can choose to store the data, that is processed by various workflow steps (and passed using workflow variables), out of JCR storage into an external data store owned and managed by them. To know more about persisting workflow data in an external storage, see Using workflow variables for customer owned datastores.
Adobe Experience Manager provides Workflow API UserMetaDataPersistenceProvider to store workflow variables in external Azure blob storages. For details about using the API, see Use workflow variables to parameterize sensitive data and store in external data stores.

Edit a variable edit-a-variable

Delete a variable delete-a-variable

Before deleting the variable, remove all the references of the variable from the workflow. Ensure that the variable is not used in the workflow.

Execute the following steps to delete a variable:

References references

For more examples on using variables in AEM Forms Workflow steps, see Variables in AEM workflows.