Process Parameters

General information

Parameters are objects that are stored together with a process, and may provide for the transition logic or be used as process artifacts. For instance, they may store the comments conveyed by a user upon execution of a command to provide for the business logic in Actions. In general, process Parameters may store the whole document which is being approved within a process. There is only one requirement set for an object stored in Parameters: it should be properly JSON-(de)serialized; in particular, it should have a constructor without parameters.

Parameters may be declared in a scheme explicitly or implicitly. Description of Parameters in a scheme is done in the Parameters section, which may be accessed by clicking on a corresponding button in the toolbar.

When Parameter is created, the following properties are specified.

  • Name - Parameter name. All Parameters are identified by their name. Name is case-sensitive;
  • Type - a CLR type of Parameter. The list has an autocomplete feature that suggests available names. Primitive types may be specified with a short name without a namespace: String, Int32, Guid, etc. Other types should be specified with the full namespace: Business.SomeEntity, System.Text.Encoding, etc. Generic types are specified in the following way: System.Collections.Generic.Dictionary<String,Int32>, System.Collections.Generic.List<Business.SomeEntity>. By default, the autocomplete suggests only primitive types. The registration of types for the autocomplete is performed in Designer with the runtime.RegisterAssemblyForCodeActions(...) method. By default, all types from an assembly will be displayed in Designer. To avoid this, a filter function may be set. For instance, the following code will register only types from the System.Collections.Generic namespace:
    runtime.RegisterAssemblyForCodeActions(Assembly.GetAssembly(typeof(System.Collections.Generic.List<>)), false,
    type => type.FullName.StartsWith("System.Collections.Generic"));
  • Purpose - Parameters may be Temporary and Persistence. Temporary Parameter exists from the time of its conveying to a process, or its setting within a process, till the end of the transition process. In other words, if you convey Parameter with Purpose = Temporary to the process through Command, it will be possible to obtain its Value only until the process stops and begins waiting for another Command. Persistence Parameter is stored in a database in the WorkflowProcessInstancePersistence table (or object). Its Value may be accessed at any time after it has been set. The third type of Purpose is a system one. System Parameters cannot be created; they are used by Workflow Engine for its proper operation. You may access them trough the ProcessInstance object. These Parameters will be discussed in detail further on;

  • Initial Value is the initial value of Parameter. It can be specified only for Parameters with Purpose = Persistence. It contains the initial value of Parameter, which will be assigned to the latter immediately after the process has been created. Value represents JSON. Open the JSON editor to see what it looks like. For instance, the Format button formats the JSON; the Create button creates an object's sample in the following way: first, it creates an object with the requested type on the server, which is further serialized in JSON and displayed in Designer. It is quite convenient when working with large business objects.

Conveying Parameters to the process

You may convey Parameters to a process in the following ways:

  • Persistence Parameters who have an Initial Value set will be initialized immediately after the process has been created;

  • Upon creating of a new process. You may convey both Temporary and Persistence Parameters in this way. Temporary Parameters may be required, for instance, if a process executes a code immediately after initialization:

    var createInstanceParams = new CreateInstanceParams("SchemeCode", processId)
    {
    InitialProcessParameters = new Dictionary<string, object>()
    {
        {"Parameter1", parameter1Value},
        {"Parameter2", parameter2Value}
    },
    };
    WorkflowInit.Runtime.CreateInstance(createInstanceParams);
  • Trough Parameters of Commands;

  • You may also adjust process Parameters manually from the outside. To do this, you need to obtain the ProcessInstance object's instance, change its Parameters and save their Values.
    var processInstance = WorkflowInit.Runtime.GetProcessInstanceAndFillProcessParameters(processId);
    processInstance.SetParameter("ParameterName", newParameterValue);
    WorkflowInit.Runtime.PersistenceProvider.SavePersistenceParameters(processInstance);

Working with process Parameters

  • Obtaining Parameter's Value:

    var parameterValue = processInstance.GetParameter<ParameterType>("ParameterName");
  • Changing Parameter's Value:

    processInstance.SetParameter("ParameterName",parameterValue);
  • Removing Persistence's Parameter. Removal of Persistence's Parameter will also take place, if Parameter's Value is set to null. Parameters that are null are removed from the database:

    processInstance.RemoveParameter("ParameterName");
  • Checking whether Parameter exists in the process:
    bool isExisting = processInstance.IsParameterExisting("ParameterName");

Implicit Parameters

In fact, it is not necessary to declare Parameters in a scheme, if they do not function outside the process, for instance, if they are not conveyed to it through Commands. For instance, the following code will create a Temporary Parameter, if Parameter with the "ImplictParameter" name was not explicitly declared in the scheme:

processInstance.SetParameter("ImplictParameter",parameterValue);

In order to create a Persistence Parameter, use the following code. It will create a Parameter and save it in the database:

processInstance.SetParameter("ImplictParameter",parameterValue,ParameterPurpose.Persistence);

You should specify ParameterPurpose.Persistence only for the first time. Further, you may use the implicit Parameter in the same way you would use a Parameter declared in the scheme, using the methods described in the previous section.

Parameter visibility area

Parameter visibility area means a moment in time when it is possible to get parameter value (by calling the GetParameter method). You can convey parameters to the process at any time. Parameter visibility area depends on the Purpose attribure.

  • Temporary - parameter will be accessible from the moment of its conveyance (through a command, initial process parameters or by calling the SetParameter method) until the end of a transition process, i.e. until the time when the process stops and starts waiting for the next command.
  • Persistence - accessible at any time.

Main system Parameters

You may access system Parameters trough special properties of the ProcessInstance object. Here are the main ones:

  • processInstance.ProcessId - Guid - process identifier;
  • processInstance.SchemeId - Guid - scheme identifier from the WorkflowProcessScheme table;
  • processInstance.SchemeCode - string - scheme code (name);
  • processInstance.RootProcessId - Guid - root process identifier; equals to ProcessId for the base root process;
  • processInstance.ParentProcessId - Guid - parent process identifier;
  • processInstance.CurrentState - current recorded state name;
  • processInstance.PreviousState - previous recorded state name;
  • processInstance.PreviousStateForDirect - name of the previous state recorded at the direct Classifier = Direct transition;
  • processInstance.PreviousStateForReverse - name of the previous state recorded at the reversal Classifier = Reverse transition;
  • processInstance.ExecutedActivityState - executed Activity's state name;
  • processInstance.CurrentActivity - name of the current recorded Activity;
  • processInstance.PreviousActivity - name of the previous recorded Activity;
  • processInstance.PreviousActivityForDirect - name of the previous Activity recorded at the direct Classifier = Direct transition;
  • processInstance.PreviousActivityForReverse - name of the previous Activity recorded at the reversal Classifier = Reverse transition;
  • processInstance.ExecutedActivity - ActivityDefinition whose Actions are currently being implemented;
  • processInstance.ExecutedTransition - TransitionDefinition which is currently being executed;
  • processInstance.StartTransitionalProcessActivity - name of Activity that started the transition process;
  • processInstance.CurrentCommand - name of the currently executed Command;
  • processInstance.ExecutedTimer - name of the currently executed Timer;
  • processInstance.IdentityId - user identifier conveyed trough ExecuteCommand or SetState;
  • processInstance.ImpersonatedIdentityId - impersonated user identifier conveyed trough ExecuteCommand or SetState;
  • processInstance.IsPreExecution - returns true, if Action was called in the Pre-execution mode;
  • processInstance.IdentityIds - list of identifiers of users who potentially could execute a transition to Activity. Specified only in the Pre-execution mode;
  • processInstance.IdentityIdsForCurrentActivity - list of identifiers of users who can execute a transition from the executed Activity. Specified only in the Pre-execution mode.
Top