The Command Option

Overview

The Command Option defines an action that finalizes/completes the instance defined by its containing activity. This action may result in the completion of the entire process (instance) to which the activity belongs, referred to as archiving, or may result in the creation of more activity instances.

Unlike other Processware objects, Command Options are always grouped by (and therefore accessible through) a special Object Group referred to as the trigger group. Command Options can therefore not be explicitly grouped. The Command Option selected, will have its VBScript executed; all other Command Options on the same activity will be ignored. The selected Command Option will also be persisted, while others on the same activity will not be persisted – the absence of a persisted Command Option therefore becomes an indication that it was not selected.

Properties

Command Options support the following properties:

Attributes - Options

DisableRequiredFieldValidation

A Boolean value instructing the runtime engine on whether to perform its default required-field-validation assertions, disallowing the associated activity from completing if any of the empty objects on it are configured as requiring values. This is useful in scenarios where an activity is "saved", for completion at a later stage. The default value is False.

How do I get the DisableRequiredFieldValidation value of a Command Option

Using C#:

var optionsValue = control.DisableRequiredFieldValidation;

Via VBScript:

optionValue = control.Options.Item("DisableRequiredFieldValidation")

How do I set the DisableRequiredFieldValidation value of a Command Option

Using C#:

control.DisableRequiredFieldValidation = false;

Via VBScript:

control.Options.Item("DisableRequiredFieldValidation") = "True"

Caution

The value assigned (as it relates to VBScript) must be a string value (enclosed with double quotes) and not the more natural Boolean equivalent as the latter can sometimes be incorrectly translated (due to localization/globalization).

In both cases the Command Option is referenced as described in the sections Reference a Command Control and Reference a Command Option for Managed Code and VBScript, respectively.

Behavior

Type

The type associated with the Command Option; this value is typically set on dragging-and-dropping a specific object.

How do I get the Type of a Command Option

Using Managed Code:

The type of a control in Managed Code is implicit (based on the control hierarchy), and in the case of a Command Option the target control type is CommandControl.

Via VBScript:

controlType = control.Type

Where the Command Option is referenced as described in the sections Reference a Command Control and Reference a Command Option for Managed Code and VBScript, respectively.

Column - Obsolete

This property played a role in the past, but has no effect anymore.

Business Intelligence

BI Node

A Boolean value indicating whether the values of the Command Option are to be included in Business Intelligence Tools (such as QlikView, etc.). The default value is False.

BI Caption

An (optional) short text based description associated with, and overriding the default Caption for, the Command Option in Business Intelligence Tools. Either captions are only included with all the object’s values based on the BI Node value for the object (as mentioned earlier).

Content Definition

Trigger

The VBScript script to be executed at runtime as associated with the Command Option.

Identification

ID

Displays the (read-only) numeric identifier of the Command Option.

How do I get the ID of a Command Option

Using C#:

var id = control.Id;

Via VBScript:

id = control.ID

Where the Command Option is referenced as described in the sections Reference a Command Control and Reference a Command Option for Managed Code and VBScript, respectively.

Parent

Displays the (read-only) numeric identifier of the activity containing (or parenting) the Command Option.

How do I get the ID of a Command Option’s parent activity in VBScript

By directly referencing its parent, as in:

id = fcBusinessEvent.EventID

Name

The unique (per activity name of the Command Option that can be used to reference the object at runtime (via VBScript). It is usually of the form ActivityNamePrefix_ObjectName, where ActivityNamePrefix usually denotes part of the activity name (and very often the activity's index in the process containing it). As an example, an object displaying the number of days some user has accrued for leave in an activity named LR10_ApplyForLeave (the first activity in a process called Leave Requisition) could be named LR10_NumberOfLeaveDaysAvailable.

How do I get the Name of a Command Option

Using C#:

var name = control.Name;

Via VBScript:

name = control.Name

Where the Command Option is referenced as described in the sections Reference a Command Control and Reference a Command Option for Managed Code and VBScript, respectively.

Note

The name cannot be changed.

Caption

The title (or short text description) describing the action represented by the Command Option.

How do I get the Caption of a Command Option

Using C#:

var caption = control.Caption.Text;

Via VBScript:

caption = control.DisplayName

How do I set the Caption of a Command Option

Using C#:

control.Caption.Text = "Control Caption";

Via VBScript:

control.DisplayName = "Object Caption"

In both cases the Command Option is referenced as described in the sections Reference a Command Control and Reference a Command Option for Managed Code and VBScript, respectively.

Tooltip Text

An optional narrative to be displayed by supporting clients to further describe the Command Option, its expected value and/or its intent in the activity.

How do I get the Tooltip Text of a Command Option

Using C#:

toolTipText = control.ToolTip.Text;

Via VBScript:

toolTipText = control.Description

How do I set the Tooltip Text of an Command Option

Using C#:

control.ToolTip.Text = "Some narrative describing the object’s intent.";

Via VBScript:

control.Description = "Some narrative describing the object’s intent."

In both cases the Command Option is referenced as described in the sections Reference a Command Control and Reference a Command Option for Managed Code and VBScript, respectively.

Index

A unique (per activity) integer value that, firstly orders the script execution of the current object relative to all the other objects on the same activity (as in the script on object with index i will always be executed prior to the script on the succeeding object with index i+1), and secondly orders the rendering of all the Command Options by a client (Command Option with index i will be rendered before a Command Option with index i+1, assuming both are visible).

How do I get the Index of a Command Option

Using C#:

using FlowCentric.Engine.Entities.Classic;
//...
var index = Extensions.GetIndex(control);
// or
var index = control.GetIndex();

Via VBScript:

index = control.Index

How do I set the Index of a Command Option

using FlowCentric.Engine.Entities.Classic;
//...
Extensions.SetIndex(control, 130);
// or
control.SetIndex(130);

Via VBScript:

control.Index = 130

In both cases the Command Option is referenced as described in the sections Reference a Command Control and Reference a Command Option for Managed Code and VBScript, respectively.

Warning

Object indexes must be unique within the activity, that is, two objects are not allowed to have the same index – this will result in runtime errors.

How do I (using Managed Code (.NET))

The class hierarchy in Managed Code, as it pertains to Command Controls, is shown here:

Reference a Command Control

Managed code implementations of Processware activities must extend the type FlowCentric.Engine.Managed.TaskForm (located in the FlowCentric.Engine.Contracts assembly) to be considered by the engine for execution. This base type provides a single method for accessing (un-grouped/normal) controls, with the following signature:

protected TControl GetControl<TControl>(string controlName) where TControl : Control;

and in VB.NET

Protected Function GetControl(Of TControl As Control)(controlName As String) As TControl

Accessing a Command Control from within a sub-TaskForm is accomplished with

var control = base.GetControl<CommandControl)("NameOfControl");

Retrieve the value of a Command Control

From within the same activity implementation (TaskForm)

To retrieve the value of a normal/un-grouped control, simply access it's Selected property, as in:

selectedValue = control.Selected;

The specific control is retrieved as is illustrated in the preceding section.

From within a subsequent activity implementation (TaskForm)

To access the value of a control within a subsequent TaskForm, the specific control needs to be located from history. This requires looking up the specific TaskForm, and from it the specific control. Translating the aObjects construct requires finding the first such TaskForm instance in the branch originating from the current TaskForm implementation (and ending in the first activity that started the associated process instance):

var task = context.FirstParentOfCurrent(parent =>
    StringComparer.Ordinal.Equals(parent.Name, "SomePrecedingTaskName"));

Where context is one of the FormXXXContext parameters from an appropriately overridden TaskForm method.

The value of a preceding Command Control is accessed as follows:

// Locate the field of interest:
var field = task?.Fields.OfType<IImmutableField>().FirstOrDefault(f =>
    StringComparer.Ordinal.Equals(f.Name, "ControlName"));
// Get it's value:
var textValue = field?.Value;

Set the value of a Command Control

To set the value of a normal/un-grouped control, simply access it's Selected property, as in:

control.Selected = true;

The specific control is retrieved as is illustrated in a preceding section.

Visibility of a Command Control

Unlike the other Processware objects, there is no Visible property that can be modified at design time, but it is possible to show and hide Command Controls in code.

How do I get the Visibility of a Command Control

optionValue = control.Visible;

How do I set the Visible value of a Command Option

control.Visible = true;

In both cases the control is retrieved as is illustrated in a preceding section.

How do I (in VBScript)

Reference a Command Option

To reference a Command Option, follow the hierarchy: current activity -> trigger Object Group -> Command Option, as in:

Set controlGroup = fcBusinessEvent.ObjectGroups.Item("-1")
Set control = controlGroup.Items("ObjectName")

Or simply

Set control = fcBusinessEvent.ObjectGroups.Item("-1").Items("ObjectName")

Visibility of a Command Option

Unlike the other Processware objects, there is no Visible property that can be modified at design time, but it is possible to show and hide Command Options via VBScript.

How do I get the Visible value of a Command Option?

optionValue = control.Options.Item("Visible")

How do I set the Visible value of a Command Option?

control.Options.Item("Visible") = "True"

Caution

The value assigned must be a string value (enclosed with double quotes) and not the more natural Boolean equivalent as the latter can sometimes be incorrectly translated (due to localization/globalization).

In both cases the Command Option is referenced as described in the section Reference a Command Option.

Property Compatibility Matrix

The following details the client support for the properties of Command Options