Orchestrator REST API

15 minute read

Create and read entities

The Orchestrator REST API enables to create and read all the different kinds of Digital Twin entities described in Model section.

This API is available through a dedicated Swagger interface for each Clawdite instance. Furthermore, it is possible to generate API clients for several languages, such as Python, Java and JavaScript. The mentioned clients are already generated and available within each Clawdite instance and make it possible to interact with Clawdite’s Orchestrator from external components.

In the following a few examples on entities management via API clients will be provided. For mandatory entity attributes refer to the Model section.

Install the Orchestrator client dependencies

In order to use the generated API clients inside external components it is needed to correctly setup and install the dependencies. Note that you need a personal GitLab token for accessing the registries. In case you don’t have it please contact the project’s maintainers.

pip install orchestrator-python-client --index-url https://__token__:<your_personal_token>@gitlab-core.supsi.ch/api/v4/projects/86/packages/pypi/simple

<dependencies>
    <dependency>
      <groupId>ch.supsi.dti.isteps.hdt</groupId>
      <artifactId>orchestrator-java-client</artifactId>
      <version>x.y.z</version>
    </dependency>
</dependencies>

<repositories>
  <repository>
    <id>gitlab-maven</id>
    <url>https://gitlab-core.supsi.ch/api/v4/projects/86/packages/maven</url>
  </repository>
</repositories>

npm install orchestrator-javascript-client --registry https://token:<your_personal_token>@gitlab-core.supsi.ch/api/v4/projects/86/packages/npm/

Create a Factory

The creation of a Factory is independent of other entities. While not mandatory, defining this entity can be very useful when modeling a Clawdite instance. A Factory serves as the “container” for all related FactoryEntities, such as workers, cells, machines, and equipment.

import os
from datetime import datetime
import orchestrator_python_client as hdt_client
from orchestrator_python_client import ApiClient, FactoryDto

# NOTE: you need to specify the HDT_ENDPOINT and HDT_API_KEY environment variables

configuration = hdt_client.Configuration(host=os.getenv('HDT_ENDPOINT'))
configuration.api_key['apiKeyAuth'] = os.getenv('HDT_API_KEY')
api_client = hdt_client.ApiClient(configuration)

factory_api = hdt_client.FactoryApi(api_client)

clawdite_factory = factory_api.create_factory(
    FactoryDto(name="Clawdite Factory")).payload

import java.util.Collections;
import java.time.LocalDateTime;
import org.openapitools.client.ApiClient;
import org.openapitools.client.api.FactoryApi;
import org.openapitools.client.model.FactoryDto;

private void createFactory() {
    // NOTE: you need to specify the HDT_ENDPOINT and HDT_API_KEY environment variables
    ApiClient apiClient = new ApiClient().setBasePath(System.getenv("HDT_ENDPOINT"));
    String apiKey = System.getenv("HDT_API_KEY");
    if(apiKey != null && !apiKey.isEmpty())
        apiClient.addDefaultHeader("x-api-key", apiKey);

    final FactoryApi factoryApi = new FactoryApi(apiClient);

    FactoryDto clawditeFactory = factoryApi.createFactory(
            new FactoryDto()
                    .setName("Clawdite Factory"));
}

import { Configuration, FactoryApi, FactoryDto } from 'orchestrator-javascript-client';

// NOTE: you need to specify the HDT_ENDPOINT and HDT_API_KEY environment variables
const configuration = new Configuration({
    basePath: process.env.HDT_ENDPOINT,
    apiKey: { apiKeyAuth: process.env.HDT_API_KEY }
});

const factoryApi = new FactoryApi(configuration);

async function createFactory() {
    await factoryApi.createFactory(new FactoryDto({ name: "Clawdite Factory" }));
}

Create a Worker

In order to create a Worker entity (or a FactoryEntity in general) it is mandatory to define the associated FactoryEntityModelCategoty and FactoryEntityModel in advance. This entity represents all the human beings characterizing the Factory.

import os
from datetime import datetime
import orchestrator_python_client as hdt_client
from orchestrator_python_client import ApiClient, FactoryEntityModelCategoryDto, FactoryEntityModelDto, WorkerDto

# NOTE: you need to specify the HDT_ENDPOINT and HDT_API_KEY environment variables

configuration = hdt_client.Configuration(host=os.getenv('HDT_ENDPOINT'))
configuration.api_key['apiKeyAuth'] = os.getenv('HDT_API_KEY')
api_client = hdt_client.ApiClient(configuration)

factory_entity_model_category_api = hdt_client.FactoryEntityModelCategoryApi(api_client)
factory_entity_model_api = hdt_client.FactoryEntityModelApi(api_client)
worker_api = hdt_client.WorkerApi(api_client)

operator_category = factory_entity_model_category_api.create_factory_entity_model_category(
                        FactoryEntityModelCategoryDto(name="Operator",
                            description="description")).payload

worker_model = factory_entity_model_api.create_factory_entity_model(
                        FactoryEntityModelDto(name="Worker",
                            description="description",
                            factory_entity_model_categories_id=[operator_category.id])).payload

worker = worker_api.create_worker(
                        WorkerDto(creation_date=datetime.now().isoformat(),
                            factory_entity_model_id=worker_model.id)).payload

import java.util.Collections;
import java.time.LocalDateTime;
import org.openapitools.client.ApiClient;
import org.openapitools.client.api.FactoryEntityModelCategoryApi;
import org.openapitools.client.api.FactoryEntityModelApi;
import org.openapitools.client.api.WorkerApi;
import org.openapitools.client.model.FactoryEntityModelCategoryDto;
import org.openapitools.client.model.FactoryEntityModelDto;
import org.openapitools.client.model.WorkerDto;

private void createWorker() {
    // NOTE: you need to specify the HDT_ENDPOINT and HDT_API_KEY environment variables
    ApiClient apiClient = new ApiClient().setBasePath(System.getenv("HDT_ENDPOINT"));
    String apiKey = System.getenv("HDT_API_KEY");
    if(apiKey != null && !apiKey.isEmpty())
        apiClient.addDefaultHeader("x-api-key", apiKey);

    final FactoryEntityModelCategoryApi factoryEntityModelCategoryApi = new FactoryEntityModelCategoryApi(apiClient);
    final FactoryEntityModelApi factoryEntityModelApi = new FactoryEntityModelApi(apiClient);
    final WorkerApi workerApi = new WorkerApi(apiClient);

    FactoryEntityModelCategoryDto operatorCategory = factoryEntityModelCategoryApi.createFactoryEntityModelCategory(
            new FactoryEntityModelCategoryDto()
                    .setName("Operator")
                    .setDescription("description"));

    FactoryEntityModelDto workerModel = factoryEntityModelApi.createFactoryEntityModel(
            new FactoryEntityModelDto()
                    .setName("Worker")
                    .setDescription("description")
                    .setFactoryEntityModelCategoriesId(Collections.singletonList(operatorCategory.getId())));

    WorkerDto worker = workerApi.createWorker(
            new WorkerDto()
                    .setCreationDate(LocalDateTime.now().toString())
                    .setFactoryEntityModelId(workerModel.getId()));

}

import { Configuration, FactoryEntityModelCategoryApi, FactoryEntityModelApi, WorkerApi } from 'orchestrator-javascript-client';

// NOTE: you need to specify the HDT_ENDPOINT and HDT_API_KEY environment variables
const configuration = new Configuration({
    basePath: process.env.HDT_ENDPOINT,
    apiKey: { apiKeyAuth: process.env.HDT_API_KEY }
});

const factoryEntityModelCategoryApi = new FactoryEntityModelCategoryApi(configuration);
const factoryEntityModelApi = new FactoryEntityModelApi(configuration);
const workerApi = new WorkerApi(configuration);

async function createWorker() {
    const operatorCategory = await factoryEntityModelCategoryApi.createFactoryEntityModelCategory({
        name: "Operator",
        description: "description"
    });
    
    const workerModel = await factoryEntityModelApi.createFactoryEntityModel({
        name: "Worker",
        description: "description",
        factoryEntityModelCategoriesId: [operatorCategory.payload.id]
    });
    
    await workerApi.createWorker({
        creationDate: new Date().toISOString(),
        factoryEntityModelId: workerModel.payload.id
    });
}

Create a FactoryEntity

Similarly to Worker entity creation, in order to create a FactoryEntity it is mandatory to define the associated FactoryEntityModelCategoty and FactoryEntityModel in advance. A typical instance of FactoryEntity is the physical factory’s cell to which workers are assigned or a machine.

This example details the creation of a Device, which is a particular type of FactoryEntity. In fact, it requires a DeviceModel to be defined, a specialization of FactoryEntityModel.

import os
from datetime import datetime
import orchestrator_python_client as hdt_client
from orchestrator_python_client import ApiClient, FactoryEntityModelCategoryDto, DeviceModelDto, FactoryEntityDto

# NOTE: you need to specify the HDT_ENDPOINT and HDT_API_KEY environment variables

configuration = hdt_client.Configuration(host=os.getenv('HDT_ENDPOINT'))
configuration.api_key['apiKeyAuth'] = os.getenv('HDT_API_KEY')
api_client = hdt_client.ApiClient(configuration)

factory_entity_model_category_api = hdt_client.FactoryEntityModelCategoryApi(api_client)
device_model_api = hdt_client.DeviceModelApi(api_client)
factory_entity_api = hdt_client.FactoryEntityApi(api_client)

device_category = factory_entity_model_category_api.create_factory_entity_model_category(
    FactoryEntityModelCategoryDto(name="Wearable",
    description="description")).payload

device_model = device_model_api.create_device_model(
    DeviceModelDto(name="Device",
    description="description",
    brand="brand",
    model="model",
    factory_entity_model_categories_id=[device_category.id])).payload

device = factory_entity_api.create_factory_entity(
    FactoryEntityDto(creation_date=datetime.now().isoformat(),
    factory_entity_model_id=device_model.id)).payload

import java.util.Collections;
import java.time.LocalDateTime;
import org.openapitools.client.ApiClient;
import org.openapitools.client.api.FactoryEntityModelCategoryApi;
import org.openapitools.client.api.DeviceModelApi;
import org.openapitools.client.api.FactoryEntityApi;
import org.openapitools.client.model.FactoryEntityModelCategoryDto;
import org.openapitools.client.model.DeviceModelDto;
import org.openapitools.client.model.FactoryEntityDto;

private void createDevice() {
// NOTE: you need to specify the HDT_ENDPOINT and HDT_API_KEY environment variables
    ApiClient apiClient = new ApiClient().setBasePath(System.getenv("HDT_ENDPOINT"));
    String apiKey = System.getenv("HDT_API_KEY");
    if(apiKey != null && !apiKey.isEmpty())
        apiClient.addDefaultHeader("x-api-key", apiKey);

    final FactoryEntityModelCategoryApi factoryEntityModelCategoryApi = new FactoryEntityModelCategoryApi(apiClient);
    final DeviceModelApi deviceModelApi = new DeviceModelApi(apiClient);
    final FactoryEntityApi factoryEntityApi = new FactoryEntityApi(apiClient);

    FactoryEntityModelCategoryDto deviceCategory = factoryEntityModelCategoryApi.createFactoryEntityModelCategory(
            new FactoryEntityModelCategoryDto()
                    .setName("Wearable")
                    .setDescription("description"));

    DeviceModelDto deviceModel = deviceModelApi.createDeviceModel(
            new DeviceModelDto()
                    .setName("Device")
                    .setDescription("description")
                    .setBrand("brand")
                    .setModel("model")
                    .setFactoryEntityModelCategoriesId(Collections.singletonList(deviceCategory.getId())));

    FactoryEntityDto device = factoryEntityApi.createFactoryEntity(
            new FactoryEntityDto()
                    .setCreationDate(LocalDateTime.now().toString())
                    .setFactoryEntityModelId(deviceModel.getId()));

}

import { Configuration, FactoryEntityModelCategoryApi, DeviceModelApi, FactoryEntityApi } from 'orchestrator-javascript-client';

// NOTE: you need to specify the HDT_ENDPOINT and HDT_API_KEY environment variables
const configuration = new Configuration({
    basePath: process.env.HDT_ENDPOINT,
    apiKey: { apiKeyAuth: process.env.HDT_API_KEY }
});

const factoryEntityModelCategoryApi = new FactoryEntityModelCategoryApi(configuration);
const deviceModelApi = new DeviceModelApi(configuration);
const factoryEntityApi = new FactoryEntityApi(configuration);

async function createDevice() {
    const deviceCategory = await factoryEntityModelCategoryApi.createFactoryEntityModelCategory({
        name: "Wearable",
        description: "description"
    });
    
    const deviceModel = await deviceModelApi.createDeviceModel({
        name: "Device",
        description: "description",
        brand: "brand",
        model: "model",
        factoryEntityModelCategoriesId: [deviceCategory.payload.id]
    });
    
    await factoryEntityApi.createFactoryEntity({
        creationDate: new Date().toISOString(),
        factoryEntityModelId: deviceModel.payload.id
    });
}

Create a CharacteristicDescriptor & CharacteristicValue

In order to create a CharacteristicDescriptor it is mandatory to define the associated FactoryEntityModel (with its FactoryEntityModelCategory) and optionally the entities associated to the base AbstractDescriptor (such as UnitOfMeasure, Category, Scale and Taxonomy).

Once the CharacteristicDescriptor is created, it is possible to assign a concrete CharacteristicValue, by specifying the value itself and the FactoryEntity it refers to.

import os
from datetime import datetime
import orchestrator_python_client as hdt_client
from orchestrator_python_client import ApiClient, FactoryEntityModelCategoryDto, FactoryEntityModelDto, 
    WorkerDto, CharacteristicDescriptorDto, CharacteristicValueDto, FieldType

# NOTE: you need to specify the HDT_ENDPOINT and HDT_API_KEY environment variables

configuration = hdt_client.Configuration(host=os.getenv('HDT_ENDPOINT'))
configuration.api_key['apiKeyAuth'] = os.getenv('HDT_API_KEY')
api_client = hdt_client.ApiClient(configuration)

factory_entity_model_category_api = hdt_client.FactoryEntityModelCategoryApi(api_client)
factory_entity_model_api = hdt_client.FactoryEntityModelApi(api_client)
worker_api = hdt_client.WorkerApi(api_client)
characteristic_descriptor_api = hdt_client.CharacteristicDescriptorApi(api_client)
characteristic_value_api = hdt_client.CharacteristicValueApi(api_client)

factory_entity_model_category = factory_entity_model_category_api.create_factory_entity_model_category(
    FactoryEntityModelCategoryDto(name="Operator",
    description="description")).payload

factory_entity_model = factory_entity_model_api.create_factory_entity_model(
    FactoryEntityModelDto(name="Worker",
    description="description",
    factory_entity_model_categories_id=[factory_entity_model_category.id])).payload

worker = worker_api.create_worker(
    WorkerDto(creation_date=datetime.now().isoformat(),
    factory_entity_model_id=factory_entity_model.id)).payload

characteristic_descriptor = characteristic_descriptor_api.create_characteristic_descriptor(
    CharacteristicDescriptorDto(name="Sex",
    description="description",
    factory_entity_model_id=factory_entity_model.id)).payload

characteristic_value = characteristic_value_api.create_characteristic_value(
    CharacteristicValueDto(values={datetime.now().isoformat(): "Male"},
    type=FieldType.STRING,
    characteristic_descriptor_id=characteristic_descriptor.id,
    factory_entity_id=worker.id)).payload

import java.util.Collections;
import java.time.LocalDateTime;
import org.openapitools.client.ApiClient;
import org.openapitools.client.api.FactoryEntityModelCategoryApi;
import org.openapitools.client.api.FactoryEntityModelApi;
import org.openapitools.client.api.WorkerApi;
import org.openapitools.client.api.CharacteristicDescriptorApi;
import org.openapitools.client.api.CharacteristicValueApi;
import org.openapitools.client.model.FactoryEntityModelCategoryDto;
import org.openapitools.client.model.FactoryEntityModelDto;
import org.openapitools.client.model.WorkerDto;
import org.openapitools.client.model.CharacteristicDescriptorDto;
import org.openapitools.client.model.CharacteristicValueDto;

private void createCharacteristics() {
    // NOTE: you need to specify the HDT_ENDPOINT and HDT_API_KEY environment variables
    ApiClient apiClient = new ApiClient().setBasePath(System.getenv("HDT_ENDPOINT"));
    String apiKey = System.getenv("HDT_API_KEY");
    if(apiKey != null && !apiKey.isEmpty())
        apiClient.addDefaultHeader("x-api-key", apiKey);

    final FactoryEntityModelCategoryApi factoryEntityModelCategoryApi = new FactoryEntityModelCategoryApi(apiClient);
    final FactoryEntityModelApi factoryEntityModelApi = new FactoryEntityModelApi(apiClient);
    final WorkerApi workerApi = new WorkerApi(apiClient);
    final CharacteristicDescriptorApi characteristicDescriptorApi = new CharacteristicDescriptorApi(apiClient);
    final CharacteristicValueApi characteristicValueApi = new CharacteristicValueApi(apiClient);

    FactoryEntityModelCategoryDto operatorCategory = factoryEntityModelCategoryApi.createFactoryEntityModelCategory(
            new FactoryEntityModelCategoryDto()
                    .setName("Operator")
                    .setDescription("description"));

    FactoryEntityModelDto workerModel = factoryEntityModelApi.createFactoryEntityModel(
            new FactoryEntityModelDto()
                    .setName("Worker")
                    .setDescription("description")
                    .setFactoryEntityModelCategoriesId(Collections.singletonList(operatorCategory.getId())));

    WorkerDto worker = workerApi.createWorker(
            new WorkerDto()
                    .setCreationDate(LocalDateTime.now().toString())
                    .setFactoryEntityModelId(workerModel.getId()));

    CharacteristicDescriptorDto characteristicDescriptor = characteristicDescriptorApi.createCharacteristicDescriptor(
            new CharacteristicDescriptorDto()
                    .setName("Sex")
                    .setDescription("description")
                    .setFactoryEntityModelId(factoryEntityModel.getId()));

    CharacteristicValueDto characteristicValue = characteristicValueApi.createCharacteristicValue(
            new CharacteristicValueDto()
                    .setValues(Collections.singletonMap(LocalDateTime.now().toString(), "Male"))
                    .setType(FieldType.STRING)
                    .setCharacteristicDescriptorId(characteristicDescriptor.getId())
                    .setFactoryEntityId(worker.getId()));
}

import { Configuration, FactoryEntityModelCategoryApi, FactoryEntityModelApi, WorkerApi, CharacteristicDescriptorApi, CharacteristicValueApi } from 'orchestrator-javascript-client';

// NOTE: you need to specify the HDT_ENDPOINT and HDT_API_KEY environment variables
const configuration = new Configuration({
    basePath: process.env.HDT_ENDPOINT,
    apiKey: { apiKeyAuth: process.env.HDT_API_KEY }
});

const factoryEntityModelCategoryApi = new FactoryEntityModelCategoryApi(configuration);
const factoryEntityModelApi = new FactoryEntityModelApi(configuration);
const workerApi = new WorkerApi(configuration);
const characteristicDescriptorApi = new CharacteristicDescriptorApi(configuration);
const characteristicValueApi = new CharacteristicValueApi(configuration);

async function createCharacteristics() {
    const operatorCategory = await factoryEntityModelCategoryApi.createFactoryEntityModelCategory({
        name: "Operator",
        description: "description"
    });
    
    const workerModel = await factoryEntityModelApi.createFactoryEntityModel({
        name: "Worker",
        description: "description",
        factoryEntityModelCategoriesId: [operatorCategory.payload.id]
    });
    
    const worker = await workerApi.createWorker({
        creationDate: new Date().toISOString(),
        factoryEntityModelId: workerModel.payload.id
    });
    
    const characteristicDescriptor = await characteristicDescriptorApi.createCharacteristicDescriptor({
        name: "Sex",
        description: "description",
        factoryEntityModelId: workerModel.payload.id
    });
    
    await characteristicValueApi.createCharacteristicValue({
        values: { [new Date().toISOString()]: "Male" },
        type: "STRING",
        characteristicDescriptorId: characteristicDescriptor.payload.id,
        factoryEntityId: worker.payload.id
    });
}

Create a MeasurementDescriptor

In order to create a MeasurementDescriptor it is mandatory to define the associated FactoryEntityModel (with its FactoryEntityModelCategory) and optionally the entities associated to the base AbstractDescriptor (such as UnitOfMeasure, Category, Scale and Taxonomy).

In this example the MeasurementDescriptor refers to a simple metric named HR from a Polar device. Note that the fields keys (in this case only hr) are mandatory and have to correspond with the JSON message keys when publishing a metric over the IIoT Middleware. In case of complex metrics with more than a single field, list all the fields in both MeasurementDescriptor fields and OutputMap parameterList using the exact same syntax.

Despite not essential, it is highly suggested to model also the OutputMap(s) associated to a MeasurementDescriptor (along with corresponding DeviceModel). This enables to map the same metric coming from different devices to the same MeasurementDescriptor. Additionally, it permits to specify the logical order in which to interpret the metric fields, particularly useful when they are complex. For example, in the case of a spatial value, [x-y-z] or [z-x-y].

import os
from datetime import datetime
import orchestrator_python_client as hdt_client
from orchestrator_python_client import ApiClient, FactoryEntityModelCategoryDto, FactoryEntityModelDto,
    WorkerDto, DeviceModelDto, MeasurementDescriptorDto, OutputMapDto, FieldType

# NOTE: you need to specify the HDT_ENDPOINT and HDT_API_KEY environment variables

configuration = hdt_client.Configuration(host=os.getenv('HDT_ENDPOINT'))
configuration.api_key['apiKeyAuth'] = os.getenv('HDT_API_KEY')
api_client = hdt_client.ApiClient(configuration)

factory_entity_model_category_api = hdt_client.FactoryEntityModelCategoryApi(api_client)
factory_entity_model_api = hdt_client.FactoryEntityModelApi(api_client)
worker_api = hdt_client.WorkerApi(api_client)
device_model_api = hdt_client.DeviceModelApi(api_client)
measurement_descriptor_api = hdt_client.MeasurementDescriptorApi(api_client)
output_map_api = hdt_client.OutputMapApi(api_client)

factory_entity_model_category = factory_entity_model_category_api.create_factory_entity_model_category(
    FactoryEntityModelCategoryDto(name="Operator",
    description="description")).payload

factory_entity_model = factory_entity_model_api.create_factory_entity_model(
    FactoryEntityModelDto(name="Worker",
    description="description",
    factory_entity_model_categories_id=[factory_entity_model_category.id])).payload

worker = worker_api.create_worker(
    WorkerDto(creation_date=datetime.now().isoformat(),
    factory_entity_model_id=factory_entity_model.id)).payload

wearable_category = factory_entity_model_category_api.create_factory_entity_model_category(
    FactoryEntityModelCategoryDto(name="Wearable",
    description="description")).payload

device_model_polar_h10 = device_model_api.create_device_model(
    DeviceModelDto(brand="Polar",
    model="H10",
    name="Polar H10",
    description="description",
    factory_entity_model_categories_id=[wearable_category.id])).payload

hr_descriptor = measurement_descriptor_api.create_measurement_descriptor(
    MeasurementDescriptorDto(fields={"hr": FieldType.NUMBER}, # sub-metric name on Clawdite
    name="HR",
    description="Heart Rate",
    factory_entity_model_id=factory_entity_model_worker.id)).payload

output_map_hr_polar_h10 = output_map_api.create_output_map(
    OutputMapDto(parameters_list=["hr"],
    measurement_descriptor_id=measurement_descriptor_hr.id,
    device_model_id=device_model_polar_h10.id)).payload

import java.util.Collections;
import java.time.LocalDateTime;
import org.openapitools.client.ApiClient;
import org.openapitools.client.api.FactoryEntityModelCategoryApi;
import org.openapitools.client.api.FactoryEntityModelApi;
import org.openapitools.client.api.WorkerApi;
import org.openapitools.client.api.DeviceModelApi;
import org.openapitools.client.api.MeasurementDescriptorApi;
import org.openapitools.client.api.OutputMapApi;
import org.openapitools.client.model.FactoryEntityModelCategoryDto;
import org.openapitools.client.model.FactoryEntityModelDto;
import org.openapitools.client.model.WorkerDto;
import org.openapitools.client.model.DeviceModelDto;
import org.openapitools.client.model.MeasurementDescriptorDto;
import org.openapitools.client.model.OutputMapDto;

private void createMeasurement() {
    // NOTE: you need to specify the HDT_ENDPOINT and HDT_API_KEY environment variables
    ApiClient apiClient = new ApiClient().setBasePath(System.getenv("HDT_ENDPOINT"));
    String apiKey = System.getenv("HDT_API_KEY");
    if(apiKey != null && !apiKey.isEmpty())
        apiClient.addDefaultHeader("x-api-key", apiKey);

    final FactoryEntityModelCategoryApi factoryEntityModelCategoryApi = new FactoryEntityModelCategoryApi(apiClient);
    final FactoryEntityModelApi factoryEntityModelApi = new FactoryEntityModelApi(apiClient);
    final WorkerApi workerApi = new WorkerApi(apiClient);
    final DeviceModelApi deviceModelApi = new DeviceModelApi(apiClient);
    final MeasurementDescriptorApi measurementDescriptorApi = new MeasurementDescriptorApi(apiClient);
    final OutputMapApi outputMapApi = new OutputMapApi(apiClient);

    FactoryEntityModelCategoryDto operatorCategory = factoryEntityModelCategoryApi.createFactoryEntityModelCategory(
            new FactoryEntityModelCategoryDto()
                    .setName("Operator")
                    .setDescription("description"));

    FactoryEntityModelDto workerModel = factoryEntityModelApi.createFactoryEntityModel(
            new FactoryEntityModelDto()
                    .setName("Worker")
                    .setDescription("description")
                    .setFactoryEntityModelCategoriesId(Collections.singletonList(operatorCategory.getId())));

    WorkerDto worker = workerApi.createWorker(
            new WorkerDto()
                    .setCreationDate(LocalDateTime.now().toString())
                    .setFactoryEntityModelId(workerModel.getId()));

    FactoryEntityModelCategoryDto wearableCategory = factoryEntityModelCategoryApi.createFactoryEntityModelCategory(
            new FactoryEntityModelCategoryDto()
                    .setName("Wearable")
                    .setDescription("description"));

    DeviceModelDto device_model_polar_h10 = deviceModelApi.createDeviceModel(
            new DeviceModelDto()
                    .setBrand("Polar")
                    .setModel("H10")
                    .setName("Polar H10")
                    .setDescription("description")
                    .setFactoryEntityModelCategoriesId(Collections.singletonList(wearable_category.getId())));

    MeasurementDescriptorDto hr_descriptor = measurementDescriptorApi.createMeasurementDescriptor(
            new MeasurementDescriptorDto()
                    .setFields(Collections.singletonMap("hr", FieldType.NUMBER))
                    .setName("HR")
                    .setDescription("Heart Rate")
                    .setFactoryEntityModelId(factory_entity_model_worker.getId()));

    OutputMapDto output_map_hr_polar_h10 = outputMapApi.createOutputMap(
            new OutputMapDto()
                    .setParametersList(Collections.singletonList("hr"))
                    .setMeasurementDescriptorId(measurement_descriptor_hr.getId())
                    .setDeviceModelId(device_model_polar_h10.getId()));
}

import { Configuration, FactoryEntityModelCategoryApi, FactoryEntityModelApi, WorkerApi, DeviceModelApi, MeasurementDescriptorApi, OutputMapApi } from 'orchestrator-javascript-client';

// NOTE: you need to specify the HDT_ENDPOINT and HDT_API_KEY environment variables
const configuration = new Configuration({
    basePath: process.env.HDT_ENDPOINT,
    apiKey: { apiKeyAuth: process.env.HDT_API_KEY }
});

const factoryEntityModelCategoryApi = new FactoryEntityModelCategoryApi(configuration);
const factoryEntityModelApi = new FactoryEntityModelApi(configuration);
const workerApi = new WorkerApi(configuration);
const deviceModelApi = new DeviceModelApi(configuration);
const measurementDescriptorApi = new MeasurementDescriptorApi(configuration);
const outputMapApi = new OutputMapApi(configuration);

async function createMeasurement() {
    const operatorCategory = await factoryEntityModelCategoryApi.createFactoryEntityModelCategory({
        name: "Operator",
        description: "description"
    });
    
    const workerModel = await factoryEntityModelApi.createFactoryEntityModel({
        name: "Worker",
        description: "description",
        factoryEntityModelCategoriesId: [operatorCategory.payload.id]
    });
    
    await workerApi.createWorker({
        creationDate: new Date().toISOString(),
        factoryEntityModelId: workerModel.payload.id
    });
    
    const wearableCategory = await factoryEntityModelCategoryApi.createFactoryEntityModelCategory({
        name: "Wearable",
        description: "description"
    });
    
    const deviceModelPolarH10 = await deviceModelApi.createDeviceModel({
        brand: "Polar",
        model: "H10",
        name: "Polar H10",
        description: "description",
        factoryEntityModelCategoriesId: [wearableCategory.payload.id]
    });
    
    const hrDescriptor = await measurementDescriptorApi.createMeasurementDescriptor({
        fields: { hr: "NUMBER" },
        name: "HR",
        description: "Heart Rate",
        factoryEntityModelId: workerModel.payload.id
    });
    
    await outputMapApi.createOutputMap({
        parametersList: ["hr"],
        measurementDescriptorId: hrDescriptor.payload.id,
        deviceModelId: deviceModelPolarH10.payload.id
    });
}

Create a FunctionalModule

Despite the creation of a FunctionalModule entity in not dependent on other entities, it is important to define the associated FunctionalModuleInput and FunctionalModuleOutput. This will enable the creation of the StateDescriptor, representing the result of the FunctionalModule processing (i.e. the output that will be sent to the IIoT Middleware).

The FunctionalModuleInput is not mandatory, but it is essential when the FunctionalModule necessitates as input some data from Clawdite, such as metrics or characteristics of the entities. In this example the input is the HearthRate saved through a dedicate MeasurementDescriptor, which is supposed to exist already. Refer to Create a MeasurementDescriptor.

import os
from datetime import datetime
import orchestrator_python_client as hdt_client
from orchestrator_python_client import ApiClient, FunctionalModuleDto, FunctionalModuleInputDto, FunctionalModuleOutputDto

# NOTE: you need to specify the HDT_ENDPOINT and HDT_API_KEY environment variables

configuration = hdt_client.Configuration(host=os.getenv('HDT_ENDPOINT'))
configuration.api_key['apiKeyAuth'] = os.getenv('HDT_API_KEY')
api_client = hdt_client.ApiClient(configuration)

functional_module_api = hdt_client.FunctionalModuleApi(api_client)
functional_module_input_api = hdt_client.FunctionalModuleInputApi(api_client)
functional_module_output_api = hdt_client.FunctionalModuleOutputApi(api_client)

custom_module = functional_module_api.create_functional_module(
                        FunctionalModuleDto(name="CustomModule", description="description")).payload

# NOTE: this supposes that hr_descriptor already exists
custom_module_input = functional_module_input_api.create_functional_module_input(
                        FunctionalModuleInputDto(input_param_name="hr", path="HR", functional_module_id=custom_module.id,
                                    descriptor_id=hr_descriptor.id)).payload

custom_module_output = functional_module_output_api.create_functional_module_output(
                        FunctionalModuleOutputDto(functional_module_id=custom_module.id,
                                    output_param_name="prediction")).payload

import java.util.Collections;
import java.time.LocalDateTime;
import org.openapitools.client.ApiClient;
import org.openapitools.client.api.FunctionalModuleApi;
import org.openapitools.client.api.FunctionalModuleOutputApi;
import org.openapitools.client.api.FunctionalModuleInputApi;
import org.openapitools.client.model.FunctionalModuleDto;
import org.openapitools.client.model.FunctionalModuleInputDto;
import org.openapitools.client.model.FunctionalModuleOutputDto;

private void createFunctionalModule() {
    // NOTE: you need to specify the HDT_ENDPOINT and HDT_API_KEY environment variables
    ApiClient apiClient = new ApiClient().setBasePath(System.getenv("HDT_ENDPOINT"));
    String apiKey = System.getenv("HDT_API_KEY");
    if(apiKey != null && !apiKey.isEmpty())
        apiClient.addDefaultHeader("x-api-key", apiKey);
    
    final FunctionalModuleApi functionalModuleApi = new FunctionalModuleApi(apiClient);
    final FunctionalModuleInputApi functionalModuleInputApi = new FunctionalModuleInputApi(apiClient);
    final FunctionalModuleOutputApi functionalModuleOutputApi = new FunctionalModuleOutputApi(apiClient);

    FunctionalModuleDto customModule = FunctionalModuleApi.createFunctionalModule(
            new FunctionalModuleDto()
                    .setName("CustomModule")
                    .setDescription("description"));
    
    // NOTE: this supposes that hr_descriptor already exists
    FunctionalModuleInputDto customModuleInput = FunctionalModuleInputApi.createFunctionalModuleInput(
            new FunctionalModuleInputDto()
                    .setInputParameterName("hr")
                    .setPath("HR")
                    .setFunctionalModuleId(customModule.getId())
                    .setDescriptorId(hrDescriptor.getId()));

    FunctionalModuleOutputDto customModuleOutput = FunctionalModuleOutputApi.createFunctionalModuleOutput(
            new FunctionalModuleOutputDto()
                    .setFunctionalModuleId(customModule.getId())
                    .setOutputParameterName("prediction"));
}

import { Configuration, FunctionalModuleApi, FunctionalModuleInputApi, FunctionalModuleOutputApi } from 'orchestrator-javascript-client';

// NOTE: you need to specify the HDT_ENDPOINT and HDT_API_KEY environment variables
const configuration = new Configuration({
    basePath: process.env.HDT_ENDPOINT,
    apiKey: { apiKeyAuth: process.env.HDT_API_KEY }
});

const functionalModuleApi = new FunctionalModuleApi(configuration);
const functionalModuleInputApi = new FunctionalModuleInputApi(configuration);
const functionalModuleOutputApi = new FunctionalModuleOutputApi(configuration);

async function createFunctionalModule(hrDescriptorId) {
    const customModule = await functionalModuleApi.createFunctionalModule({
        name: "CustomModule",
        description: "description"
    });
    
    await functionalModuleInputApi.createFunctionalModuleInput({
        inputParamName: "hr",
        path: "HR",
        functionalModuleId: customModule.payload.id,
        descriptorId: hrDescriptorId
    });
    
    await functionalModuleOutputApi.createFunctionalModuleOutput({
        functionalModuleId: customModule.payload.id,
        outputParamName: "prediction"
    });
}

Create a StateDescriptor

In order to create a StateDescriptor it is mandatory to model the associated FunctionalModule. In fact, the FunctionalModuleOutput, together with the Block, enable to correctly create a StateDescriptor. Despite the Block is not mandatory, it facilitates to understand and parse the structure of the State.

In this example the FunctionalModule takes no input, and its output is a single numeric value named prediction. Note that the outputParameterName has to correspond with the JSON message key when publishing a State over the IIoT Middleware.

import os
from datetime import datetime
import orchestrator_python_client as hdt_client
from orchestrator_python_client import ApiClient, FunctionalModuleDto, FunctionalModuleOutputDto, 
NumberBasedDto, StateDescriptorDto

# NOTE: you need to specify the HDT_ENDPOINT and HDT_API_KEY environment variables

configuration = hdt_client.Configuration(host=os.getenv('HDT_ENDPOINT'))
configuration.api_key['apiKeyAuth'] = os.getenv('HDT_API_KEY')
api_client = hdt_client.ApiClient(configuration)

functional_module_api = hdt_client.FunctionalModuleApi(api_client)
functional_module_output_api = hdt_client.FunctionalModuleOutputApi(api_client)
number_based_api = hdt_client.NumberBasedApi(api_client)
state_descriptor_api = hdt_client.StateDescriptorApi(api_client)

custom_module = functional_module_api.create_functional_module(
    FunctionalModuleDto(name="CustomModule", description="description")).payload

custom_module_output = functional_module_output_api.create_functional_module_output(
    FunctionalModuleOutputDto(functional_module_id=custom_module.id,
    output_param_name="prediction")).payload

number_based_dto = number_based_api.create_number_based(NumberBasedDto()).payload

custom_module_state_descriptor = state_descriptor_api.create_state_descriptor(
    StateDescriptorDto(functional_module_output_id=custom_module_output.id,  # to know the origin of the State
    blockId=number_based_dto.id,  # link the data structure
    name="CustomModuleState",
    description="prediction",
    factory_entity_model_id=worker_model.id)  # the entities model this state refers to
).payload

import java.util.Collections;
import java.time.LocalDateTime;
import org.openapitools.client.ApiClient;
import org.openapitools.client.api.FunctionalModuleApi;
import org.openapitools.client.api.FunctionalModuleOutputApi;
import org.openapitools.client.api.NumberBasedApi;
import org.openapitools.client.api.StateDescriptorApi;
import org.openapitools.client.model.FunctionalModuleDto;
import org.openapitools.client.model.FunctionalModuleOutputDto;
import org.openapitools.client.model.NumberBasedDto;
import org.openapitools.client.model.StateDescriptorDto;

private void createStateDescriptor() {
    // NOTE: you need to specify the HDT_ENDPOINT and HDT_API_KEY environment variables
    ApiClient apiClient = new ApiClient().setBasePath(System.getenv("HDT_ENDPOINT"));
    String apiKey = System.getenv("HDT_API_KEY");
    if(apiKey != null && !apiKey.isEmpty())
        apiClient.addDefaultHeader("x-api-key", apiKey);

    final FunctionalModuleApi functionalModuleApi = new FunctionalModuleApi(apiClient);
    final FunctionalModuleOutputApi functionalModuleOutputApi = new FunctionalModuleOutputApi(apiClient);
    final NumberBasedApi numberBasedApi = new NumberBasedApi(apiClient);
    final StateDescriptorApi = new StateDescriptorApi(apiClient);

    FunctionalModuleDto customModule = FunctionalModuleApi.createFunctionalModule(
            new FunctionalModuleDto()
                    .setName("CustomModule")
                    .setDescription("description"));

    FunctionalModuleOutputDto customModuleOutput = FunctionalModuleOutputApi.createFunctionalModuleOutput(
            new FunctionalModuleOutputDto()
                    .setFunctionalModuleId(customModule.getId())
                    .setOutputParameterName("prediction"));

    NumberBasedDto numberBased = NumberBasedApi.createNumberBased(new NumberBasedDto());

    StateDescriptorDto customModuleStateDescriptor = StateDescriptorApi.createStateDescriptor(
            new FunctionalModuleOutputDto()
                    .setFunctionalModuleOutputId(customModuleOutput.getId()) // to know the origin of the State
                    .setBlockId(numberBased.getId()) // link the data structure
                    .setName("CustomModuleState")
                    .setDescription("description")
                    .setFactoryEntityModelId(workerModel.getId())); // the entities model this state refers to 
}

import { Configuration, FunctionalModuleApi, FunctionalModuleOutputApi, NumberBasedApi, StateDescriptorApi } from 'orchestrator-javascript-client';

// NOTE: you need to specify the HDT_ENDPOINT and HDT_API_KEY environment variables
const configuration = new Configuration({
    basePath: process.env.HDT_ENDPOINT,
    apiKey: { apiKeyAuth: process.env.HDT_API_KEY }
});

const functionalModuleApi = new FunctionalModuleApi(configuration);
const functionalModuleOutputApi = new FunctionalModuleOutputApi(configuration);
const numberBasedApi = new NumberBasedApi(configuration);
const stateDescriptorApi = new StateDescriptorApi(configuration);

async function createStateDescriptor(workerModelId) {
    const customModule = await functionalModuleApi.createFunctionalModule({
        name: "CustomModule",
        description: "description"
    });
    
    const customModuleOutput = await functionalModuleOutputApi.createFunctionalModuleOutput({
        functionalModuleId: customModule.payload.id,
        outputParamName: "prediction"
    });
    
    const numberBased = await numberBasedApi.createNumberBased({});
    
    await stateDescriptorApi.createStateDescriptor({
        functionalModuleOutputId: customModuleOutput.payload.id,
        blockId: numberBased.payload.id,
        name: "CustomModuleState",
        description: "prediction",
        factoryEntityModelId: workerModelId
    });
}

Read an entity

In order to retrieve any type of entity from Clawdite (in this example a Worker entity) it is mandatory to specify the associated ID and use the API dedicated to such entity (in this case the Worker API).

import os
import orchestrator_python_client as hdt_client
from orchestrator_python_client import ApiClient

# NOTE: you need to specify the HDT_ENDPOINT and HDT_API_KEY environment variables

configuration = hdt_client.Configuration(host=os.getenv('HDT_ENDPOINT'))
configuration.api_key['apiKeyAuth'] = os.getenv('HDT_API_KEY')
api_client = hdt_client.ApiClient(configuration)

worker_api = hdt_client.WorkerApi(api_client)

# NOTE: you need to specify the worker_id UUID
worker_id = "3fa85f64-5717-4562-b3fc-2c963f66afa6"

worker = worker_api.get_worker_by_id(worker_id)

import java.util.Collections;
import java.time.LocalDateTime;
import org.openapitools.client.ApiClient;
import org.openapitools.client.api.WorkerApi;
import org.openapitools.client.model.WorkerDto;

private void readWorker() {
// NOTE: you need to specify the HDT_ENDPOINT and HDT_API_KEY environment variables
ApiClient apiClient = new ApiClient().setBasePath(System.getenv("HDT_ENDPOINT"));
String apiKey = System.getenv("HDT_API_KEY");
if(apiKey != null && !apiKey.isEmpty())
apiClient.addDefaultHeader("x-api-key", apiKey);

    final WorkerApi workerApi = new WorkerApi(apiClient);

    // NOTE: you need to specify the workerId UUID
    workerId = "3fa85f64-5717-4562-b3fc-2c963f66afa6";

    WorkerDto worker = workerApi.getWorkerById(workerId);
}

import { Configuration, WorkerApi } from 'orchestrator-javascript-client';

// NOTE: you need to specify the HDT_ENDPOINT and HDT_API_KEY environment variables
const configuration = new Configuration({
    basePath: process.env.HDT_ENDPOINT,
    apiKey: { apiKeyAuth: process.env.HDT_API_KEY }
});

const workerApi = new WorkerApi(configuration);

async function readWorker(workerId) {
    return workerApi.getWorkerById(workerId);
}