Understanding VidiFlow Contracts [VF 22.1 IG]

This chapter contains a draft concept of contracts and is subject to change without further notice.

VidiFlow often uses the term contract to describe an abstract input/output interface of a task. Currently, these tasks can be

Service Tasks
Workflows (see Workflow: Definitions, Instances)
Business Rules

ConfigPortal also provides contracts and stores them in its repository. These contracts add to those described in this section.

All contracts use a single, generalized JSON definition as a template, which is displayed below, to describe different tasks.
Please note that the following is not a valid JSON since it contains comments and line breaks for documentation purposes.

Task Contract Definition

{
"BriefDescription": "A brief description of the task.",

// An array of values categorizing this task contract.
// Used for filtering different sorts of tasks.
"Categories": [
"Category1",
"Category2"
],
"FullDescription": "The full description of the task.",

// A user friendly name used to display.
"FriendlyName": "A user friendly name used to display.",

// Shall contain an array of generic (globally defined) events that
// this task can emit. (FOR FUTURE USE)
"GenericOutputEvents": null,

// A GUID uniquely identifying the task contract independent of its version.
// Will be automatically generated!
"Guid": "82e6f018-3c25-43fb-9bed-23fa61d0b2cf",
"Name": "ContractName",

// This section describes all externally visible input parameters of a task.
"Parameters": [
{
// This array can be used to describe different values for various use
// case scenarios or enumerate possible values of the parameter.
// It is intended to be displayed in the workflow designer to provide
// helpful information for the user.
"Examples": [
"Example 1",
"Example 2"
],
"FullDescription": "The full description of the parameter.",
"Name": "ParameterName",

// Possible types are: 0 (string), 1 (bool), 2 (int), 3 (double), 4 (DateTime)
"Type": 0,

// The default value of an optional parameter (see below).
// The value is stored as a string and must be convertible to the
// parameter's type.
"DefaultValueAsString": null,

// Indicates if the parameter is optional, i.e. does have a default value
// when modeling the task in the workflow designer.
// An optional parameter must have a default value (see above).
"IsOptional": false
}
],

// This section describes all externally visible output results.
"Results": [
{
// This array can be used to describe different values for various use
// case scenarios or enumerate possible values of the parameter.
// It is intended to be displayed in the workflow designer to provide
// helpful information for the user.
"Examples": [ ],
"FullDescription": "The full description of the result parameter.",
"Name": "ResultName",
"Type": 0
}
],

// Shall contain an array of events specifically defined for this task that it can
// emit. (FOR FUTURE USE)
"SpecificOutputEvents": [ ],

// Possible contract types are: 0 (Agent), 1 (Workflow), 2 (BusinessRule)
"Type": 0,
"Version": "1.1",

// This section describes all parameters that are actually internally passed
// for the execution.
// It can contain additional parameters that are not externally visible,
// tuned parameters (e.g. Object URIs converted into physical URIs), etc..
"ProvisionedParameters": [
{
"Examples": [ ],
"FullDescription": "The full description of the provisioned parameter.",
"Name": "ProvisionedParameterName1",
"Type": 2
},
{
"Examples": [ ],
"FullDescription": "The full description of the provisioned parameter.",
"Name": "ProvisionedParameterName2",
"Type": 0
}
],

// This section describes the result parameters that are internally
// given back after execution.
"ProvisionedResults": [
{
"Examples": [ ],
"FullDescription": "The full description of the provisioned result parameter.",
"Name": "ProvisionedResultName",
"Type": 0
}
]
}

This definition can be separated into three main sections:

Contract identification (marked in red).
External input/output (marked in green).
Internal input/output (marked in blue).

Contract Identification

A contract is uniquely identified by the triple of Type, Name and Version. Type specifies whether it is a contract for a Service Task (aka Agent), Workflow or Business Rule. Name is the name of the contract and Version its version in the format of major.minor.
Please note that the distinction by minor version is currently not supported. It must always be 0 (zero).

External Input/Output

This section describes what the input and output of the task is. This is the set of parameters that must be provided / will be received by the module that triggers the task execution.
All (input) parameters and (output) results are defined by a Type and Name.
An input parameter can also be declared optional, i.e. it is not necessary to specify a value for this parameter when triggering the task executing. Instead, the task will be executed using the (in this case mandatory) default value specified in the contract.

Internal Input/Output

This set of parameters provides a special functionality (called "provisioning") for task contracts of the type "Agent". It will not be covered in this document. For all other contract types this set of parameters is currently irrelevant.