The Workflow Monitor controls workflow execution and presents a detailed view of the workflow execution status. Agent states and events can be monitored during workflow execution.

The monitor also allows for dynamic updates of the configuration for certain agents by sending commands. A command can, for example, tell an agent to flush or reset data in memory. For further information about applicable commands, see the section for the relevant agent.

Note!

The Workflow Monitor can apply commands to only one workflow at a time, in one monitor window per workflow. The monitor functionality is not available for groups or the whole workflow configuration. The Workflow Monitor displays the active version of the workflow.

Monitoring a workflow does not imply exclusive rights to start or stop it, the workflow can be activated and deactivated by another user while monitored, or by scheduling.

Opening the Workflow Monitor

You can open the workflow monitor from either a workflow configuration or the Execution Manager.

To open the monitor from a workflow configuration:

Click the
(Run) button
From the Run Workflow dialog, Select the workflow you want to view in the workflow monitor.
Click the Run button to open the selected workflow in the workflow monitor. The workflow will only run once you click on the Start button in the workflow monitor.

Workflow Monitor

To open the monitor from the Execution Manager, see the section The Right-Click Menu, in the Execution Manager.

Viewing Agent Events

While a workflow is running, agents report progress in terms of events. These events can be monitored in the two Agent debug panels at the bottom. You can also Enable Debug to view more events or messages from the debug command in the Analysis or Aggregation agents.

Note!

When you Enable Debug, it may slow down the workflow due to logging, especially if you set it to log debug into files in the workflow properties. For more regarding debug in workflow properties, refer to Debug Type in the Execution Tab.

The following steps must be taken in order to view these events.

To view events for all agents in the workflow, click Select All from either of the Agent debug panels.
To only view events for some selected agents, click Select agent(s) to monitor event from either of the Agent debug panels and select only the agents you want to view events for.

Workflow Execution States

All running workflows are monitored by the workflow server on the Platform. A workflow can be in any one of the following states:

The workflow state diagram

State

Description

Building

When a workflow, or any of a workflow's referenced configurations, are being re-built, for example when saving or recompiling, the workflow will be in the Building state.

When a workflow is in the Building state, in the worklow monitor, the text "Workflow is building" is also displayed. Workflows started by scheduling configurations will wait until the workflow leaves the Building state before they start.

Executed

A Workflow becomes Executed after one of the following:

Running:	A successful execution is completed.
Unreachable:	After the Platform re-establishes connection with the Execution Context, and the workflow has finished execution during the period of disconnection.
Manual stop:	A user stopped the execution.

Note!

This is a transient state, after the workflow has run, where cleanup is handled. This state is not reached if the workflow is aborted. In the GUI, the workflow is shown as Stopped even after it has reached the Idle state.

Hold

A workflow that is in the Idle state and is being imported - either by the mzsh systemimport r | sr | sir | wr or by the System Importer configured to Hold Execution - enters the Hold state until the import activity is finished. The Workflow group then resumes its Idle state.

Idle

A workflow is in Idle state if there is no activity going on in the workflow. It means that the workflow is not running, not in process of starting or stopping, or not in any other state (Invalid or Hold). After execution, although the workflow is indeed Idle, the state space on the display may remain as one of the following states:

Aborted	At least one of the workflow agents has aborted. You can track the reason for the error either by double-clicking the aborted agent, or by examining the System Log.
Completed	The workflow has executed and gone back to the Idle state with no errors.
Not started	The workflow has not run since the platform started.

Invalid

The workflow configuration is erroneous. Once you correct the error, the workflow assumes the Idle state.

Note!

The workflow cannot be executed if it is in invalid state.

Loading

The platform is uploading the workflow to the Execution Context. When the transfer is complete, the Execution Context initializes the agents. When the workflow starts running the state changes to Running.

Running

The workflow is currently executing.

Unreachable

If the Platform fails to establish connection with the EC where a workflow is executing, the workflow enters the Unreachable state. When the workflow server successfully reestablishes the connection, the workflow is marked as Running, Aborted, or Executed, depending on the state that the workflow is in. An Unreachable workflow may require manual intervention if the workflow is not running any more. For further information see Execution Context in Desktop User's Guide.

Waiting

The Waiting state applies only to workflows that are included as members in a workflow group. In the Waiting state, the workflow cannot start execution due to two parameters in the workflow group configuration: The Startup Delay parameter, and the Max Simultaneous Running quota. A workflow in the Waiting state changes to Running when triggered either by a user, the scheduling criteria of its parent workflow group, or by a more distant ancestor's scheduling criteria. For further information see Scheduling.

Locked

Locked state is a special case that is only relevant when a batch workflow is present in multiple versions. That is, there are multiple workflows with the same name and instance id from the same workflow configuration. These can be in different versions of a package or be the same as a workflow outside any package.

This means that in case of same workflows, the packages that these workflows are part of are ignored when considering whether they are different versions of the same workflow. If this is the case (and again, only for batch workflows), then only one version is allowed to run at a time. When one version of the workflow starts, the other ones enter into the locked state until the started one completes its execution. Only then is the next version allowed to start. This allows for collection using the file sequence number service to stay consistent even if the workflow version is updated.

Workflow Execution State

The workflow execution state provides granular information about a workflow's current execution status. In APL, there are function blocks that are called for each workflow execution state. For more information about which APL functions that can be used in each state, see Analysis Agent.

Real-time agents only have three different execution states, that occur at every execution of the workflow.

Execution flow for real-time agents

The batch agents are more complex and contain additional states in order to guarantee transaction safety.

Execution flow for batch agents

State	Description
`initialize`	The `initialize` state is entered once for each invocation of the workflow. During this phase the workflow is being instantiated and all agents are set up according to their configuration.
`beginBatch`	This state is only applicable for batch workflows. At every start of a new batch, the batch collection agent emits a `beginBatch` call. All agents then prepare for a new batch. This is normally done every time a new file is collected, but differs depending on the collection agent.
`consume`	The agents handle all incoming UDRs or bytearrays during the `consume` state.
`drain`	This state is only applicable for batch workflows. When all UDRs within a batch have been executed, the agents enter the `drain` state. This state can be seen as a final consume state with the difference that there is no incoming UDR or bytearray. The agent may however send additional information before the `endBatch` state.
`endBatch`	This state is only applicable for batch workflows. The collection agent calls for the `endBatch` state when all UDRs or the byte arrays are transferred into the workflow. This is normally done at the file end, but is dependent on the collection agent or when a `hintEndBatch` call is received from any agent capable of utilizing APL code.
`commit`	This state is only applicable for batch workflows. Once the batch is successfully processed or sent to the ECS, the `commit` state is entered. During this phase, all actions that concern transaction safety are executed.
`deinitialize`	This is the last execution state for each workflow invocation. The agents clean and release resources, such as memory and ports, and stop execution.
`cancelBatch`	This state is only applicable for batch workflows. If an agent fails the processing of a batch it may emit a `cancelBatch` call and the setting in Workflow Properties defines how the workflow should act. For more information regarding the Workflow Properties, see Error Tab in Workflow Properties. Note! The execution states `cancelBatch` and `endBatch` are mutually exclusive - only one per batch can be executed.
`rollback`	This state is only applicable for batch workflows. If the last execution of the workflow aborted, the agents enter the `rollback` execution state right after the `initialize` state. The agents recover the state prior to the failing transaction and then enter `beginBatch` or `deinitialize` depending on if there are additional batches to process.

Viewing Abort Reasons

In most cases if a workflow has aborted, one of its agents has a red square outline surrounding it. Double-clicking such an agent displays the Agent Status dialog with the abort reason. The System Log also holds valid information for these cases.

A workflow with an aborted agent, indicated by the red square outline.

In a batch workflow, a detected error causes the workflow to abort and the detected error is shown as part of the abort reason and inserted into the System Log. A real-time workflow handles errors by only sending them to the System Log. The only time a real-time workflow aborts is when an internal error has occurred. It is therefore important to pay attention to the System Log or subscribe to workflow error events to fully understand the state of a real-time workflow.

Note!

Although a workflow has aborted, its scheduling is still valid. Thus, if it is scheduled to execute periodically, it is automatically started again the next time it is due to commence. This is because the abortion might be a lost connection to a network element, which may be available again later. Therefore, a periodically scheduled workflow, which has aborted, is treated as Active until it is manually deactivated.

Status details for an aborted agent

In the Agent Status dialog, there is a Stack Trace section provided in the dialog. Use the information that it provides when consulting Support.

Agent States

An agent can have one of the following states:

State	Description
Created	The agent is starting up. No data may be received during this phase. This state only exists for a short while during workflow startup.
Idle	The agent is started, awaiting data to process. This state is not available for a real-time workflows.
Running	The agent has received data and is executing. For agents that are running, there is a green square outline surrounding them.
Stopped	The agent has successfully finished processing data.
Aborted	The agent has terminated erroneously. For an agent that is aborted, there is a red square outline surrounding the aborted agent. The error reason can be tracked either by double-clicking the agent or by examining the System Log.

Agent Configuration

Some agents allow parts of them to be reconfigured while active. When double-clicking the agent in monitor mode, the agent's configuration is shown if the agent can be reconfigured. When the configuration has been updated it can be committed to the active workflow using the Dynamic Update button in the toolbar.

Dynamic Update

While a real-time workflow is being executed, you can change the value of the following parameters:

The Host and Port parameters of the TCP/IP agent
The NAS list of the Radius agent
The Interval of the Pulse agent

Example of the TCP/IP configuration in a running Realtime workflow

To be able to dynamically update TCP/IP Host and Port parameters, you need to set them to either Default or Per Workflow in the Workflow Properties dialog. See the figure The Workflow Table Tab in Workflow Table Tab.

To update, click Dynamic Update. On the bottom left of the workflow monitor, the text Dynamic Update followed by a number appears. It represents the number of times that you have updated the workflow configuration while running it, that is, since the last time you started it.

Example of a dynamic update status after clicking the Dynamic Update button

Transactions

A workflow operates on a data stream and supplies a transaction model where persistent synchronization is made from the workflow data and agent-specific counters. In theory the synchronization could be performed continuously on a byte level, but in practice this would drastically decrease the performance of the system.

The transaction model is based on the premises that collection agents are free to initiate a transaction to the transaction server. At the moment the complete workflow is frozen and the transaction server saves the state of the workflow data that is queued for each agent. In practice, agents indirectly emit a transaction when an End Batch is propagated. When all data is secured, the workflow continues the execution.

Debug

A workflow can be configured to send debug logs as an event or to a file. When an event is selected, the debug logs will be present in the text areas in Workflow Monitor View.

When the Debug Type is File, the debug will be written to a file in MZHOME of the Execution context. The default file location is in a debug directory inside the temporary directory decided by this property pico.tmpdir. It can also be set directly using this property, mz.wf.debugdir.

When the debug is sent to a file, an additional button will be visible in the Workflow Monitor, Download debug files.

After a run the Download debug files button is enabled and once you click on the button, the following dialog appears.

Screenshot 2024-04-17 at 09.12.52.png