Requesting Smart Instrumentation's Metadata - Intergraph Smart Instrumentation - 2.3.12 - Training - Intergraph

Intergraph Smart Instrumentation Web API Tutorial

Language
English
Product
Intergraph Smart Instrumentation
Subproduct
Web API
Search by Category
Training
Smart Instrumentation Web Version
2.3

Before running the queries, make sure the variables in the Postman environment are populated with values matching your environment. For example: {{baseUri}} should have a value like https://hostName.domain.com matching your web server.

Get Description

The first request in the sample collection of Smart Instrumentation Web API exposes the description information. This includes the API version, information on the Smart API manager provider (token issuer), BaseUri, installed licenses, and other information.

  • Select the request 01.02 Get Description and click Send.

    {{baseUri}}api/si/{{versionNumber}}/Description

    View the response:

Get EDM (Entity Data Model)

This request gets the Entity Data Model (EDM) for the Smart Instrumentation. The EDM for a Web API is exposed via a single document (called the metadata document). The response is in XML format. The metadata includes important information about the API, entity sets (collections of entities), entities, navigation properties, and uri references.

  1. Select the request 01.03 Get EDM (Entity Data Model) and click Send.

    The URL is: {{baseUri}}api/si/{{versionNumber}}/$metadata

    Sending GET requests using the pre-configured JSON queries (1) (v2

    The following shows a partially collapsed example of the XML:

    • The response you get will look different from this example because the response depends on the BaseUri and domains existing in your database.

    • In Postman, collapse sections of the .xml by clicking on the small arrow next to the line numbers.

    • There are several Uri references that point to external metadata documents such as,Vocabularies, Annotations, PlantGroup metadata, and DataServices.

  2. Collapse the rows for a minimized version.

For more information about the XML schema definition, using a browser navigate to http://docs.oasis-open.org/odata/ns/edmx.

Reference Metadata

  • Vocabularies reference - A document containing terms. Each term defines information, for example a characteristic or behavior, that can further describe data. The core vocabulary provides terms to add more detailed information about data types in the Web API.


  • Annotations reference - This document defines the base model annotations. It provides complementary information for entities, properties, and navigation properties, such as a meaningful display name of the property, a description and title for entities, collections and so forth. The base model annotations do not include information about UDFs or UDTs which are covered by specific PlantGroup reference.

    GET Requests to Smart Instrumentation Metadata

    The next set of Uri references are complimentary metadata for each PlantGroup (domain).

    GET Requests to Smart Instrumentation Metadata (22)

    These Uri's include only visible UDFs and UDTs metadata relevant to each PlantGroup (domain),

  • Edmx:DataServices - One or more schemas describing the entity model exposed by the OData API.

Smart Instrumentation metadata is found under Com.Ingr.SiApi.V2 namespace. You can expand the Com.Ingr.SiApi.V2 namespace to reveal all the discoverable data Types.

When you expand each entity type, the list of visible properties is revealed, followed by navigation properties. The navigation properties reveal the relations between the current entity type and other entity types.

For example, under Instrument entity type you will find meaningful property names such as InstrumentName, InstrumentService, LoopName, and so forth.

Further down, below the instrument property list, search for a Navigation Property Name to see the relation between Instrument entity type, and Loop entity type.

Property and navigation property names are taking advantage of Pascal casing for better readability. These names originate from the same display names as in the desktop version but without any special characters. In the same manner, entity type names will mostly use Pascal casing as well, although there are some exceptions.

Get Annotations

The Smart Instrumentation Web API uses annotations to define additional information. These annotations describe the metadata that is common for all Smart Instrumentation domains (base model).

  1. Select the request 01.04 Get Annotations and click Send.

    {{baseUri}}api/si/{{versionNumber}}/Annotations/$metadata

  2. In the top right corner of the payload section, click to open a search box, and type InstrumentName. Since the same display name is used for multiple entity types, there are several results.

    The Target starts with the Com.Ingr.SiApi.V2 namespace, then the EntityType — DimensionalData, followed by the property name.

    If you want to view the InstrumentName property (that belongs to the Instrument entity type), search for Instrument/InstrumentName. This yields two results, where the second result is for the InstrumentNamePrefix property:

    GET Requests to Smart Instrumentation's Metadata (24)

    Each annotation provides also a Description and DisplayName for properties. The DisplayName value is the same display name as defined in the SI data dictionary in the desktop application.

    The PropertyGroup annotation enables clients to group properties by common characteristic.

    Properties of type double or that represent unit of measure are identified by UnitCategory annotation for the unit kind where applicable.

    Double properties get a value of Any.

    Example:

    Units of Measure Example

    Entity Type Annotations

    Entity types also have annotations with an additional Title annotation. The Title annotation denotes the property used to represent instances of complex or entity types and typically points to the Name (or similar) property for an entity.

  3. In the top right corner of the payload section, click to open a search box, type Instrument/InstrumentLoop, to search for the navigation property under the Instrument Entity type. The search returns two results. The first one is the actual navigation we want to look at.

    A similar navigation property is provided from the loop entity.

    GET Requests to Smart Instumentation's Metadata

Get PlantGroup Metadata

This PlantGroup metadata request is derived from the base model metadata (EDM), and its response is also in XML format. The PlantGroup metadata includes visible user defined fields (UDFs and UDTs).

  • Select the request 01.05 Get PlantGroup Metadata and click Send.

    {{baseUri}}api/si/{{versionNumber}}/Sites('{{SiteId}}')/PlantGroups('{{PlantGroupId}}')/$metadata.

    The XML describes all visible custom fields and UDTs.

    The reference Uri (that is marked with an arrow above) is the request to run for the PlantGroup annotations (next request).

Get PlantGroup Annotations

The PlantGroup annotations request is derived from the PlantGroup metadata request and its response is also in XML format. The PlantGroup metadata includes visible user defined fields and tables (UDFs and UDTs) only.

  1. Select the request 01.06 Get PlantGroup Annotations and click Send

    {{baseUri}}api/si/{{versionNumber}}/Sites('{{SiteId}}')/PlantGroups('{{PlantGroupId}}')/Annotations/$metadata

    The XML shows only the annotations of the visible UDFs and UDTs in the current PlantGroup.

  2. In the top right corner of the payload section, click to open a search box, and type Instrument/Supplier.

    The DisplayName is Supplier and the Description is (in our case) Supplier for entity Com.Ingr.SiApi.V2.WEB9.WEB9DEMO.Instrument based on UDF_C01.