Workflows

Workflow Status and Locking

Business Rules and Data Management sequences often need to check workflow status before acting — is the entity certified? Is the period locked? Can data be loaded? This guide covers the API surface for querying and controlling workflow state programmatically, including the primary key objects, the WorkflowInfo result, and the locking methods.

WorkflowUnitPk vs WorkflowUnitClusterPk

Two key objects identify workflow targets. Choosing the right one depends on whether you are operating on a single entity or a group.
WorkflowUnitPk identifies a single workflow unit: a specific Profile + Scenario + Time combination. Use this when you need to target one entity's workflow state.
WorkflowUnitClusterPk identifies a cluster of related workflow units — typically used when operating on a group of entities under the same profile. The cluster key aggregates status across children, so querying at this level tells you whether all entities in the cluster are locked, certified, and so on.
Use WorkflowUnitPk for individual entity checks. Use WorkflowUnitClusterPk when querying or locking at the profile level, which includes all child entities.
1' Build a WorkflowUnitPk for a specific entity
2Dim wfUnitPk As New WorkflowUnitPk( _
3  workflowProfileId, scenarioId, timeId, channelKey)
4
5' Build a WorkflowUnitClusterPk for a profile
6Dim wfClusterPk As New WorkflowUnitClusterPk( _
7  workflowProfileId, scenarioId, timeId)

WorkflowInfo Properties

Calling BRApi.Workflow.Status.GetWorkflowStatus returns a WorkflowInfo object. The table below lists the properties you will use most often in automation logic.
PropertyTypeDescription
LockedBooleanWhether the workflow unit is currently locked.
IsCertified()BooleanWhether the workflow unit has been certified (checks if the Certify step is completed).
GetStep(StepClassificationTypes.X)WorkflowStepInfoReturns the step info for a given step classification (e.g., LoadCube, Certify).
Step-level status is accessed through the GetStep() method. For example, wfInfo.GetStep(StepClassificationTypes.LoadCube).Status returns the WorkflowStatusTypes value for the Load step.
ℹ️Info
The WorkflowStatusTypes enum defines step status values: 0 = NotStarted, 1 = InProgress, 2 = Completed, 10 = Error, 20 = NoStatus. Check for value 2 (complete) when gating downstream logic on a prior step's success.

Querying Workflow Status

The most common call is BRApi.Workflow.Status.GetWorkflowStatus. Pass a WorkflowUnitClusterPk and the API returns the aggregated status for that cluster.
1' Get workflow status for a specific workflow unit
2Dim wfClusterPk As New WorkflowUnitClusterPk( _
3  workflowProfileId, _
4  si.WorkflowClusterPk.ScenarioKey, _
5  si.WorkflowClusterPk.TimeKey)
6
7Dim wfInfo As WorkflowInfo = _
8  BRApi.Workflow.Status.GetWorkflowStatus(si, wfClusterPk)
9
10' Check if the unit is locked or certified
11If wfInfo.Locked OrElse wfInfo.IsCertified() Then
12  BRApi.ErrorLog.LogMessage(si, "Unit is read-only")
13End If
14
15' Check step-level status
16Dim loadStatus As Integer = _
17  wfInfo.GetStep(StepClassificationTypes.LoadCube).Status
18If loadStatus = WorkflowStatusTypes.Completed Then
19  BRApi.ErrorLog.LogMessage(si, "Load step is complete")
20End If

Locking and Unlocking

The BRApi.Workflow.Locking namespace provides methods to lock and unlock workflow units programmatically. These are typically called from Data Management steps or administrative Business Rules.
1' Lock a workflow unit
2BRApi.Workflow.Locking.LockWorkflowUnit(si, wfClusterPk)
3
4' Unlock a workflow unit
5BRApi.Workflow.Locking.UnlockWorkflowUnit(si, wfClusterPk)
⚠️Warning
Locking and unlocking via API bypasses the UI security checks. Ensure your Business Rule validates that the calling user has appropriate permissions before executing these calls.

StepClassificationTypes Enum

Each step in the workflow task bar maps to a value in the StepClassificationTypes enum. You will encounter these when inspecting step-level status or building custom task automation.
Enum ValueIntegerDescription
Unknown-1Default / unknown state.
ManageWorkflow0Manage Workflow task.
InputForms1Forms / Dashboard input task.
InputJournals2Journal entry task.
DataLoadTransform11Data load transformation task.
DataLoadClearData15Clear data task.
ValidateTransform20Validate transformation task.
ValidateIntersection21Validate intersection task.
LoadCube30Load data to cube task.
ProcessCube40Process / Calculate task.
Confirm50Confirm task.
Certify60Certify task.

Check-Before-Write Guard Clause

A common pattern in automation rules is to verify workflow status before writing data. If the entity is locked or certified, the rule logs a message and returns early instead of attempting a write that would fail.
1' Guard clause: skip data write if the period is locked
2Dim wfInfo As WorkflowInfo = _
3  BRApi.Workflow.Status.GetWorkflowStatus(si, wfClusterPk)
4
5If wfInfo.Locked Then
6  BRApi.ErrorLog.LogMessage(si, _
7      $"Skipping write — entity {entityName} is locked " & _
8      $"for {scenarioName}/{timeName}")
9  Return
10End If
11
12' Safe to write data
13api.Data.SetDataCell(si, memberList, amount)
💡Tip
Always check workflow status before writing data in automation rules. Writing to a locked or certified entity will either fail silently or throw an exception, depending on the API method used.

Related Content