Entities

Entities provisioning

• Entity types & statuses
• Devices
• Subscriptions
• Subscribers
• Assets
• Bulk provisioning

Entity object structure

In the context of the Internet of Things (IoT), an entity represents any monitoring element.

OpenGate offers four types of entities: asset, device, subscription, and subscriber. The resourceType field is used to set the entity type. The following table illustrates the process for setting each entity type:

Common objects and attributes

All the entities have several attributes, objects, and arrays in common. The following sections provide further details on these shared objects.

{
  "provision": {
    "administration": {
      "channel": {
        "_current": {
          "value": "wind_farm_channel"
        }
      },
      "organization": {
        "_current": {
          "value": "wind_farm_organization"
        }
      },
      "serviceGroup": {
        "_current": {
          "value": "emptyServiceGroup"
        }
      }
    },
    "device": {
      "identifier": {
        "_current": {
          "value": "wind_mill_id"
        }
      }
    }
  }
}

Identifier attributes

OpenGate supports a variety of entities, each of which is identified by a unique identifier.

Administrative data attributes

• id: Each Internet of Things (IoT) entity on the platform is assigned a unique identifier automatically by the platform.
• provision.device.identifier: The customer-generated ID is a string that identifies a device in a specific organisation.. HTTP/1.1 201 Created Location: http://api.opengate.es/north/v80/provision/organizations/{organizationName}/devices/device_1 It is imperative that you use this identifier as a URL suffix when you wish to retrieve, update or delete your device.
• provision.device.communicationModules[].identifier: The customer-generated ID is a string that identifies a communication module.
• provision.device.communicationModules[].subscription.identifier: It is a customer-generated identifier comprising a string that identifies a subscription.
• provision.device.communicationModules[].subscriber.identifier: It is a customer-generated identifier comprising a string that identifies a subscriber.

Administration object attributes

It is a requirement for all OpenGate entities to operate within an administrative context.

Attributes

• organization: the organization that owns the entity.
  • Forbidden in entity update operation
  • Required in entity insert operation
  • Constraints: [a-zA-Z0-9] max 50 chars The “channel” designation is an administrative grouping method for your entities.
• channel: an administrative grouping method for your entities.
  • Required in entity insert operation.
  • Constraints: [a-zA-Z0-9] max 50 chars The “channel” designation is an administrative grouping method for your entities.
• administrativeState: see administrativeState values

• serviceGroup: Service configuration: configuration of services, operations available, etc.
  • Constraints: [a-zA-Z0-9] max 50 chars The “channel” designation is an administrative grouping method for your entities.
  • Forbidden in bundle operations.
• workgroup: the workgroup is the way to establish the relationships between devices and users. It’s used, for example, when you want to create software bundles.
  • Constraints: [a-zA-Z0-9] max 50 chars
  • This field only applies to OpenGate users. -plan (optional): an administrative concept that allows limiting the number of events sent by the device, this concept only applies to devices
  • Constraints: [a-zA-Z0-9] max 50 chars
  • Forbidden in bundle operations.
  • Optional in entity insert and update operation.

{
  "provision": {
    "administration": {
      "channel": {
        "_current": {
          "value": "YOUR_CHANNEL_NAME"
        }
      },
      "organization": {
        "_current": {
          "value": "YOUR_ORGANIZATION_NAME"
        }
      },
      "serviceGroup": {
        "_current": {
          "value": "SERVICE_GROUP_FOR_THE_ENTITY"
        }
      },
      "plan": {
        "_current": {
          "value": "FLOW_RATE_100"
        }
      }
    }
  }
}

Service group

It is of the utmost importance to select the correct entity service group. The service group you choose will determine how OpenGate behaves when managing your devices in the following ways:

• Permitted operations.
• This document outlines the process by which the platform transmits scheduled operations to devices.
  • Always: This type is designed for devices that are continuously connected. In this scenario, OpenGate will initiate operations on the devices in accordance with the pre-defined schedule. In the event that the target device is not connected, the operation will be cancelled and an error message will be generated. On-session-connection: In this instance, the platform saves operations for subsequent use. Upon establishing a connection with the platform, the device will be notified of any pending operations and these will be sent to the device. This mode is applicable to devices utilising web sockets or MQTT connectors.
  • On-demand: In this instance, the device will request any outstanding operations. This approach enables devices to conserve battery power and retrieve pending operations when active.

• Trusted boot: It is a requirement that all messages received by the platform include a field with the trusted boot value. In the absence of this field, OpenGate will reject the message.
• Device security mode: This option allows you to select the desired security level for communications between the device and platform. The available options are:
  • Please note that all communications will not be encrypted.
  • Level 1: One-way authentication (or platform authentication). The platform is the sole entity responsible for authenticating itself to the client. It issues the client a certificate to confirm the platform’s authenticity.
  • At Level 2, both the client and the server authenticate themselves to each other, ensuring the veracity of the certificate presented by the platform.
  • At Level 3, both the client and the server authenticate themselves to each other, confirming the availability of the platform’s device certificate.

Service groups available on OpenGate cloud instance

Plan feature

As outlined in the organization’s plan, usage limits are to be established for the OpenGate platform. In the case of entities, if your organization has not defined a collection event limit, it must be set at the time of entity creation.

Flattened format

It is possible to create and search for data stream values (see default data models) using the flat format. This format is the same as that used on the South API. To indicate if data streams are in a flattened form, use the Boolean parameter ‘flattened’ in the URL.

The format is:

{
  "parameter1_id": {
    "_value": {
      "_current": {
        "value": "value1"
      }
    }
  },
  "parameter2_id": {
    "_value": {
      "_current": {
        "value": "value2"
      }
    }
  },
  ...
  "parameterN_id": {
    "_value": {
      "_current": {
        "value": "valueN"
      }
    }
  }
}

The following examples demonstrate the process of transforming a hierarchical JSON format into a flattened JSON format. There are two types of values: simple and complex.

Simple values

The hierarchical JSON format is:

{
  "provision": {
    "administration": {
      "identifier": {
        "_current": {
          "value": "device_battery"
        }
      }
    }
  }
}

The flattened JSON format is:

{
  "provision.administration.identifier": {
    "_value": {
      "_current": {
        "value": "device_battery"
      }
    }
  }
}

Complex values

To illustrate this concept, we will examine two contrasting examples.

The hierarchical JSON format is:

{
  "provision": {
    "device": {
      "location": {
        "_current": {
          "value": {
            "position": {
              "type": "Point",
              "coordinates": [-3.7028, 40.41675]
            },
            "postal": "28013"
          }
        }
      }
    }
  }
}

The flattened JSON format is:

{
  "provision.device.location": {
    "_value": {
      "_current": {
        "value": {
          "position": {
            "type": "Point",
            "coordinates": [-3.7028, 40.41675]
          },
          "postal": "28013"
        }
      }
    }
  }
}

Another example:

The hierarchical JSON format is:

{
  "provision": {
    "device": {
      "communicationModules": [
        {
          "identifier": {
            "_current": {
              "value": "commsMod_battery_id"
            }
          },
          "name": {
            "_current": {
              "value": "commsMod_battery_name"
            }
          }
        }
      ]
    }
  }
}

In the context of creative operations, the flattened JSON format is as follows:

{
  "provision.device.communicationModules[].identifier": [
    {
      "_index": {
        "value": "commsMod_battery_id"
      },
      "_value": {
        "_current": {
          "value": "commsMod_battery_id"
        }
      }
    }
  ],
  "provision.device.communicationModules[].name": [
    {
      "_index": {
        "value": "commsMod_battery_id"
      },
      "_value": {
        "_current": {
          "value": "commsMod_battery_name"
        }
      }
    }
  ]
}

In the case of a reading operation, the flattened JSON format is as follows:

{
  "provision.device.communicationModules[].identifier": [
    {
      "_index": {
        "path": "provision.device.communicationModules[].identifier",
        "value": {
          "_current": {
            "value": "commsMod_battery_id",
            "provType": "MONITORING",
            "date": "2017-09-25T09:34:32.119Z"
          }
        }
      },
      "_value": {
        "_current": {
          "value": "commsMod_battery_id",
          "provType": "MONITORING",
          "date": "2017-09-25T09:34:32.119Z"
        }
      }
    }
  ],
  "provision.device.communicationModules[].name": [
    {
      "_index": {
        "path": "provision.device.communicationModules[].identifier",
        "value": {
          "_current": {
            "value": "commsMod_battery_id",
            "provType": "MONITORING",
            "date": "2017-09-25T09:34:32.119Z"
          }
        }
      },
      "_value": {
        "_current": {
          "value": "commsMod_battery_name",
          "provType": "MONITORING",
          "date": "2017-09-25T09:34:32.169Z"
        }
      }
    }
  ]
}

We will also demonstrate how to transform the existing normalised/flattened JSON examples into CSV format. The above examples will be joined together in a single CSV file comprising three lines, one for each example (a straightforward example and two complex examples).

Transforming the flattened format into CSV format is a relatively straightforward process, as the CSV file’s content adheres to the same guidelines as the flattened format. The first line (header) contains the name of the data stream, separated by “;”, and the following lines represent the different entities, with the field value of the data stream separated by “;” in the same order as the first line.

The following lines illustrate the format of a CSV file.

provision.administration.identifier;provision.device.location;provision.device.communicationModules[].identifier;provision.device.communicationModules[].name
device_battery;;;
;"{"position":{"type":"Point","coordinates":[-3.7028,40.41675]},"postal":"28013"}";;
;;commsMod_battery_id;commsMod_battery_name

In the event that an entity contains a unique communication module, it is possible to indicate the name without the use of square brackets and without the inclusion of an identifier. In light of this, it can be seen that the two strings in question, namely [commsMod_battery_name(commsMod_battery_id)] and commsMod_battery_name, are identical.

Comprehensive API actions

Searching entities

This API enables the retrieval of a comprehensive list of entities, offering a multitude of options for:

• Filtering (see Specific Filter Fields)
• Sorting (see Sorting)
• Selecting Required Fields (see Selecting)
• Summarising (see Summary)

The results can be obtained in two distinct formats:

• JSON Format (Default)
• CSV Format

Additionally, the results can be obtained in a flattened format through the use of flattened parameters.

API specification