Description:

The Get Matrix Value workflow step retrieves a value from a specified cell in an in-memory matrix.

The step identifies the matrix via a Variable or Global that contains the matrix XML, specifies the target column and row index, and stores the retrieved value in another Variable or Global.

The step supports:

• Retrieving a value from a matrix cell.
• Selecting the Variable or Global that contains the matrix XML.
• Specifying the target matrix column.
• Specifying the target row index.
• Storing the retrieved value in a Variable or Global.
• Dynamically retrieving matrix values during workflow execution.
• Returning a True or False result.

Usage:

The Get Matrix Value step is typically used when a workflow needs to read information from a particular cell in matrix data.

The workflow identifies:

• The Variable or Global containing the matrix XML.
• The target column.
• The target row.
• The Variable or Global that receives the retrieved value.

The retrieved value can then be used by subsequent workflow activities.

Typical uses include:

• Reading a value from a specific matrix row.
• Retrieving a status or other field from a matrix.
• Processing matrix records one row at a time.
• Using matrix data in workflow decisions.
• Passing matrix values to subsequent workflow steps.
• Extracting a matrix value for calculations or processing.
• Reading values from an in-memory matrix before modifying or using the data elsewhere.

Typical Workflow Suggestions:

Retrieve a Matrix Status

Use Get Matrix Value to retrieve a status from a particular matrix row.

Example:

Get Matrix Value → Evaluate Status → Continue

For example:

• Column: Status
• Row: 2
• Destination Variable: CurrentStatus

The value stored in CurrentStatus can then be used by subsequent workflow logic.

Make a Decision Based on Matrix Data

Retrieve a matrix value and use it in a decision.

Example:

Get Matrix Value → Decision → Approve / Reject

For example:

Get Matrix Value

Column:

Status

Row:

2

Destination:

CurrentStatus

Then:

CurrentStatus = Approved → Approval Processing

CurrentStatus = Rejected → Rejection Processing

Process Matrix Rows

Use Get Matrix Value when a workflow processes matrix data one row at a time.

Example:

Determine Row → Get Matrix Value → Process Value → Next Row

The step provides an explicit Index of the row property for identifying the row to read.

Retrieve a Specific Matrix Field

Use the column name to retrieve a particular field from a matrix record.

Example:

Identify Record → Get Matrix Value → Process Customer Name

For example:

• Column: CustomerName
• Row: 3
• Destination Variable: CustomerName

The step provides the Name of the column property used to identify the target column.

Use Retrieved Data in Calculations

Retrieve a matrix value and use it in a subsequent calculation.

Example:

Get Matrix Value → Calculate → Update Result

For example:

Amount can be retrieved from a matrix row and then used by a calculation step.

Retrieve Values Before Updating a Matrix

Use Get Matrix Value before Set Matrix Value when a workflow needs to read an existing value before deciding whether to change it.

Example:

Get Matrix Value → Evaluate Existing Value → Set Matrix Value

This can be useful when a workflow should modify a cell only under certain conditions.

Compare Existing and New Values

Retrieve an existing matrix value and compare it with a newly calculated value.

Example:

Calculate New Value → Get Matrix Value → Compare Values → Update if Different

This pattern can help avoid unnecessary matrix updates.

Retrieve Data for External Processing

Read a matrix value before sending it to another system or workflow.

Example:

Get Matrix Value → Prepare Request → Send to External System

The retrieved value is stored in the configured Variable or Global and can then be used by subsequent activities.

Retrieve Multiple Values

Use multiple Get Matrix Value steps when several fields from the same matrix row are required.

Example:

Get Customer Name → Get Customer Status → Get Customer Amount → Process Customer

Each step can target a different column and store its result in a separate Variable or Global.

Process an Indexed Matrix Record

Use a dynamically determined row index to retrieve a value from the appropriate matrix record.

Example:

Determine Row Index → Get Matrix Value → Process Current Record

The XML defines the row index as a string property, allowing the row selection to be supplied as workflow data.

Success and Failure Handling

Use the two return paths to distinguish between successful and unsuccessful retrievals.

Example:

Get Matrix Value → True → Continue Processing

↳ False → Log Failure / Retry / Notify Administrator

The step explicitly provides True and False return values.

Example:

Let’s build and execute the “getSetMatrixValueDef” example.          

• Create a new definition named “getSetMatrixValueDef” and open it in designer mode. 
• Drag a “setMatrixValue, getMatrixValue” step to the canvas. 
• Connect the dots between the “Start” step and the other steps, as shown above.
• Select the line between the steps to configure the “Connection Properties”. The default property values are “None, True, False, Error, and Evaluate”. Depending on the step’s purpose, additional configuration options are available.
• Define a variable or a global to store the matrix data and the cell value.
• Click the "setMatrixValue" step to configure its "Required" properties. Provide a name for the step, then click the Save button. Note: Click the "AI Predict" button to have the Copilot add new process steps that match your process description. 

• The following XML 2x2 matrix values are used in this example. 

• Click the "setMatrixValue" step to configure its "Optional" properties. Provide a variable or global reference to hold the XML data. Provide the matrix column name. You may configure individual (1 x 1) matrix values by specifying the data and the row index. Click the button to configure multiple matrix values. A pop-up window appears for configuration. Click the Add Row (+) button to insert an empty row. Provide the row index value, column name, and the value to assign. Click the Save button. You may insert multiple matrix row indexes and values using the Add Row button. 

• Click the "getMatrixValue" step to configure its "Required" properties. Provide a name for the step, then click the Save button. Note: Click the "AI Predict" button to have the Copilot add new process steps that match your process description. 

• Click the "getMatrixValue" step to configure its "Optional" properties. Provide the variable or global reference that holds the XML reference. Provide the column name and the row index value. Provide a variable or global reference to store the cell value. Click the Save button. 

• The “Logging” configuration is necessary for documentation and also measures workflow progress and percent complete. This is achieved by configuring the step state and percent fields individually, as shown below. Configure the “Logging” using the following properties.

• Save the process definition, create a new instance, and execute it. Render the process instance. Click the process step to view its properties. When the workflow reaches the Get Matrix Value step, FlowWright uses the configured matrix XML, column, and row index to retrieve the corresponding matrix value and store it in the specified Variable or Global. The XML explicitly describes the step as one that gets the value from an N by N in-memory matrix. The workflow then follows the True or False return path according to the operation result.

Tips:

• Provide the Variable or Global containing the matrix XML.
• Verify that the supplied XML represents the expected matrix structure.
• Confirm that the specified column exists.
• Confirm that the row index identifies the intended row.
• Validate dynamically generated row indexes before using them.
• Use meaningful names for Variables that receive retrieved matrix values.
• Use separate destination Variables when retrieving several values from a row.
• Test the workflow with representative matrix data.
• Test different row positions when using dynamic row indexes.
• Verify the expected row-indexing convention in the target FlowWright implementation; the XML does not specify whether indexing is zero-based or one-based.
• Use the True path to continue processing only after the retrieval operation succeeds.
• Use the False path for appropriate error handling.
• Consider logging the row and column being accessed when troubleshooting matrix-processing workflows.
• Validate the retrieved value before using it in calculations or decisions.
• When retrieving several values, keep the relationship between source columns and destination Variables clear.
• Avoid assuming that an empty optional property produces a particular runtime behavior.
• Test behavior when the requested row does not exist.
• Test behavior when the requested column does not exist.
• Test behavior when the source matrix contains an empty value.
• If matrix data is subsequently modified, carefully control the order of Get Matrix Value and Set Matrix Value operations.
• Keep matrix row and column conventions consistent across related workflows.

Notes:

• The Get Matrix Value step is defined in the Engine category with the internal name getmatrixvalue, label “Gets the value from a N by N in-memory matrix”, and display name “Get Matrix Value.”
• The step is implemented by FlowWright.Workflow.GetMatrixValue in FlowWright.Workflow.dll and is a Process step with 2 incoming connections and 2 outgoing connections.
• The XML defines four configurable properties, none of which are marked as required.
• The four properties are:
  • xmlVariable – Variable/Global that holds the XML
  • columnName – Name of the column
  • rowIndex – Index of the row
  • valueVariable – Variable/Global to store the value 
• All four properties use the string data type.
• The string property type is implemented by FlowWright.DataTypes.ClsTextBox in FlowWright.DataTypes.dll.
• The step provides two predefined return values: False and True.

Definition Sample:

You may download the sample definition(s) from the link provided and import them into your FlowWright Process Definition.

Note: Verify and complete any missing configuration after importing the sample, including:

• Variable/Global containing the matrix XML.
• Target column.
• Row index.
• Variable/Global that will store the retrieved value.
• Environment-specific Variable or Global mappings.
• Downstream True and False workflow paths.

Verify that the target row and column correspond to the intended matrix cell before executing the workflow.

After verifying the configuration, save the Process Definition before execution.

Click here to download the sample file.