Variables in AEM Forms workflows
| Version | Article link |
|---|---|
| AEM as a Cloud Service | Click here |
| AEM 6.5 | This article |
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:
- Create a variable of a data type based on the information type that you want to store in it.
- Set a value for the variable using the Set Variable workflow step.
- Use the variable in all AEM Forms Workflow steps to retrieve the stored value and in OR Split and Goto steps to define a routing expression.
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
You create variables using the Variables section available in the sidekick of the workflow model. AEM workflow variables support the following data types:
NOTEYou 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:
-
On an AEM instance, navigate to Tools
-
Select Create and specify the title and an optional name for the workflow model. Select the model and select Edit.
-
Select the variables icon available in the sidekick of the workflow model and select Add Variable.
-
On the Add Variable dialog, specify the name and select the type of the variable.
-
Select the data type from the Type drop-down list and specify the following values:
- Primitive data type - Specify an optional default value for the variable.
- JSON or XML - Specify an optional JSON or XML schema path. The system validates the schema path while mapping and storing properties available in this schema to another variable.
- Form Data Model - Specify a Form Data Model path.
- ArrayList - Specify a sub-type for the collection.
-
Specify an optional description for the variable and select
When you create variables, consider the following practices:
- Create as many variables as a workflow requires. However, to conserve database resources, use the minimum number of variables required, and reuse variables when possible.
- Variables are case-sensitive. Ensure that you reference variables using the same case in your workflow.
- Avoid using special characters in the name of 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:
-
Literal: Use the option when you know the exact value to specify.
-
Expression: Use the option when the value to use is calculated based on an expression. The expression is created in provided expression editor.
-
JSON Dot Notation: Use the option to retrieve a value from a JSON or FDM type variable.
-
XPATH: Use the option to retrieve a value from an XML type variable.
-
Relative to payload: Use the option when the value to be saved to variable is available at a path relative to payload.
-
Absolute path: Use the option when the value to be saved to variable is available at an absolute path.
You can also update specific elements of a JSON or XML type variable using JSON DOT Notation or XPATH notation.
Add mapping between variables
Execute the following steps to add mapping between variables:
- On the workflow edit page, select the Steps icon available in the sidekick of the workflow model.
- Drag-and-drop the Set Variable step to the workflow editor, select the step and select
- On the Set Variable dialog, select Mapping > Add Mapping.
- In the Map Variable section, select the variable to store data, select the mapping mode, and specify a value to store in the variable. The mapping modes vary based on the type of variable.
- Map more variables to make a meaningful expression. Select
Example 1: 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
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
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:
- Set the value of variables using other workflow variables, numbers, or mathematical expressions.
- Use workflow variables, string, number, or an expression within a mathematical expression
- Add conditions to set values of variables.
- Add operators between conditions.
It is based on adaptive forms rule editor with following changes. Rule editor in variables:
- Does not support functions.
- Does not provide a UI to view summary of rules
- Does not have code editor.
- Does not support enabling and disabling value of an object.
- Does not support setting property of an object.
- Does not support calling a web service.
For more information, see adaptive forms rule editor.
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
All AEM Forms Workflow steps support variables. For more information, see Forms-centric workflow on OSGi.
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
Use the following APIs in the ECMA Script to retrieve values for existing variables based on the data type:
| Variable data type | API |
|---|---|
| Primitive (Long, Double, Boolean, Date, and String) | workItem.getWorkflowData().getMetaDataMap().get(variableName, type) |
| Document | Packages.com.adobe.aemfd.docmanager.Document doc = workItem.getWorkflowData().getMetaDataMap().get(“docVar”, Packages.com.adobe.aemfd.docmanager.Document.class); |
| XML | Packages.org.w3c.dom.Document xmlObject = workItem.getWorkflowData().getMetaDataMap().get(variableName, Packages.org.w3c.dom.Document.class); |
| Form Data Model | Packages.com.adobe.aem.dermis.api.FormDataModelInstance fdmObject = workItem.getWorkflowData().getMetaDataMap().get(variableName, Packages.com.adobe.aem.dermis.api.FormDataModelInstance.class); |
| JSON | Packages.com.google.gson.JsonObject jsonObject = workItem.getWorkflowData().getMetaDataMap().get(variableName, Packages.com.google.gson.JsonObject.class); |
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
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
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
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
- On the edit workflow page, select the Variables icon available in the sidekick of the workflow model. The Variables section in the left pane displays all existing variables.
- Select the
- Edit the variable information and select
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:
- On the edit workflow page, select the Variables icon available in the sidekick of the workflow model. The Variables section in the left pane displays all existing variables.
- Select the Delete icon next to the variable name that you want to delete.
- Select
References
For more examples on using variables in AEM Forms Workflow steps, see Variables in AEM workflows.
Experience Manager
Espressos & Experience Manager: AEM Forms
Espressos & Experience Manager
Thursday, Mar 6, 7:00 PM UTC
Join Adobe's AEM product team as they highlight AEM Forms' latest innovations, including: the new Gen AI Assistant, Unified Composition with AEM Sites, and new ways to deploy forms through conversations.
RegisterAdobe Experience Manager Forms at Summit
Register for these sessions:
- Elevate and Empower Teams with Agentic AI for Exceptional Experiences (attend online)
- The Future of Forms: Experience Success Across the Enrollment Journey (attend online)
- The True Cost of a Failed Implementation (attend online)
- Driving Marketing Agility and Scale: Transforming your Content Supply Chain with AI (attend online)
- Put the Customer at the Center and Build Relationships That Last a Lifetime (attend online)
Connect with Experience League at Summit!
Get front-row access to top sessions, hands-on activities, and networking—wherever you are!
Learn more