Commands

General information

Command is one of the triggers that make a process leave the idle state and perform a certain action. Command is an external trigger. You should never think of a Command only as of an action performed by a system user. For example, Command can be executed by an external server or an external timer. Command is also one of the major ways of conveying Parameters to the process. Access to Command is controlled not by Command itself, but by Restrictions specified in the transition triggered by this Command. For more details, refer to the Rules section.

Description of Commands in the scheme is set in the Commands section, which may be accessed by clicking on a corresponding button in the toolbar. The following Command properties are available for modification:

• Name - Command's name. All Commands are identified by a name, which is case-sensitive;
• Input parameters - description of the input parameters for a Command. Each Command may have any amount of input parameters, from 0 to infinity.

Each input parameter has the following properties:

• Name - name of the parameter in Command. It is used for localization and access to parameters in a Command. You should not confuse it with a parameter name, though, it is quite convenient when two names coincide;
• Parameter - link to a Parameter;
• Required - attribute that determines whether Parameter Value should necessarily be specified in this Command;
• Default - default Value for an input parameter. It may contain JSON, and is used for specifying default Values for complex objects.

The description of parameters represents metadata, which may be used to generate user input form for each Command.

Let's look at the case describing how to get a Command, specify its parameters and convey it to WorkflowRuntime for further execution.

Working with commands

Imagine we got a list of Commands by using the following method:

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

This method returns a list of the WorkflowCommand objects that contain the following information:

• Command name and its localized name (if localization is set for this Command):

  string commandName = command.CommandName;
  string localizedName = command.LocalizedName;

• The names of Activity and State the Command relates to. In other words, it is where a process triggered by this Command starts:

  string activityName = command.ValidForActivityName;
  string stateName = command.ValidForStateName;

• A list of identifiers of users who can execute this Command. This parameter should be considered only if impersonation is used:

  IEnumerable<string> identities = command.Identities;

• Id of the process which Command relates to, as well as an attribute specifying whether it was received for a subprocess. This parameter should be considered, if there are subprocesses in the scheme:

  Guid processId = command.ProcessId;
  Guid isSubprocessCommand = command.IsForSubprocess;

• Classifier of the transition triggered by a Command. It may be direct and reversal. For more details, refer to the Transitions section.

  TransitionClassifier classifier = command.TransitionClassifier;

• A collection of parameters - CommandParameter objects:

  IEnumerable<CommandParameter> parameters = command.Parameters;

  Each parameter's name and localized name can be accessed with:

  string parameterName = parameter.ParameterName;
  string localizedName = parameter.LocalizedName;

  Each parameter's Type, default Value, Value (if it was set) and an attribute identifying whether a parameter is required can be accessed with:

  Type parameterType = parameter.Type;
  object defaultValue = parameter.DefaultValue;
  object parameterValue = parameter.Value;
  bool isRequired = parameter.IsRequired;

The information contained in WorkflowCommand and CommandParameter objects is enough to automatically create a form for each Command.

You may specify Command parameters for their further conveying to the process before Command execution. To do this, you may use the following methods of the WorkflowCommand object:

• Setting all parameters to default Values:

  command.SetAllParametersToDefault();

• Setting one parameter to a default Value:

  command.SetParameterToDefault("ParameterName");

• Setting a parameter to an arbitrary Value:

  command.SetParameter("ParameterName", parameterValue);

• Validating whether Command parameters are required and belong to the corresponding type:

  string errorMessage;
  bool isValid = command.Validate(out errorMessage);

After parameters have been set in a Command (if it is required), the Command may be conveyed to the WorkflowRuntime object for further execution:

WorkflowInit.Runtime.ExecuteCommand(command, identityId, impersonatedIdentityId);

If the parameters conveyed in a Command have Purpose = Persistence, they will be saved in the database. As for Temporary Parameters, they will be available till the end of the transition process, i.e. until process execution stops.

Implicit parameters and commands

If you do not generate forms using information on command parameters, then you do not need to describe these parameters. It means that the command's Input Parameters section can be empty, but you still can convey parameters to the process through it. Here's how it works. Say you are trying to convey a parameter with the "ParameterName" name to the process through a command.

• If the parameter with the "ParameterName" name is found in the Input Parameters section of the command, then the information specified in that section is used.
• If the parameter with the "ParameterName" name is found in the Parameters section of scheme, then the information specified in that section is used. It shall be defined that this parameter is Temporary or Persistence.
• If the parameter with the "ParameterName" name is not found either in the Parameters section or in the Input Parameters section of the respective command, then the parameter will be conveyed to the process as Temporary.