Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Developer Guide: The Asset model and API
An asset can be anything that is connected to your system in some way. An asset is always attached to a tenant, so data is not shared between tenants. OpenRemote stores your current asset status in its database, and manages it in rules and flows. This collectively is called the context of your OpenRemote system.
An asset might be an actual external service or an installed device at some location, or you can use the asset hierarchy to model an organizational structure. An example would be a Customer asset that is the parent of some Device assets which are currently in use for that customer.
OpenRemote understands certain built-in asset types and provides extra functionality, such as Building, Floor, Residence, Room, Flight, and so on. There are also special assets such as an Agent, which links external services and devices with other assets.
The superuser has full access across all tenants (realms). An OpenRemote installation has only one superuser, and it's always named
admin and it's always in the
master realm. It cannot be renamed or deleted, just like the master realm. Any number of new realms and therefore tenants may be created.
Each realm can have regular users. Those would usually have administrative functions within a realm, they manage the realm. Depending on assigned roles, a regular user may read/write any asset data in the realm or manage other users in the realm.
An asset is by default private, it can only be accessed by the superuser or regular users of its realm. This can be relaxed by giving restricted or public access to assets.
A realm may have restricted users. The definition of such a user is a regular user that has been linked to a set of assets within its realm. This is a many-to-many relationship, an asset might be linked to many users, and a user might have links to many assets. The position of the assets within the asset tree is not relevant, linking a user with a parent doesn't mean it is linked to its child assets. The existence of linked assets is what makes a user "restricted". Assets which are linked to a user are not private or for managers only, yet still require authentication to access.
Consider the following example: You are the manager of a smart building with many apartments. A realm/tenant has been created for the whole building. The superuser who created the realm gives you a regular account in that realm and all the roles you need. You now want to give the residents of the apartments individual accounts, one per residence. You must limit what the residents can access within the building. Each resident's account should only be able to access a particular Residence asset, representing their apartment, but not the whole Building asset. To further limit access to the necessary minimum, you would then also give each resident access to some Room and Thing assets within the apartment. You would however not give access to any Agent assets, as this would allow the resident to configure connections to actual services and devices. Only managers should be allowed to do that; the same applies to any other assets you want to keep private.
Restricted users can only access their linked assets and depending on assigned roles, may read/write such asset data. The following limitations apply to restricted users/clients:
When a restricted client reads assets, only dynamic attributes with
AssetMeta#ACCESS_RESTRICTED_READand attribute meta items with
When a restricted client updates existing assets, new dynamic attributes can be added, but only attributes with
AssetMeta#ACCESS_RESTRICTED_WRITEcan be updated or deleted. Any new attributes are automatically set with
AssetMeta#ACCESS_RESTRICTED_WRITE, thus ensuring that a restricted client can fully access its own attributes. Any added, updated, or removed meta items of attributes must be
MetaItemDescriptor.Access#restrictedWrite. When a restricted client updates an asset attribute, it is assumed that the client performs an update with a complete list of writable meta items, that is, any existing writable meta items of an attribute will be removed and replaced with the writable meta items provided by the client.
A restricted client can not create or delete assets. A restricted client can not change the name, parent, or realm of an asset. A restricted user can not make an asset public. A restricted user can change the location of an asset.
Note that third-party metadata items (not in the
org.openremote.model.Constants#NAMESPACE) are never included by default in restricted read/write asset operations. To make third-party meta items read- or writable by restricted clients, provide meta item descriptors and desired access permissions through the
An asset can be made accessible by public clients without authentication by setting
true. The public client must use a query to retrieve such assets, see the public query operations on the
Any attributes of public assets are not public by default, they are private. To make an attribute public you must add
AssetMeta#ACCESS_PUBLIC_READ. Any meta items of such attributes are only included if they are
MetaItemDescriptor.Access#publicRead. Third-party meta items can be configured through the
You can read more following the docs on the main entry point: AssetResource.java