Parameter edit form for Action, Condition or Rule

General information

Parameter which is transferred into Action, Condition or Rule can be a complex JSON object, that is why it might be useful to help user fill in this object. In the Workflow Engine you can specify a form which will be displayed in the designer when editing this parameter. There are two ways to describe this form:

• In case of Actions, created in the designer (Code Actions), you can describe the parameter form in the designer (i.e. in the scheme), or write a class implementing the IDesignerParameterFormatProvider interface and connect it to WorkflowRuntime on the server.
• On the other hand, Actions implemented through the Action provider or Rule provider you can use IDesignerParameterFormatProvider only.

Parameter edit form description in the designer

Parameter edit form window is called from the Code Actions in the Designer toolbar. Each described form is bound to the specific Code Action.

You can create fields of the following types:

• Text - string input field.
• Number - any number.
• Checkbox - checkbox field; if the field is non-required, the form will show a three state checkbox - checked, unchecked, undefined. If the field is required, the form will show a two state checkbox - checked, unchecked.
• Dropdown - field with a dropdown list to choose a value.
• Date/Time - date and time in the ISO 8601 format (for example, 2005-08-09T18:31:42).
• Json - any valid JSON.

You need to specify name for each field. You can mark the field as required, and the edit form will check if this field has been filled. You can also set value by default for each field.

Parameter edit form is opened upon clicking the Edit value in JSON button. If no parameter edit form has been specified for a certain Code Action, the JSON editor window will open. If it has been specified - the edit form will open.

You can always switch into the JSON editor from the edit form and edit parameter value in it.

Single value parameter

Sometimes the parameter transferred into Action, Condition or Rule is a single value, not a complex JSON (for example, number, string, true or false). In this case, the parameter input form must consist of a single nameless field to be created.

Then, there will be a single nameless parameter in the parameter edit form. Parameter value will be single, not a JSON object.

Parameter edit form description on the server - IDesignerParameterFormatProvider

If you don't want to create parameter forms in the designer or if your Actions, Conditions or Rules are defined on the server, you can write server code that will specify parameter edit forms appearance displayed in the Designer.

• Write a class implementing the IDesignerParameterFormatProvider interface, for example:

  public class DesignerParameterFormatProvider : IDesignerParameterFormatProvider
  {
      public List<CodeActionParameterDefinition> GetFormat(CodeActionType type, string name)
      {
          if (type == CodeActionType.Action && name == "UpdateTransitionHistory")
          {
              return new List<CodeActionParameterDefinition>()
              {
                  new CodeActionParameterDefinition
                  {
                      DefaultValue = "Some text",
                      IsRequired = true,
                      Name = "TextParameter",
                      Title = "Text parameter",  
                      Type = ParameterType.Text
                  },
                  new CodeActionParameterDefinition
                  {
                      DefaultValue = "12",
                      IsRequired = false,
                      Name = "NumberParameter",
                      Title = "Number parameter",  
                      Type = ParameterType.Number
                  },
                  new CodeActionParameterDefinition
                  {
                      DefaultValue = "true",
                      IsRequired = true,
                      Name = "BooleanParameter",
                      Title = "Boolean parameter", 
                      Type = ParameterType.Checkbox
                  },
                  new CodeActionParameterDefinition
                  {
                      DefaultValue = "Value1",
                      IsRequired = false,
                      Name = "DropdownParameter",
                      Title = "Dropdown parameter",  
                      Type = ParameterType.Dropdown,
                      DropdownValues = new List<DropdownValue>
                      {
                          new DropdownValue
                          {
                              Name = "Name1",
                              Title = "Title1",  
                              Value = "Value1"
                          },
                          new DropdownValue
                          {
                              Name = "Name2",
                              Title = "Title2",  
                              Value = "Value2"
                          }
                      }
                  },
                  new CodeActionParameterDefinition
                  {
                      DefaultValue = "2018-11-30",
                      IsRequired = true,
                      Name = "DateParameter",
                      Title = "Date parameter",  
                      Type = ParameterType.DateTime
                  },
                  new CodeActionParameterDefinition
                  {
                      DefaultValue = "{property1: 100, property2: \"Some string\"}",
                      IsRequired = false,
                      Name = "JsonParameter",
                      Title = "Json parameter",  
                      Type = ParameterType.Json
                  },
              };
          }
          
          return null;
      }
  }

  This provider example thoroughly describes the form which we have created earlier. You need to implement one method only - GetFormat, which will have the following parameters in the input:

  • type - enumeration, which defines a scheme element the parameter edit form is called for (possible values - RuleGet, Action or Condition).
  • name - Action, Condition or Rule name parameter edit form is called for. This form will be displayed only if you have chosen the * UpdateTransitionHistory* Action. Method must return a list of fields for the form which will be displayed in the Designer for parameter editing. The code above covers all types of form fields.

• Specify your Parameter format provider when configuring WorkflowRuntime as follows:

  runtime.WithDesignerParameterFormatProvider(new DesignerParameterFormatProvider());

Substitutions

The parameter value for Action, Action-Condition, Code Action or Rule is always JSON. Even if a form is used to edit this parameter, it is still JSON. In the JSON, the process parameter values can be substituted. The syntax of substitutions is very similar to the syntax of expressions.

• @ParameterName - the easiest option, the parameter value named 'parameterName' is substituted from the process. String conversion is done with a simple call of .ToString().
• @ObjectParameter.ObjectProperty.StringProperty - partial parameters can be used in the expression. That is, if you have a complex, multi-level object stored in the parameter, you can substitute a part of this object.
• @ParameterName:formatString - expression with a format string. A string formatted according to the formatString template is substituted using the format syntax for the .NET platform. Please, for more details see here.
• @(ParameterName:formatString) - if different special characters and delimiters are used in the format string, you must additionally enclose the expression in round brackets.
• @ObjectParameter.ObjectProperty.IntProperty:json - special formatting when a JSON is used as the JSON value of the action parameter.

Below some examples are provided to illustrate substitutions.

Suppose, an object named 'Document' is saved in the process parameters in the following form:

var Document = new {
    Amount = 42,
    Name = "Some Document",
    Number = 142,
    CreateDate = DateTime.Today // 17-06-2020
};

The JSON parameter value is:

{
  Amount: "@Document.Amount:json", // we need it here
  Number: "@Document.Number", // we set in here
  Title: "@Document.Name number @Document.Number year @Document.Date:yyyy month @Document.Date:MM day @Document.Date:dd"
}

Then, we get the resulting JSON after the substitution.

{
  Amount: 42,
  Number: "142",
  Title: "Some Document number 142 year 2020 month 06 day 17"
}