# Operations

# Introduction

# Why do you need an operations service?

If you’re reading this document, then you’re interested in device monitoring and management, maybe you’re involved in the operations department in your company. If so, then you usually execute operations on your remote devices, like reboot or send an ICMP ping it to check its availability. OpenGate comes to help you with your massive field operations. The operations service API is the programmatic way to perform your operations using OpenGate.

# Existing Operationes

The platform implements by default a set of device operation types that are ussually implemented by the device. Find the list in the Default Operations Catalog.

# New operations

The operations engine is a powerful and extensible tool, so new operations can be created to cover new needs on demand. The OpenGate operations API is very flexible, you can configure each operation with the operation name and the parameter list to be used. Using this interface you can invoke new operations without change the programmatic interface.

# Rich operations

The underlying OpenGate engine supports multi step operations, therefore when you invoke the execution of an operation, you must expect a list containing the result of each single step.

# Executing operations

The operations API is not an exception, it fits the REST architectural style. While the provision service makes an extensive use of entity/collection pattern, the operation service implements the command pattern. How does it? Easy, OpenGate manages operations as entities, so when you want to execute an operation you only have to send a POST request with an operation object.

Yes, this use of REST could inflame some religious war, but we are in the real operations world, so please take it easy, it simply works fine.

WARNING

A single operation could be executed on a few entities or on thousand of entities if you use a tag instead a target array. So please, use it with caution.

The list of the operation types are defined in the section Default Operations Catalog.

# Execution modes

The operations service API provides two ways to execute an operation, tasks and jobs. A job immediately executes the operation on remote devices, while a task define scheduled jobs whose programming options detailed below.

# Jobs

# Job object

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

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

# JSON as interchange format

OpenGate Data Collector uses JSON as interchange format in its RESTful interface. 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 facilitates data migration between different systems.

What Format Sample
Year YYYY (eg 2015)
Year and month YYYY-MM (eg 2015-10)
Complete date YYYY-MM-DD (eg 2015-10-06)
Complete date plus hours and minutes YYYY-MM-DDThh:mm (eg 2015-10-06T17:35)
Complete date plus hours, minutes and seconds YYYY-MM-DDThh:mm:ss (eg 2015-10-06T17:35:21)
Complete date plus hours, minutes, seconds and a decimal fraction of a second YYYY-MM-DDThh:mm:ss.s (eg 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 standart used for all dates.

Open resource of documentation at Wikipedia (opens new window)

# Job Life Cycle

In the figure below you can see the Job life cycle: 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 individual result.

Figure 4. Job summary and results

# Reading a job report

See Reading a job report

# Pause & Resume a job

A Job execution can be paused and resumed using the Update operation modifying the "active" parameter:

  • Pause: Setting "active" to false when Job is already running. The Job passes to the PAUSE status

  • Resume: Setting "active" to true when Job is already paused. The Job passes to the IN_PROGRESS status

See Updating Job operation section.

# Job Callbacks (Push service)

If "callback" parameter is well configured when Job is created, the OpenGate platform will perform different callbacks (See figure below):

Figure 5. Push Callback Flow

The callbacks executed are:

# 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 bellow to see an initiated Job callback example.

DETAILS
{
  "id": "a38f7735-dcef-4f5a-9ca4-b6a8f7517522",
  "request": {
    "name": "REBOOT_EQUIPMENT",
    "parameters": {
      "TYPE": "HARDWARE"
    },
    "active": true,
    "notify": false,
    "user": "user@mail.com",
    "userNotes": "My notes"
  },
  "report": {
    "execution": {
      "activatedDate": "2014-03-12T11:43:35Z",
      "startedDate": "",
      "finishedDate": ""
    },
    "summary": {
      "status": "SCHEDULED",
      "total": 300,
      "inProgress": {
        "total": 0,
        "scheduled": 0,
        "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 after the Job execution is started

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

Expand bellow to see a started Job callback example.

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

    "request": {
      "name": "REBOOT_EQUIPMENT",
      "parameters": {
        "TYPE": "HARDWARE"
      },
      "notify": true,
      "user": "user@mail.com"
    },

    "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 cancelled
  • 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

Expand bellow to see a finished Job callback example.

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

    "request": {
      "name": "REBOOT_EQUIPMENT",
      "parameters": {
        "TYPE": "HARDWARE"
      },
      "notify": true,
      "user": "user@mail.com"
    },
    "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",
          "entityType": "GATEWAY",
          "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": "user@mail.com",
          "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",
          "entityType": "GATEWAY",
          "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": "user@mail.com",
          "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 provides the option of scheduling orders, either for a single execution at a given date or to schedule a task to run repeatedly over time you deem appropriate.

See Task object at component/schemas/task