User definition
Users are defined by an opUser property in JSON file or by opUser.* columns in the user's sheet of an Excel file. You can define systems properties, roles, assign claims, give users access to sites and sources and configure sources access restrictions.
System properties
Master Data allow the set/modification of the following user system properties
Property | Mandatory | Default value if not set | Remark |
---|---|---|---|
FirstName | empty | ||
LastName | empty | ||
UserName | email value | ||
x | May not be empty | ||
Language | the language code of the theme | If specified, must be [FR,NL,EN,DE] | |
PhoneNumber | empty |
User email
The email is mandatary and must be unique across all users in the same account. If the user name is not provided, it will be set to the provided email.
Roles
The roles define part of the user's rights.
Although multiple roles may be granted to a user in DataHub, Master Data allows to set one single role user: either User or Manager.
Roles are defined by opUser.Roles keyword. There are 2 ways to define roles:
- Explicitely, where the role name of users in the data files is either User or Manager (see Explicit roles list (Excel) or Explicit roles list (Json) samples)
- Through mapping, were the role name of users in the data files corresponds to one of the keys specified in the mapping sheet of the JSON Master Data Template File (see Roles list (Excel) or Roles list (Json) samples)
Claims
Claims grant specific rights to a user. A claim is a key/value pair, the key being the granted right and the value being the right itself.
You can provide any claim key/value that you want but some specific claims are reserved for DataHub.
DataHub claims
DataHub claim keys
- http://opisense.opinum.com
- http://opisense.opinum.com/buildingproperties
- http://opisense.opinum.com/sensors
- http://opisense.opinum.com/event
- http://opisense.opinum.com/storage
- http://opisense.opinum.com/tickets
- http://opisense.opinum.com/control
- http://opisense.opinum.com/schedule
- http://opisense.opinum.com/settings
- http://opisense.opinum.com/reports
- http://opisense.opinum.com/triggers
- http://opisense.opinum.com/invoices
DataHub claim values
- NONE
- READ
- WRITE
- ADMIN
Important
By design, there is no way to delete a claim from a user. If you want to 'remove' a DataHub claim from a user, set it's value to 'NONE'.
Claims definition
Claims are defined by opUser.Claims identifier.
Users may have multiple claims. This is done in the [Master Data Temp(../glossary.md) by applying a CONVERT transformation that converts an alias into a list of claims (see Claims list conversion (Excel) or Claims list conversion (Json) samples).
If all users must have the same claims, you can omit the opUser.Claims definition in the users template sheet and apply a FORCE transformation on opUser.Claims in the JSON Master Data Template File, providing a list of claims that will be granted to any new user (see Force claims for all users (Excel) or Force claims for all users (Json) samples).
Assign sites and sources
MasterData allows to define sites and sources that each user may access. This can be done either in JSON or Excel.
Sites/sources merge mode
The merge mode dictates the way the MDE will grant site/source access to users. There are 2 merge modes :
- Set: the user's list of sites/sources provided by the JSON Master Data Upload File is interpreted as a discrete list will overwrite the current list (the current list of entities will be cleared prior to add the one provided by the [Master Data Uploaglossary.md) file.
- Merge: the user's list of sites/sources provided by the JSON Master Data Upload File is interpreted as a discrete list will be merged with the current rights (any existing rights will be preserved. It is not possible to remove sites/sources in this mode, you can only add entities.
If no merge mode is specified in the JSON Master Data Template File file, it will default to Merge.
Note
To remove all sites and/or sources from a user, use the Set mode and provide an empty list.
Warning
It is not possible to remove sites/sources from users using the Merge, you can only add entities.
Merge mode is defined by UserSitesAndSourcesMergeMode element in JSON file or by UserSitesAndSourcesMergeMode key in Excel file
Sources access restrictions
The purpose of the source restrictions is to grant user access to sources during one or many periods of time. A typical usage of source restriction is a user renting a house at Address1 that is able to see it's electrical power dashbord in DataHub. When it moves to another house at Address2, he must be able to see the data from the sources related to Address1 but only during the renting period.
If no period is specified, to user has access to all source data points. If at least one period is specified, the user has access to data points inside the specified period(s).
The element containing the sources restrictions is specify by a Validity sibling element of opUser.Sources in the opUser JSON Master Data Template File element.
Important
Only JSON files allow the definition sources access restrictions, there is no way to do it using Excel files.
Template
{
"OpUser": {
"RootPath": "myUsers[*]",
"Items": [
...
{
"OpIdentifier": "opUser.Sources",
"Path": "sourcesForUser[*].SourceSerialNumber",
"Validity": "RestrictionPeriods"
}
]
}
Warning
The Validity property is only meaningful as sibling of opUser.Sources, it is ignored in any other elements.
{
"myUsers": [
...
{
"EMAIL": "maintenance@opinum.com",
...
"sourcesForUser": [
{
"SourceSerialNumber": "SN0001",
"RestrictionPeriods": [
{
"from": "2006-01-01T00:00:00Z",
"to": "2017-12-31T00:00:00Z"
},
{
"from": "2019-01-01T00:00:00Z",
"to": "2020-03-31T00:00:00Z"
}
]
},
{
"SourceSerialNumber": "SN0002",
"RestrictionPeriods": [
{
"from": "2021-01-01T00:00:00Z",
"to": "2022-12-31T00:00:00Z"
},
{
"from": "2021-05-01T00:00:00Z",
"to": "2021-07-31T00:00:00Z"
}
]
},
{
"SourceSerialNumber": "SN0003"
}
]
}
]
}
Important
Dates must be expressed in UTC ISO 8601 format
Periods may overlap in the JSON Master Data Upload File, there are all merged to create as less holes as possible.
In the previous example, user ***maintenance@opinum.com*** is allowed to access the data points of the sources according to the following table:
Source | Stat date (included) | End date (excluded) |
---|---|---|
SN0001 | 2006-01-01T00:00:00Z | 2017-12-31T00:00:00Z |
SN0001 | 2019-01-01T00:00:00Z | 2020-03-31T00:00:00Z |
SN0002 | 2021-01-01T00:00:00Z | 2022-12-31T00:00:00Z |
SN0003 | No restriction | No restriction |
See Restrictions periods (Json) sample.
Sources access restrictions end
When a JSON Master Data Upload File contains a period that only mentions the end date, it indicates that this date is the end date for this user/source. Based on this information the MDE will ensure that none of the period end dates will exist beyond this date.
Based on the previous JSON data sample
{
"myUsers": [
...
{
"EMAIL": "maintenance@opinum.com",
...
"sourcesForUser": [
{
"SourceSerialNumber": "SN0001",
"RestrictionPeriods": [
{
"to": "2021-06-01T00:00:00Z"
}
]
},
{
"SourceSerialNumber": "SN0002",
"RestrictionPeriods": [
{
"to": "2021-06-01T00:00:00Z"
}
]
},
{
"SourceSerialNumber": "SN0003"
}
]
}
]
}
After the handling of the previous example, user ***maintenance@opinum.com*** is allowed to access the data points of the sources according to the following table:
Source | Stat date (included) | End date (excluded) |
---|---|---|
SN0001 | 2006-01-01T00:00:00Z | 2017-12-31T00:00:00Z |
SN0001 | 2019-01-01T00:00:00Z | 2020-03-31T00:00:00Z |
SN0002 | 2021-01-01T00:00:00Z | 2021-06-01T00:00:00Z |
SN0003 | No restriction | No restriction |
See Restrictions end (Json) sample.
When an end date only is provided, no other restriction periods is allowed, meaning that the folling file will be rejected:
Data
{
"myUsers": [
...
{
"EMAIL": "maintenance@opinum.com",
...
"sourcesForUser": [
{
"SourceSerialNumber": "SN0001",
"RestrictionPeriods": [
{
"to": "2021-06-01T00:00:00Z"
},
{
"from": "2021-01-01T00:00:00Z",
"to": "2021-06-01T00:00:00Z"
}
]
}
]
}
]
}
Important
If the end date is beyond the start date of a restriction period, this >start date will be set to the end date, which will deny user access to >this sources because the end date is excluded when querying data.
Imagine the first JSON Master Data Upload File content:
Data
{
"myUsers": [
...
{
"EMAIL": "maintenance@opinum.com",
...
"sourcesForUser": [
{
"SourceSerialNumber": "SN0001",
"RestrictionPeriods": [
{
"from": "2006-01-01T00:00:00Z",
"to": "2017-12-31T00:00:00Z"
},
{
"from": "2019-01-01T00:00:00Z",
"to": "2020-03-31T00:00:00Z"
}
]
}
]
}
]
}
The following JSON Master Data Upload File is then uploaded:
Data
{
"myUsers": [
...
{
"EMAIL": "maintenance@opinum.com",
...
"sourcesForUser": [
{
"SourceSerialNumber": "SN0001",
"RestrictionPeriods": [
{
"to": "2018-01-31T00:00:00Z"
}
]
}
]
}
]
}
The user will have access to SN0001 data points from 2006-01-01T00:00:00Z to 2017-12-31T00:00:00Z only.
Sources access restriction merge mode
The merge mode dictates the way the MDE will merge existing restrictions. There are 2 merge modes :
- Set: the user restrictions are replaced by those defined in the JSON Master Data Upload File.
- Merge: the user restrictions are merged by those defined in the JSON Master Data Upload File.
The merge mode is defined by UserRestrictionsSetMode element in the JSON Master Data Template File:
Template
"template": {
...
"config": {
"UserRestrictionsSetMode" : "Set"
}
...
}
Important
If no merge mode is specified in the JSON Master Data Template File, it defaults to Merge