Skip to main content

Information model and API

Deviation type Definition#

Deviation type is for grouping deviations and having type specific property definitions for specific group of deviations.

PropertyDefinitions field#

Deviation type can have linked property definitions to it. By linking property definitions user specifies which properties can be used in the deviation.

Only those property definitions can be linked to deviation type that have "deviatioType" application rule.

Property Definition metadata#

To replace deviation identifier in the mobile application, one of the property definitions can be marked as a display name. To achieve it you must update property definitioin metadata field and add displayNameField boolean field to it. Example:

{    "name": "location",    "metadata":{        "displayNameField": true    }}

Icon#

Icon's name is a key of icon that is agreed with FE. Icon's color is a HEX color.

General deviation type#

In the system, by default, exists default deviation type called "General" and all old deviations are linked to it. General deviation type will be chosen by default when creating a deviation.

Deviation Definition#

Deviation is an Observation/Assessment with any damage, which does not allow a system or system component to function as it was designed. Deviation can be observed during an inspection of an asset or captured by monitoring systems. For example, HSS broken teeth observed during an inspection is a Deviation.

Deviation may have properties that are used to describe it.

Deviations filtering#

Deviations Get all endpoint includes several filters that can be used to refine the results of a query.

GET /Deviations

By using these filters, users can easily search for Deviations based on specific criteria.

Filters:

  • ids: Ids of Deviations
  • excludeIds: Ids of Deviations to not include
  • searchText: Search text to search with ReferenceId
  • statuses: Deviations statuses
  • objectOwnerIds: Ids of ObjectOwners
  • typeIds: Ids of Deviations Type
  • riskIds: Ids of Risks
  • equipmentIds: Ids of Equipment
  • mainSystemIds: Ids of MainSystems
  • plantNames: Name of Plants
  • designObjectIds: Ids of DesignObjects
  • properties: See in properties filtering section
  • order: See in ordering section

Deviation unique values#

This endpoint is used to retrieve a list of unique values for a given filtering field in the Deviations API. This endpoint is helpful for identifying the possible values that can be used to filter Deviations.

GET /Deviations/UniqueValues

See unique values section

Type#

Deviation can have a type which is used to group them as well as separate properties.

Properties#

In deviation there can be used only PropertyDefinitions

  • Which ApplicationRule is Deviation
  • Are linked to it's deviation type

Designation of Deviation Object#

In order to designate a given deviation to a specific design, function or location, or any other aspect, assetReference attribute is used. The user can add main system, as well as the corresponding design object, e.g., designate to a function aspect that performs speed conversion function within chosen design.

The deviation can also be assigned to specific equipment that corresponds to the designated design.

Relationships#

The system also allows to link a deviation with related deviations via relationships attribute.

InstructionImageEndpoint

Work Type#

See in Entity types generic concept

Work Template#

Work Templates are templates based on which Work Items are created and they are revisioned entities.

Work Template has two dependent entities (WorkTemplateActivityTemplate and SectionTemplate). The initial work template has revision 1. It is unique with Id and revision.

Work Template behaviour is different whether there is Work Item created based on it or not. The system behaves like usual in case there are no Work Items. We will discuss the second scenario in the last headline.

Work Templates filtering#

Work Templates Get all endpoint includes several filters that can be used to refine the results of a query.

GET /WorkTemplates

By using these filters, users can easily search for WorkTemplates based on specific criteria.

Filters:

  • ids: Ids of Work Templates
  • excludeIds: Ids of Work Templates to not include
  • searchText: Search text to search with DispayName and ReferenceId
  • statuses: Work template statuses
  • objectOwnerIds: ids of ObjectOwners
  • tags: tags filter
  • properties: See in properties filtering section
  • order: See in ordering section

Work Templates unique values#

This endpoint is used to retrieve a list of unique values for a given filtering field in the WorkTemplate API. This endpoint is helpful for identifying the possible values that can be used to filter WorkTemplates.

GET /WorkTempltes/UniqueValues

See unique values section

Create-Delete-Get Work Template#

Create Work Template using the following endpoint:

POST /WorkTemplates

The user always gets the last revision of Work Template(s).

GET /WorkTemplates

GET /WorkTemplates/{id}

The user is allowed to delete only the latest revision of the Work Template in case there are no Work Items created based on it.

DELETE /WorkTemplates/{id}

Work Template Has Work Items#

Each of the following endpoints will create new revision of a Work Template in the following way. The system will make an exact copy of the Work Template and its dependent objects with +1 revision and apply the changes to it.

PUT /WorkTemplates

PUT /WorkTemplates/{id}/ActivityTemplates

POST /WorkTemplates/{id}/ActivityTemplates

PUT /WorkTemplates/{id}/SectionTemplates

POST /WorkTemplates/{id}/SectionTemplates

DELETE /WorkTemplates/{id}/SectionTemplates/{sectionTemplateId}

DELETE /WorkTemplates/{id}/SectionTemplates/{sectionTemplateId}

Files on Work Templates#

Work templates can also have linked file references

Using this endpoint user can create a link between work template and file reference.

POST /WorkTemplates/{id}/FileReferences

File location can be

When a work item is created based on the work template file references linked to the work template will also be linked to the work item.

With this endpoint user can delete the link between work template and file reference.

DELETE /WorkTemplates/{id}/FileReferences

With this endpoint user can get all file references that are linked to the work template

GET /WorkTemplates/{id}/FileReferences

Or get a specific file reference with the following endpoint

GET /WorkTemplates/{id}/FileReferences/{fileReferenceId}

Work Template Tags#

Tags serve as metadata that describe the Entities and allow for easy categorization and organization. The tags are stored as an array of strings within each Work Template object. The tags field is an array of strings representing the tags associated with the Entity.

Activity Template#

Activity Templates are templates based on which Activities are created and they are revisioned entities.

Activity Template has one dependent entity (InputTemplate). The initial activity template has revision 1. It is unique with Id and revision.

Activity Template behaviour is different whether there is Activity created based on it or not. The system behaves like usual in case there are no Activities. We will discuss the second scenario in the last headline.

Create-Delete-Get Activity Template#

Create Activity Template using the following endpoint:

POST /ActivityTemplates

The user always gets the last revision of Activity Template(s).

GET /ActivityTemplates

GET /ActivityTemplates/{id}

Unlike Work Templates there is a case where we can get old revisions of ActivityTemplate. When creating Work Item, Activities are being created based on Activity Templates that are linked to the Work Template. The user is allowed to add Activities to the Work Item only if they are created based on the revision of Activity Template that was used initially.

The following endpoint will return revisions of Activity Templates related to the particualar Work Item:

GET /WorkItems/{id}/ActivityTemplates

The user is allowed to delete only latest revision of Activity Template in case there are no Activities created based on it.

DELETE /ActivityTemplates/{id}

Activity Templates filtering#

GET /ActivityTemplates

By using these filters, users can easily search for ACtivityTemplates based on specific criteria.

Filters:

  • ids: Ids of Activities
  • excludeIds: Ids of Activities to not include
  • searchText: Search text to search with DisplayName and ReferenceId
  • statuses: Activity statuses
  • objectOwnerIds: Ids of ObjectOwners
  • activityTypeIds: Ids of ActivityTypes
  • templateTypes: Template type filter
  • workItemIds: WorkItem ids filter
  • order: See in ordering section
  • skip: Skip first n elements
  • take: Take first n elements

Activity Templates unique values#

This endpoint is used to retrieve a list of unique values for a given filtering field in the Activity Templates. This endpoint is helpful for identifying the possible values that can be used to filter Activity Templates.

GET /ActivityTemplates/UniqueValues

See unique values section

Activities#

Activities filtering#

GET /Activities

By using these filters, users can easily search for Activities based on specific criteria.

Filters:

  • ids: Ids of Activities
  • excludeIds: Ids of Activities to not include
  • searchText: Search text to search with DisplayName and ReferenceId
  • statuses: Activity statuses
  • dateOfActivityFrom: Filter by DateOfActivity from given date
  • dateOfActivityTo: Filter by DateOfActivity to given date
  • dateOfActivities: Filter by DateOfActivits
  • objectOwnerIds: Ids of ObjectOwners
  • responsibleIds: Ids of Responsibles
  • basedOnIds: Ids of BasedOn ActivityTemplates
  • typeIds: Ids of ActivityTypes
  • equipmentIds: Ids of Equipment
  • mainSystemIds: Ids of MainSystems
  • plantNames: Name of Plants
  • designObjectIds: Ids of DesignObjects
  • order: See in ordering section
  • skip: Skip first n elements
  • take: Take first n elements

Activities unique values#

This endpoint is used to retrieve a list of unique values for a given filtering field in the Activites. This endpoint is helpful for identifying the possible values that can be used to filter Activities.

GET /Activities/UniqueValues

See unique values section

Activity Template Has Activities#

Each of the following endpoints will create new revision of Activity Template in the following way. The system will make an exact copy of the Activity Template and its dependent objects with +1 revision and apply the changes to it.

PUT /ActivityTemplates

PUT /ActivityTemplates/{id}/InputTemplates

POST /ActivityTemplates/{id}/InputTemplates

DELETE /ActivityTemplates/{id}/InputTemplates/{inputTemplateId}

DELETE /ActivityTemplates/{id}/InputTemplates/{inputTemplateId}


Work Item#

When creating Work Items using Work Templates, the process involves the instantiation of all activities and inputs specified in the template. This streamlined approach ensures that each Work Item aligns with the predefined structure and requirements set by the template, promoting consistency and efficiency in project management.

It can be achieved using "basedOn" property in the Work Item DTO.

After the initial creation of Work Items based on templates, users can update "basedOn" field and add new templates. As new Work Templates are introduced to the list, the process insures the instantiation newly provided templates.

Work Item filtering#

GET /WorkItems

By using these filters, users can easily search for WorkItems based on specific criteria.

Filters:

  • ids: Ids of WorkItems
  • excludeIds: Ids of WorkItems to not include
  • searchText: Search text to search with DisplayName and ReferenceId
  • statuses: WorkItems statuses
  • dueDateFrom: Filter by DueDate from given date
  • dueDateTo: Filter by DueDate to given date
  • dueDates: Filter by DueDates
  • objectOwnerIds: Ids of ObjectOwners
  • tags: Filter by tags
  • basedOnIds: Ids of BasedOn WorkTemplates
  • equipmentIds: Ids of Equipment
  • mainSystemIds: Ids of MainSystems
  • plantNames: Name of Plants
  • designObjectIds: Ids of DesignObjects
  • properties: See in properties filtering section
  • order: See in ordering section
  • skip: Skip first n elements
  • take: Take first n elements

Work Item unique values#

This endpoint is used to retrieve a list of unique values for a given filtering field in the WorkItems. This endpoint is helpful for identifying the possible values that can be used to filter WorkItems.

GET /WorkItems/UniqueValues

See unique values section

Files on Work Items#

Work items can also have linked file references

Using this endpoint user can create a link between work item and file reference.

POST /WorkItems/{id}/FileReferences

File location can be

When a work item is created based on the work template file references linked to the work template will also be linked to the work item.

With this endpoint user can delete the link between work item and file reference.

DELETE /WorkItems/{id}/FileReferences

With this endpoint user can get all file references that are linked to the work item

GET /WorkItems/{id}/FileReferences

Or get a specific file reference with the following endpoint

GET /WorkItems/{id}/FileReferences/{fileReferenceId}

Linking Deviations to WorkItems#

Link Deviations to WorkItems to have overview on which deviations technicians are going to perform activities in scope of particular Work Item.

Use the following endpoints to link, unlink or get Work Item's Deviations or Deviation's Work Items.

GET /WorkItems/{id}/Deviations

POST /WorkItems/{id}/Deviations/{deviationId}

DELETE /WorkItems/{id}/Deviations/{deviationId}

GET /Deviations/{id}/WorkItems

POST /Deviations/{id}/WorkItems/{workItemId}

DELETE /Deviations/{id}/WorkItems/{workItemId}


Work Item Tags#

Tags serve as metadata that describe the Entities and allow for easy categorization and organization. The tags are stored as an array of strings within each Work Item object. The tags field is an array of strings representing the tags associated with the Entity.

When Work Item is created based on Work Template the Work Item inherits the tags associated with the Work Template.

File reference#

AIH location#

If location of the file reference is "AIH" then file is located in "Files" microservice. "id" field of "aihFile" corresponds to the file's Id in "Files" microservice.

External location#

If location of the file reference is "External" then the "url" of the source should be specified. User also has the option to name the file from the external source.

Tags#

Tags serve as metadata that describe the Entities and allow for easy categorization and organization. The tags are stored as an array of strings within each Work Item object.

Endpoints:

GET /Tags

This endpoint returns a list of all the distinct tags associated with Work Items and Work Templates in the system.

Medias#

Images#

Image Identification Criteria#

To ensure that the uploaded file is an image, the system checks several criteria:

  1. Extension: The system examines the file extension to identify if it matches common image formats. Supported image extensions include:
  • .jpg
  • .jpeg
  • .png
  • .gif
  • .bmp
  • .tiff
  • .ico
  • .webp
  • .heic
  • .svg
  • .avif
  1. MIME Type: The Multipurpose Internet Mail Extensions (MIME) type is another method of verifying the file's nature. The system validates the MIME type against a list of accepted image MIME types:
  • image/jpeg
  • image/jpeg
  • image/png
  • image/gif
  • image/bmp
  • image/tiff
  • image/x-ico
  • image/webp
  • image/heic
  • image/svg+xml
  • image/avif

  1. File Headers: The system analyzes the first 8 bytes of the file to determine its type. These file headers provide crucial information about the file and are different from the file extension. This method helps prevent users from deceiving the system by renaming files with incorrect extensions.

  2. File Content: The system checks for file corruption to ensure that the uploaded file remains intact during the resizing process. If the file appears to be tampered with or corrupt, the system retains the original image without any resizing.

Image resizing#

When users upload images to the system via the POST /Medias endpoint. The system performs various checks to determine if the uploaded file is indeed an image. If the file is a valid image, the system resizes it based on predefined rules and stores the resized versions for retrieval.

If the system successfully identifies the uploaded file as a valid image, it initiates the image resizing process. However, images are resized only if their dimensions exceed a predefined threshold. The resizing follows the guidelines below:

  • Original Size: The image can be retrieved in its original size by using the query parameter size=Original when accessing the /Medias/{id}/Data endpoint.

  • Medium Size: To obtain a resized version with a maximum dimension of 1000 pixels, use the query parameter size=Medium. The aspect ratio of the original image is preserved, meaning the max dimension (width or height) will be adjusted to fit within the 1000 pixels limit while maintaining proportionality.

  • Small Size: Similarly, you can retrieve a smaller version with a maximum dimension of 256 pixels using the query parameter size=Small. The aspect ratio is maintained during this resizing process.

In GET /Medias/{id}/Data will be added new query parameter size with values [Original, Medium, Small] which for now will be supported only for Images.