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
Email 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:

  1. 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)
  2. 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

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 :

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