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 GE Digital APM enables an application built on GE Digital APM 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. GE Digital APM allows you to create multiple levels in the hierarchy. You can model your assets as follows:
Beginning from hereYou can create this type of classification instance
EnterpriseYou can create a child-Enterprise, or a Site.
SiteYou can create a child-Site, a Segment, or an Asset.
SegmentYou can create a child-Segment, or an Asset.
AssetYou can create a child-Asset.
TagYou 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
FieldRequirement
idMust be unique per classification and can only contain alphabets (a-z, A-Z), digits (0-9), underscores _, hyphens -, dots . and quotes "
"id":"3BCL"
nameThe name of the classification.
"name":"3MCL"
descriptionThe general description for the classification.id.
"description":"3MCL model of centrifugal compressor"
parentIf inherited from an existing class, provide the parent classification id. Not required, if base class.
"parent":"Centrifugal_Compressor"
comClassThe GE Digital APM 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"
propertiesDefine 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"
               ]
            }]
reservedPropertiesDefine 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
FieldRequirement
idMust 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"
nameMust be provided to view or search by name in the APM application.
"name":"Acme Inc."
classificationMust be an existing classification in the model
"classification":"Company"
comClassThe 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"
propertiesid 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"
               ]
            }]
reservedPropertiesDefine 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
  },
locationStores 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:
  1. 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.

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

  4. 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 GE Digital APM 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
FieldRequirement
idMust 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
FieldRequirement
idMust be source key id of the tag and can contain alphanumeric and UTF-8 special characters.
"id": "TagType1"
nameProvide 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 GE Digital APM 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 GE Digital APM 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 GE Digital APM:
  • 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 GE Digital APM:

FieldRequirement
idMust be unique per group and can only contain alphabets (a-z, A-Z), digits (0-9), underscores _, hyphens -, dots . and quotes ".
nameThe name of the group.
"name" : "Group Name 1"
description(Optional) The general description for the group.
"description": "This is a group1 for temperature"
ccomClassThe GE Digital APM s95 adapter uses four ccomClass to represent the levels within the asset model hierarchy.
"ccomClass": "GROUP"
associatedEntityCcomClassThe GE Digital APM 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:
  1. 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.

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

  3. 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.

ScenarioExpected BehaviorExample
Scenario 1 - A single value of instance validated against a classificationEnter characters to select an option in the drop-down list.Unit of Measure
Scenario 2 - A single value of instance not validated against a classificationEnter the value in the text box. Make or Model
Scenario 3 - Multiple values of instances validated against a classificationSelect one or more values in a list. NA
Scenario 4 - Multiple values of instances not validated against a classificationAllows 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 NameExpected Values or Range of Values
CharacterSingle character
Short–32,768 to 32,767
Integer–2,147,483,648 to 2,147,483,647
Float3.4E +/- 38 (7 digits)
Double1.7E +/- 308 (15 digits)
Booleantrue or false
Timestampmm/dd/yyyy hh:mm:ss
StringNot 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 NameField NameDisplay NameData TypeDefault Value
assettypeequipmentTypeEquipment TypeStringnull
assettypefamilyTypeFamily TypeStringnull
assettypefaultModeFault ModeStringnull
assettypemaintenanceCriticalityRiskScoreMaintenance Criticality Risk ScoreIntegernull
assettypemakeMakeStringnull
assettypemodelModelStringnull
assettypeserialNumberSerial NumberStringnull
assettypeseriesSeriesStringnull
assettypestateStateString6
assettypestatusStatusString3
enterprisetypestateStateString6
enterprisetypestatusStatusString3
segmenttypestateStateString6
segmenttypestatusStatusString3
sitetypestateStateString6
sitetypestatusStatusString3
tagtypealiasesAliasesStringnull
tagtypebadObservationPersistentBad Observation Persistent / Penalty WindowInteger2880
tagtypecategoryCategoryStringnull
tagtypedataTypeData TypeStringString
tagtypefalseAlarmProbabilityFalse Alarm ProbabilityDouble0.001
tagtypeflatTestWeightFlat Test WeightDouble1
tagtypehighestThresholdValueHighest Threshold ValueDoublenull
tagtypelowestThresholdValueLowest Threshold ValueDoublenull
tagtypemaxOperatingValueMax Operating ValueDoublenull
tagtypeminOperatingValueMin Operating ValueDoublenull
tagtypemissedAlarmProbabilityMissed Alarm ProbabilityDouble0.001
tagtypenanTestWeightNaN Test WeightDouble1
tagtypenullHypothesisVarianceNull Hypothesis VarianceDouble0.0025
tagtypeoutlierTestWeightOutlier Test WeightDouble1
tagtypepaintBrushingTestWeightPaint Brushing Test WeightDoublenull
tagtyperesolutionData ResolutionStringnull
tagtypesampleFailureMagnitudesMeanSAMPLE FAILURE MAGNITUDES MEANInt10
tagtypesampleFailureMagnitudesVarianceSample Failure Magnitudes VarianceInteger40
tagtypesensorHealthIndexSensor Health IndexDoublenull
tagtypesensorHealthStatusSensor Health StatusBooleannull
tagtypeshiFlatLineEpsilonSensor Health Index Flat Line EpsilonDouble1.00E-08
tagtypeshiFlatLineNumberSensor Health Index Flat Line NumberInteger720
tagtypeshiHighThresholdSensor Health Index High ThresholdDouble1
tagtypeshiLowThresholdSensor Health Index Low ThresholdDouble0
tagtypeshiOutlierLimitsHighSHI Outlier Limits HighDoublenull
tagtypeshiOutlierLimitsLowSHI Outlier Limits LowDoublenull
tagtypestatusStatusString1
tagtypetimeseriesDataSourceTimeseries Data Source IdentifierStringnull
tagtypetimeseriesLinkTimeseries LinkStringnull
tagtypeuomGroupUnit of Measurement GroupUnitOfMeasurenull
tagtypestandardUomStandard Unit of MeasurementUnitOfMeasurenull
tagtypestandardUomGroupStandard Unit of Measurement GroupUnitOfMeasurenull

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 unquotedEndpoints
\ (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