Skip to main content

Information model and API

Aspects#

Aspect is used to describe viewpoints from which we can study an object or the interrelations of this object to other objects.

AspectEndpoints

Aspect object#

The information in Aspect:

  • Id - unique id
  • Name(*)
  • Type - allowed values : Custom | Standard

There are 4 standard aspects when Designations API is installed:

  1. Function
  2. Location
  3. Product
  4. Type

Applier Languages#

Applier Language allows to provide the designation information in more than one language.

ApplierLanguageEndpoints

Applier Language object#

The information in ApplierLanguage:

  • Id - unique id
  • Name(*)

Schemas#

A schema functions as an extensive database containing codes related to system and component categories.

SchemaEndpoints

Schema object#

The information in Schema:

  • Id - unique id
  • Name(*)
  • Status - current status
  • Version - current version
  • ObjectOwner(*) - owner of Schema

Schema Nodes#

Schemas feature node trees that illustrate codes along with accompanying examples.

SchemaNodeEndpoints

The following endpoint enables the update of a node along with its children. However, if the parentId is not specified in the request, the entire tree will be replaced with the new tree provided in the request:

PUT/Schemas/{schemaId}/Nodes

Schema Node object#

The information in SchemaNode:

  • Id - unique id
  • Name(*)
  • Code(*)
  • Definition
  • Example
  • ParentId - field to establish tree structure of SchemaNodes
  • Children - field to establish tree structure of SchemaNodes

Here is an example of a SchemaNodes tree:

[     {        "id": "f1930d5a-45f7-4f88-97a0-0f04fe7c8230",        "name": "MAIN SYSTEM",        "code": "Main system",        "definition": null,        "example": null,        "parentId": null,        "children":         [            {                "id": "cd7aa19d-5917-4c00-90f5-d856435b07b2",                "name": "ENERGY CONVERTION SYSTEM",                "code": "G",                "definition": null,                "example": null,                "parentId": "f1930d5a-45f7-4f88-97a0-0f04fe7c8230",                "children": []            },            {                "id": "e856f1df-0cbd-42e5-be78-312ad614a436",                "name": "COMMON COMMUNICATION SYSTEM",                "code": "K",                "definition": null,                "example": null,                "parentId": "f1930d5a-45f7-4f88-97a0-0f04fe7c8230",                "children": []            },            {                "id": "9e6e1621-9f8e-434e-8161-7337289a4430",                "name": "TRANSMISSION OF ENERGY OR RESOURCE",                "code": "W",                "definition": null,                "example": null,                "parentId": "f1930d5a-45f7-4f88-97a0-0f04fe7c8230",                "children": []            }        ]    }]

Structures#

A structure is a hierarchical arrangement of components, organized based on a particular aspect.

StructureEndpoints

Structure object#

The information in Structure:

  • Id - unique id
  • Name(*)
  • Status - current status
  • Version - current version
  • ObjectOwner(*) - owner of Structure
  • Aspect(*)
  • Group - StructureGroup that structure belongs to
  • Schemas - field to link Schemas by Id and Version
    • Id
    • Name
    • Version

Structures can only be linked to a Schema's version that is currently in an active status.

Structure Nodes#

Structure feature a node tree for assets with predefined characteristics, utilizing pre-existing codes from published schemas.

StructureNodeEndpoints

The following endpoint enables the update of a node along with its children. However, if the parentId is not specified in the request, the entire tree will be replaced with the new tree provided in the request:

PUT/Structures/{structureId}/Nodes

Structure Node object#

The information in StructureNode:

  • Id - unique id
  • Name(*)
  • Instance
  • SchemaNode - field to link SchemaNode by Id
    • Id
    • Code
    • Name
  • ApplierStructures - field to specify node's Code and Name with different languages
    • ApplierLanguage
    • Code
    • Name
  • ApplicableProperties - field to apply properties by Id for later usage in DesignObjects
    • Id
    • Name
    • AppliedOnDescendants - applies properties for child nodes
    • IsInherited - specifies if property is inherited or not
  • ParentId - field to establish tree structure of StructureNodes
  • Children - field to establish tree structure of StructureNodes

Here is an example of a StructureNodes tree:

[    {        "id": "69d03a71-e25b-407e-a8f3-3ac0915969dc",        "name": "Battery System",        "instance": null,        "schemaNode":         {            "id": "f10b955f-0102-4e03-ba84-630d9fd064ee",            "code": "C",            "name": "Need Name"        },        "applierStructures": [],        "applicableProperties": [],        "parentId": null,        "children":         [            {                "id": "dc8a1c39-8252-482f-96a7-27e51bd7e967",                "name": "LV Distribution systems",                "instance": null,                "schemaNode":                 {                    "id": "0025a118-6323-4c32-97df-573591647e65",                    "code": "BFA",                    "name": "Low voltage distribution board"                },                "applierStructures": [],                "applicableProperties": [],                "parentId": "69d03a71-e25b-407e-a8f3-3ac0915969dc",                "children":                 [                    {                        "id": "f615488a-39f1-4c4f-a8a9-17e488c3b7bf",                        "name": "low voltage distribution system",                        "instance": "11",                        "schemaNode":                         {                            "id": "0025a118-6323-4c32-97df-573591647e65",                            "code": "BFA",                            "name": "Low voltage distribution board"                        },                        "applierStructures": [],                        "applicableProperties": [],                        "parentId": "dc8a1c39-8252-482f-96a7-27e51bd7e967",                        "children": []                    }                ]            }        ]    }]

The Validation endpoint serves the purpose of validating a Structure. A Structure is considered valid when all of its nodes do not have any broken references. A broken reference may occur when a SchemaNode, which is linked to one of the StructureNodes, has been removed in a new version of the Schema, and the Structure's Schema reference is updated to that new version.

GET/Structures/{structureId}/Validation

The endpoint provides the following response:

{    "title": "The node is broken.",    "status": 200,    "brokenReferences":     [        {            "id": "90512c82-37bf-4672-9e17-3a6a08b2925b",            "referencedId": "67bde097-38be-42bf-825b-c1dd4d4ed29f"        },        {            "id": "a2cdd1e3-7f81-4a13-9b41-9046232ede0b",            "referencedId": "90cfaea1-4dbd-40b9-a8b8-6bef142bfa85"        }    ]}

In this response, the Id represents the StructureNode's Id, while the ReferenceId represents the SchemaNode's Id, which has been deleted.

Structure Groups#

Structure Group allows to group similar structures together for a clear view.

StructureGroupEndpoints

Structure Group object#

The information in StructureGroup:

  • Id - unique id
  • Name(*)

Designs#

A design encompasses a collection of components, represented by design objects.

DesignEndpoints

Design object#

The information in Design:

  • Id - unique id
  • Name(*)
  • Status - current status
  • Version - current version
  • ReferencedStructures - field to link Structures by Id and Version
    • Id
    • Name
    • Version
    • IsPrimary - specifies if the structure is the primary one or not
  • Parameters - optional components
  • ObjectOwner - owner of Design
  • Properties - additional properties

Only one structure reference can be set as primary. Designs can only be linked to Structures that are currently in a draft or active status.

Design Objects#

The design object is used to represent a component in an asset.

DesignObjectEndpoints

Design Object object#

The information in DesignObject:

  • Id - unique id
  • Name(*)
  • ObjectOccurences - field to link StructureNode with specifing aspects and giving values to applied properties
    • StructureNodeReference
      • StructureId
      • Version
      • NodeId
    • Aspect
    • Properties
  • Parameters - optional component identification
  • Designation - field which unambiguously identifies an object of interest within the considered system See in Reference Designation section

Parameters are established within designs, and subsequently, DesignObjects are associated with these parameters. When a DesignObject is connected to a parameter, it becomes conditionally dependent on whether that parameter is activated within a specific MainSystem or not.

The Validation endpoint serves the purpose of validating a Design. A Design is considered valid when all of its objects do not have any broken references. A broken reference may occur when:

  1. A StructureNode linked to one of the DesignObjects has been removed in a new version of the Structure, and the Design's Structure reference is updated to that new version.
  2. A StructureNode linked to one of the DesignObjects previously had a property linked to the DesignObject, but this property is no longer applicable in a new version of the Structure, and the Design's Structure reference is updated to that new version.
  3. A property that was previously linked to a DesignObject with a null value has now become required.
  4. A required property is applicable to a StructureNode, and the StructureNode is linked to a DesignObject, but the property itself is not linked to the DesignObject.

GET/Designs/{designId}/Validation

The endpoint provides the following response:

{  "title": "The object is broken.",  "status": 200,  "brokenDesignObjects": [    {      "id": "ae73b170-3469-40c7-a2e9-7d89789c76b4",      "brokenReferences": [        {          "structureId": "5cdd26f4-66ec-4082-abcf-cd34349b3aa1",          "nodeId": "f2cedc6d-bc0a-4735-a87a-2ad788f1fd62",          "brokenProperties": [            "hopheight"          ]        }      ]    },    {      "id": "851d8ea4-8db3-41a1-ae0a-994cd4f8b3e9",      "brokenReferences": [        {          "structureId": "2d2e32ae-4773-440a-a485-7bfdc062692c",          "nodeId": "8db099a2-79d5-455d-9fca-78d21a442e52",          "brokenProperties": []        }      ]    }  ]}

In this response, the Id represents the DesignObject's Id.

Audit log on Designations objects#

Users can view the complete history of an object by specifying its id. This history includes information on the designation object's creation, modifications, old and new values, as well as details on when changes were made and by whom. All types have the following endpoint:

GET/Schemas/{id}/AuditTrails

AuditTrail object#

The information in AuditTrail:

  • Id
  • AuditorId
  • AuditorEmail
  • State - values : Added | Modified | Deleted
  • OldValues
  • NewValues
  • CreatedDate - when audit was tracked

Versioning#

Many external APIs rely on the data in Designations API. To avoid breaking changes to the data (e.g. references to deleted objects), there is versioning. Versioning means that the user can make changes to the data, but history is kept. Once a data structure is set to active, it can never be deleted again, and if changes are required, then the configurator must issue a new version. When referencing data in the Designations API, the external system must reference both id (GUID) and version of the structure.

versioning

External systems should not reference draft data structures, since there is no ensurance that the data will not change. Once the data is activated (published), then the external system can be sure that the data can never change, thus references will never break.

versioning

In simple terms, versioning helps us keep track of changes, ensures data remains available, and makes sure external systems always know which version of the data they're using.

Schemas/Structures/Designs undergo versioning. To access information about all versions, including their version numbers and corresponding statuses, for a particular object, you can use the following endpoint:

Get /Schemas/{id}/Versions

Reference Designation#

The purpose of a reference designation is to clearly and uniquely identify a specific object within a given system.

Consider the following example:

Design Object: 161 KV XLPE CABLE (IC1)

Reference Designation: =T001.AE_.AEC.AEC01.WB001\n+T001.UMS01.L001

In this context:

'=' signifies the prefix associated with the first aspect of the structure.

'T001' represents a combination of the schema node's code and instance at the first level of the tree structure, followed by codes of subsequent structure nodes, linked with periods ('.').

To separate different occurrences of the object, '/n' is used. Following this, the same structural logic is repeated for the next occurrence of the object.