User's Guide

ot-mongo:
   image: mongo:3.6
   container_name: ot-mongo
   command: --nojournal
   volumes:
     - ./ot-mongodata:/data/db
 ot-core:
   image: pixelh2020/ot:0.2
   container_name: ot-core
   links:
     - ot-mongo
   volumes:
     - /var/run/docker.sock:/var/run/docker.sock
     - ./ot-config/tomcat-users.xml:/usr/local/tomcat/conf/tomcat-users.xml:ro
     - ./ot-config/context.xml:/usr/local/tomcat/conf/Catalina/localhost/manager.xml:ro
     - ./ot-config/context.xml:/usr/local/tomcat/conf/Catalina/localhost/host-manager.xml:ro
     - ./ot-config/default.configuration.xml:/usr/local/tomcat/default.configuration.xml
     - ./ot-logs:/usr/local/tomcat/logs
   ports:
     - "8080:8080"

Redeployments and Monitoring

Deploy/update a new OT version

Logs and Monitoring

API - Swagger Interface

{  
  "dockerInfo": {
    "dockerName": "pixelh2020/dummysei:0.1",
    "label": "getInfo"    
  }  
}

{
  "id": "5ed7784971409d0623b6c57a",
  "generalInfo": null,
  "dockerInfo": {
    "dockerName": "pixelh2020/dummysei:0.1",
    "label": "getInfo",
    "dockerRepo": null
  },
  "creation": 1591179337033,
  "otStatus": "created"
}

Graphical User Interface

Models

• Creating a model: If you want to create a new model, just click on the main (left) panel on Models. You should see a list of already published models, unless it is a fresh installation.

Just click on Add a New Model. A basic form will appear asking for the name of the model in your Docker repository as well as the label where all descriptive information is included (also in the Docker image). If you don't have one by your side available, let's follow the process with a dummy example. Just enter the following values:

As you may deduce, pixelh2020 is an open (public) repository in Dockerhub, dummysei:01 is the name and version of the Docker image to be used, and getInfo is the included label in the Docker image that described the model with a specific format defined in PIXEL. In a certain way, it is similar to a WSDL for web services. The web form also includes the option to point to a private Docker repository, in that case, you will have to enter the credentials to access. After clicking the Save button on the top right corner, you will see the model on the list as created:

Note that there is still no name nor category for the model, as it needs to be first otained (pulled) from the Docker repository. You can track this activity by monitoring the otpixelEngineCreateModel.log file:

If you refresh now your browser, you should see that model has changed its status to deployed. Now there is a name and a category, which has been extracted from the given label of the Docker image.

You should have noticed a list of actions represented by 4 icons: edit, delete, run and schedule. Clicking on the Edit Model icon will allow you to see the complete description of the model. We will not discuss the format, but basically it describes basic fields, connectors, inputs, outputs and logging configuration.

By clicking on the Delete Model icon, the model enters a deleted status. After a short while, if you refresh the browser the model will have disappeared. The other options (run,schedule) are commented on the next subsections.

• Running a model (creating an instance): Once you have published and deployed a model (see previous step), you should be able to run the model. For that, just click on the Run model action button, and you should see a new page with a list of executions associated to that model. After a fresh installation, there will be no item in the list.

Let's create a new execution by clicking on the New Instance button. A modal dialog appears where you will have to enter a JSON file describing the details of the execution.

The introduction of data here is a particularization of the description of the model, with specific inputs and outputs, and varies from model to model. You should look at the specific model to enter valid data here. Once you do, just press the Save button in the modal. The new instance appears in the Menu with status created.

There is a backend process that periodically reads this table and runs the pending instances. You can track this activity by monitoring the otpixelEngineCreateInstances.log:

After the execution, if you refresh your browser, you will see the details of the execution (instance) in the list.

Here you have two action icons. The Delete instance is obvious, whereas the View instance allows to visualize the details of the instance. It is pretty much the same as the input data provided when the instance was created, with some additional information added by the backend process (creation time, start, otStatus, dockerId). Note that the result of the execution is stored in Elasticsearch; the visualization of such result is model dependent as is provided by the PIXEL Dashboard.

• Schedule a model (creating an scheduledInstance): Some models are useful every day, every week, etc., and can be run automatically (scheduled), without any reason for user presence. The process of scheduling a model is analogous to the previous one (running a model), just click on the Schedule model action icon of the models list and you should be able to follow a similar process.

The only difference here resides in the fact that the model is going to be launched periodically in this case, not just once. Therefore, when we enter the JSON data of a scheduled instance, we need to include such data, which follows the structure:

"scheduleInfo": {
        "start": "2021-01-20T11:11:11+02:00",
        "unit": "minute",
        "value": 1
}

The start field indicates (ISO 8601) when the model must be first launched, the unit filed represents the possible units (second, minute, hour, day) and the value field represents the amount of units to wait between consecutive executions. In the example above, model will be run every minute. The given start time should typically represent one timestamp in the future. However, if the given start time is any time in the past, the OT engine will recalculate the nearest point of time in the future as result of the N-th multiple of the given amount of time (here multiples are count every minute). You can trace the backend process that periodically reads the corresponding table and runs the pending scheduled instances. The log is on otpixelEngineCreateScheduledInstances.log:

Now in the list of scheduled instances you should see the added scheduled instance. The Last status column should say running, unless there is an error (error trying to execute the Docker instance) in any of the executions.

There is one final comment and relates to timing issues. If one of the inputs for the execution of the model is a time dependent parameter, e.g. current day of the execution, then this should be parametrized and interpreted by the OT engine. The user cannot provide here a fixed timestamp (otherwise this would provide the same result continuously). As example, let’s suppose a model that requires as inputs a start time and an end time to make its internal calculation; this could be the case of getting vessels calls in a time window. If we want to run the model every day, then we need to parametrize this somehow in the JSON data structure. An example could be:

{
        "name": "start",
        "type": "date-time (ISO 8601)",
        "description": "start of calculation period",
        "value": "${DATE_DAY_INIT}"
}, {
        "name": "end",
        "type": "date-time (ISO 8601)",
        "description": "end of calculation period",
        "value": "${DATE_DAY_INIT}"
}

Here, every time the model is executed, the OT engine previously interprets the parametrized date values (${}) and changes it with the corresponding operation. Currently the OT engine supports the following ones: