Capability Description, Parsing and Execution

Capability-based Execution: Overview

Capability Process Overview

Four important roles/stakeholders:

Capability Maker (Human): programmer who creates the capability for a Machine

Process Creator (Human): programmer that uses the capability and writes code for it (e.g. in a Script Task)

Deployment Decider (Software): analyses all available capabilities of every reachable Process Engine and decides where to deploy the process (due to the required Capabilities for the next process steps)

Capability Executor (Software): during process execution translates the abstract call of a Capability to the local implementation of the capability

Step 1: Capability Description

What is needed to be described:

Inside the Semantic Description Example Does the Process Creator or Deployment Decider need to know this information for calling and finding the correct capability? (Otherwise it can be used for Capability Executor)
Kind of Capability https://schema.org/PhotographAction X
File Name index.js
Function Name takePhoto()
Parameter and Return Values
Type of Parameter Input List, Array, Object
takePhoto( width, height )
takePhoto( { width: ..., height: ...} )
takePhoto( [width, height] )
(depends on the definition of the capability call for the implementer, the executor can translate this information)
Kind of Value https://schema.org/width
https://schema.org/height		 X
Parameter/Property Name w, h
Data Type simple xsd:string and complex, e.g. objects(how ?) X
Unit RGB, HSL, HEX, px, cm, pt, ... X
Encoding jpg, base64, xml, json X (if it not given, it means there is no special encoding and the implementer doesn’t need to know it for working with the value. E.g. a name can be a normal string. But a picture can have the datatype xsd:string and an encoding in base64 – the implementer needs to know that for working with the picture )
Default Value 43 X
Optional or Required width is required for this PhotoAction to be executed X
Additional Validations minlength, maxlength, size, pattern, ... X

Different Capability Descriptions for the Process Creator and the Capability Executor

  • The Capability Executor translates the semantic call (written by the Process Creator with the defined function, e.g. startCapability( <KindOfCapability>, [<{Parameter-Object}>] )) to execute the capability
  • therefore the Capability Executor needs some more information than the Process Creator
    • but this additional information is mostly even optional, because todays programming languages can be very flexible and it depends how the capability is exactly implemeted and called
    • e.g. JS Modules can export only one function, so the Function Name is not always needed
    • e.g. depending on the Type of Parameter Input there could be a fixed sequence of parameters, e.g. the first one is always width. But as part of an objects property, it is usually necessary to know the _Parameter Name

How to describe a Capability (Capability Maker)

All the capability descriptions have the following components: kind of capability, function name, parameter and return values, type of parameter input (if the parameter does not have a primitive type, the complex type is used), kind of Value, data type, unit, encoding, default value, optional or required and additional validations.

The capability.jsonld is a valid JSON-LD file, which is installed with the capability on the Machine. It has the following format: After defining some prefixes for the used vocabularies inside @context, it uses the @graph Graph Notation of JSON-LD to describe multiple components (also called “nodes”) independently of each other. Each component describes a different aspect of the capability such as parameters, function call or implemetation.

In JSON-LD @id keyword is used to uniquely identify concepts/things (which are IRIs) about which the JSON-LD document can make statements. This is an important aspect of linked data, because with a unique id you are able to identify a semantic description. (E.g. schema.org/PhotographAction for identifying the concept of taking a photo.)

In PROCEED a capability is installed on multiple machines, and we want to describe that after installation the Machine now has a specific capability. The problem is at the time we create the semantic capability description, we don’t know yet on which Machine the capability will be installed on. So we use a blank node identifier to make the statement that the capability is installed on a unknown Machine. A blank node syntactically starts the id with _:. (After installation the Machine could replace this id with an id uniquely identifying the Machine - but we don’t do that and it’s not necessary.)

Every other node in the @graph also has no IRI, but they are specified as blank nodes. (Actually the creator of the capability could specify an IRI.) As you can see in the examples, the nodes often reference each other by using this blank node identifiers.

A description of a capability first needs to state the type of action. In order to describe it, Schema.org offers a useful keyword potentialAction which “indicates a potential Action, which describes an idealized action in which this thing would play an ‘object’ role”. You can find a list of directly supported Actions on Schema.org. If there is no fitting keyword, you can use other ontologies.

When creating a capability it it can be useful to first look at the existing capability descriptions inside the (PROCEED) network. If there is a similar one, the only adaptations for the Capability Maker to make are for the function implementation description.

After having stated what kind of capability is described, you need to describe the calling and implementation of it on the machine. The Function Ontology uses expects keyword in order to describe the parameter descriptions. Therefore in the semantic description, the universal identifier of the parameter names are used and the function parameters are described in another component of @graph. So all in all, the semantic description does the following: If the function expects for instance schema:height, which means that the function expects The height of the item. and the height of the item is used as h in the function implementation.

If the function does not require any parameter or does not return anything, for the sake of the structure the keywords fno:returns or fno:expects are still included and return an empty object.

Examples and Use Cases

PhotographAction Capability
Turn On Green/Red Light On Capability
PROCEED MotionSensor Capability
PROCEED PhotographAction Capability

Step 3: Sending the Capabilities (Optional Step)

Capability Process Overview

  • a compacted semantic description is sent. That means the description does not contain any local implementation details (which is only needed by an Engine to know how to execute the capability, see Table 1)
  • since a Machine can have multiple Capabilities installed, a consollidated list with all Capabilities is sent from the Machine
  • a valid JSON-LD description is sent

Step 4: Creating the process and writing the Script Tasks

see BPMN Script Task

For every created script task, that uses a capability in its code, an additional meta-data section is appended to the BPMN which contains a description of the required capabilities to run the script task. This is called the process capability description and is encoded in JSON-LD.

Step 5: Decide where to execute the the (next) Task

This decision is done by the Decider. Essentially it gets the compacted capability description of all capabilities of every engine in the network. It compares this description with the process capability description and finds out, which engine can run the needed capability.

(TODO: show example of process capability description)

Within this comparison step

  1. all the required parameters of the process description should be included in the required and optional parameters of the compacted capability description and
  2. all the required parameters of the compacted capability description should be included in the required and optional parameters of the process description

Step 6: Calling the Capability on an Engine

Capability Process Overview

  • the Capability Executor translates the call of the Capability in the Script Task to the local installed Capability function