Exposing the Engineering Data Editor - Intergraph Smart Instrumentation - Help - Intergraph

Intergraph Smart Instrumentation Smart API Tutorial

PPMProduct
Intergraph Smart Instrumentation
PPMCategory_custom
Help
Version_WebSI
2.1

The Smart Instrumentation Smart API exposes the Smart Instrumentation (desktop) Engineering Data Editors (EDEs) and their folders using an extension of the OData protocol called Parametric Filters.

  • The Smart API EDE payload reflects the base query which currently is saved to the query builder from which the EDE was generated. Layout changes made to the EDE during or after its creation such as filters, additions of columns, changes to the query, sort order, and so forth are ignored.

  • Smart API EDE requests are supported from Smart Instrumentation desktop version 2018 HF2 or above.

  • EDEs are project specific. You must specify which engineering project you require the EDE information for.

  • To get the actual EDE payload, you need to send a POST ExecuteEngineerinDataEditor action request.

  • Each EDE has an Instance Annotation request that you should send. This describes the content of the EDE; the column names, display names, their item type, data type, sequence of columns in the grid, visibility, read-only information, information about supported parameters: objectHierarchy and queryExpression.

  • Whenever objectHierarchy is defined as supported by the instance annotation, the POST request must provide parameters specifying the HighestPlantGroup, IntermediatePlantGroup and LowestPlantGroup. In other words, these parameters are required when the “Only run query on this level” option is selected in the query builder. Failing to do so or sending the wrong objectHierarchy parameter will result with HTTP 400 bad request error.

  • For an EDE to be discoverable, it must be generated first under the project.

  • For a view type (EDE folder) to be discoverable, it must have at least one discoverable EDE underneath.

  • Private and General EDE View Types (folders) and their EDEs are not exposed.

  • The EDE payload and instance annotation includes both the visible and invisible attributes and properties. It is the client side that should ignore the invisible properties identified by the instance annotation.

  • ExecuteEngineeringDataEditor: the payload of Select-Lists properties is displayed as in the desktop EDE and are not reflecting the index of the select list item.

  • The Id in the payload of each listed result of the ExecuteEngineeringDataEditor action has a fixed value of -1. It doesn’t play any role in the payload and it can be ignored (query options on this Id are meaningless).

  • In the case of an EDE that has no specific order defined on any of its columns, the default ascending order is applied to the first column. In case $orderby exists in the query expression body, the sorting will be according to $orderby query expression.

  • The ExecuteEngineeringDataEditor action payload does not provide the next page link at the bottom of the page. The client application must therefore manage the pagination using the $skip and $top query expressions.

Prerequisite

You should prepare a few EDEs in Smart Instrumentation (desktop) that you are connected to via the API. Do not create the EDEs under the General or Private view types. Also, create at least one EDE where you specify include Only run query on this level on one of the PAU item types. We recommend creating an EDE based on the shipped query Index- Instrument Index Basic Query.

Example:

  • As the EDEs and view types used by this tutorial may be different than the one you have, you will need to adjust the requests given in the collection by placing the Id values from your specific payloads.

  • If you have not selected Only run query on this level in your EDE and an objectHierarchy parameter is included in your request, an HTTP 400 Unexpected Object Hierarchy Resource ID Value is returned.

GET EDE View Types

This request lists the EDE view types (folders) for which there is at least one generated EDE.

  • Select the 09.01 Get EDE View Types request and click Send.

    {{baseUri}}api/si/{{versionNumber}}/Sites('{{SiteId}}')/PlantGroups('{{PlantGroupId}}')/Projects('0')/ViewTypeProject

    Example payload:

GET EDE List under a View Type

This request lists the EDEs under a specific view type.

  • Select the 09.02 Get EDE List under EDE View Type request.

    This example uses Id=1990 from the previous request. Before sending the request, modify the Id per your data and click Send.

    {{baseUri}}api/si/{{versionNumber}}/Sites('{{SiteId}}')/PlantGroups('{{PlantGroupId}}')/Projects('0')/ViewTypeProject('1990')/ViewTypeEde

    Example payload:

Get EDE Instance Annotation

This request describes the annotations of a specific view type.

Instance Annotation - is an OData extensibility mechanism that allows services and clients to include information other than raw data in request or response payload. The instance annotation is also used to include control information. In the Case of the Ede instance annotations, it includes parametric filter definition (parametricFilterDefinition) about supported parameters, supported object hierarchies, supported query options and column definitions.

To request the annotation for an EDE, query for a single instance with the "$format=application.json;odata.metadata=full" OData format parameter.

In addition, you must include the Prefer HTTP header on the request with the value: odata.include-annotations="*".

  • Select the 09.03 Instance Annotation request.

In this example, 1990 is used for the view type and 21979 is used for the EDE. Before sending the request, modify the Ids per your data source and click Send.

{{baseUri}}api/si/{{versionNumber}}/Sites('{{SiteId}}')/PlantGroups('{{PlantGroupId}}')/Projects('0')/ViewTypeProject('1990')/ViewTypeEde('21979')?$format=application/json;odata.metadata=full

The following are examples of different sections of the payload and their meaning:

SupportedParameters:- Describes which type of parameters are supported by the action.

For supported object hierarchy, look for the SupportedObjectHierarchies. When "PAU" is defined for SupportedObjectHierarchies, it implies that the base query limits the results on one of the Plant-Area-Unit hierarchies by setting the flag Only run query on this level.

In such case, the execute EDE action MUST provide the Highest, Intermediate and Lowest plant groups parameters (together with their Id) in the body of the execute POST request.

SupportedQueryOptions: - Describes which type of query options are supported to be used as parameters in the body of the request.

The query expression should be according to OData syntax.

ColumnDefinitions: - Lists the EDE columns with additional information:

  • PropertyName - The EDM property name

  • TypeName - The entity type it belongs to

  • IsReadOnly - Read only flag (set according to Smart Instrumentation rules)

  • DisplayName - The actual caption given to this column in the desktop query builder (If no caption exists the attribute DBDisplayName will be displayed)

  • SequenceNumber - The order of the column in the query builder grid

  • DataType - The columns data type

  • IsVisible - Defines if the property is visible

    True = Visible

    False = Hidden

    The client application is responsible for hiding the properties that have IsVisible=false.

  • IsDistint - Identifies that the base query has a flag to suppress repeating values.

At the end of the annotations file you will find the Name and the Description given to the EDE.

Body and Headers Definitions

The ExecuteEngineeringDataEditor POST request must include the following headers:

  • Key=Content-Type

  • Value=application/json

The Body of the request must include the SupportedParameters as follows:

  1. When no parameters are supported:

    {

    objectHierarchy; null,

    queryExpression: null

    }

    Empty closed brackets {}, will return the same result.

  2. For supported queryExpression, provide the query expression according to OData syntax, for example:

    {

    objectHierarchy:null,

    queryExpression: "$select=Id.LineNumberName&$orderby=LineNumberNamedesc&$filter=contains(LineNumberName,'1502')"

    }

  3. For supported PAU objectHierarchy, include the HighestPlantGroup and downstream paths to the LowetPlantGroups. In case there are more than three levels, include only three levels with the IntermediatePlantGroup that is closest to the LowestPlantGroup. for example:

    {

    objectHierarchy:{

    Name: "PAU",

    Path: null,

    ResourceIds:

    ["HighestPlantGroups('4003')/IntermediatePlantGroupHighestPlantGroup('4008')/LowestPlantGroupIntermediatePlantGroup('4012)"]

    }.

    queryExpression: null

    }

A request without a valid body, results ina HTTP 400 error being displayed.

  • Select the 09.04 ExecuteEngineeringDataEditor Action with objectHiearchy and $count query expression request.

    This request includes the count of items in the query expression and the object hierarchy in the body of the request:

To send this request, make sure that the EDE you are about to call supports PAU objectHierarchy parameters. Before sending the request, modify the Ids per your specific data and then click Send.

{{baseUri}}api/si/{{versionNumber}}/Sites('{{SiteId}}')/PlantGroups('{{PlantGroupId}}')/Projects('0')/ViewTypeProject('1990')/ViewTypeEde('21979')/Com.Ingr.SiApi.V2.ExecuteEngineeringDataEditor

The following is a sample payload.

ExecuteEngineeringDataEditor Action with objectHierarchy and Query expression

This request executes the similar request as before with additional queryExpressions in the body of the request.

  • Select the 09.05 ExecuteEngineeringDataEditor Action with objectHierarchy and Query expression request.

Since your EDE might not include the same columns as in this example, you need to update the queryExpression according to the EDE that you have created.

The body of the request for this example

To send this request, make sure that the EDE you are about to execute supports PAU objectHierarchy parameters. Before sending the request, modify the Ids per your specific data and then click Send.

ExecuteEngineeringDataEditor Action - Pagination

In this example the body includes objectHierarchy and the following query options in the query expression: $orderby, $count, $select, $top and $skip which list the second page of instruments.

Before sending the POST request, update your Ids as in previous requests.

Select the 09.06ExecuteEngineeringDataEditor Action - Pagination request and click Send.