Capability Content

Introduction

The content field of a capability is a json structure that defines:

What action is performed with this capability ("action")
What data is requested from the user to perform this action and how it is shown in the UI ("input")
What properties can be defined for a device that has this capability ("properties")
What events can be thrown when using the capability ("events")

In general a capability should be created by the module that has the capability (e.g. the recorder that performs this “Record” action). But there might be cases where it is useful to adapt the capabilities content. For example if there should be special hints or labels for an input parameter in the UI or if translations should be added.

To be able to do that without causing damage to the system, this page describes the parts of the capability content and the possibilities it offers to the administrator.

Example

For demonstration purpose find an example json here. The following chapters will describe the parts that can be found in it:

JSON

{
  "action": "Record",
  "input": {
    "targetPath": {
      "label": "Target Path",
      "hint": "The target path of the recording",
      "defaultValue": "DefaultPath",
      "type": "string",
      "optional": "true"
    },
    "boolValue": {
      "label": "[{\"Lang\":\"en_US\",\"Text\":\"A label\"},{\"Lang\":\"de_DE\",\"Text\":\"Eine Beschriftung\"}]",
      "defaultValue": "true",
      "type": "bool",
      "optional": "true"
    },
    "color": {
      "label": "Color",
      "hint": "Please select your favorite color.",
      "type": "enum",
      "optional": "true",
      "items": {
        "item0": {
          "label": "Blue",
          "value": "b"
        },
        "item1": {
          "label": "Red",
          "value": "r",
          "default": true
        },
        "item2": {
          "label": "Yellow",
          "value": "y"
        },
        "item3": {
          "label": "Green",
          "value": "g"
        }
      }
    }
  },
  "properties": {
    "nonBlockingProvisioningTime": {
      "type": "integer",
      "kind": "fix"
    }
  },
  "events": [
    "RecorderMock.fileCreated",
    "RecorderMock.recordingFailed",
    "RecorderMock.recordingStarted",
    "RecorderMock.recordingFinished"
  ]
}

Parts of the Content

Action

The action specifies what action is performed when this capability is used. This could for example be “Record”, “Switch” or “Workflow”.

Changing this can have high impact on the behavior of the whole system and thus should be avoided.

Input

The input area defines what information about an execution of the capability a user can or must hand over to the executing module. This could for example be a preset for a recorder or the path a recording is stored at.

The fields that are supported by the module are fix in most cases, but it might make sense for the administrator to change some parts of the fields definition, like it’s presentation in the UI or the values of a drop down field / enum.

The following values are configurable per field:

Name	Required?	Description	Possible Values / Examples
label	No	Caption of the field in the booking dialog. Can be a simple string, but also supports json strings defining translations for different languages. Optional (if not defined, the name of the field is taken as caption).	`"Target Path"` `"[{\"Lang\":\"en_US\",\"Text\":\"A label\"},{\"Lang\":\"de_DE\",\"Text\":\"Eine Beschriftung\"}]"`
hint	No	Tooltip that is shown when hovering over a field. Also shown in some input fields (e.g. for strings) if nothing is entered and no default value is defined. Can be a simple string, but also supports json strings defining translations for different languages. Optional.	`"Target Path"` `"[{\"Lang\":\"en_US\",\"Text\":\"A label\"},{\"Lang\":\"de_DE\",\"Text\":\"Eine Beschriftung\"}]"`
type	Yes	The type of the value. This affects the values possible as input and the input fields itself (e.g. there is a date and time picker for type “datetime”). All possible values are listed in the column to the right. Required.	`int` `integer` `long` `datetime` `double` `float` `bool` `enum` `string`
optional	No (“false” by default)	If set to “true”, the user can leave the field empty, otherwise he or she is required to enter a value.	`true` `false`
defaultValue	No	Value that is automatically written to the input field in the booking dialogue and can be changed by the user there.	Possible values depend on type, e.g. `"Any string"` (for type string) `"12.4"` (for type double or float) `"false"` (for type bool)
items	Yes for type “enum”, otherwise mustn’t be set	Contains a json structure with the enum’s possible values. They are shown in a drop down in UI. For each value, a name, a label and a value are defined. Besides that one of the items may have a property “default” set to “true”. By this, that value is the one that is selected automatically when creating a new booking. If none of the items has this property, the first is selected by default.	JSON `"items": { "item0": { "label": "Blue", "value": "b" }, "item1": { "label": "Red", "value": "r", "default": true }, "item2": { "label": "Yellow", "value": "y" }, "item3": { "label": "Green", "value": "g" }`

The interplay between "defaultvalue" and "optional" is not trivial. To lighten the decision what to configure, the following table shows the effects of the different combinations:

defaultValue	optional	behaviour
true	true	Field is prefilled with default value. User may delete the value and leave blank. Then, null is returned. Input is validated if not empty.
true	false/not given	Field is prefilled with default value. User can change the value. But it may not left blank. Input is validated.
false/not given	true	Field shows hint text. User may leave empty by intention. Then, null is returned. Input is validated if not empty.
false/not given	false/not given	Field shows hint text. User can change the value. But it may not left blank. Input is validated.

Properties

In Properties, the module defines what can or must be configured for a device or pool that should use this capability. For example it is possible to configure a provisioning time for most recorders, which is the time span the start command is sent to the actual device before the execution time.

Besides the name properties have a "type" (for example "string" or "int") and a "valueType" which is either "fix" or "runtime". The first one means, that the value can be configured at the pool/device, the latter means that the value is determined at runtime (currently not supported).

Events

In “events” all the events a device is able to throw are listed. This has only informational purpose, as editing it would have no effect on the events actually thrown. The events are brought in the system by the module.