WorkflowRuntime: Process Management

This Section describes basic workflow management functionality. In fact, there are far more ways of managing workflows through Workflow Engine, however, in most cases you are likely to apply only these methods.

Process Creation

A minimum version of the CreateInstanceAsync method accepts two parameters: scheme code (name) and process ID:

await WorkflowInit.Runtime.CreateInstanceAsync("SchemeCode", processId);

The most extensive version of the CreateInstanceAsync method accepts CreateInstanceParams. This object contains supplementary input parameters for process creation:

var createInstanceParams = new CreateInstanceParams("SchemeCode", processId)
{
    InitialProcessParameters = new Dictionary<string, object>()
    {
        {"Parameter1", parameterValue}
    },
    IdentityId = identityId,
    ImpersonatedIdentityId = impersonatedIdentityId
};

await WorkflowInit.Runtime.CreateInstanceAsync(createInstanceParams);

• InitialProcessParameters is a process parameters dictionary that is passed during the process creation;
• IdentityId and ImpersonatedIdentityId are identifiers of the user performing an operation and the one on whose behalf it is performed. These attributes should be transferred during the creation stage only if the process demands so right after the start;
• ImpersonatedIdentityId should be transferred only if you use impersonation (user performs operations on behalf of another user), otherwise it doesn't have to be transferred.

During workflow instance creation the only required parameters you have to fill are the scheme code (name) and process ID.

Commands Retrieval and Execution

The GetAvailableCommandsAsync method that accepts process ID and user ID, it can be called in order to get a list of commands available to a user.

The IEnumerable<WorkflowCommand> retrieves a list of commands available for a particular user, enquiring process ID and user identity ID:

var commandsList = await WorkflowInit.Runtime.GetAvailableCommandsAsync(processId, identityId);

Here, WorkflowCommand contains information on original and localized command names, along with parameters that should be transferred along with the command. This object supports serialization both in JSON and XML formats, thus, enabling you to easily retrieve it from your services.

You should invoke the method ExecuteCommandAsync to execute a command as indicated below:

await WorkflowInit.Runtime.ExecuteCommandAsync(command, identityId, impersonatedIdentityId);

The identityId and impersonatedIdentityId parameters define the user performing the operation and the one on whose behalf it is performed. If you don't use impersonation, simply submit identityId as impersonatedIdentityId.

Indeed, command is a command retrieved by calling the GetAvailableCommandsAsync method.

A use case for web application that already contains client data validation looks like this:

var processId = ...; // Get it from a request
var commandName = ...; // Get it from a request

var currentUser = HttpContext.User.Identity.Name;
var commands = await WorkflowInit.Runtime.GetAvailableCommandsAsync(processId, currentUser);

var command = commands.FirstOrDefault(c => c.CommandName == commandName);

if (command == null)
    return; // Or throw an error      

await WorkflowInit.Runtime.ExecuteCommandAsync(command, currentUser, currentUser);

Furthermore, you may enquire for user login, database GUID or anything else in order to identify the user's identityId.

Two additional methods were added into Workflow Engine ≥ 4.0 - getting a list of available commands and command execution:

• getting a list of available commands with additional conditions check

  var commands = await WorkflowInit.Runtime.GetAvailableCommandsWithConditionCheckAsync(processId, currentUser);

  In addition to restrictions, these methods checks all conditions linked to corresponding command triggered transitions.

• command execution with additional restrictions check

  await WorkflowInit.Runtime.ExecuteCommandWithRestrictionCheckAsync(command, currentUser, impersonatedUser);

  The standard method ExecuteCommandAsync does not perform restrictions secondary check, whilst the ExecuteCommandWithRestrictionCheckAsync performs additional check whether command transition is available for user impersonatedUser.

example

An example that demonstrates how can be used ExecuteCommand method in WorkflowController class in a sample application, it can be found in our Tutorials section.

Workflow State Retrieval and Change

The GetAvailableStateToSetAsync method which accepts process ID, it can be called to get a list of available states.

var statesList = await WorkflowInit.Runtime.GetAvailableStateToSetAsync(processId);

The WorkflowState contains information on original and localized state names. This object supports serialization both in JSON and XML formats, enabling you to easily retrieve it from your services.

The SetStateAsync method is applied for setting up the process state. It accepts a SetStateParams object that contains all necessary parameters:

var setStateParams = new SetStateParams(processId, stateName)
{
    IdentityId = identityId,
    ImpersonatedIdentityId = impersonatedIdentityId,
    PreventExecution = false
};

setStateParams.AddPersistentParameter("Parameter1", parameterValue);

await WorkflowInit.Runtime.SetStateAsync(setStateParams);

The SetStateParams constructor accepts processId and stateName as required parameters. Additional properties:

• ProcessId - Process id;
• StateName - State name to set forcibly;
• IdentityId - The user id which execute operation;
• ImpersonatedIdentityId - The user id for whom executes operation;
• ProcessParameters - Parameters to be passed to the process;
• Persist - Names of persist parameters in ProcessParameters;
• PreventExecution - Actions due to transition process do not executed if true. If this parameter is set to false, then WorkflowEngine will execute the Implementation section of the initial Activity of the current state, and start the transient process if possible. In case PreventExecution is set to true, the current state and activity will be changed, while no execution will be performed.

You can add parameters using AddPersistentParameter method (for persisted parameters) or AddTemporaryParameter method (for temporary parameters).

The minimum parameter set of the SetStateAsync function includes:

var setStateParams = new SetStateParams(processId, stateName);
await WorkflowInit.Runtime.SetStateAsync(setStateParams);

Process Deletion

The DeleteInstanceAsync method removes the entire process with the associated artifacts from persistence storage:

await WorkflowInit.Runtime.DeleteInstanceAsync(processId);

Async API

info

Starting from Workflow Engine version 21.0, WorkflowRuntime provides only asynchronous API. All synchronous methods have been removed.

If you need synchronous behavior, you can use the .GetAwaiter().GetResult() pattern on async methods:

// Synchronous call example
WorkflowInit.Runtime.CreateInstanceAsync("SchemeCode", processId).GetAwaiter().GetResult();

However, it's strongly recommended to use async/await throughout your application for better performance and scalability.

Base Events

In day-to-day work you may need 2 events:

runtime.OnProcessActivityChanged += (sender, args) => { };
runtime.OnProcessStatusChanged += (sender, args) => { };

OnProcessActivityChanged event is raised every time the current process activity is changed. Two objects are passed in event arguments: ProcessInstance with all process parameters and CurrentActivity defining the updated current activity. TransitionalProcessWasCompleted attribute signifies whether or not the transient process is completed. If it is, then the process stops, awaiting for a command or timer. It is appropriate to fill in the WorkflowInbox table in this event-handler.

OnProcessStatusChanged event happens, when the process status is changed, for example if running-to-idled transition (and vice versa) has taken place. Event arguments contain the former and new status data, giving access to the ProcessInstance object. This event-handler enables you to delete the process once it reached the finalized status.