Conditions¶

Conditions define a set of specifications for evaluating parameter values. The specifications support complex interdependency checking such as relationships between multiple parameters (i.e. Valid values for parameter one depend upon the value of parameter two). Here is the Conditions Schema

Documentation containing examples of the following conditions for the different supported controls are available at: https://elyra-canvas-test-harness.u20youmx4sm.us-south.codeengine.appdomain.cloud/#/conditions

A conditions file contains an array of conditions. Each condition takes one of the following forms:

Validation definition¶

A single validation. The fail_message is displayed upon validation failure.

The attributes for the validation definition are:

id (string) A unique identifier for the validation. This is required if multiple validations have the same focus_parameter_ref value.
fail_message (object) Required The message to display if the validation fails. Each fail_message consist of the following attributes
- message (object) Required The message to display.
  - See Resource Definition
- focus_parameter_ref (string) Required The parameter control to get focus after displaying the error/warning. If the validation refers to a table cell, then control must have the column indicator. For example if the validation is for MyTable cell column 2 then MyTable[2].
- type (string) Type of messages. Valid values are error, warning, info.
evaluate (object) Specification for how to evaluate the validity of the parameter. The evaluate attribute can be one of the following structures.
- condition (object) This is a single condition that evaluates to true or false.
  - op (string) Required A single operator for the properties of the condition. Valid values are: isEmpty, isNotEmpty, greaterThan, lessThan, equals, notEquals, matches, notMatches, contains, notContains, colNotExists, isDateTime, dmTypeEquals, dmTypeNotEquals, dmMeasurementEquals, dmMeasurementNotEquals, dmRoleEquals, dmRoleNotEquals lengthEquals, lengthGreaterThan, lengthLessThan.
- parameter_ref (string) Required The primary parameter.
- parameter_2_ref (string) Second parameter for multi-parameter validation.
- value (string, boolean, number) Value against which to compare the primary parameter value.
- values (array[string]) Values against which to compare the primary parameter value is in. Used only in filter conditions.
or (object) This is a container of ‘or’ conditions. Evaluates to true if ANY sub-condition evaluates to true. Can nest any number of additional conditional types.
and (object) This is a container of ‘and’ conditions. Evaluates to true if ALL sub-condition evaluates to true. Can nest any number of additional conditional types.

Enabled definition¶

Enablement test. Disables controls if evaluate is false.

The attributes for the enabled definition are:

parameter_refs (array[string]) Array of parameter names affected by this operation. If evaluate is false, then the controls associated with these parameters are disabled. Note that individual radio buttons can be disabled by using the radio button value name instead of the overall property name in the parameter_refs array.
action_refs (array[string]) Array of action names affected by this operation. If evaluate is false, then the action button or image associated with these action names are disabled.
evaluate (object) see the evaluate attribute in validation definition.

Visible definition¶

Visibility test. Hides controls if evaluate is false.

The attributes for the visible definition are:

parameter_refs (array[string]) Array of parameter names affected by this operation. If evaluate is false, then hide the controls associated with these parameters.
action_refs (array[string]) Array of action names affected by this operation. If evaluate is false, then the action button or image associated with these action names are disabled.
evaluate (object) see the evaluate attribute in validation definition.

Filter definition¶

Filter test. The filter will determine which data record fields to include in a control.

The attributes for the filter definition are:

parameter_ref (string) Parameter id affected by this operation. This must be a parameter that operates upon datarecord-metadata columns.
parameter_refs (string) Exclusive with parameter_ref and used with dmSharedFields. Parameter ids affected by this operation. They must be parameters that operate upon datarecord-metadata columns.
evaluate (object) see the evaluate attribute in validation definition.

Supported operations (op):

dmType - filters type value from schema.
dmMeasurement - filters measurement value from schema.
dmModelingRole - filters modeling_role value from schema.
dmSharedFields - shares source fields with all field chooser property names found in the parameter_refs array.

Examples:

{
  "filter": {
    "parameter_ref": "fields_filter_measurement",
    "evaluate": {
      "condition": {
        "op": "dmMeasurement",
        "value": "discrete"
      }
    }
  }
}

{
  "filter": {
    "parameter_ref": "fields_filter_type",
    "evaluate": {
      "condition": {
        "op": "dmType",
        "values": ["integer", "double"]
      }
    }
  }
}

{
  "filter": {
    "parameter_refs": [
       "fields_filter_type",
       "multi_field_chooser_table",
       "field_chooser_in_another_panel"
    ],
    "evaluate": {
      "condition": {
        "op": "dmSharedFields"
      }
    }
  }
}

Enum Filter definition¶

Filters the available options for enumeration parameters. Reduces the available enumeration items if evaluate is true.

The attributes for the enum_filter definition are:

target (object) Contains a target parameter_ref reference and a replacement values array.
evaluate (object) see the evaluate attribute in validation definition.

Example:

{
  "enum_filter": {
    "target": {
      "parameter_ref": "radioset_filtered",
      "values": [
        "red",
        "yellow",
        "green"
      ]
    },
    "evaluate": {
      "condition": {
        "parameter_ref": "filter_radios",
        "op": "equals",
        "value": true
    }
  }
}

Allow Change definition¶

Allow change validates that a change is allowed on a property. If it evaluates to true then the value for the property is changed. This is typically used to restrict values that are invalid in one property based on the value in another property. For example, if the property represents a storage type with a value of string, then a property that represents a measurement type should not be allowed to be set to continuous.

The attributes for the allow_change definition are:

parameter_refs (array[string]) Array of parameter names affected by this operation.
evaluate (object) see the evaluate attribute in validation definition.

Example:

{
      "allow_change": {
        "parameter_refs": [
          "ST_mse_table[2]"
        ],
        "evaluate": {
          "or": [
            {
              "condition": {
                "parameter_ref": "ST_mse_table[2]",
                "op": "notEquals",
                "value": "Football"
              }
            },
            {
              "condition": {
                "parameter_ref": "ST_mse_table[5]",
                "op": "notEquals",
                "value": "European"
              }
            }
          ]
        }
      }
    }

Default value definition¶

Sets the default value on the parameter_ref property if condition evaluates to true. If multiple conditions evaluate to true only the first condition is used. Default value condition is evaluated only once when loading properties. If user updates the value of parameter_ref, default value will be overwritten by the new value.

The attributes for the default_value definition are:

parameter_ref (string) Parameter whose default value is to be set.
value (string, boolean, number, object, array) This will be the default value of parameter_ref if condition evaluates to true.
evaluate (object) see the evaluate attribute in validation definition.

Example:

{
  "default_value": {
    "parameter_ref": "conditional_default",
    "value": "Value defined in default_value condition. You will see this sentence when default value of mode equals Include.",
    "evaluate": {
      "condition": {
        "parameter_ref": "mode",
        "op": "equals",
        "value": "Include"
      }
    }
  }
},
{
  "default_value": {
    "parameter_ref": "conditional_default",
    "value": ["This is a second condition for conditional_default. You should never see this value."],
    "evaluate": {
      "condition": {
        "parameter_ref": "mode",
        "op": "equals",
        "value": "Include"
      }
    }
  }
}

A note on table cell conditions¶

Support for table cell conditions is achieved via the use of the array subscript operator, []. When evaluating table cells, one uses the table identifier with an array subscript indicating the zero-based table column being operated upon (which also corresponds to the sub-control index as defined in complex_types).

So for example if one has a StructureTable property named myTable, column conditions on that table are referred to using myTable[1], myTable[3], etc.

Example¶

Example of a condition section.

  "conditions": [
      {
        "validation": {
          "fail_message": {
            "type": "error",
            "focus_parameter_ref": "inputFieldList",
            "message": {
              "resource_key": "input_field_list_not_empty"
            }
          },
          "evaluate": {
            "condition": {
              "parameter_ref": "inputFieldList",
              "op": "isNotEmpty"
            }
          }
        }
      },
      {
    "visible": {
      "parameter_refs": [
         "oneofselectPets"
      ],
      "evaluate": {
         "condition": {
            "parameter_ref": "oneofselectAnimals",
        "op": "notContains",
        "value": "lion"
          }
      }
    }
      },
     {
    "visible": {
      "action_refs": [
         "action_button"
      ],
      "evaluate": {
         "condition": {
            "parameter_ref": "button_hide_checkbox",
        "op": "equals",
        "value": false
          }
      }
    }
      },
      {
    "enabled": {
      "parameter_refs": [
        "radiosetColor"
      ],
      "evaluate": {
        "condition": {
          "parameter_ref": "checkboxEnable",
          "op": "checked"
            }
      }
    }
      },
      {
    "validation": {
      "fail_message": {
        "type": "error",
        "focus_parameter_ref": "subsamplingRate",
        "message": {
          "resource_key": "subsampling_rate_not_valid"
        }
      },
      "evaluate": {
        "and": [
          {
            "condition": {
              "parameter_ref": "subsamplingRate",
              "op": "greaterThan",
              "value": 0
            }
          },
          {
            "or": [
              {
                "condition": {
                  "parameter_ref": "subsamplingRate",
                  "op": "lessThan",
                  "value": 1
                }
              },
              {
                "condition": {
                  "parameter_ref": "subsamplingRate",
                  "op": "equals",
                  "value": 1
                }
              }
            ]
          }
        ]
      }
    }
      },
      {
    "enabled": {
      "parameter_refs": [
        "field_types[2]"
      ],
      "evaluate": {
        "condition": {
          "parameter_ref": "field_types[1]",
          "op": "checked"
        }
      }
    }
      }
    }
  ]