Reference

About Asset References

Asset references are conceptual clarifications and details for modeling and expected behavior of attributes.

About Asset Model

An asset is a digital abstraction of something in the physical world. It can be an enterprise, organization, site, machine train, or equipment. Creating an asset model in Predix Essentials enables an application built on Predix Essentials consistently derive data for these common assets.

The asset model elements consist of the following:

Classifications - Defines the hierarchical levels of the asset model.
Instances - Relates node (levels in the hierarchy tree) with classification and ccomClass.
Connections - Defines parent-child relationships among nodes.
Tag Classifications - Defines classification types for tags.
Tag Associations - Associate a tag instance to a node instance and specify the tag classification for the tag instance.

From a global perspective, you can define and report on your company's overall asset performance or report from a regional or local level. Predix Essentials allows you to create multiple levels in the hierarchy. You can model your assets as follows:

Beginning from here	You can create this type of classification instance
Enterprise	You can create a child-Enterprise, or a Site.
Site	You can create a child-Site, a Segment, or an Asset.
Segment	You can create a child-Segment, or an Asset.
Asset	You can create a child-Asset.
Tag	You can create a Tag instance anywhere in the hierarchy.

Asset Classification

A classification is a reusable definition of a specific entity in your business object hierarchy. You can also represent multiple entities that are essentially the same and define it as a single classification. For example, you can create a classification machine to identify machinery that have common attributes and properties. You can create sub-classifications such as turbines, compressors, and shafts from this broader class machine. Sub-classifications inherit all properties from the parents and can have their own specialized properties.

Classification Rules

A classification is governed by the following rules:

It must contain an id that is unique per classification. If you ingest a model with the same classification ID the existing data will be overwritten with the new data.
It must be tied to one of the four classification types (ccomClass).
It may or may not be derived from a parent classification.
The classification and its parent must have the same classification type.
The classification inherits all properties from its parent classification. Any custom properties defined in the child classification are customized to the child.

JSON Fields

Make sure your {"classifications": []} block in the JSON has the following fields:

Table 1. JSON Fields for Classification
Field	Requirement
id	Must be unique per classification and can only contain alphabets (a-z, A-Z), digits (0-9), underscores _, hyphens -, dots . and quotes " "id":"3BCL"
name	The name of the classification. "name":"3MCL"
description	The general description for the classification.`id`. "description":"3MCL model of centrifugal compressor"
parent	If inherited from an existing class, provide the parent classification `id`. Not required, if base class. "parent":"Centrifugal_Compressor"
comClass	The Predix Essentials s95 adapter uses four ccomClass to represent the levels within the asset model hierarchy. Each classification must be tied to one of the four ccomClasses such as `ENTERPRISE_TYPE`, `SITE_TYPE`, `SEGMENT_TYPE`, and `ASSET_TYPE` . If inherited, must match the ccomClass of the parent classification. "ccomClass":"ASSET_TYPE"
properties	Define properties for the classification in key-value pairs. If inherited from an existing class, only enter properties customized to the sub-classification. Each property block contains `type`, `id` and `value`. You can define multiple blocks with `properties: [ ]` A best practice is to define static properties as part of the classification. "properties":[ { "type":"string", "id":"customer_address", "value":[ "2336 Camino Ramon" ] }]
reservedProperties	Define reserved properties aka system defined attributes and default values for the asset classification. Each reservedProperties block contains the list of expected reserved properties defined at the asset framework level. If you do not define the reserved properties block in your model, the system will automatically insert any required reserved attributes and set it to the default values. "reservedProperties": { "familyType": "", "equipmentType": "", "make": "GE", "model": "GTX-50", "series": "GTX", "serialNumber": null, "maintenanceCriticalityRiskScore": 7, "faultMode" : "" }

Example Classification

enterprise > site > segment > segment > segment > asset:

Company (enterprise_type)
Region (site_type)
Plant Location (segment_type)
Production Line (segment_type)
Production Line Assembly (segment_type)
Compressor (asset_type)

The following code sample shows a sample classification for the structure listed above:

{ "classifications":[ { "id":"Company", "name":"Company", "description":"Company or Enterprise", "ccomClass":"ENTERPRISETYPE", "properties":[ { "type":"string", "id":"customeraddress", "value":[
] }, { "type":"string", "id":"contract_information", "value":[
] }, { "type":"string", "id":"city", "value":[
] }, { "type":"string", "id":"contracttype", "value":[ "Warranty", "Transactional", "Null" ] }, { "type":"double", "id":"contract_duration", "value":[
] } ] }, { "id":"Region", "name":"Region", "description":"Regional information", "ccomClass":"SITE_TYPE", "properties":[ { "type":"string", "id":"country", "value":[
] }, { "type":"string", "id":"state", "value":[
] }, { "type":"string", "id":"county", "value":[
] } ] }, { "id":"Plant", "name":"Plant", "description":"Plant Location or site", "ccomClass":"SEGMENTTYPE", "properties":[ { "type":"string", "id":"locationid", "value":[
] }, { "type":"string", "id":"Address", "value":[
] }, { "type":"string", "id":"City", "value":[
] }, { "type":"string", "id":"Note", "value":[
] }, { "type":"string", "id":"Customer_Duns", "value":[
] }, { "type":"string", "id":"CONTINENTID", "value":[ "Africa", "America", "Asia", "Europe", "Oceania" ] }, { "type":"double", "id":"Delta_Dst", "value":[
] }, { "type":"string", "id":"Last_Timestamp", "value":[
] }, { "type":"string", "id":"DateStartDst", "value":[
] }, { "type":"string", "id":"DateEndDst", "value":[
] } ] }, { "id":"ProdLine", "name":"Production Line", "description":"Production Line", "ccomClass":"SEGMENTTYPE", "properties":[ { "type":"string", "id":"ReportTo", "value":[
] }, { "type":"string", "id":"TrainId", "value":[
] }, { "type":"string", "id":"TriplogConfigurationStatus", "value":[
] }, { "type":"string", "id":"Triplog_Note", "value":[
] }, { "type":"string", "id":"Note", "value":[
] }, { "type":"string", "id":"Lineup_Code", "value":[
] }, { "type":"string", "id":"Replication", "value":[
] }, { "type":"string", "id":"VIBRMONITORTYPE", "value":[ "System1" ] }, { "type":"string", "id":"VIBRMONACCESSTYPE", "value":[ "Partial", "NA", "Complete", "Missing" ] }, { "type":"double", "id":"ReplicationActivation_Date", "value":[
] }, { "type":"double", "id":"ReplicationContractFrequency", "value":[
] }, { "type":"double", "id":"ReplicationActivationFrequency", "value":[
] }, { "type":"double", "id":"FirstReplicationContract_Date", "value":[
] }, { "type":"double", "id":"FirstReplicationActivation_Date", "value":[
] }, { "type":"double", "id":"ReplicationContractCOV_Start", "value":[
] }, { "type":"double", "id":"ReplicationContractCOV_End", "value":[
] }, { "type":"double", "id":"ReplicationActivationCOV_Start", "value":[
] }, { "type":"double", "id":"ReplicationActivationCOV_End", "value":[
] }, { "type":"double", "id":"ReplicationpenalityMax", "value":[
] }, { "type":"double", "id":"JobCCNNCM", "value":[
] }, { "type":"string", "id":"TripStartDate", "value":[
] }, { "type":"string", "id":"TripEndDate", "value":[
] } ] }, { "id":"AssemblyLine", "name":"Production Assembly Line", "description":"Production Assembly Line", "ccomClass":"SEGMENTTYPE", "properties":[] }, { "id":"Machine", "name":"Machine", "description":"Machine", "ccomClass":"ASSETTYPE", "properties":[ { "type":"string", "id":"Version", "value":[
] }, { "type":"string", "id":"Low_Nox", "value":[
] }, { "type":"string", "id":"Supplier_ID", "value":[
] }, { "type":"string", "id":"NPJobNumber", "value":[
] }, { "type":"string", "id":"Note", "value":[
] }, { "type":"string", "id":"Supplier", "value":[
] }, { "type":"string", "id":"GIBSerialNumber", "value":[
] }, { "type":"string", "id":"OEMSerialNumber", "value":[
] }, { "type":"string", "id":"SKEDAMACerailNumber", "value":[
] }, { "type":"string", "id":"Equipment_Code", "value":[
] }, { "type":"string", "id":"Technology_Code", "value":[
] }, { "type":"string", "id":"GIB_Status", "value":[
] }, { "type":"string", "id":"Cost_ID", "value":[
] }, { "type":"string", "id":"Channel_ID", "value":[
] }, { "type":"string", "id":"Installation_Date", "value":[
] }, { "type":"string", "id":"CSAContractID", "value":[
] }, { "type":"string", "id":"RMDServiceLevel", "value":[
] }, { "type":"string", "id":"RMDContractService_Type", "value":[
] }, { "type":"string", "id":"RMDContractID", "value":[
] }, { "type":"string", "id":"PerformanceCalculationPlatform", "value":[
] }, { "type":"string", "id":"PerformanceCalculationConfigured", "value":[
] }, { "type":"string", "id":"Static_Pulsations", "value":[
] }, { "type":"string", "id":"PerformancedataAcquisition", "value":[
] }, { "type":"string", "id":"Sesimic_Vibration", "value":[
] }, { "type":"string", "id":"SesimicVibrationfequency_Analysis", "value":[
] }, { "type":"string", "id":"Radial_Vibration", "value":[
] }, { "type":"string", "id":"RadialVibrationfequency_Analysis", "value":[
] }, { "type":"string", "id":"Axial_Displacements", "value":[
] }, { "type":"string", "id":"Vibration_Notes", "value":[
] }, { "type":"string", "id":"Note", "value":[
] }, { "type":"string", "id":"CompressionPhaseNo", "value":[
] }, { "type":"string", "id":"id", "value":[
] }, { "type":"string", "id":"MANUFACTURER_ID", "value":[
] }, { "type":"string", "id":"MODELID", "value":[
] }, { "type":"double", "id":"TripInternalLimit", "value":[
] }, { "type":"double", "id":"TripNotificationPenality", "value":[
] }, { "type":"double", "id":"AnomalyNotificationTimelimit", "value":[
] }, { "type":"double", "id":"AnomalyInternalLimit", "value":[
] }, { "type":"double", "id":"AnomalyNotificationPenality", "value":[
] }, { "type":"string", "id":"MonitoringActivationStart_Date", "value":[
] }, { "type":"string", "id":"MonitoringContractStart_Date", "value":[
] }, { "type":"string", "id":"MonitoringActivationEnd_Date", "value":[
] }, { "type":"string", "id":"MonitoringContractEnd_Date", "value":[
] } ] }, { "id":"Compressors", "name":"Compressors", "description":"Compressors", "ccomClass":"ASSET_TYPE", "parent":"Machine", "reservedProperties": { "familyType": "", "equipmentType": "", "make": "", "model": "", "series": "", "serialNumber": null, "maintenanceCriticalityRiskScore": 7, "faultMode" : "" }, "properties":[
] }, { "id":"RotatingCompressor", "name":"Rotating Compressor", "description":"Rotating Compressor", "ccomClass":"ASSETTYPE", "parent":"Compressors", "reservedProperties": { "familyType": "Compressors", "equipmentType": "Rotating Compressors" }, "properties":[
] }, { "id":"CentrifugalCompressor", "name":"Centrifugal Compressor", "description":"Centrifugal Compressor", "ccomClass":"ASSETTYPE", "parent":"Rotating_Compressor", "reservedProperties": { "familyType": "Compressors", "equipmentType": "Centrifugal Compressors" }, "properties":[
] }, { "id":"2BCL", "name":"2BCL", "description":"2BCL", "ccomClass":"ASSETTYPE", "parent":"CentrifugalCompressor", "reservedProperties": { "make": "GE", "model": "BCL", "series": "2BCL", "maintenanceCriticalityRiskScore": 7 }, "properties":[
] }, { "id":"2MCL", "name":"2MCL", "description":"2MCL", "ccomClass":"ASSETTYPE", "parent":"CentrifugalCompressor", "reservedProperties": { "make": "GE", "model": "MCL", "series": "2MCL", "maintenanceCriticalityRiskScore": 7 }, "properties":[
] }, { "id":"3BCL", "name":"3BCL", "description":"3BCL", "ccomClass":"ASSETTYPE", "parent":"CentrifugalCompressor", "reservedProperties": { "make": "GE", "model": "BCL", "series": "3BCL", "maintenanceCriticalityRiskScore": 7 }, "properties":[
] }, { "id":"3MCL", "name":"3MCL", "description":"3MCL", "ccomClass":"ASSETTYPE", "parent":"CentrifugalCompressor", "reservedProperties": { "make": "GE", "model": "MCL", "series": "3MCL", "maintenanceCriticalityRiskScore": 7 }, "properties":[
] } ] }

Asset Instances

After you define your classifications, you can create instances of those classifications.

Example Instance

The general structure of this asset model is given by:

The following code samples illustrate instances for classes Company and Region.

{  
   "instances":[  
      {  
         "id":"c4837964-27fb-4f98-91a2-2c6e406ca1fe",
         "name":"Acme Inc.",
         "description":"",
         "classification":"Company",
         "properties":[  
            {  
               "type":"string",
               "id":"customer_address",
               "value":[  
                  "2336 Camino Ramon"
               ]
            },
            {  
               "type":"string",
               "id":"contract_information",
               "value":[  
                  ""
               ]
            },
            {  
               "type":"string",
               "id":"city",
               "value":[  
                  "San Ramon"
               ]
            },
            {  
               "type":"string",
               "id":"contracttype",
               "value":[  
                  ""
               ]
            },
            {  
               "type":"double",
               "id":"contract_duration",
               "value":[  
                  ""
               ]
            }
         ],
         "ccomClass":"ENTERPRISE"
      },
      {  
         "id":"rnk6fdj98-Hkshdnks67",
         "name":"North America",
         "description":"Regional information",
         "classification":"Region",
         "properties":[  
            {  
               "type":"string",
               "id":"country",
               "value":[  
                  "USA"
               ]
            },
            {  
               "type":"string",
               "id":"state",
               "value":[  
                  "CA"
               ]
            },
            {  
               "type":"string",
               "id":"county",
               "value":[  
                  "Contra Costa"
               ]
            }
         ],
         "ccomClass":"SITE"
      }
   ]
}

JSON Fields

Make sure your {"instances": []} block in the JSON has the following fields:

Table 2. JSON Fields for Instances
Field	Requirement
id	Must be unique and can only contain alphabets (a-z, A-Z), digits (0-9), underscores _, hyphens -, dots . and quotes " "id":"c4837964-27fb-4f98-91a2-2c6e406ca1fe"
name	Must be provided to view or search by name in the APM application. "name":"Acme Inc."
classification	Must be an existing classification in the model "classification":"Company"
comClass	The APM s95 adapter uses four ccomClass to represent the levels within the asset model hierarchy. Each class instance must be tied to one of the four ccomClasses `ENTERPRISE`, `SITE`, `SEGMENT`, and `ASSET`. It should also match the classification ccomclass. For example, if the ccomClass for the classification is `Enterprise_type` then the instance of that classification must have the ccomClass `Enterprise.` "ccomClass":"ENTERPRISE"
properties	id within `properties` is mandatory and can only contain alphabets (a-z, A-Z), digits (0-9), underscores _, hyphens -, dots . and quotes ". If the same property is defined at both class and instance levels, the property defined for the instance takes precedence over the class. For example, if the property color has the default value `black` at the classification level, the instance value `red` for color takes precedence for that instance. You can add properties directly to an instance. Therefore, the instance is not limited to properties defined in its classification. A best practice is to define static properties as part of the classification, and to define dynamic properties as part of the instance. "properties":[ { "type":"string", "id":"customer_address", "value":[ "2336 Camino Ramon" ] }] If you wish to add an asset alias, you can define it as a property as given in the code example below. Note: If the property type is not defined as a string and ID as alias for an asset instance, the aliases will not be available on the APM user interface. "properties":[ { "type":"string", "id":"alias", "value":[ "Asset Alias 1" ] }]
reservedProperties	Define reserved properties aka system defined attributes and default values for the asset instances only (instances with the ccomClass ASSET). Each reservedProperties block contains the list of expected reserved properties defined at the asset framework level. If you do not define the reserved properties block in your model, the system will automatically insert any required reserved attributes and set it to the default values. "reservedProperties": { "state": "06", "status": "03", "familyType": "", "equipmentType": "", "make": "GE", "model": "EX8863", "series": "EX1", "serialNumber": "123456ABC", "faultMode": "5", "maintenanceCriticalityRiskScore": 7 },
location	Stores the geographical location of a company, a device, an equipment a site, a plant, a specific area (group of geolocation points). "location": { "geoPoints": [ { "name": "geo point 1", "order": 1, "latitude": 37.7799, "longitude": -121.978, "altitude": 150 }, { "name": "geo point 2", "order": 2, "latitude": 37.4965, "longitude": -121.7759, "altitude": 138 }, { "name": "geo point 3", "order": 3, "latitude": 37.5841, "longitude": -123.7578, "altitude": 138 }, { "name": "geo point 4", "order": 4, "latitude": 38.1133, "longitude": -120.4214, "altitude": 138 } ] }

Relationships

Connections establish relationships among two or more instances. In a simple asset hierarchy, you can identify an individual asset by specifying its path in the hierarchy. You can have a parent-child relationship between instances. You define connection from one instance to one or more instances. You would start from the top of the hierarchy and traverse down to connect.

Important: You must define the instances before you can connect them.

Parent-Child Connection

Before connecting two instances, consider the following:

An enterprise object is the parent of one or more site objects.
A site object is the parent of at least one segment or asset object. A site object cannot be a parent of another site object.
A segment object is the parent of at least one segment or asset object.
An asset object can be the parent of zero or more asset objects.

The following code example shows connections from between North America (Class: Region) and Acme, Inc (Class: Company) . You must define the child in the from {} block and the parent in the to{} block. The type field is parent and is defined in the to{} block.

"connections": [
        {
            "from": {
                "id": "rnk6fdj98-Hkshdnks67",
                "ccomClass": "SITE"
            },
            "to": [
                {
                    "type": "parent",
                    "id":"c4837964-27fb-4f98-91a2-2c6e406ca1fe",
                    "ccomClass": "ENTERPRISE"
                }
            ]
        
        }
    ]

Asset Modeler Workflow

The asset modeler creates the business functional hierarchy through APIs or ingestion using one or more JSONs.

The asset modeler can set up a tenant business functional hierarchy that includes:

Classifications
Instances
Parent-child connections
Groups for classifications or instances

To create an asset model for a tenant, do the following:

Create asset classifications, which define the asset hierarchy.
Values for classification in the JSON include:
- id
- name
- description
- ccomClass
The ccomClass values for a classification represent the type (ENTERPRISE_TYPE, SITE_TYPE, SEGMENT_TYPE, or ASSET_TYPE).
Next, add values for reserved attributes. Adding values for reserved attributes to a classification allows sub-classifications to inherit those values. Values for reservedProperties and properties are added under the named classification node.
Create asset instances.
Instances represent a specific entity associated with a type of classification. Values for instances in the JSON include:
- id
- name
- description
- classification
- prooperties
- ccomClass
The classification values for an instance represent a type of named entry, such as a company name, or regional designation. The ccomClass values for an instance are predetermined according to their place in the hierarchy (ENTERPRISE, SITE, SEGMENT, ASSET).
Next, add location geopoints to define the instance location. Geopoints represent coordinates that define the location of the instance. The location may include a group of geopoints. Values for location > geopoints include:
- name
- order
- latitude
- longitude
- altitude
Add connections which define the parent-child relationships between asset instances and Business Functional Objects.
Connections represents a mapped connection from an instance to another instance in a parent-child relationship.
Values for connection > from include:
- id
- ccomClass
The ccomClass values for the from connection are predetermined according to their place in the hierarchy (ENTERPRISE, SITE, SEGMENT, or ASSET).
Values for connection > to include:
- type
- id
- ccomClass
The type values are parent or child. The ccomClass values for the to connection are predetermined according to their place in the hierarchy (ENTERPRISE, SITE, SEGMENT, or ASSET).
Add group associations for the asset instances.
Group associations include classifications of one type that are related or connected in some way. Groups include member instances which can be added in the JSON. Values for groups > mappedInstances include:
- id
- name
- description
- ccomClass
- associatedEntityCcomClass
- properties
The ccomClass value is predefined as GROUP. The associatedEntityCcomClass values is the type (ASSET or TAG) of the member instance listed under the group parent node.
For more information, refer to the ingestion or APIs documentation to complete the workflow.

About Tag Model

Anatomy of a tag

A tag can have many characteristics defined as separate attributes or properties. Creating a tag model enables you to derive data from common tags for data analysis.

The following example has some common attributes of a sensor tag:

unit of measure
unit group
range (min and max values)
resolution (number of data points)
compression (for example, dead band filtering applied)
interpolated (true or false)
threshold (true or false)
binary (true or false)
number of significant digits

Tag Classification

You can model classification for tags with common characteristics and define a standard tag at the Predix Essentials level. A tag classification is a reusable definition of a specific instrument. For example, you can create a tag classification called Standard_Inlet_Temperature.

Table 3. JSON Fields for Tag Classification
Field	Requirement
id	Must be unique per tag classification and can only contain alphabets (a-z, A-Z), digits (0-9), underscores _, hyphens -, dots . and quotes " `"id": "TagType1"`
name	(optional) The name of the tag classification. `"name": "Tag 1"`
description	(optional) The general description for the tag classification. `"description":"Standard tag for temperature"`
properties	(optional) Define properties for the tag classification in key-value pairs. Each property block contains `type`, `id` and `value`. You can define multiple blocks with `properties: [ ]` A best practice is to define static properties as part of the classification. `"properties": [ { "id": "configured", "value": [false], "type": "boolean" } ]` Note: You can add UTF-8 special characters in the tag classification.
reservedProperties	(optional) Define reserved properties aka system defined attributes and default values for the tag classification. Each reservedProperties block contains the list of expected reserved properties defined at the asset framework level. If you do not define the reserved properties block in your model, the system will automatically insert any required reserved attributes and set it to the default values. `"reservedProperties": { "uom": "ºF", "dataType": "Double", "resolution": "" }`

An example of usage of the tag classification is to represent the characteristics of a specific sensor type, such as manufacturer, make, model, weight, or dimension. Tag classifications help you define similar types of tags. The tag instances are defined within tag associations.

{ "tagClassifications":[  
      {
  "id": "HISTORIAN-TAG",
  "name": "HISTORIAN-TAG",
  "description": "This is historian tag",
  "reservedProperties": {
    "uom": "ºF",
    "dataType": "Double",
    "resolution": ""
  },
  "properties": [
     {
      "id": "Downtime",
      "value": [
        "true"
      ],
      "type": "string"
     } 
  ]
}
         ]
      }
   ]}

Tag Instances

Tag instances are defined inside tagAssociations (also refer to Tag Relationships). Every object instance of a tag is unique. A tag instance can have its own properties and common properties inherited from its tag classification. You can add properties directly to an instance. Therefore, the instance is not limited to properties defined in its classification.

Best practice is to define static attributes as part of the tag classification, and to define dynamic attributes as part of the instance. If the same attribute is defined at the class and instance levels, the attribute value defined in the instance takes precedence over the class. For example, the default value for unit of a temperature tag can be set as Fahrenheit; however, an instance can be set as Celsius.

A tag instance can represent a unique measurement from sensors, an asset-specific analytic calculation, or an asset-specific software input.

You can associate a tag classification with an asset classification. When an asset instance is created from an asset classification, the asset instance automatically creates an appropriate tag-instance where the tag classification was associated to the asset classification.

Table 4. JSON Fields for Tag Instances
Field	Requirement
id	Must be source key id of the tag and can contain alphanumeric and UTF-8 special characters. `"id": "TagType1"`
name	Provide a unique name for searchability in the user interface. If not provided, the name field will store the tag classification name as the default value. `"name": "Temp_tag_SS_134"` Note: You can add UTF-8 special characters in the name.
description	(optional) The general description for the tag instance. `"description":"Temperature tag for asset1"` Note: You can add UTF-8 special characters in the description.
aliases	(optional) Possible alias names for the tag instance as a string array. `"aliases": ["TagAlias3_1", "TagAlias3_2"]`
properties	(optional) Provide property values for the tag instance. `"properties": [ { "id": "configured", "value": [false], "type": "boolean" } ]`
reservedProperties	(optional) Define reserved properties aka system defined attributes and default values for the tag instances. Each reservedProperties block contains the list of expected reserved properties defined at the asset framework level for the tag instances. If you do not define the reserved properties block in your model, the system will automatically insert any required reserved attributes and set it to the default values. Any properties values defined at the tag instance level overrides the default values set at the tag classification. The following are reserved properties at the tag instance level. `"reservedProperties": { "status": "02", "uom": "ºF", "dataType": "Double", "resolution": "", "timeseriesLink": "" }`

Tag Relationships

After defining your tag classifications, you must also define the tags and their associations:

Tag Association

Defines the tag instances and associates tag instances to a node in the asset hierarchy. Tag instances must belong to one of the defined tag classifications. This is the most common relationship for an asset configuration in which a sensor can be configured into any level of equipment: system, module, component or part.

A tag can also be associated with a group of assets, for example, a lineup of equipment.

{ "tagAssociations": [
    {
      "monitoredEntity": {
        "id": "Sample-CA-ASSET-ID1",
        "ccomClass": "ASSET"
      },
      "tags": [
        {
          "name": "Sample Asset Tag Pressure name",
          "id": "Sample-CA-ASSET-ID1.Sample_Tag_Pressure_ID",
          "classification": "Sample_Tag_Type_Classification_ID",
          "unit": "",
          "reservedProperties": {
            "status": "02",
            "uom": "atm",
            "dataType": "Double",
            "resolution": ""
          },
          "aliases": [
            "Sample Atmospheric Tag Pressure Alias"
          ]
        }
      ]
    },
    {
      "monitoredEntity": {
        "id": "Sample-CA-SEGMENT-ID",
        "ccomClass": "SEGMENT"
      },
      "tags": [
        {
          "name": "Sample Segment Tag name",
          "id": "Sample-CA-SEGMENT-ID.Sample_Tag_Segment_ID",
          "classification": "Sample_Tag_Type_Classification_ID",
          "unit": "",
          "aliases": [
            "Sample Tag Segment Alias 1"
          ]
        }
      ]
    },
    {
      "monitoredEntity": {
        "id": "Sample-CA-SITE",
        "ccomClass": "SITE"
      },
      "tags": [
        {
          "name": "Sample Site Tag name",
          "id": "Sample-CA-SITE.Sample_Tag_Site_ID",
          "aliases": [
            "Sample Tag Site Alias 1"
          ],
          "classification": "Sample_Tag_Type_Classification_ID"
        }
      ]
    },
    {
      "monitoredEntity": {
        "id": "Sample-CA-ASSET-ID1",
        "ccomClass": "ASSET"
      },
      "tags": [
        {
          "name": "Sample Asset Tag Pressure name",
          "id": "Sample-CA-ASSET-ID2.Sample_Tag_Pressure_ID2",
          "classification": "Sample_Tag_Type_Classification_ID",
          "unit": "",
          "reservedProperties": {
            "status": "02",
            "uom": "atm",
            "dataType": "Double",
            "resolution": ""
          },
          "nextRelatedTag": {
            "id": "Sample-CA-ASSET-ID1.Sample_Tag_Pressure_ID"
          },
          "aliases": [
            "Sample Tag Pressure Alias"
          ]
        }
      ]}

Tag Alias

Defines an alternative name for a tag. Use tag aliases when multiple groups in an organization or different source systems use different names for the same tag. For example, a user may use a meaningful name for the tag as a reminder of its purpose, or may use an alias that customers use. A tag can have one or more aliases. An alias only contains a string.

"aliases": ["TagAlias3_1", "TagAlias3_2"]

Tag Correlation

Tag correlation is a way of associating a tag with another closely related tag. Correlated tags show a linear association. Tags should only be correlated if they capture the same measurement data but are labeled differently, and may have different quality and density.

For example, suppose an equipment engineer configures a tag for collecting the vibration frequency of a drill pump at the controller of the machine. The data points are collected at the rate of 0.5 secs and the tag name is PUMP1.VIBEFRQ1. The OSM collects the data from the controllers in a round-robin style at a data rate of 1 minute. The tag name in the OSM is now PUMP1.VIBEUPPER1. When the same data moves to the cloud storage, the IT specialist configures the tag at a standardized frequency and renames the tag CLOUD.TXOIL.PUMP1.VIBEUPPER1. Finally, the IT specialist standardizes all vibrations tags to a common name for applications and labels it STD.PUMP.FREQUENCY.

Tag Correlation Example

The tag correlation can be represented as follows in the tag instance definition of the asset ingestion JSON file:

 "nextRelatedTag": {
             "id": "SY0513959.Control_Pressure"
           }

Note:

When correlating tags, consider the following:

The nextRelatedTag.id must be the tag ID for an already ingested tag instance or the tag instance must be defined for the tag prior to correlation in the tags [] block. If the nextRelatedTag.id does not already exist in the Predix Essentials asset store or is in the incorrect order in the tags [] block, then the ingestion will fail.
Pass the value for nextRelatedTag.id as null to remove a correlation that has been established in Predix Essentials asset store through a prior ingestion.
To replace an existing correlation with a new one, you must first pass the value for nextRelatedTag.id as null to delete the existing correlation, and then set the value to the new correlated tag ID.

Tag Group

A tag group can aggregate data from multiple tags. For example, rather than creating 50 individual inputs, you can use a tag group to aggregate data from 50 tags to provide a single input to an analytic.

Groups

A group object provides a mechanism to group a homogeneous group of asset objects under a single entity.

The following are types of groups available in Predix Essentials:

Asset Classification Groups - Contains asset classification objects.
Tag Classification Groups - Contains tag classification objects.
Asset Instance Groups - Contains asset instance objects.
Tag Instance Group - Contains tag instance objects.
Business Functional Hierarchy Groups - Contains Business Functionality Hierarchy objects.

The following are the JSON fields available for groups in Predix Essentials:


Field	Requirement
id	Must be unique per group and can only contain alphabets (a-z, A-Z), digits (0-9), underscores _, hyphens -, dots . and quotes ".
name	The name of the group. "name" : "Group Name 1"
description	(Optional) The general description for the group. "description": "This is a group1 for temperature"
ccomClass	The Predix Essentials s95 adapter uses four ccomClass to represent the levels within the asset model hierarchy. "ccomClass": "GROUP"
associatedEntityCcomClass	The Predix Essentials s95 adapter uses four ccomClass to represent the levels within the asset model hierarchy. Each group must be associated to one of the four ccomClasses such as ENTERPRISE_TYPE, SITE_TYPE, SEGMENT_TYPE, and ASSET_TYPE . "associatedEntityCcomClass": "TAG_TYPE"
properties	(Optional) Define properties for the group in key-value pairs. You can define multiple blocks with properties: [ ] A best practice is to define static properties as part of the group."properties": `[ { "id": "Sample-CA-GROUP-ID1_model_number", "value": [ "Sample-CA-GROUP-ID1 id description" ], "type": "string" } ]`
associatedEntityIds	(optional) defines the members of the group. A group can have one or more homogeneous members associated using their source Key. "associatedEntityIds": ["Sample_Tag_Type_Classification_ID", "Sample_Tag_Type_Classification_ID1"]

Below is an example:

"groups":[
      {
         "id": "Sample-CA-GROUP-ID1",
         "name": "Sample Intake temperature group1",
         "description": "This is a group1 for temperature",
         "ccomClass": "GROUP",
         "associatedEntityCcomClass": "TAG_TYPE",
         "properties": [
            {
               "id": "Sample-CA-GROUP-ID1_model_number",
               "value": [
                  "Sample-CA-GROUP-ID1 id description"
               ],
               "type": "string"
            }
         ],
         "associatedEntityIds": ["Sample_Tag_Type_Classification_ID", "Sample_Tag_Type_Classification_ID1"]
      },
      {
         "id": "Sample-CA-GROUP-ID2",
         "name": "Sample Intake temperature group2",
         "description": "This is a group2 for temperature",
         "ccomClass": "GROUP",
         "associatedEntityCcomClass": "TAG_TYPE",
         "properties": [
            {
               "id": "Sample-CA-GROUP-ID2_model_number",
               "value": [
                  "Sample-CA-GROUP-ID2 id description"
               ],
               "type": "string"
            }
         ],
         "associatedEntityIds": ["Sample_Tag_Type_Classification_ID2", "Sample_Tag_Type_Classification_ID3"]
      }
   ]

Tag Modeler Workflow

The tag modeler creates standard tag classifications and instances through APIs or ingestion for one or more JSONs.

The tag modeler can set up tags that include:

Classifications
Instances and connections to assets
Groups for classifications or instances

To create a tag model for a tenant, do the following:

Create tag classifications, which define the standard instances with common characteristics.
Values for tagclassifications in the JSON include:
- id
- name
- description
Next, add values for reserved attributes. Adding values for reserved attributes to a classification allows sub-classifications to inherit those values. Values for reservedProperties and properties are added to the named tag classification node. Static attributes should be defined as part of the tag classification.
Create tag instances and tag correlations.
Tag instances represent specific tags associated with a type of tag classification, and connect to an asset instance.
Note: You can associate a tag classification with an asset classification. When an asset instance is created from an asset classification, the asset instance automatically creates an appropriate tag instance where the tag classification was associated to the asset classification.
Values for tagAssociations > monitoredEntity in the JSON include:
- id
- ccomClass
The ccomClass vaue for monitoredEntity is predetermined according to their place in the hierarchy (ENTERPRISE, SITE, SEGMENT, or ASSET).
Values for tagAssociations > tags in the JSON include:
- id
- name
- classification
- reservedProperties
- aliases
- nextRelatedTag
Values for reservedProperties are added under the named tag instance. Dynamic attributes should be defined as part of the tag instance.
Note: If the same attribute is defined at the class and instance levels, the attribute value defined in the instance takes precedence over the class.
Values for classification are the tag classification. Values for aliases are alternative tag names. Values for nextRelatedTag are correlated tag names. Correlated tags capture the same measurement data but are labeled differently and may have different quality and density.
Add group associations for the tag instances.
Group associations include classifications of one type that are related or connected in some way. Groups include member tag instances which can be added in the JSON.
Values for groups include:
- id
- name
- description
- ccomClass
- associatedEntityCcomClass
- properties
- associatedEntityIds
The ccomClass value is predefined as GROUP. The associatedEntityCcomClass value is the type (ENTERPRISE_TYPE, SITE_TYPE, SEGMENT_TYPE, or ASSET_TYPE) of the member instance listed under the group parent node. The members of the group are added using the sourcekey for associatedEntityIds.

For more information, refer to the APIs or ingestion documentation to complete the workflow.

Expected Behavior for Reserved Attributes

You can use the different scenarios to add, modify, or remove attribute values.

The following table describes the different scenarios for reserved attributes and their expected behaviors.


Scenario	Expected Behavior	Example
Scenario 1 - A single value of instance validated against a classification	Enter characters to select an option in the drop-down list.	Unit of Measure
Scenario 2 - A single value of instance not validated against a classification	Enter the value in the text box.	Make or Model
Scenario 3 - Multiple values of instances validated against a classification	Select one or more values in a list.	NA
Scenario 4 - Multiple values of instances not validated against a classification	Allows you to create values. Classifications - Allows you to create multiple values. Instances - Allows you to select provided values or add more.	Fault Mode

Attribute Data Types and Values

List of supported data types and expected range of values.

Table 5. Data Types and Range of Values
Data Type Name	Expected Values or Range of Values
Character	Single character
Short	–32,768 to 32,767
Integer	–2,147,483,648 to 2,147,483,647
Float	3.4E +/- 38 (7 digits)
Double	1.7E +/- 308 (15 digits)
Boolean	true or false
Timestamp	mm/dd/yyyy hh:mm:ss
String	Not applicable. Any text value is acceptable.

Assets Reserved Attributes

This topic provides a list of supported reserved attributes, types, data types, and default values.

Note: You can add UTF-8 special character in the Default Value field of the attributes. If you want to search for the assets with default value that contains ,:\=()|’* special characters, you must add a \(backslash) before the special character to escape the character. For more information, refer to Escape Special Characters for Endpoints.


Type Name	Field Name	Display Name	Data Type	Default Value
assettype	equipmentType	Equipment Type	String	null
assettype	familyType	Family Type	String	null
assettype	faultMode	Fault Mode	String	null
assettype	maintenanceCriticalityRiskScore	Maintenance Criticality Risk Score	Integer	null
assettype	make	Make	String	null
assettype	model	Model	String	null
assettype	serialNumber	Serial Number	String	null
assettype	series	Series	String	null
assettype	state	State	String	6
assettype	status	Status	String	3
enterprisetype	state	State	String	6
enterprisetype	status	Status	String	3
segmenttype	state	State	String	6
segmenttype	status	Status	String	3
sitetype	state	State	String	6
sitetype	status	Status	String	3
tagtype	aliases	Aliases	String	null
tagtype	badObservationPersistent	Bad Observation Persistent / Penalty Window	Integer	2880
tagtype	category	Category	String	null
tagtype	dataType	Data Type	String	String
tagtype	falseAlarmProbability	False Alarm Probability	Double	0.001
tagtype	flatTestWeight	Flat Test Weight	Double	1
tagtype	highestThresholdValue	Highest Threshold Value	Double	null
tagtype	lowestThresholdValue	Lowest Threshold Value	Double	null
tagtype	maxOperatingValue	Max Operating Value	Double	null
tagtype	minOperatingValue	Min Operating Value	Double	null
tagtype	missedAlarmProbability	Missed Alarm Probability	Double	0.001
tagtype	nanTestWeight	NaN Test Weight	Double	1
tagtype	nullHypothesisVariance	Null Hypothesis Variance	Double	0.0025
tagtype	outlierTestWeight	Outlier Test Weight	Double	1
tagtype	paintBrushingTestWeight	Paint Brushing Test Weight	Double	null
tagtype	resolution	Data Resolution	String	null
tagtype	sampleFailureMagnitudesMean	SAMPLE FAILURE MAGNITUDES MEAN	Int	10
tagtype	sampleFailureMagnitudesVariance	Sample Failure Magnitudes Variance	Integer	40
tagtype	sensorHealthIndex	Sensor Health Index	Double	null
tagtype	sensorHealthStatus	Sensor Health Status	Boolean	null
tagtype	shiFlatLineEpsilon	Sensor Health Index Flat Line Epsilon	Double	1.00E-08
tagtype	shiFlatLineNumber	Sensor Health Index Flat Line Number	Integer	720
tagtype	shiHighThreshold	Sensor Health Index High Threshold	Double	1
tagtype	shiLowThreshold	Sensor Health Index Low Threshold	Double	0
tagtype	shiOutlierLimitsHigh	SHI Outlier Limits High	Double	null
tagtype	shiOutlierLimitsLow	SHI Outlier Limits Low	Double	null
tagtype	status	Status	String	1
tagtype	timeseriesDataSource	Timeseries Data Source Identifier	String	null
tagtype	timeseriesLink	Timeseries Link	String	null
tagtype	uomGroup	Unit of Measurement Group	UnitOfMeasure	null
tagtype	standardUom	Standard Unit of Measurement	UnitOfMeasure	null
tagtype	standardUomGroup	Standard Unit of Measurement Group	UnitOfMeasure	null

APM Asset Data Migration

APM Asset Data is migrated to enhance the asset schema.

Important: After APM Asset Data migration, the classification definition and the instance definition must conform to each other at the attribute level. If an attribute with the same name exists in an instance and classification, the datatype must match.

In the existing data, if the instance attribute datatype does not match with the classification attribute datatype, the most prevalent datatype is derived from the instance, and the remaining attributes are prefixed with dtm (datatype mismatch).
For example, you have a turbine classification with 50 instances, and a motor diameter attribute with string datatype. When the instances are created, the motor diameter attribute is redefined at the instance level with 10 instances as boolean datatype and the remaining 40 instances as integer datatype. In this case, the most prevalent datatype is integer, and during data migration, the classification attribute, motor diameter will be updated from string to integer to match with the instance. For the remaining 10 instances, the attribute name will be prefixed with dtm_<attribute_name>.
You can delete the attributes with the prefix dtm from the instance. However, before deleting, you can create an attribute with the original name that matches the datatype of the attribute in the classification and assign the original value.
UOM and StandardUom are the tag instance reserved attributes, and their values are defined in UOMService.
If the existing tags has UOM or StandardUom values that does not exist in UOMService of a tenant, during data migration the attributes are mapped to UnknownUOM group. To update the tags with UnknownUOM, you must update the unknown groups and their values by replacing them with existing values through UOMService, Asset Ingestion, or API. The non-existing values will be migrated without any change.

Escape Special Characters for Endpoints

This topic provides a list of special characters that must be escaped based on the quoted or unquoted values in the request for specific GET APIs and Query endpoints. You must add a \(backslash) before the special character to escape the characters.

Characters to be escaped always (quoted or unquoted)	Characters to be escaped only when unquoted	Endpoints
\ (backslash) ' (single quote) * (asterisk)	None	`/v3/assets?sourceKey=<value> /v3/assets?name=<value> /v3/assets/search?sourceKey=<value> /v3/assets/search?name=<value> /v3/assets/search?sourceKey=<sourceKey>&name=<name> /v3/assets/bySourceKey?sourceKey=<value> /v3/tags/bySourceKey?sourceKey=<sourceKey1> /v3/assets/<uuid>/tags?sourceKey=<value> /v3/assets/<uuid>/tags?name=<value>`
\ (backslash) ' (single quote) * (asterisk)	, (comma)	`/v3/tags?sourceKeys=<sourceKey1> /v3/tags?sourceKeys=<sourceKey1>,<sourceKey2>`
\ (backslash) ' (single quote) * (asterisk)	: (colon) \| (pipe) = (equals)	`/v3/[assets\|segments\|sites\|enterprises]/query /v3/[assets\|segments\|sites\|enterprises]/<uuid>/tags/download /v3/tags/query`

Characters to be escaped always

(quoted or unquoted)

Characters to be escaped only when unquoted

Endpoints

\ (backslash)

' (single quote)

* (asterisk)

None

/v3/assets?sourceKey=<value>
/v3/assets?name=<value>
/v3/assets/search?sourceKey=<value>
/v3/assets/search?name=<value>
/v3/assets/search?sourceKey=<sourceKey>&name=<name>
/v3/assets/bySourceKey?sourceKey=<value>
/v3/tags/bySourceKey?sourceKey=<sourceKey1>
/v3/assets/<uuid>/tags?sourceKey=<value>
/v3/assets/<uuid>/tags?name=<value>

\ (backslash)

' (single quote)

* (asterisk)

, (comma)

/v3/tags?sourceKeys=<sourceKey1>
/v3/tags?sourceKeys=<sourceKey1>,<sourceKey2>

\ (backslash)

' (single quote)

* (asterisk)

: (colon)

| (pipe)

= (equals)

/v3/[assets|segments|sites|enterprises]/query
/v3/[assets|segments|sites|enterprises]/<uuid>/tags/download
/v3/tags/query