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 CreateInstance method accepts two parameters: scheme code (name) and process ID:

WorkflowInit.Runtime.CreateInstance("SchemeCode", processId);

The most extensive version of the CreateInstance 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}
    },
    SchemeCreationParameters = new Dictionary<string, object>()
    {
        {"GeneratorParameter1", parameterValue}
    },
    IdentityId = identityId,
    ImpersonatedIdentityId = impersonatedIdentityId
};

WorkflowInit.Runtime.CreateInstance(createInstanceParams);

• InitialProcessParameters is a process parameters dictionary that is passed during the process creation;
• SchemeCreationParameters are parameters passed to the scheme generator. They are not used in case the generator is delivered to persistence providers;
• 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 GetAvailableCommands 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 = WorkflowInit.Runtime.GetAvailableCommands(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 ExecuteCommand to execute a command as indicated below:

WorkflowInit.Runtime.ExecuteCommand(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 GetAvailableCommands 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 = WorkflowInit.Runtime.GetAvailableCommands(processId, currentUser);

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

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

WorkflowInit.Runtime.ExecuteCommand(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 = WorkflowInit.Runtime.GetAvailableCommandsWithConditionCheck(processId, currentUser);

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

• command execution with additional restrictions check

  WorkflowInit.Runtime.ExecuteCommandWithRestrictionCheck(command, currentUser, impersonatedUser);

  The standard method ExecuteCommand does not perform restrictions secondary check, whilst the ExecuteCommandWithRestrictionCheck 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 GetAvailableStateToSet method which accepts process ID, it can be called to get a list of available states.

var statesList = WorkflowInit.Runtime.GetAvailableStateToSet(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 SetState method is applied for setting up the process state:

IDictionary<string, object> parameters = null;
bool preventExecution = false;
WorkflowInit.Runtime.SetState(processId, identityId, impersonatedIdentityId, stateName,
    parameters, preventExecution);

The attributes processId, identityId, impersonatedIdentityId are equivalent to those submitted to the command execution method. stateName is the state name parameter on the scheme. parameters dictionary are attributes assigned to the process. preventExecution determines the way a process state is being configured. 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.

The minimum parameter set of the SetState function includes:

WorkflowInit.Runtime.SetState(processId, identityId, impersonatedIdentityId, stateName);

Process Deletion

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

WorkflowInit.Runtime.DeleteInstance(processId);

Async API

All the methods described have asynchronous versions. Simply add Async at the end of the method's name, as in ExecuteCommand and ExecuteCommandAsync.

Base Events

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

runtime.ProcessActivityChanged += (sender, args) => { };
runtime.ProcessStatusChanged += (sender, args) => { };

ProcessActivityChanged 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.

ProcessStatusChanged 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.