An overview of important concepts and hierarchies you will encounter when using our services.
We have created a flexible yet simple hierarchy for organizing devices into projects. The figure below shows how the various services are interconnected, each of which is explained in the following sections.
The organization is the top level in the hierarchy and represents the legal entity that owns the sensors and is invoiced for device subscriptions. This could be an organization, a department within an organization, or an individual.
Organizations and projects can have members with different roles. A member can be either a User or a Service Account. By default, the person who creates an organization is made an Organization Administrator who can create new projects and invite new members.
Projects are used within an organization to create a collection of devices. The intention is to make it easier for users to get an overview and manage access control of select devices. An Organization Admin can create as many new projects as they see fit, and they can add and grant new members access to specific projects.
Although users can create as many projects as they want, every organization starts with a default project called Inventory.
A Project Member is a user or a Service Account with access to the devices in a project. A role determines the access level for the user or Service Account and must be assigned to each new Project Member that is created. See roles for more information about the types of roles available.
Service Accounts are used to give other services access to projects through the use of REST APIs. While a user represents a person and is used for logging in to DT Studio, Service Accounts represent services like programs running on another server. See our guide on Creating a Service Account.
Once a Service Account is created, it has to be added as a member to one or more Projects or Organizations and assigned a Role that determines what it is allowed to view or edit.
Keys are credentials used by an application to authenticate the Service Account against our cloud service. A Service Account can be issued multiple keys that can be used by one or several services.
Data Connectors are used to reliably send data from sensors in a project to a 3rd party service. A project can have multiple Data Connectors, and the data sent through each one can be configured using DT Studio or our REST API.
Event is a term used to describe a collection of data sent between services. This is primarily sensor measurements such as temperature and other things such as when the labels for a device change. All event types will have the same base JSON structure, and the data related to the specific event is represented in the
datafield found within.
Labels are key-value pairs that can be assigned as metadata to a device through DT Studio or using the REST API. Each device can have multiple labels, and they can be used as a filter when listing devices or setting up event streams. They can also be included in the JSON structure for the events that are pushed to Data Connectors.
Labels are a great way to group and organize devices within a project. Typical use-cases for labels include specifying which floor or building the devices are installed in, the current status of a device, such as if it is currently being installed or not, or a tag to make it easier to search for it in 3rd party services.
DT Studio uses labels with the keys
descriptionto show as the display name and the description of a device. It is recommended that an integration uses these labels in the same way when displaying or updating a device.