Intro

Why do you need an IoT operations service?

If you’re reading this document, then you’re interested in device monitoring and management. Maybe you’re involved in yours company’s operations department. If so, you usually execute actions or operations on your remote devices, like reboot, update the firmware or send ICMP pings to them to check their availability. OpenGate comes to help you with your massive field operations. The operations service API is the programmatic way to execute your operations using OpenGate.

Existing operations

The platform offers a catalog of device operations usually implemented by the devices. These default operations can be cloned by your organization administrators according to the needs and characteristics of the devices you use in your environment. See how to create new operations for your organization in this section or use the already existing operations.

New operations

The operations engine is a powerful and extensible tool. Operations teams can create new operations to cover the needs on demands of your devices. The OpenGate operations API is very flexible. You can configure each operation with the operation name and the parameter list to use. You can execute new operations using this interface without changing the programmatic interface.

Rich operations

The underlying OpenGate engine supports multi-step operations. Therefore, when you invoke an operation’s execution, expect a response with a list containing the result of each step.

Executing operations

The operations API is not an exception in the OpenGate REST API support. It fits the REST architectural style. While the provisioning service extensively uses entity-collection patterns, the operation service implements the command pattern. How does it? Easy, OpenGate manages operations as entities, so you only have to send a POST request with an operation object when you want to execute an operation.

It is also possible to execute an operation over a set of devices or a group of objects that meet specific execution criteria.

Operations catalog

You can execute a single operation on a few or thousands of entities using a tag or filter criteria instead of a bounded target entities array. So please, use it with caution.

You will only be able to use the cloned operations in your domain for the entities of your organization. Operation types from the default operations catalog that has not been inherited cannot be executed. The way to create operations, either cloning them from the catalog or creating them from scratch, can be found here.

See the list of default operations.

Execution modes

The operations service API provides two ways of executing an operation: tasks and jobs. A job immediately runs operations on remote devices, while a task defines scheduled jobs according to desired programming options.

Jobs

Job object

A job defines the operation configuration and selected remote devices to send a request with the following attributes.

Attributes	Constraints
id	UUID format
taskId	UUID format
request	see Job Request Object from schemas
report	see Job summary Object from schemas

JSON as the interchange format

OpenGate Data Collector uses JSON as an interchange format in its RESTful interface. The following sections show you how data is formatted.

Numbers

A number can be an integer or double-precision float. Here are some examples:

time: 1356695180301
value: 299.99
maxValue: 1.23e11
minValue: -10.5

The property name (i.e., maxValue, etc.) is a string surrounded by double quotes, but the value does not have quotes. A number can be prefixed by a minus sign. The exponent portion (denoted by e or E) comes after the number value and can have an optional plus or minus sign. Neither leading zeroed, octal, nor hexadecimal values are allowed.

Dates

Within OpenGate Data Collector REST API dates, parameters are represented by strings with ISO 8601:2004 standard. This standard is related to data elements and interchange formats – Information interchange – Representation of dates and times specifies date and times representation providing unambiguous notation and facilitating data migration between different systems.

What	Format	Sample
Year	YYYY	(eg 2015)
Year and month	YYYY-MM	(e.g., 2015-10)
Complete date	YYYY-MM-DD	(e.g., 2015-10-06)
Complete date plus hours and minutes	YYYY-MM-DDThh:mm	(e.g., 2015-10-06T17:35)
Complete date plus hours, minutes, and seconds	YYYY-MM-DDThh:mm:ss	(e.g., 2015-10-06T17:35:21)
Complete date plus hours, minutes, seconds, and a decimal fraction of a second	YYYY-MM-DDThh:mm:ss.s	(e.g., 2015-10-06T17:35:21.45)

YYYY = four-digit year
MM = two-digit month (01=January, etc.)
DD = two-digit day of month (01 through 31)
hh = two digits of hour (00 through 23) (am/pm NOT allowed)
mm = two digits of minute (00 through 59)
ss = two digits of second (00 through 59)
s = one or more digits representing a decimal fraction of a second

UTC (Coordinated Universal Time) is the time standard used for all dates.

The format is YYYY-MM-DDThh:mm:ss.sTZD (i.e. 2021-07-16T19:20:30.00+01:00) as described in the ISO 8601 standard or in Date and Time Formats of W3C

Job Life Cycle

TODO new image In the figure below, you can see the Job life cycle:

Creating a job

See creating a job.

What happens when you execute a job?

An execution involves as many entities as you reference in the JSON document. Therefore, you must expect one execution result per each entity you referenced. In other words, an execution explodes in many results.

The operations API lets you get both the operation summary and each result.

Reading a job report

See reading a job report.

Pause & Resume a job

Job execution can be paused and resumed using the Update operation modifying the “active” parameter:

Pause: setting active to false when a job is already running. The job passes to the PAUSE status.
Resume: setting active to true when a job is already paused. The job goes to the IN_PROGRESS status.

See updating job operation section.

Job Callbacks (Push service)

If the “callback” parameter is well configured when a job is created, the OpenGate platform will perform different callbacks (See figure below):

The following sections explain in detail callback execution.

Job Initiated Callback

The callback will be called when the initiated process has finished

Joined to the callback will be attached a JSON object including a Job object including:

id: With the JobId
request
report: object with the next objects:
execution
summary

Expand below to see an initiated Job callback example.

{
  "id": "a38f7735-dcef-4f5a-9ca4-b6a8f7517522",
  "request": {
    "name": "REBOOT_EQUIPMENT",
    "parameters": {
      "TYPE": "HARDWARE"
    },
    "active": true,
    "notify": false,
    "user": "[email protected]",
    "userNotes": "My notes"
  },
  "report": {
    "execution": {
      "activatedDate": "2014-03-12T11:43:35Z",
      "startedDate": "",
      "finishedDate": ""
    },
    "summary": {
      "status": "SCHEDULED",
      "total": 300,
      "inProgress": {
        "total": 0,
        "scheduled": 300,
        "pendingExecution": 0,
        "waitingForConnection": 0,
        "started": 0
      },
      "finished": {
        "total": 0,
        "successful": 0,
        "error": 0,
        "cancelled": {
          "total": 0,
          "byEngine": 0,
          "byUser": 0,
          "byTimeout": 0,
          "byExternalTimeout": 0,
          "byExternal": 0
        }
      },
      "finishedOutOfTime": {
        "total": 0,
        "successful": 0,
        "error": 0
      }
    }
  }
}

Job started callback

The callback will be called when the job is executed. If it is scheduled the job execution starts when the scheduling parameters indicate.

Joined to the callback will be attached a JSON object including a job object including:

id: job identifier
request: object
report: object
execution

Job callback example:

{
  "job": {
    "id": "33eb9dfa-7a87-41f7-9bad-7b5a26712fec",

    "request": {
      "name": "REBOOT_EQUIPMENT",
      "parameters": {
        "TYPE": "HARDWARE"
      },
      "notify": true,
      "user": "[email protected]"
    },

    "report": {
      "execution": {
        "activatedDate": "2010-12-20T10:10:00.00Z",
        "startedDate": "2010-12-20T10:10:00.00Z",
        "finishedDate": ""
      }
    }
  }
}

Job finished callback

The callback will be called after the Job execution is finished including the options.

When scheduling info indicates the job has terminated.
When the job is canceled.
When all the operations execution are completed.

Joined to the callback will be attached a JSON object including:

id: job identifier
request:
report: object with the next objects:
- execution
- summary
result: including the first page of operations result list with the objects
- page: object
- operations: array of “operation” objects

Job callback example:

{
  "job": {
    "id": "33eb9dfa-7a87-41f7-9bad-7b5a26712fec",

    "request": {
      "name": "REBOOT_EQUIPMENT",
      "parameters": {
        "TYPE": "HARDWARE"
      },
      "notify": true,
      "user": "[email protected]"
    },
    "report": {
      "execution": {
        "activatedDate": "2014-03-12T11:43:35Z",
        "startedDate": "2014-03-12T11:43:35Z",
        "finishedDate": "2014-03-12T11:44:52Z"
      },
      "summary": {
        "status": "FINISHED",
        "total": 3,
        "inProgress": {
          "total": 0,
          "scheduled": 0,
          "pendingExecution": 0,
          "waitingForConnection": 0,
          "started": 0
        },
        "finished": {
          "total": 2,
          "successful": 1,
          "error": 0,
          "cancelled": {
            "total": 1,
            "byEngine": 0,
            "byUser": 0,
            "byTimeout": 1,
            "byExternalTimeout": 0,
            "byExternal": 0
          }
        },
        "finishedOutOfTime": {
          "total": 1,
          "successful": 1,
          "error": 0
        }
      }
    },
    "result": {
      "page": {
        "number": 1,
        "of": 50
      },
      "operations": [
        {
          "operationId": "86dd3409-6fcd-49d4-be6b-b2fa497207ec",
          "entityId": "device_1",
          "resourceType": "entity.device",
          "name": "REBOOT_EQUIPMENT",
          "parameters": {
            "TYPE": "HARDWARE"
          },
          "notify": true,
          "execution": {
            "activatedDate": "2014-10-01T09:03:42Z",
            "startedDate": "2014-10-01T09:03:45Z",
            "finishedDate": "2014-10-01T09:04:45Z"
          },
          "user": "[email protected]",
          "status": "FINISHED",
          "result": "SUCCESSFUL",
          "description": "successful operation",
          "steps": [
            {
              "name": "RESET",
              "result": "SUCCESSFUL",
              "description": "Reset ok",
              "timestamp": "2012-09-27T16:46:02.10Z"
            }
          ]
        },
        {
          "operationId": "29891afd-5f4f-4b23-800e-586bd4ecb0eb",
          "entityId": "device_2",
          "resourceType": "entity.device",
          "name": "REBOOT_EQUIPMENT",
          "parameters": {
            "TYPE": "HARDWARE"
          },
          "notify": true,
          "execution": {
            "activatedDate": "2014-10-01T09:03:42Z",
            "startedDate": "2014-10-01T09:03:45Z",
            "finishedDate": "2014-10-01T09:04:45Z"
          },
          "user": "[email protected]",
          "status": "FINISHED",
          "result": "SUCCESSFUL",
          "description": "successful operation",
          "steps": [
            {
              "name": "RESET",
              "result": "SUCCESSFUL",
              "description": "Reset ok",
              "timestamp": "2012-09-27T16:46:02.10Z"
            }
          ]
        }
      ]
    }
  }
}

The HTTP method for push service is POST.

Tasks

The operations service API allows scheduling orders for a single execution at a given date or scheduling a task to run repeatedly over time you deem appropriate.

See task object at component/schemas/task.