Skip to content

Guide: Modeling Organization and Systems

This guide discusses how to use the group structure for modeling organizational access controls and functionality for organizing complex equipment systems as assets.

What you should learn from this guide:

Group Hierarchy can be used for any combination of:

  • Locales / Sites / Locations
  • Customers
  • Physical or Administrative Organization of assets
  • Regional support / sales / administration
  • Divisions with a larger organization
  • Direct customers vs Partner/Distribution managed customers

The ExoSense group hierarchy functionality is designed to be flexible to handle many different kinds of organizations, whether used to monitor assets at a single location or to deploy to a global customer base. Ownership and Access of objects in ExoSense are at the group level - Assets, IoT Devices, etc. This group can be at any depth in the access hierarchy tree and represent any number of physical or business aspects.

Groups are Dynamic

Assets, IoT devices, and child-groups may be moved to another group in the hierarchy tree to allow for changes in structure over time. This flexibility provides options for maintaining viewing and access rights to users as a part of companies, sites/locations, groups inside a location, etc.

Overview of objects and their relation to the group hierarchy:

  • Users

    • When a user is invited to a group, this defines their access and home group.
    • Users are unaware of any other hierarchy higher in the tree.
    • Users may be moved by a user with user management permission existing at the same group level or higher.

  • Roles

    • A user's Role specifies the functionality they have access to at their home group level and below.
    • Roles are available to users in sub-groups of the group the role was created in.
    • Typically solution wide / common roles are defined at the root level with more unique roles added to child sub-groups in the tree.

  • Assets

    • Assets, which represent machines, equipment, and systems, are created in a group.
    • Users with access to this group or higher in the hierarchy tree have access to this Asset.

  • Devices

    • Devices are 'owned' by a group, either by claiming or assignment.
    • Once a device exists at a group, any asset may use it as a source of data within this group or in any lower child sub-groups.

  • Asset Templates

    • Asset Templates are tied to a group. Any user in that group or child sub-groups may use it to create new assets or migrate existing assets to.
    • For solution wide templates, add to the root level.
    • For group (e.g. a customer) templates, add to that specific group.

Business Model Questions

Before getting to far, it's good to think about some business model questions.

  • What is being sold? What's the business model?
  • How will customers use the solution compared to internal teams?
  • Who will install the hardware solutions and setup assets?

These will help to think about building out the grouping structure and roles along with needs for automation.

Example: Customers as Groups

A machine builder or equipment provider might build out a group hierarchy model with each of the first level groups representing a customer. This allows the machine builder's team to exist at the root level, with access to create solution structure, roles, and asset templates, while onboarding each unique customer into their own group.

The users at this equipment provider added at the root are going to be able to view all of the customer group nodes. This allows them to onboard new customers by creating a group and inviting users to that customer group. In addition, users at the root level can create roles to be used solution wide (or down at a customer) and create Asset Templates to be used solution wide (or at a customer).

Root User Hierarchy
[GROUP] Root 
│  ├── Users 
│      ├─ Root User 1
│      ├─ Root User 2
│      └─ ...
│
├── [GROUP] Customer A 
│    ├── Users 
│    │   ├─ User A1
│    │   ├─ User A2
│    │   └─ ...
│    ├── IoT Devices 
│    │   ├─ device1
│    │   ├─ device2
│    │   └─ ...
│    └── Assets 
│        ├─ Machine 1
│        ├─ Machine 2
│        └─ ...
│
├── [GROUP] Customer B
│    ├── ...
│
├── [GROUP] Customer C
│    ├── ...
│
...
│
└── [GROUP] Customer N

Users invited to the customer group (example Customer A) are only aware of their sub hierarchy, this is their home as far as they are considered in the application. If a customer user has the Group Management permission through their role, they would be able to build out their own sub-group hierarchy.

From that customer user's perspective, the hierarchy looks like:

Customer A User Hierarchy
Home 
  ├── Users 
  │   ├─ User A1
  │   ├─ User A2
  │   └─ ...
  ├── IoT Devices 
  │   ├─ device1
  │   ├─ device2
  │   └─ ...
  └── Assets 
      ├─ Machine 1
      ├─ Machine 2
      └─ ...

Tips

  • Plan it out first - Although the group structure is very flexible and can always be changed, it's good to plan out the hierarchy ahead of time and ensure standard conventions are used each time so later on your team isn't having to go clean things up.
  • Create groups at the root called such as Admin, Development, and Internal. Use these for creating assets to use for Asset Template, testing new functionality, and internal use cases (sales demos, internal use cases, etc).
  • Plan out and think about solution wide roles based on internal and customer user personas in addition to what functionality and access is being sold. More customized roles (even if just a different name) can be created at each Customer group but that can be a lot of manage and administrate.

Example: Divisions and Regions

For a larger organization that may have 100's or 1000's of customers, it often makes sense to create more grouping categorization of customers. This could also be applied to a company with many divisions and sites.

This allows adding administrative and/or support users into those regions or divisions in the overall organization. This might also be leveraged in use cases with distribution partners, so the structure may align more with partners vs direct customers.

Regional Organizational Root User Hierarchy
Root 
│  └── Users 
│      ├─ Root User 1
│      ├─ Root User 2
│      └─ ...
│
├── APAC 
├── EMEA 
├── North America 
│    │  └── Users 
│    │     ├─ Regional Admin User 1
│    │     ├─ Regional Support User 2
│    │     └─ ...
│    │
│    ├── Northeast
│    ├── Southeast
│    └── Midwest
│         │
│         ├── Customer A 
│         │    ├── Users 
│         │    ├── IoT Devices 
│         │    └── Assets 
│         │
│         ├── Customer B
│         │    ├── ...
│         │
│         ├── Customer C
│         │    ├── ...
│         │
│         ...
│         │
│         └── Customer N
│
│
└── South America

Example: Site Locations

A business may use groups to organize their equipment across varies sites and locations for limiting access and/or for helping to organize, monitor, and report on their assets in each of these locations. These locations may also have their own sub-grouping such as different buildings or places at the site location to further group assets.

Business Site Locations Root User Hierarchy
Root
│  ├── Users
│      ├─ Business Admin User 1
│      ├─ Business Support User 2
│      └─ ...
│
├── Minneapolis Site
│    ├── Users 
│    │   ├─ Minneapolis Technician User
│    │   ├─ Minneapolis Manager User
│    │   └─ ...
│    ├── IoT Devices
│    │   ├─ device1
│    │   ├─ device2
│    │   └─ ...
│    │
│    ├── West Building
│    │     └── Assets
│    │         ├─ Machine 1
│    │         ├─ Machine 2
│    │         └─ ...
│    │
│    └── North Building
│          └── Assets
│              ├─ Machine 1402
│              ├─ Machine 141
│              └─ ...
│
├── Duluth Site
│    ├── ...
│
├── Luverne Site
│    ├── ...
│
└── Hardwick Site
     └── ...

Onboarding and Automation

Group / Customer / User Onboarding

To onboard a new group, in this example as representing a Customer, a root user can create the new group, name it for the customer and invite users to it. This can all be handled in the application.

If this was a process that was repeated often, this onboarding process may be automated using the ExoSense API. This automation could be tied into existing CRM and/or billing tools or by using a form or registration website.

Automation Example

  1. Form / Registration / Contract submitted triggers script or service.

  2. Create a new Customer group with a Name and Description for the customer.

    ExoSense API GraphQL Request Example: Create a Group
    {
    "query":"mutation ($group: CreateGroup) { createGroup(group: $group) {id}}",
    "variables":
    {
        "group":
        {
            "parent_node_id":"<parent_group_uuid>",
            "name":"Customer Example",
            "description":"Organization of Customer Example",
            "custom_id":"cust_example"
        }
    }
}

  3. Invite the users from the customer into this new group at the role you plan to use for these customers.

    ExoSense API GraphQL Request Example: Invite User(s)
    {
    "query":"mutation InviteUser($invite: Invitation) { inviteUser(invite: $invite) {id}}",
    "variables":
    {
        "invite":
        {
            "email":"newuser@examplecompany.com",
            "locale":"en",
            "role_id":"<unique_role_uuid>",
            "group_ids":["<new_group_uuidd>"]
        }
    }
}

Device Onboarding

The IoT edge device gateways and sensors that will be installed and connected at the customer also need to be onboarded or 'assigned ownership' to the customer group. This can also be completed in the application by the equipment provider (root users) or by the Customer users. Once devices are claimed/assigned to the customer group, they can be used as sources for Asset signals.

Device assignment and claiming can be automated with the ExoSense API.

Device Managment

Asset Creation

If the equipment has a standard definition of signals, rules, dashboards, etc, Asset Templates are ideal for creating new assets to represent the equipment at the customer. Alternatively if each installation is customized, from a device (or devices) an asset can be created unique to the machine using the device's channels.

The root Equipment provider should provide Asset Templates to be used site wide. Any assets created will be duplicate of the template, just using different IoT device sources. From there, the asset can continue to track with the Asset Template to receive updated versions or stopped from tracking the template to be customized from there.

Asset creation using templates can be automated with the ExoSense API.

Assets Overview

Additional References