# Common objects and attributes

All the entities have several attributes, objects and arrays in common. The attributes associated to these common objects are shown in the following sections.

Common objects and attributes

{
  "provision": {
    "administration": {
      "channel": {
        "_current": {
          "value": "battery_channel"
        }
      },
      "organization": {
        "_current": {
          "value": "battery_organization"
        }
      },
      "serviceGroup": {
        "_current": {
          "value": "emptyServiceGroup"
        }
      }
    },
    "device": {
      "identifier": {
        "_current": {
          "value": "device_battery_id"
        }
      }
    }
  }
}

# Identifiers Atributes

There are different identifiers for entities_

Administrative data attributes

  • id
    • Description: Each IoT entity have a unique identifier all over the platform. This identifier is auto generated by the platform (UUID format).
  • provision.device.identifier
    • Description: It is a customer generated id consisting in a string that identifies a Device in a specific organization. HTTP/1.1 201 Created Location: http://[your_opengate_address]/north/v80/provision/organizations/{organizationName}/devices/device_1 You must use this identifier as URL suffix when you want to get, update or delete your device.
  • provision.device.communicationModules[].identifier
    • Description: It is a customer generated id consisting in a string that identifies a Communication Module
  • provision.device.communicationModules[].subscription.identifier
    • Description: It is a customer generated id consisting in a string that identifies a Subscription
    • provision.device.communicationModules[].subscriber.identifier
    • Description: It is a customer generated id consisting in a string that identifies a Subscriber

# Administration object attributes

This object and all its attributes are required and must be created using the OpenGate Administration Console prior to use them in provision operations.

All OpenGate entities must be included into an administration context. The administrative data contains specific data attributes, some of which are required and some of which are optional.

# Atributes


organization
  • Constraints
    • [a-zA-Z0-9] max 50 chars
  • Description The organization that owns the entity.
    • Forbidden in entity update operation
    • Required in entity insert operation

In entity POST & PUT operations this field will be ignored because the used organization value is taken from the URL. It is included to maintain compatibility with the objects returned in search operations.

channel
  • Constraints
    • [a-zA-Z0-9] max 50 chars
  • Description An administrative grouping method for your entities.
    • Required in entity insert operation
administrativeState
serviceGroup
  • Constraints
    • [a-zA-Z0-9] max 50 chars
  • Description Service configuration: configuration of services, operations available, etc.
    • Forbidden in bundle operations
workgroup
  • Constraints
    • [a-zA-Z0-9] max 50 chars
  • Description 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.
    • Forbidden in entity operations
plan (optional)
  • Constraints
    • [a-zA-Z0-9] max 50 chars
  • Description An administrative concept that allow limit the number of events sent by the device, this concept only applies with devices
    • Forbidden in bundle operations
    • Optional in entity insert and update operation

Administrative data as JSON document into a device entity

{
  "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 concept

Please pay special attention to the entity service group, you must select the appropiate service group because there are several ways of behaviour determinated by a service group, the options are:

  • Operations that can be performed

  • How the platform send the scheduled operations over the devices

    • Always, this type is oriented to devices allways connected, in this case the operation will be sent to the device according to the schedule

    • Session connected, this type is oriented to devices that use web socket or mqtt conections. In this case the platform save the operations in its store and when the device open the conection with the platform automatically, the platform will detect this conection and will send the pending operations to the device.

    • On demand, this type is oriented to devices that only open their connections for some seconds in order to save battery, In this case the device will send a special post to the platform for request pending operation.

      You can use in the case of mqtt connections the option "on Demand" if you want that all the operations will be requested by the device

  • Trusted boot, all the message received by the platform has mandatory to have a field with the trusted boot value, if not the message will not collected

  • Device security mode, with this option you can select the level of security in the comunications between the device and platform. You can choose between:

    • None, all the comunications won’t be encrypted

    • Level 1, One-way authentication (or platform authentication): Only the platfotm authenticates itself to the client. The platform sends the client a certificate verifying that the platform is authentic.

    • Level 2, Two-way authentication (or bilateral authentication): Both client and server authenticate themselves to each other verifying that the certificate autenticator it’s available in the platform

    • Level 3, Two-way authentication with certificate checking: Both client and server authenticate themselves to each other verifying that the device certificate is available in the platform.

Service Groups available on OpenGate Cloud instance

Name Entity Type Operation Group Operation on Demand Security Mode Trusted Boot
emptyServiceGroup Asset, Gateway, Communications Module, Subscriber, Subscription emptyServiceGroup Send Always None disabled
emptyServiceGroup onDemand Asset, Gateway emptyServiceGroup Send On Demand None disabled
emptyServiceGroup onSession Asset, Gateway emptyServiceGroup Send On Session Connection None disabled
level1SecurityServiceGroup Asset, Gateway emptyServiceGroup Send Always Level1 disabled
level2SecurityServiceGroup Asset, Gateway emptyServiceGroup Send Always Level2 disabled
level3SecurityServiceGroup Asset, Gateway emptyServiceGroup Send Always Level3 disabled
noUpdate Asset, Gateway, Communications Module noUpdate Send Always None disabled
trustedLevel1SecurityServiceGroup Asset, Gateway emptyServiceGroup Send Always Level1 enabled
trustedLevel2SecurityServiceGroup Asset, Gateway emptyServiceGroup Send Always Level2 enabled
trustedLevel3SecurityServiceGroup Asset, Gateway emptyServiceGroup Send Always Level3 enabled
trustedNoneSecurityServiceGroup Asset, Gateway emptyServiceGroup Send Always None enabled
trustedNoneSecurityServiceGroup_onDemand Asset, Gateway emptyServiceGroup Send On Demand None enabled

# Plan Concept


This concept is very interesting in OpenGate, this is the way to limit the number of events recived by the platform from a concrete organization or sent by an specific device. One organization must have assigned an specific plan where you can fix:

  • Maximum device. The maximun number of devices, gateways or assets, that an organization can have

  • Max storage. The maximun period of time for storing the historical data

  • Flow Rate. The maximum number of event recibed by the platform in a period of time

In the devices of an organization you can specify a diferent plan where you can change only the flow rate

# Flattened concept


This concept allows send and receive a datamodel parameters list (see Default Datamodels) with the flattened format in the devices provision and in the responses of the search. In this way is the same that is received and sent by the south api. It is used a boolean parameter, flattened, in the URL to indicate if the file to send/receive is in flattened format.

The format is:

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

In the following examples, we can see how is transformed a normal json format to flattened json format. There are two types of values, simple and complex:

Simple values

The normal json format is:

example normal json format with simple value

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

The flattened json format is:

example flattened json format with simple value

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

Complex value

We are going to see two different examples to clarify this concept

Example1 The normal json format is:

example1 normal json format with complex value

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

The flattened json format is:

example1 flattened json format with complex value

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

Example2

The normal json format is:

example2 normal json format with complex value

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

The flattened json format when it is a creative operation is:

example2 flattened json format with complex value in creative operation

{
  "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"
        }
      }
    }
  ]
}

The flattened json format when it is a reading operation is:

example2 flattened json format with complex value in reading operation

{
  "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"
        }
      }
    }
  ]
}

Also, we are going to see how is transformed the previous normal/flattened json examples into to CSV format. We are going to join examples above in a unique csv file with three lines one for each examples above (one simple example and two complex examples)

It is easier to transform flattened format into csv format because the content of csv file follows the same guidelines to flattened format. The first line (header) contains the name of datastream separated by ";" and the next lines are the different entities and contains the field value of the datastream separated by ";" in the same order as the first line

csv format example

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
To clarify the csv, when the entity contains an unique communication module, it is possible indicates the name without [] and without the identifier [commsMod_battery_name(commsMod_battery_id)] or commsMod_battery_name,it is the same