Skip to content

Service Configuration

The configuration object (below) is probably the most important part to consider in the development of a new service compatible with I3HUB. As you can see, this contains several fields, some of which have been reduced for simplicity.

 {
    "name": "unique_name",
    "label": "My New Service",
    "description": "Description of the service",
    "type": "full",
    "image": "path/to/an/image.png",
    "configuration": {
      "serviceConfiguration": { ... },
      "subjectConfiguration": { ... },
      "activitiesConfiguration": { ... },
      "sessionConfiguration": { ... }
    },
  }
}

Remember that this object is requested with the format application/json within the specified endpoint here. This endpoint is called several times by the MetaService in order to always have updated information on the configuration, since the information can change over time.

For example, activities within an application can be configurable and new types of activities can be created. This means that the content of the configuration.activitiesConfiguration field must not be static, but obtained dynamically (from a database, for example).

Main Attributes

name

REQUIRED

The name under which the application is viewed by I3HUB. Although it is not necessary to define a unique name for the single application, it is recommended to have greater clarity of the logs that are generated later.

Name format

The name must be written in lowercase following the snake notation and therefore must not contain spaces.

label

REQUIRED

The label is the field that shows the name of the service read by the system user.

Label format

The label can also be written using spaces and other characters within UTF-8. (pls, no emoji)

description

OPTIONAL
DEFAULT null

The description is the field that shows more information about the service and is read by the system user.

Description format

The description can also be written using spaces and other characters within UTF-8. (pls, no emoji)

type

OPTIONAL
DEFAULT "full"

TBD.

image

OPTIONAL
DEFAULT null

The information contained in the "image" field must be a valid path leading to a file in a format readable by the background-image attribute of an HTML element (JPEG, PNG, SVG, base64...).

configuration

REQUIRED

The configuration field is the most complex, as it contains all the information on how to run the service, on what activities it contains and how the session activities should be managed by I3HUB. Given its complexity, each subsection is discussed in detail below.

Configuration Details

Service configuration

The serviceConfiguration field contains the basic information needed by I3HUB to understand how to contact the service. Here are the parameters:

"serviceConfiguration": { 
    "hasActivities": true, // Boolean
    "hasConfigurableActivities": false, // Boolean
    "serviceUrl": "https://path.to.service/host", // String
},

All the fields below are mandatory.

  • hasActivities specifies whether the service has selectable activities, or the service itself is the executable activity. When you want to have a service with configurable activities, the approach of setting this field to true and inserting a single activity with configurable fields is always recommended

  • hasConfigurableActivities specifies whether there are any activities that can be configured for later use. This type of configurability is different than the live mode and will both be discussed in the activity configuration section.

  • serviceUrl specifies the service's URL. Although this parameter is entered manually the first time the service is registered within the MetaService, it is requested here to give the possibility to dynamically change the location of the service (ex. The service is moved to the cloud or on a different platform and having a different URL). This parameter always overrides the URL with which the service is inserted into the MetaService.

Subject configuration

Some applications might require user data which are usually not entered during registration, as they are not mandatory data. This could lead to limitations in some applications, and to avoid these cases the subject configuration field is provided.

An example that shows the structure of the subject Configuration object is shown below. Suppose that the custom service we want to use needs to pass information about the user to a virtual reality viewer. To understand at what height to place the user's gaze, it is necessary to know the user's physical height. This data will be entered in configuration.subjectConfiguration to be asked at start-up (if mandatory and not entered) by the therapist.

The structure of this object is as follows:

"subjectConfiguration": {
    "isMandatory": false, // Boolean
    "manifest": {
        "id": "/service_name.subject",
        "type": "object",
        "properties": {
            "other": {
                "label": "Height",
                "description": "Height of the user",
                "type": "number",
                "default": 100,
            }
        }
    }
}
  • isMandatory defines if the configuration is required to continue with the activity or if it is optional
  • manifest this object is used to inform I3HUB of how the fields that it will have to request from the user are structured. It is important to note that the structure of this object follows the convention of the JSON Schema and is validated with it. Since the format is also used in other parts of the structure, a more accurate description of the format (with the types of attributes that can be used) is discussed separately.

Activities configuration

Activities are a fundamental part of the service we are going to create, and we want to be sure that they can be interpreted correctly by I3HUB in order to be able to modify and use them.

The structure of this object is the following:

"activitiesConfiguration": {
    "activities": [
        {
            "name": "activity_name",
            "label": "Activity Name",
            "description": "Description of the activity",
            "image": "path/to/an/image.png",
            "isConfigurable": true,
            "type": "live",
            "children": [],
            "manifest": {
                "id": "/service_name.activities.activity_name",
                "type": "object",
                "required": ["audio"],
                "properties": {
                "audio": {
                    "label": "Audio played",
                    "description": "The audio to be played",
                    "inputType": "select",
                    "type": "string",
                    "anyOf": [ ... ],
                },
                },
            },
            "configuration": {},
        },
    ],
}

  • name: The name under which the activity is viewed by I3HUB. Although it is not necessary to define a unique name for the single application, it is recommended to have greater clarity of the logs that are generated later. The format of this parameter is the following: myservice.activity_name. If you have nested activities, the format becomes: mysevice.activity_name.subactivity_name

  • label: this is the name that will be visualized in the i3hub platform by the users

  • description: this is the description that will be visualized in the i3hub platform by the users

  • image: must be a valid path leading to a file in a format readable by the background-image attribute of an HTML element

  • type: parameter that inform the system if the activity can be edited while starting a new session or if the default/already existing configuration is to be used. Actually, only live value is supported. Soon also the premade value will be implemented, allowing the user to store their personal activity configurations

  • isConfigurable: boolean parameter that determines if the application can be configurated by the user of the i3hub platform. This will work as intended in both the live and premade mode

Nested structure

The structure used to organize activities within a service is inspired by the hierarchical structure of a filesystem. This choice was made to allow greater flexibility and granularity in configuring the activities and to have an easy and intuitive visualization system. Formally we have two types of entities:

  • A group of activities
  • A single activity

The activity group is nothing more than a container of single activities or other groups of activities (like a folder). The single activity, on the other hand, is the "leaf" of this hierarchical tree.

To determine if a node is single or group, the children parameter is checked. If present and not empty, the node is a group activity.

Some examples of how this structure can be used efficiently are reported in the following Use Cases (UC):

In this project it was necessary to find a structure for activities which require the same configuration parameters but which have different devices to be used (virtual reality, telephone with recorder). The (simplified) structure in this case would be as follows:

- With Device (group)
    - Bar Activity (single)
    - Doctor Activity (single)
    - Party Activity (single)
    - Classroom Activity (single)
- Without Device (group)
    - Classroom with Microphone (single)
        - text (configuration)

By using the structure discussed so far we can translate the previous example in this (simplified not to become excessively verbose, contains only one example for each subcategory):

"activitiesConfiguration": {
    "activities": [
        {
            "name": "with_device",
            "label": "Activities with VR Device",
            "description": "This group contains only the activity playable with a VR device",
            "image": "path/to/an/image.png",
            "isConfigurable": true,
            "type": "live",
            "children": [
                // Omitted for brevity, look the example below
            ],
            "manifest": {},
            "configuration": {},
        },
        {
            "name": "without_device",
            "label": "Activities without any Device",
            "description": "This group contains the activity playable without devices",
            "image": "path/to/an/image.png",
            "isConfigurable": true,
            "type": "live",
            "children": [
                {
                    "name": "classroom_with_microphone",
                    "label": "Classroom with Microphone",
                    "description": "This activity is placed in a classroom environment and you have just a microphone",
                    "image": "path/to/an/image.png",
                    "isConfigurable": true,
                    "type": "live",
                    "manifest": {
                        "id": "/sip.activities.classroom_with_microphone",
                        "type": "object",
                        "required": ["text"],
                        "properties": {
                            "text": {
                                "label": "Text to say",
                                "description": "The text to be said with the microphoe",
                                "inputType": "select",
                                "type": "string",
                                "anyOf": [ ... ],
                            },
                        },
                    },
                    "configuration": {},
                },
            ],
            "manifest": {},
            "configuration": {},
        },
    ],
}

The Mars project needs to collect audio from recordings to analyze it in a later time. The type of activity is always the same and takes place in the same way. The only thing that changes is the configuration before starting. 

- Say it again (single)
    - audio (configuration)

Which can be translated in the following way

"activitiesConfiguration": {
    "activities": [
        {
            "name": "say_it_again",
            "label": "Say It Again",
            "description": "In this activity the user needs to repeat the audio proposed",
            "image": "path/to/an/image.png",
            "isConfigurable": true,
            "type": "live",
            "manifest": {
                "id": "/mars.activities.say_it_again",
                "type": "object",
                "required": ["text"],
                "properties": {
                    "audio": {
                        "label": "Audio",
                        "description": "The audio to be repeated",
                        "inputType": "select",
                        "type": "string",
                        "anyOf": [ ... ],
                    },
                },
            },
            "configuration": {},
        },
    ],
}

Manifest

The manifest represents the object within an activity that specifies its configuration template. This object was created to allow I3HUB to interpret the parameters and generate a suitable configuration form.

Once selected, parameters are passed to the configuration of the object, discussed below.

The manifest must be expressed following the JSON Schema convention to be interpreted correctly. Currently supported types are as follows:

  • input string (type: string)
  • multiple choice string (type: array of strings)

Other types will be added later or if necessary (contact us by email in case).

Below an example of this notation:

  • inputType: text
  • type: string

In this example we want to be able to insert a custom string:

manifest: {
    "id": "/service_name.activities.activity_name",
    "type": "object",
    "required": ["mychoice"],
    "properties": {
        "mychoice": {
            "label": "Property name",
            "description": "Property description",
            "inputType": "text",
            "type": "string",
        },
    },
},
  • inputType: select
  • type: string

In this example we want to be able to select multiple strings:

manifest: {
    "id": "/service_name.activities.activity_name",
    "type": "object",
    "required": ["mychoice"],
    "properties": {
        "mychoice": {
            "label": "Property name",
            "description": "Property description",
            "inputType": "select",
            "type": "string",
            "anyOf": [
                {
                    "const": "value1",
                    "label": "Label for the first value"
                },
                {
                    "const": "value2",
                    "label": "Label for the second value"
                },
            ],
        },
    },
},

Note that the const fields contain the actual value that will be used, while thelabel field is the field shown to the user.

Configuration

Each activity can have one or more configuration parameters. From now configuration will be the name for this set of parameters. When an activity is configurable, before starting it, the user must fill in all the fields present in its configuration, that are all the fields inserted in the manifest.

An activity can already have a default configuration. In this case the configuration field of an activity will appear to the user already filled in. Alternatively, it is also possible to use the default field in the properties of the manifest, following the appropriate conventions.

In this example we want to insert a custom string

configuration: {
    "mychoice": "String inserted by the user"
},

In this example we want to select multiple strings

configuration: {
    "mychoice": ["value1", "value2"]
},

In this case, for example, both values have been selected.

Session configuration

The session configuration field is necessary to communicate to I3HUB how to manage the launch and execution of the sessions of the individual services.

Subject to change

Since this field deals with managing cases that have not been contemplated, it could undergo changes in the convention with which it is expressed.

Below we define the main fields:

Live Session

This field is used to define the behavior of I3HUB when starting a new session for the selected service. 

{
"sessionConfiguration": {
    "liveSessionConfiguration": {
        "payloadThrough": "frontend",
        "livePath": "/",
        "lockControls": false,
    },
}

Here is an explanation for the fields:

  • payloadThrough: Defines how the payload is passed to the custom service. The possible options are frontend orbackend. In the first case, the payload will be inserted into the localStorage of the application frontend and will be usable when starting the main screen. The main screen is the one defined in the next point
  • livePath: It defines the path of the custom service with respect to the url with which it was registered. For example, if the page "consuming" the payload is session.html, thelivePath will have the value / session.html.
  • lockControl: It is used to know if I3HUB must block the possible user interactions during the activity (accidental page reload etc.)

Post Session

This field has yet to be defined, based on the structure of the sessions that will be saved.

Back to top