Builder steps

info

These functions are available in the Workflow Engine ≥ 4.0

Build step is an additional opportunity to change a process scheme when creating it. When Workflow Engine creates a new process, it executes the following actions:

• WorkflowBuilder searches for a relevant generated (IsObsolete = false) scheme in the WorkflowProcessScheme table (search is executed using SchemePersistenceProvider).
• if a relevant scheme has not been found, scheme generator is launched, it returns scheme as XML. For example, the out-of-the-box generator returns scheme from the WorkflowScheme table.
• WorkflowBuilder can be configured to convert the generated scheme to another scheme using Build steps. Builder executes system Build steps only by default, but you can add custom Build steps.
• converted scheme is saved to the WorkflowProcessScheme table.

Every Build step is a class inherited from the abstract class OptimaJet.Workflow.Core.Builder.BuildStep

public class CustomBuildStep : BuildStep
{
    public override string Name => "CustomBuildStep";
    
    public override BuildStepResult Execute(ProcessDefinition processDefinition,
        IDictionary<string, object> parameters)
    {
        var builder = Builder;
        var success = true;
        try
        {
            // some manipulations with process definition
            var modifiedProcessDefinition = processDefinition.Clone();
            // add or remove scheme elements here
        }
        catch (Exception ex)
        {
            return BuildStepResult.Fail(ex.Message);
        }
        
        if (success)
        {
            return BuildStepResult.Success(modifiedProcessDefinition);
        }

        return BuildStepResult.Fail("Some error message");
    }
}

From this code you can see that Build step must have a Name. Also Execute method must be implemented, it executes scheme conversion. Implementing this method you can add and delete any elements in the scheme. You have unrestricted access to the Builder property in this method. There are two scenarios:

• your Build step has completed successfully, and you return a new process scheme. By the way, this scheme object may be different from the scheme object in the input processDefinition parameter of the Execute method.

  return BuildStepResult.Success(processDefinition);

• your Build step resulted with an error which will be thrown as exception or displayed in the designer.

  return BuildStepResult.Fail("Some error message");

You can notify WorkflowBuilder that it must execute additional Build steps when configuring WorkflowBuilder and WorkflowRuntime.

var builder = new WorkflowBuilder<XElement>(provider, new XmlWorkflowParser(), provider)
    .WithDefaultCache();
// these build steps will be executed before system build steps
builder.AddBuildStep(0, BuildStepPosition.BeforeSystemSteps, new CustomBuildStep1());
builder.AddBuildStep(1, BuildStepPosition.BeforeSystemSteps, new CustomBuildStep2());
builder.AddBuildStep(2, BuildStepPosition.BeforeSystemSteps, new CustomBuildStep3());

// these build steps will be executed after system build steps
builder.AddBuildStep(0, BuildStepPosition.AfterSystemSteps, new CustomBuildStep1());
builder.AddBuildStep(1, BuildStepPosition.AfterSystemSteps, new CustomBuildStep2());
builder.AddBuildStep(2, BuildStepPosition.AfterSystemSteps, new CustomBuildStep3());

runtime = new WorkflowRuntime()
            .WithBuilder(builder)
            ...
            .Start();

You can see from this code that you can specify whether your Build steps will be executed before or after system steps. To do that, use the AddBuildStep method second parameter which can be BeforeSystemSteps or AfterSystemSteps value. The AddBuildStep method first parameter specifies the steps order for the steps executed before or after system steps. Theoretically you can add your Build step into system steps, but we do not advise to do that.

Thus, you can build custom step chain which will convert the process scheme generated by the generator.

System Build steps

At the moment Workflow Engine has got only one system Build step - InlineSchemesStep. This step is responsible for the scheme inlining, i.e. for embedding schemes into each other in order to re-use typical schemes.

Build steps and Designer

When saving a scheme, the designer executes Build steps to check them, but instead of the resulted scheme it saves the scheme which was drawn in the designer. This check is necessary to ensure that it is possible to create a process based on the saved scheme. Such check is especially important to avoid cycle references during scheme inlining.