JSON Master Data template
The template file tells the MDE where to find each piece of information in your data file, and which Insights property to put it in. It is uploaded once and reused by every subsequent data file — see the two-file model.
Structure of the root object
The root object holds a configuration part and one property per entity type. All of them are optional except the ones your data actually carries.
| Root property | Holds |
|---|---|
Account |
The account name and id this template belongs to. |
Config |
The behaviour to apply when processing a Master Data Upload file — Whatif, merge mode, customizer. |
OpSite |
Where the site nodes are, and how their properties map. |
OpSource |
Where the source nodes are, and how their properties map. |
OpVariable |
Where the variable nodes are. Only variable names are read. |
OpEvent |
Where the event nodes are, and how their properties map. |
OpUser |
Where the user nodes are, and how their properties map. |
Every entity property follows the same shape: a RootPath, which is a
JSON path locating the nodes in the data file, and a list of
Items mapping each node property to a Insights property. The items themselves are described in
JSON template items.
Tip
Start from the entity you care about rather than from the top: read
OpSite or OpSource first, then come back here to see how
the pieces sit together.
Note
The sample below mixes two spellings — OpSite with RootPath and Items, but opEvent with rootPath
and items. Pick one convention and hold to it across your own template; the per-property pages all use the
capitalised form.
A complete sample
This template covers sites, sources, users and events. It does not use OpVariable.
{
"Account": {
"Id": 987,
"Name": "Acme customer"
},
"Config": {
"Whatif": false,
"CustomizationAssembly": "MasterDataCustomization.exe",
"UserSitesAndSourcesMergeMode": "Set"
},
"OpSite": {
"RootPath": "sites[*]",
"Items": [
{
"OpIdentifier": "opKey",
"Path": "LOC_ID"
},
{
"OpIdentifier": "opSiteForm.Master Data.Technical Identifiers.BusinessKey",
"Path": "LOC_ID"
},
{
"OpIdentifier": "opSite.Name",
"Path": "LOC_NAME"
},
{
"OpIdentifier": "opSite.PostalCode",
"Path": "POSTAL_CODE"
},
{
"OpIdentifier": "opSite.City",
"Path": "CITY"
},
{
"OpIdentifier": "opSite.Street",
"Path": "STREET"
},
{
"OpIdentifier": "opSiteForm.Master Data.Technical Identifiers.Range",
"Path": "STORE_RANGE"
},
{
"OpIdentifier": "opSiteForm.Master Data.Technical Identifiers.Surface",
"Path": "STORE_SURFACE"
},
{
"OpIdentifier": "opSite.TypeId",
"Transform": {
"Operation": "force",
"Value": "15"
}
},
{
"OpIdentifier": "opSite.TimeZoneId",
"Path": "TIMEZONE_ID",
"Transform": {
"Operation": "force",
"Value": "Romance Standard Time"
}
}
]
},
"OpSource": {
"RootPath": "sites[*].sources[*]",
"Items": [
{
"OpIdentifier": "opKey",
"Path": "MTR_ID"
},
{
"OpIdentifier": "opsource.SerialNumber",
"Path": "MTR_ID"
},
{
"OpIdentifier": "opSiteForm.Master Data.Technical Identifiers.BusinessKey",
"Path": "MTR_ID"
},
{
"OpIdentifier": "opsource.Name",
"Path": "MTR_NAME"
},
{
"OpIdentifier": "opSiteForm.Master Data.Technical Identifiers.Name",
"Path": "MTR_TYP_NAME"
},
{
"OpIdentifier": "opSiteForm.Master Data.Technical Identifiers.Acquisition",
"Path": "MTR_UNIT"
},
{
"OpIdentifier": "opSiteForm.Master Data.Technical Identifiers.Part",
"Path": "MTR_PART"
},
{
"OpIdentifier": "opsource.EnergyTypeId",
"Path": "ENERGY_NAME",
"Transform": {
"Operation": "Convert",
"KeyValuePairs": [
{
"Key": "ELECTRICITY",
"Value": "1"
},
{
"Key": "GAS",
"Value": "2"
},
{
"Key": "WATER",
"Value": "3"
}
]
},
"Validity": null
},
{
"OpIdentifier": "opsource.SourceTypeId",
"Path": "SOURCE_TYPE",
"Transform": {
"Operation": "force",
"Value": "77"
},
"Validity": null
},
{
"OpIdentifier": "opsource.GatewayType",
"Path": "GATEWAY_TYPE",
"Transform": {
"Operation": "force",
"Value": "7057"
},
"Validity": null
},
{
"OpIdentifier": "opsource.DisplayVariableTypeId",
"Path": "DISPLAY_TYPE",
"Transform": {
"Operation": "force",
"Value": "131"
},
"Validity": null
}
]
},
"OpUser": {
"RootPath": "users[*]",
"Items": [
{
"OpIdentifier": "opKey",
"Path": "EMAIL"
},
{
"OpIdentifier": "opUser.UserName",
"Path": "EMAIL"
},
{
"OpIdentifier": "opUser.Email",
"Path": "EMAIL"
},
{
"OpIdentifier": "opUser.FirstName",
"Path": "FIRST_NAME"
},
{
"OpIdentifier": "opUser.LastName",
"Path": "LAST_NAME"
},
{
"OpIdentifier": "opUser.Roles",
"Path": "ROLE",
"Transform": {
"Operation": "Convert",
"KeyValuePairs": [
{
"Key": "Data analyst",
"Value": "Manager"
},
{
"Key": "Service owner",
"Value": "Manager"
},
{
"Key": "Data manager",
"Value": "Manager"
},
{
"Key": "End user",
"Value": "User"
},
{
"Key": "Energy coordinator",
"Value": "User"
}
]
}
},
{
"OpIdentifier": "opUser.Language",
"Path": "LANGUAGE"
},
{
"OpIdentifier": "opUser.Claims",
"Path": "PROFILE",
"Transform": {
"Operation": "Convert",
"KeyValuePairs": [
{
"Key": "Admin",
"Value": "[{\"Name\":\"http://opisense.opinum.com/buildingproperties\",\"Value\":\"ADMIN\"},{\"Name\":\"http://opisense.opinum.com/sensors\",\"Value\":\"ADMIN\"}]"
},
{
"Key": "Expert",
"Value": "[{\"Name\":\"http://opisense.opinum.com/reports\",\"Value\":\"ADMIN\"},{\"Name\":\"http://opisense.opinum.com/tickets\",\"Value\":\"ADMIN\"},{\"Name\":\"http://opisense.opinum.com/buildingproperties\",\"Value\":\"NONE\"},{\"Name\":\"http://opisense.opinum.com/sensors\",\"Value\":\"NONE\"}]"
},
{
"Key": "Basic",
"Value": "[{\"Name\":\"http://opisense.opinum.com/sensors\",\"Value\":\"READ\"},{\"Name\":\"http://opisense.opinum.com/reports\",\"Value\":\"READ\"},{\"Name\":\"http://opisense.opinum.com/tickets\",\"Value\":\"READ\"},{\"Name\":\"http://opisense.opinum.com/buildingproperties\",\"Value\":\"NONE\"},{\"Name\":\"http://opisense.opinum.com/sensors\",\"Value\":\"NONE\"}]"
}
]
}
},
{
"OpIdentifier": "opUser.Sites",
"Path": "SITES[*].SiteName"
},
{
"OpIdentifier": "opUser.Sources",
"Path": "SOURCES[*].Serial"
}
]
},
"opEvent": {
"rootPath": "events[*]",
"items": [
{
"opIdentifier": "opKey",
"path": "name"
},
{
"opIdentifier": "opEvent.Name",
"path": "name"
},
{
"opIdentifier": "opEvent.Info",
"path": "info"
},
{
"opIdentifier": "opEvent.ToDate",
"path": "toDate"
},
{
"opIdentifier": "opEvent.FromDate",
"path": "fromDate"
},
{
"opIdentifier": "opEvent.Tags",
"path": "tags"
},
{
"opIdentifier": "opEvent.Site",
"path": "site"
},
{
"opIdentifier": "opEvent.Sources",
"transform": {
"operation": "list",
"value": ";"
},
"path": "sources"
}
]
}
}
What the sample shows
Reading it top to bottom:
Accountidentifies the target account.ConfigsetsWhatiftofalse, names a customization assembly, and selects the user merge mode.OpSiteanchors onsites[*], takesLOC_IDas the business key, and maps names, addresses and form fields. Two items use a transformation to force a constant value.OpSourceanchors onsites[*].sources[*]— nested under the site path, which is what attaches each source to its site.OpUsermaps user properties, including the site and source lists that grant access.opEventanchors onevents[*]and uses alisttransformation to split a delimited field.
Important
OpSource sits under the site path in this sample. That nesting is what tells the engine which site a
source belongs to. A flat sources[*] path would leave every source unattached.
- OpUser - The location and structure of the user property in the Master Data Upload file