Description:

The Set Matrix Value workflow step sets the value of a specified matrix cell. The step can also be configured to set multiple matrix cell values through its grid-value mapping property.

The step works with matrix data stored in a Variable or Global and provides inputs to identify the target column and row, as well as the value to assign.

The step supports:

• Setting a value in a matrix cell.
• Selecting the Variable or Global that holds the matrix XML.
• Specifying the column in which the value should be set.
• Specifying the row index.
• Assigning a value to the selected matrix cell.
• Mapping multiple matrix cell values.
• Returning a True or False result.

Usage:

The Set Matrix Value step is typically used when a workflow needs to modify data stored in a matrix.

The workflow can identify:

• The Variable or Global containing the matrix XML.
• The target column.
• The target row index.
• The value to assign.

Alternatively, the Set multiple matrix cell values property can be used to map values in a grid.

Typical uses include:

• Updating a value in a matrix row.
• Updating status or other matrix fields.
• Applying workflow results to matrix data.
• Updating multiple matrix cells.
• Preparing matrix data for subsequent workflow processing.
• Modifying matrix data before passing it to another step.
• Dynamically updating indexed matrix records.

Typical Workflow Suggestions:

Update a Matrix Status

Use Set Matrix Value to update a status column for a particular row.

Example:

Process Record → Determine Result → Set Matrix Value → Continue

For example:

• Column: Status
• Row: 2
• Value: Approved

Update a Matrix After Approval

Modify a matrix record after an approval activity.

Example:

Approval Task → Determine Approval Result → Set Matrix Value → Complete

This can be useful when the matrix represents multiple records being processed by a workflow.

Update a Specific Row

Use the row index to target a particular matrix record.

Example:

Identify Record → Determine Row Index → Set Matrix Value → Process Next Step

The XML explicitly provides an Index of the row property.

Update a Specific Column

Use the column name to identify which field of the matrix row should be changed.

Example:

Determine Column → Set Matrix Value → Continue

The step provides a Name of the column property for this purpose.

Apply Dynamic Values

Use workflow-generated data as the value to assign.

Example:

Calculate Result → Set Matrix Value → Continue

The valueToAssign property is a string, allowing the value to be supplied dynamically.

Update Multiple Matrix Cells

Use Set multiple matrix cell values when several matrix cells need to be updated.

Example:

Calculate Results → Set Multiple Matrix Cell Values → Validate Matrix → Continue

The XML specifically provides an enterGridValues property for Set multiple matrix cell values.

Prepare Matrix Data for Another Step

Modify the matrix values before passing it to a subsequent activity.

Example:

Retrieve Matrix → Set Matrix Value → Validate → Process Matrix

Update Processing Results

Write workflow-generated results back into a matrix.

Example:

Process Row → Calculate Result → Set Matrix Value → Mark Row Complete

This is particularly useful when the matrix acts as a collection of records being processed by the workflow.

Process Indexed Matrix Records

Use the row index when processing a matrix one row at a time.

Example:

Determine Current Row → Process Data → Set Matrix Value → Next Row

The step's rowIndex property is specifically provided to identify the row index.

Update Multiple Fields for a Record

When a workflow needs to update multiple fields on a matrix record, use the multiple-value mapping capability.

Example:

Process Record → Calculate Values → Set Multiple Matrix Cell Values → Continue

The XML confirms that the step supports a grid-based Map grid values data type for this purpose.

Success and Failure Handling

Use the two return paths to separate successful matrix updates from unsuccessful executions.

Example:

Set 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 “setGetMatrixValueDef” example.          

• Create a new process definition named “setGetMatrixValueDef” and open it in designer mode. 
• Drag a “setMatrixValue, getMatrixValue” step to the canvas. 
• Connect the dots between the “Start” step and 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 values are available for configuration.
• 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 Copilot add new process steps that match your process description. 

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

• Click the "setMatrixValue" step to configure its "Optional" properties. Provide a variable or a 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 add multiple matrix row indexes and values using the Add Row button. You can use the “arrow keys” to reorder the row position. You can click the “copy” icon to duplicate the row contents into a new row.  

• 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 contains the XML value. Provide the column name and the row index. 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 in the images 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 Set Matrix Value step, FlowWright uses the configured matrix XML, column, row index, and value to update the matrix. The XML definition explicitly identifies the step as setting the value of a given matrix cell. 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 data.
• Confirm that the specified column exists in the matrix.
• Confirm that the row index identifies the intended row.
• Validate dynamically generated row indexes before updating a cell.
• Use meaningful and consistent column names.
• Use workflow Variables or Globals when the value needs to be determined dynamically.
• Test both single-cell and multiple-cell update scenarios.
• Use Set multiple matrix cell values when several cells need to be updated in a single operation.
• Test the grid-value configuration with representative matrix data.
• Test both the True and False paths.
• Add appropriate logging or error handling to the False path.
• Verify the expected row-indexing convention in the target FlowWright implementation; the XML does not specify whether indexes are zero-based or one-based.
• Verify the expected XML structure before deploying a workflow that modifies matrix data.
• Avoid dynamically constructing row indexes without validating that the target row exists.
• Validate the resulting matrix data before passing it to downstream activities.
• If several workflow steps modify the same matrix, carefully control the order of those updates.
• Use a consistent strategy for identifying matrix rows and columns.
• Test workflows with empty matrices, populated matrices, and representative row positions where appropriate.
• Do not assume that leaving optional properties empty results in a particular runtime behavior; the XML only indicates that they are not required.

Notes:

• The Set Matrix Value step is defined in the Engine category with the internal name setmatrixvalue, label “Sets the value of a given matrix cell”, and display name “Set Matrix Value.”
• The step is implemented by FlowWright.Workflow.SetMatrixValue in FlowWright.Workflow.dll and is a Process step with 2 incoming connections and 2 outgoing connections.
• The XML defines five configurable properties, none of which is marked as required.
• The five properties are:
  • xmlVariable – Variable/Global that holds the XML
  • columnName – Name of the column
  • setMatrixValues – Set multiple matrix cell values
  • valueToAssign – Value to assign
  • rowIndex – Index of the row 
• Four properties use the string data type. The multiple-cell property uses enterGridValues.
• The string property type is implemented by FlowWright.DataTypes.ClsTextBox. The enterGridValues property type is implemented by FlowWright.DataTypes.ClsEnterGridValues and is described as “Map grid values.”
• 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.
• Value to assign.
• Multiple-cell grid mappings, if applicable.
• 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.