Get started

An updating or monitoring campaign over a set of remote edge devices can be defined in a simple way as a set of operations that must be performed in a specific sequence and based on a decision flow. The operations involved in such campaign can be of many different types and depend on some conditions that must be verified before proceeding with the actual execution.

For example, the feasibility of performing an update of a operating system package, could depend on the check for sufficient disk space and the actual presence of the specific outdated version of the package on the target device.

IoT Catalyst allows the creation of even very complex workflows that can satisfy the scenario mentioned above. These workflows are named Automation Campaigns

The Automation Service is an IoT Catalyst add-on which allows to automate device management tasks over multiple Agents available in the IoT Catalyst domain. A typical use case can be updating the OS version of thousands of devices simultaneously.

IoT Catalyst Studio offers a graphical user interface which makes very easy the following operations:

• create and monitor the execution of Automation Campaigns over multiple target devices.
• create Automation Campaigns campaigns which will execute either immediately or postponed in time (specifying hours and/or minutes).
• manage Automation Campaigns schedule to repeatedly execute a campaign, either specifying hours/minutes, or by using a crontab-like format.
• alter the execution status of an Automation Campaign via various buttons which allow to pause/abort a campaign, unschedule its execution, or to launch again a finished campaign by cloning it.
• parallelize the execution of an Automation Campaign by splitting it into multiple subjobs: for example, a campaign over 10 targets can be splitted across 10 subjobs (so that every subjob will manage the whole campaign execution for a single target).
• observe the execution of a Automation Campaign in any detail.

The creation of a campaign involves the definition of one or more tasks, whose aim is to group many commands of the same kind:

At any point in time, a campaign will be in one of the following statuses:

All the information and methods managed by the Automation Service are easily accessible using the RESTFul API here described.

Invoking the APIs

Once you've set up the frontend, you can use remote HTTP requests to call the API. To do that you need to send HTTP POST requests to the API endpoint file located in the frontend directory. For example, if your IoT Catalyst Studio frontend is installed under HTTPS://{IoTCatalystStudioEndpoint}, the HTTP request to call will look like this:

curl --location --request GET '<AutomationServiceBaseURL>/campaigns/10?schedule=10&page=1&results_per_page=500' \ --header 'Authorization: Bearer <valid IoT Catalyst Studio session token>'

                    

The API makes use of query parameters in order to filter the results or simply in order to choose between id or name as keys in the results. Some endpoints have mandatory request parameters. The parameter "force_refresh", which if "true" would force the refresh of the cache, is always optional and defaults to "false".

Security

Before you can access any data inside of IoT Catalyst Automation Service you'll need to log in and obtain an authentication token. This can be done using the APISecurity.requestToken method.

Once you have obtained a valid IoTCatalyst Session Token, you should use it as a bearer token in your RESTFul API invocations

CURL Invocation Example

curl --location --request GET '<AutomationServiceBaseURL>/campaigns/10?schedule=10&page=1&results_per_page=500' \ --header 'Authorization: Bearer <valid IoT Catalyst Studio session token>'

                    

JAVASCRIPT

const myHeaders = new Headers({
    "Authorization": "Bearer <valid IoT Catalyst Studio session token>"
});

const requestOptions = {
  method: 'GET',
  headers: myHeaders,
  redirect: 'follow'
};

fetch("/campaigns/10?schedule=10&page=1&results_per_page=500", requestOptions)
  .then(response => response.json())
  .then(result => console.log(result))
  .catch(error => {
    // error handling routine goes here...
  });                 
                    

Response Format

if everything goes well, IoT Catalyst Automation Service API response will contain a valid JSON data.

Here follows an example of JSON data generated by the API GetAllHypervisorsStatuses

{
    "data": {
        "id_campaign": 10,
        "id_schedule": 10,
        "summary": {
            "id_campaign": 10,
            "id_schedule": 10,
            "progress": 0.0,
            "status": "running",
            "n_exited_subjobs": 0,
            "start_time": 1679048484,
            "end_time": null
        },
        "targets": [
            {
                "id_target": 1081,
                "id_subjob": 1,
                "progress": 0.0,
                "status": "running",
                "start_time": 1679048484,
                "end_time": null,
                "tasks": [
                    {
                        "name": "task",
                        "description": "task",
                        "conditions": [],
                        "on_error_policy": "exit",
                        "progress": 0.0,
                        "status": "running",
                        "start_time": 1679048484,
                        "end_time": null,
                        "commands": [
                            {
                                "name": "reboot",
                                "type": "SHELL",
                                "command": "sudo reboot",
                                "causes_reboot": false,
                                "timeout": 1,
                                "retries": 0,
                                "params": {},
                                "interpreter": "BASH"
                            }
                        ]
                    }
                ]
            }
        ]
    },
    "message": "",
    "info": {
        "page": 1,
        "results_in_page": 1,
        "total_pages": 1,
        "total_elements": 1
    }
}

                    

Error Handling

Here is the list of possible error codes returned by the Automation Service, with possible explanations:

### 400
Bad request body (on initialization).

### 401
Request with no Authorization header.

### 403
Request forbidden.

### 404
Apart from the obvious bad endpoint, even a correct endpoint can return this code if the Automation Service is not initialized.
When asking for the status / stats of a Hypervisor or Container by id or name, the Automation Service returns this code if the requested entity was not found.

### 409
Automation Service already initialized.

### 422
A problem was encountered when initializing the Automation Service (e.g. bad IoTCatalyst Studio credentials).
This code can also be returned when the Automation Service is not functioning properly and thus cannot process the request.
                    

Campaign's JSON definition

IoT Catalyst Automation Service uses JSON as the standard format for defining a Campaign. The JSON that describes an automation campaign can be very long and apparently complicated, because a campaign can also be very articulated and complex, i.e. organized into many tasks and many execution conditions.

In the upcoming sections, we will describe every single component (Task, Task's Conditions and Task's Commands), that extends the basic structure of the following basic JSON.

                    {
 "name": <campaign's name>,
 "description": <campaign's description>,
 "target": {
 "idComponentType": <id component type>, 
 "ids": <list of ids>
 },
 "execution": {
 "processes": <number of processes>, 
 "on_error": <on error>, 
 "suspendable": <suspendable>, 
 "abortable": <abortable>
 },
 "tasks": <list of tasks>
}

                    

Task definition

IoT Catalyst Automation Service uses JSON as the standard format for defining a Task. A task is a collection of commands of different types that are executed on a target device. The execution of a Task can be dependent on the result of the runtime evaluation of a list of conditions.

The basic structure of a JSON that defines an IoT Catalyst Automation Service Task is the following:

{
 "name":  <task name>,
 "description": <task description>,
 "on_error_policy": <task on error policy>,
 "conditions": <list of conditions>,
 "commands": <list of commands>
}

                    

Task's Conditions definition

IoT Catalyst Automation Service uses JSON as the standard format for defining Task's conditions. A condition is an atomic element containing a logical check (a comparison) that the Automation Service performs automatically before executing a Task. A condition can be linked to other conditions in a condition chain. The link is performed by adding a condition to an existing conditions list and specifying how this newly added condition is linked to the preceding ones. The type of link is a boolean operator AND or OR. A conditions list is a sequence of atomic checks linked to form a single boolean operation.

The basic structure of a JSON that defines an IoT Catalyst Automation Service Task Condition is the following:

{
 “operator”: <condition operator>,
 “checks”: <list of checks>
}

                    

{
 “operator”: <check operator>,
 “check”:   {
                “arg1”: <arg1>,
                “arg2”: <arg2>,
                “comparator”: <comparator>
            }
}

                                    

Task's Commands definition

IoT Catalyst Automation Service uses JSON as the standard format for defining Task's commands. Automation Service supports four different command types.

• Hypervisor Commands (PRESET): these are commands that are transmitted directly to the IoT Catalyst Studio management channel and are used to:
  • Start a Hypervisor (START)
  • Stop a Hypervisor (STOP)
  • Request an update of a Hypervisor (UPDATE)
• Shell Commands (SHELL): These commands will be sent to a remote device for execution in the Windows prompt / Linux shell, depending on the architecture.
  Each command's outcome and output are collected and stored by the Automation Service for future consultation.
  For each command, the following information must be entered:
  • Name
  • Timeout, after how many seconds the agent running on edge must stop waiting to receive the result of the operation
  • The number of attempts in case of failure of the operation
  • Whether the command causes a reboot or not. The system is, in fact able to manage and resume the correct state of execution even after a reboot
  • The command's code, i.e. the command that is executed on the remote device's command shell
• Metrics (METRIC): it is possible to collect data of a scalar type from remote devices, for example, the amount of disk space, free memory, etc. This scalar data is referred to as metrics.
  Metrics are used in conditions as arguments for the comparison checks.
• API Commands (API): Invokation to any IoT Catalyst Studio API methods.
  

The basic structure of a JSON that defines an IoT Catalyst Automation Service Task Command is the following:

{
    “name”: <command name>,
    “type”: <command type>
    “causes_reboot”: <causes reboot>,
    “timeout”: <timeout>,
    “retries”: <retries>,
    “params”: <params>,
    “command”: <command>,
    “refresh_interval”: <refresh interval>,
    “data_type”: <data type>,
    “date_format”: <date format>
}


                    

This endpoint gets a token from a IoT Catalyst Studio instance, the retrieved token is necessary to make authorized requests to the Automation Service as indicated in the relevant parts of this document.

METHOD

URL

POST BODY FORMAT

POST BODY

REQUEST PARAMETERS

This endpoint initializes the Automation Service. Until the Automation Service is not initialized, it does not allow the creation of any campaign.

METHOD

URL

POST BODY FORMAT

POST BODY

AUTH TYPE

AUTH FIELDS

REQUEST PARAMETERS

This endpoint initializes the Automation Service. Until the Automation Service is not initialized, it does not allow the creation of any campaign.

METHOD

URL

POST BODY FORMAT

POST BODY

REQUEST PARAMETERS

This endpoint gets the status of the Automation Service.

METHOD

URL

REQUEST PARAMETERS

This is the generic endpoint to create an Automation Service campaign and execute it based on a schedule

METHOD

URL

POST BODY FORMAT

POST BODY

REQUEST PARAMETERS

This endpoint can be used to verify the syntactic validity of a campaign JSON definition before executing it.

METHOD

URL

POST BODY FORMAT

POST BODY

REQUEST PARAMETERS

This endpoint is used by an IoTCatalyst Agent to verify the authenticity of the received campaign messages and therefore prevent Man-In-The-Middle attacks

METHOD

URL

POST BODY FORMAT

POST BODY

REQUEST PARAMETERS

This endpoint gets the list of all the campaigns in the Automation Service.

METHOD

URL

REQUEST PARAMETERS

This endpoint gets the stats of all the schedules for the campaign .

METHOD

URL

REQUEST PARAMETERS

This endpoint gets the detailed execution status of a campaign schedule. For each target, the execution result of each command is shown.

METHOD

URL

REQUEST PARAMETERS

This endpoint gets the detailed execution status of a schedule on a per-target basis.

METHOD

URL

REQUEST PARAMETERS

This endpoint gets the original campaign JSON definition associated with issued to the Automation Service.

METHOD

URL

REQUEST PARAMETERS

This endpoint removes the schedule for the campaign .

METHOD

URL

REQUEST PARAMETERS

This endpoint deletes information relative to the campaign .

METHOD

URL

REQUEST PARAMETERS

This endpoint aborts the last running schedule of the campaign .

METHOD

URL

REQUEST PARAMETERS

This endpoint pauses the last running schedule of the campaign .

METHOD

URL

REQUEST PARAMETERS

This endpoint resumes the last paused schedule of the campaign .

METHOD

URL

REQUEST PARAMETERS

This endpoint gets the logs of the Automation Service.

METHOD

URL

REQUEST PARAMETERS

This endpoint deletes logs generated before the given date.

METHOD

URL

REQUEST PARAMETERS

This endpoint gets a json with a collection of exemplary endpoints.

METHOD

URL

REQUEST PARAMETERS

This endpoint gets the Automation Service endpoints PDF guide.

METHOD

URL

REQUEST PARAMETERS

This endpoint creates a new SHELL/METRIC command and saves it into the Automation Service library.

METHOD

URL

POST BODY FORMAT

POST BODY

REQUEST PARAMETERS

This endpoint updates an existing command with a new version.

METHOD

URL

REQUEST PARAMETERS

This endpoint gets all the commands that are present into the Automation Service library.

METHOD

URL

REQUEST PARAMETERS

This endpoint deletes the specified command from the Automation Service library.

METHOD

URL

REQUEST PARAMETERS