Plant Business Life Cycle Objects

Netilion Cloud offers a structured (and some semi-structured) data storage for all data relating a plant's life cycle business objects.

Auditing & Versioning, please note :

For traceability and for functional reasons (e.g. time series data), every single modification on data is audited and also tracked. All instantiated models are persisted in a database.

For any modification done on instance attributes, the database will :

Keep the old value
Save the modification date
Save the modification event (create, update, delete)
Save the user ID that did the modification
Save the API-Key used to proceed the modification
Count up the version of instance modifications

Important concerning "renaming" instances: Although instances are identified by a technical ID and therefore any functional attribute theoretically should be editable without losing instance scope and its history, it is important to keep in mind that renaming an instance (e.g. renaming a specification key-attribute) will keep all audit entries! Renaming can't be done by creating new instances and copying current values!

You can find an example plant structure within the section Data Model

Assets
An asset represents a produced instance of a product issued a from defined manufacturer. It represents a good of a certain value and is defined by a serial number. The asset is identified by the combination of serial number and manufacturer.
An asset may be mounted to an instrumentation place. An asset may have attached specific documents such as e.g. a calibration certificate.
The mapping of documents to a specific asset indicates that these documents only belongs to that specific asset and in case of a device replacement shall also move with the asset. This also means, that attached documents neither do belong to the product nor to the instrumentation.

Access this object in API documentation

Products
A product represents a single defined product of a manufacturer. Within a manufacturer it is uniquely identifiable with its product code. Product properties such as material, specificity, communication protocols etc. will be assigned as specification data to the product. A product may have several relationships to different companies. A relationship's role may be the manufacturer and provider. Product specific documents such as operation or installation manual have to be assigned to the product.
Dependencies : Prior to create a new product, please create its Manufacturer/Company

Access this object in API documentation

Companies/Manufacturers
Companies/Manufacturers are defined with a unique name. Companies are used in different roles such as manufacturer of products.

Access this object in API documentation

Instrumentations
The instrumentation is coming from the instrumentation engineering and defines a general functional place within a plant. It may correspond to a measuring point. The instrumentation is uniquely identifiable through its address in a plant structure. Every instrumentation has a name, also known as "TAG". This TAG must be unique within its parent scope in a structural node. An instrumentation may have associated one or several assets at the same time. It defines the tasks and properties a measurement point has to fulfill. These requirements will be provided as instrumentation type and as specifications.

Access this object in API documentation

Nodes
Nodes are used to represent a plant structure. They typically are used as link list data structure. There are different node types such as Site, Location, Application, Bus, Loop or even some custom specific node types. Node structures go down in a plant structure to where the instrumentations are. There may be several different structures of a plant so different, independent and technological trees are possible. Instrumentations and assets may simultaneously get assigned to several nodes.

Access this object in API documentation

Specifications ^[1]
Specifications are the used mechanism to detail assets, products, instrumentations and nodes in a more specific way. This detailed specification is realized with semi-structured key-value-pairs. It allows great flexibility concerning data maintenance without losing a well defined data structure.
Important: Specifications always shall be attached to the entities they belong to regardless of the plant's life cycle. E.g. measurement data an asset measures during operation phase belongs to the asset. It is important to correctly define this from a functional point of view.

Access this object in API documentation

Detailed information about specifications

Status
The status describes the current state of an object. An object has exactly one status at a time and it must be strictly differentiated from other object properties or specifications. There are predefined states depending on the business object. Additionally there is the possibility to define custom states. Each model that has a status property shall have a status. In case the status is not known, the Undefined status is assigned.
States shall be defined as general as possible.
As an example, Assets have the following default states:
Active: Status of an asset which is in use
Inactive: Status of an asset that is not in use but ready for operation
Failure: Status of an asset that has a current dysfunction indication message that should be checked
Defective: Status of an asset that does not function anymore
You can also set your own statuses.

Access this object in API documentation (Asset Status)

Events
Events are certain, one-time incidents that occur at a specific time. An event always has to have a name and for better analysis purpose an event category. The naming shall help identifying each single event.
Some examples of event names:
Power blackout building A, 2nd floor (an event that may affect a lot of assets)
Configuration Upload from FieldCare device configuration software (an event that affects one asset)
Heartbeat Calibration from FieldCare device configuration software (an event that affects one asset)
An event occurs in a defined period of time. The duration gets visible with its start and end time. Events may affect a single or several assets. To that effect they have an m:n relation to assets. In an asset's life cycle typical events occur such as installation. commissioning, calibration, disruption or repair . Due to these events, documents such as calibration certificates may result. Events can be specified in a more detailed way by their type, status and again : specifications.

Access this object in API documentation

Documents
A document is a written, drawn, presented or recorded representation of thoughts. They are identifiable through their names and version. Documents are assignable to assets, products, instrumentations, events or even more entities. A document has a classficiation property (that indicates if its content is e.g. confidental, internal or public), a category and also a status.

Access this object in API documentation

Document Categories
Document categories is a meta data of a document and describes the content in an abstract way (e.g. Operation Manual). A document may belong to none or several document categories.

Access this object in API documentation

Document Classifications
The document classification indicates the intended visibility of a document's content. Documents such as a operation manuals may have a public classification. The following classifications are available per default:
Public
Internal
Confidental
It is also possible to define custom document classifications.

Access this object in API documentation

Attachments
Attachments are the files in which the content of the document is stored. These are the concrete instances of a document and they are of a special format (MIME-Type) and in dedicated language(s).
Following MIME-Types will be accepted:
text/plain
application/msword
application/pdf
application/rtf
application/xml
application/vnd.ms-excel
application/zip
image/bmp
image/gif
image/jpg
image/jpeg
image/png
image/tiff
image/vnd.dwg
Dependencies : Prior to create a new attachment, please create the related Document

Access this object in API documentation

Bill of Materials
A bill of material (in a plant's context) consists of a list of instrumentations and their specifications. The bill of material (BOM) typically originates during a engineering project and it will be used in the procurement phase to get request for quotations.

Access this object in API documentation

Request for Quotations
A request for quotation is sent to suppliers and refers to a bill of material for which an offering is demanded.

Access this object in API documentation

Quotations
A supplier's answer to a request for quotation is the quotation. The quotation contains a list of products fulfilling the required functionality of the demanded instrumentations.

Access this object in API documentation

Purchase Orders
Purchase orders are related to a supplier and to its quotation.

Access this object in API documentation

Deliveries
With a delivery the ordered products were becoming concrete (mostly) physical objects that from then on can be seen as assets. A delivery refers to one or several purchase orders.

Access this object in API documentation

Detailed information about Specifications

Products, Assets, Instrumentation and Nodes can have a specification. Meant by this is e.g. the process connection or the maximum pressure. Those examples are specific for some kind of measurement instruments but not valid for all assets of a factory.

Instead of adding this field to the asset model, and making it available to every asset, a Specifications object has been defined that belongs to the asset (one-to-one), containing this field.

The Specifications object can look like this:

   "max_pressure": {
     {
     "value": 5,
     "unit": "bar",
     "source_timestamp": "2016-07-25",
     "updated_at": "2016-07-25T07:37:04.032Z"
   },
   "communication": {
 "unit": "mA",
     "value": "4..20",
     "source_timestamp": "2016-07-25",
     "updated_at": "2016-07-25T07:37:04.032Z"
   }
 }

The specifications object of a pump could look like:

 {
   "rotation_speed_range": {
     "value": 5,
     "unit": "bar"
   },
   "approvals": {
     "value": "Ex II2 G c T4 (zone 1)",
     "unit": null
   }
 }

The two examples show how different the content of the specifications could be. To enable this dynamic object we define a specification resource on the API that behave like a key/value store. The key is the name the specification and the value is a document with two fields:

 {
"unit": "string"
"value": "string",
 }

The specification always exists in the path of its assignee (eg. /assets/1/specifiations). Possible operations are GET, PATCH and DELETE.

With GET the whole object can be accessed.
With PATCH you can update and add specifications.
With DELETE you can not remove the specifications object but only the keys from it (with PATCH you can only remove the value and/or unit of the existing key).

Since the specifications are bound to the object as if it were their own fields, they can be used to query on the owning object.
For example on the asset resource, with an asset having max_pressure defined in specifications with value=5, it could be queried like this:

 GET /assets?product\_id=2&specifications\_max\_pressure=5&specifications\_measuringrange=1-100&...

The "specifications_" is a prefix to the query to tell that the given key should be search within the specifications object. The query could be combined with other fields/keys and look like this:

 GET /assets?specifications\_max\_pressure=5

Extended Vector Specifications (only for Asset Specification)

For Asset Specification it is possible to save data in the field 'value' as vector. In the database the data is stored as jsonb.

Some requirements exists to proceed successfully:
The specification field 'unit' has to be a exactly 'vector'.

NOTE: If the field 'unit' is not exactly 'vector' the value will be stored as string and no error will be thrown. The given value has to be either a valid json or a string that contains a valid json terminated by double quotes.
The given value needs to be a flat list with the mandatory field 'value'. The field 'unit' is optional.

The specification object could look like :

Vector :

 { "event": {
     "source_timestamp": "2022-01-01T00:00:00",
     "unit": "vector",
     "value": [
        {
          "key1": {
           "value": "22",
           "unit": "C"
         }
        },
        {
          "this_key": {
            "value": "1234.56"
          }
        },
        {
          "some_key": {
            "value": ""
          }
        }
     ]
   }
 }

Vector as string:

 { "event": {
     "source_timestamp": "2022-01-01T00:00:00",
     "unit": "vector",
     "value": "[ { \"key1\": { \"value\": \"22\", \"unit\": \"C\" } } ]"
   }
 }

Hstore vs. Normalization

There are some use cases where data to a specific measurement not only consists of one key/value pair but of several ones. One example may be a predictive maintenance use case where data is needed as shown in the sample below:

 {
   "measurement": [
     {
       "FLOW_Out1Value_1": 47.33,
       "FLOW_Out2Value_1": 13.37,
       "SU_MassFlow_1": 4,
       "SU_VolumeFlow_1": 4,
       "FLOW_Out3Value_1": 13.57,
       "SU_Density_1": 4,
       "FLOW_Out6Value_1": 8.15,
       "SU_Temperature_1": 6,
       "FLOW_Out7Value_1": 15.08,
       "SU_Dynamic_Viscosity_1": 3,
       "SPV_CurrentSysConditionUnion_1": 9,
       "C4W_Frequency_1": 12.12,
       "C4W_SpvFrequencyStdDev_1": 13.12,
       "_time": 1502802741
     }
   ]
 }

This means values of specification need to be grouped, see below:

 {
   "measurement": {
     "updated_at": "2016-07-23T23:23",
     "unit": "object",
     "source_timestamp": "2016-07-23T23:23",
     "value": [
       { "FLOW_Out1Value_1": 47.33, "unit": "flow" },
       { "SU_MassFlow_1": 4, "unit": "parameter" },
       { "FLOW_Out2Value_1": 234.3, "unit": "flow" },
     ]
   }
 }

Plant Business Life Cycle Objects

Auditing & Versioning, please note :

Assets

Products

Companies/Manufacturers

Instrumentations

Nodes

Specifications [1]

Status

Events

Documents

Document Categories

Document Classifications

Attachments

Bill of Materials

Request for Quotations

Quotations

Purchase Orders

Deliveries

Detailed information about Specifications

Extended Vector Specifications (only for Asset Specification)

Hstore vs. Normalization

Specifications ^[1]