Netilion Objects

Before you start working with Netilion objects, we encourage you to read about them. It will be worth it.

Netilion objects are generally flexible. We have designed them to accurately reflect the actual situations in production facilities. What should be an advantage can turn into the opposite, if you miss the core purpose and use of the objects. It’s better to invest some time now and avoid nasty surprises later on.

Example: Most of the main objects can be connected many to many. However it is important to understand the most common use of assets, instrumentations and nodes, so that the user interface of your application presents data in a coherent way.

Main Objects

Plant structure can be built of nodes, instrumentation and assets.

Asset

An asset is a concrete instance of a product. It has its unique serial number within the scope of the product’s manufacturing company. An asset can be installed at a technical location defined by a tag (instrumentation) or directly assigned to a node, e.g. a workshop. It can have asset specific documents attached such as a calibration certificate. Specifications (see Attribute Objects) are used to further specify the properties of an asset.

A product is required to create an asset.

Instrumentation

Instrumentation is a technical location within a plant, usually corresponding to a measurement point. The unique identifier of an instrumentation is the tag. Technically, the tag must only be unique within its parent scope - can be a node or a parent tag (instrumentation). Typically, tag names are kept unique throughout an entire plant. Specifications are available to define further properties, e.g. what the measurement point must fulfill. For flexibility, an instrumentation can be associated with one or more assets at the same time.

Node

Nodes are used to represent the plant structure in Netilion. They can be nested to form up a tree. Nodes are very versatile objects that can have different node types such as site, location, application, bus, loop or custom technology types. They are used to represent any type of structure that can be found in a production site. Therefore multiple levels of node structures can be used in parallel.

To create a tree of nested nodes, simply specify the parent node when creating a subsequent node.

Document

Documents are identified by name and version. A document has a classification indicating whether it is confidential, internal or public. Optionally, a document category can be used to group it. Documents require a status.

Documents belong to assets, products, nodes, instrumentations, events and more. They can be associated with more than one object. Their permissions are derived from the main object to which they are linked.
When creating a document, it is worth considering the correct object to link it to: A calibration certificate is specific to an asset, not to the instrumentation in which it is installed. However, if the asset changes location the document will move with it.

Attribute Objects

The main objects asset, instrumentation and node can be further described by attribute objects such as specifications, events or documents. These objects can only exist in Netilion with a reference to a main object. Their access permissions are directly derived from the permissions of the main objects to which they refer. In short, they can be seen as attributes stored outside of the main objects.
These attribute objects are subordinate to their main objects and are deleted when their main object is deleted.

Address

An address object can be added to User and to company. It is an object that is not available through a specific endpoint.
It will be included in the response on the main object. If the main objects is deleted, the address is deleted with it.

Attachment

The real files behind a document. One or more attacments can be added to a document. It is recommended to use one document and several attachments only to group tranlsations or different file formats of the same content underneath a main document. Attachments are of a specific format (MIME-Type) and in a specified language.

Following MIME-Types are 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

A document is required to create an attachment.

Event

Events are occurrences that take place at a particular time and affect one or more main objects. In a plant a typical event is, for example a calibration or a maintenance activity. Events have a mandatory type and a status. An event can be associated with both an asset and an instrumentation at the same time. It is automatically deleted, when the last reference object is deleted.

An asset or instrumentation is required to create an event.

Picture

One or more pictures can be added to most main objects such as asset, instrumentation, node and to product. The picture can be included when retrieving the main resource, or via separate endpoint. Pictures have to be a valid gif, jpg, jpeg or png file. The picture is deleted upon deletion of the main object.

Specification

Specifications are a set of key:value attributes that can be added to all main objects, as well as to products and events. Specifications allow great flexibility to enrich records individually, while maintaining a clean set of minimal attributes on the object model.

Values

Assets and instrumentations can write values. These values are subordinate to the associated object. In case the asset is deleted, the values will be deleted as well.

You can retrieve a collection of measurement values from an asset or an instrumentation. There are a number of aggregations and scopes that you can apply on the value endpoints to extract time series of your choice.
See the API documentation for more details.

Masterdata

Masterdata objects are used to describe and group Netilion objects. The most common are status, type, category as well as product and manufacturer.

The concept is used consistently throughout Netilion. For example most Netilion objects have a status and a type. The default is undefined if none is specified. These mandatory masterdata objects form the basis for focused views where objects are filtered by status or type.

Netilion provides a default catalogue with a minimum selection of records for each masterdata object. For example for status there are active, inactive, unknown. These are available to all Netilion users.

Masterdata in tenant scope

In addition to the official entries, you can create other masterdata records to customise your own catalogues. To create a new instance of any masterdata object you need to have an own tenant. It will only be visible to you and members of your tenant. (learn more about tenant user roles).

To use your tenant-scoped masterdata on e.g. an asset, the asset also needs to be associated with your tenant. This consistency of the asset’s tenant and the status’ tenant is validated by the API.

We offer the option to maintain translations for your tenant-scoped masterdata objects. Learn more in the internationalisation section.

Tenant

The tenant is your domain for customised masterdata and is defined by a unique name. It is associated with one or more users through the user roles tenant_admin and tenant_user. Create your own tenant before adding custom masterdata in Netilion. The user role tenant_admin is automatically assigned to the creator.

If you are using a Netilion service application, a tenant will be created in the background when you start adding your custom data to tenant-scoped objects.

To manage the tenant and the users assigned to it, go to
Netilion ID > Profile > Administration > Tenants

Read more about tenants in the Tenant section.

Company

Companies are defined by a unique name. They can play different roles, the most common being the manufacturer of products.

A tenant is required to create a company.

Product

A product is what is typically listed in a catalogue and can be ordered from a manufacturer. Its unique identifier is the product code within the scope of the manufacturing company. It may be accompanied by product-specific documents, such as an operating or installation manual.
Additional attributes may be added using specifications.

A manufacturing company is required to create a product, as well as your own tenant.

Type

The type is a mandatory attribute for many Netilion objects. The type is used to form subgroups according to the speciality or application of an object.
See the API documentation to check out all available objects.

Some examples of types are:

Node: location, loop, application
Instrumentation: flow, pressure, temperature
Event: configuration, calibration

A tenant is required to create a custom type.

Status

The status describes the current state or condition of an object. Status is a mandatory attribute for most Netilion objects. Some examples of states are:

Asset: active, inactive, failure
Instrumentation: active, inactive
Product: available, phase_out, order_stop
Event: scheduled, processing, done

A tenant is required to create a custom status.

Document Category

Document categories describe the content of the document e.g. operation manual. A document can belong to none or several document categories. Categories can be nested to form subcategories.

Some examples of categories are:

Document: certificates, calibration_report, manual

A tenant is required to create a custom document category.

Document Classification

The document classification describes the level of disclosure of a document. Documents such as a operation manuals can have a public classification. The following classifications are available by default:

Document: public, internal, confidental

A tenant is required to create a custom document classification.

User-related Objects

User

Each user can get its own user object using

v1/users/current

A user can be extended with a complete address in addition to the email. In case an address is added, it requires a defined set of attributes to be valid.

User Groups

User groups can be added by every user. The creator will have full permissions on the user group and is able to add other users to the group by providing the email of the invitee. User groups serve to share object permissions among several users.

User Roles

User roles regulate access on general actions. Netilion admins can add user roles. When you use the Netilion API you only need to be aware of tenant-specific user roles in order to share masterdata with other users.