GET Requests to expose Items and their Properties - Intergraph Smart P&ID - 2.0 - Customization & Programming - Hexagon

This tutorial uses vessels as the examples in requests, however, you can run requests for any of the items types available in the metadata.

• The number of items that is retrieved in the payload is limited to 25. A link at the bottom of the payload provides access to the next 25 items, including all their related properties. To view the next 25 items, scroll down to the bottom of the payload to find a link and then copy and paste the link into the URL address bar. The example provided here is based on our tutorial environment:

  https://apiservername.domain.com/WebApi/SPID/V2/Sites%28%27WEBAPISITE001%27%29/Plants%28%27PLANT001%27%29/Vessels
  ?%24skip=25

  

• Request responses do not include case data properties. From Version 2.0.6, the case data properties can be included in the payload by adding the string '?$casedata=true' at the end of the request, for example:

  https://apiservername.domain.com/WebApi/SPID/V2/Sites('WEBAPISITE001')/Plants('PLANT001')/
  Vessels?$casedata=true

  The additional string '?$casedata=true' is not required for requests that include case data properties within query options such as $select, $filter, $orderby, and so forth.

  For more information about case data properties, see the introductory topic Properties Glossary.

Vessels

The following request runs on Vessels in a plant. "/Vessels" is added to the request after the plant Id, in this case "PLANT001". The payload exposes only common properties.

• Select the request 03.01 Vessels and click Send.

  https://apiservername.domain.com/WebApi/SPID/V2/Sites('WEBAPISITE001')/Plants('PLANT001')/
  Vessels

Vessels plus count

The following request includes the total count of vessels in the payload.

• Select the request 03.02 Vessels + count and click Send.

  https://apiservername.domain.com/WebApi/SPID/V2/Sites('WEBAPISITE001')/Plants('PLANT001')/
  Vessels?$count=true

  Use $count=true when dealing with data. This lets the service know how many items are needed to report and avoids the need for an unnecessary link to the next page. The count appears at the beginning of the payload and is shown highlighted:

  

  The count shows the total number of items in the entire payload and not just on the current page of the response.

Vessels plus count plus selected properties

The following request is built on the previous one, with additional parameters for selected properties.

• Select the request 03.03 Vessels + count + selected properties and click Send.

  https://apiservername.domain.com/WebApi/SPID/V2/Sites('WEBAPISITE001')/Plants('PLANT001')/
  Vessels/Com.Ingr.SPID.V2.WEBAPISITE001.PLANT001.Vessel/?$count=true&$select=Id,ItemTag,
  EquipmentSubclass,EquipmentType,aabbcc_code

  

  

  • When selected properties appear in the request, you must include the namespace containing the specific site, plant, and item type:

    /Com.Ingr.SPID.V2.WEBAPISITE001.PLANT001.Vessel

    This is necessary because the properties are defined at the level of the plant metadata.

  • Any invalid characters in site or plant names such as space, colon, backslash, are replaced by a double underscore (__) in the namespace.

  • For selection of more than one property, each property parameter is separated by a comma, without spaces.

Vessels ordered by item tag in ascending order plus selected properties

The following request adds the method of sorting items by their item tags in ascending order.

• Select the request 03.04 Vessels + order by Item Tag Asc + selected properties and click Send.

  https://apiservername.domain.com/WebApi/SPID/V2/Sites('WEBAPISITE001')/Plants('PLANT001')/
  Vessels/Com.Ingr.SPID.V2.WEBAPISITE001.PLANT001.Vessel/?$orderby=ItemTag&$select=Id,ItemTag,
  EquipmentSubclass,EquipmentType,aabbcc_code

  

Vessels ordered by item tag in descending order plus selected properties

The following request adds the method of sorting items by their item tags in descending order.

• Select the request 03.05 Vessels + order by Item Tag Desc + selected properties and click Send.

  https://apiservername.domain.com/WebApi/SPID/V2/Sites('WEBAPISITE001')/Plants('PLANT001')/
  Vessels/Com.Ingr.SPID.V2.WEBAPISITE001.PLANT001.Vessel/?$orderby=ItemTag desc&$select=Id,
  ItemTag,EquipmentSubclass,EquipmentType,aabbcc_code

  

In the above requests, we used the entity type ‘Vessel’. There are other collections of entity types in the plant. Those collections are exposed in the request 02.02 Common metadata. In the response, search for the string: ‘EntityType Name=Plant’ to reveal a list of all the navigation properties of the plant.

Specific vessel

The following request retrieves a specific vessel based on its item tag using the $filter function. In the example below, the filter is used to find a vessel with an Item Tag value = ‘V-100A’.

• Select the request 03.06 Specific vessel and click Send.

  https://apiservername.domain.com/WebApi/SPID/V2/Sites('WEBAPISITE001')/Plants('PLANT001')/
  Vessels?$filter=ItemTag eq 'V-100A'

  This filter retrieves the vessel with all its properties. For details of other ways in which the $filter function can be used, see GET Requests using Filters.

Specific vessel + selected properties

The following request is built on the previous one, with additional parameters for selected properties.

• Select the 03.07 Specific vessel + selected properties request and click Send.

  https://apiservername.domain.com/WebApi/SPID/V2/Sites('WEBAPISITE001')/Plants('PLANT001')/
  Vessels/Com.Ingr.SPID.V2.WEBAPISITE001.PLANT001.Vessel/?$filter=ItemTag eq 'V-100A'&$select=
  Id,ItemTag,EquipmentSubclass,EquipmentType,aabbcc_code

  

Specific vessel + expand nozzles

This request retrieves all the properties of a specified entity (vessel) and of the instances of an associated entity type (nozzles). For this purpose, the $expand function for the entity is used in the request. In this request, you will specify the vessel by entering its Id as discovered in the previous request.

Smart P&ID Web API does not support multiple levels of item expansion. For example, you can run a single request to view all the nozzles associated with a vessel, but you cannot further expand the nozzles to view their piping points. To view the piping points for the nozzles, you must run a separate request for each individual nozzle that includes the parameter '?$expand=PipingPoints'.

• Select the 03.08 Specific vessel + expand nozzles request and click Send.

  https://apiservername.domain.com/WebApi/SPID/V2/Sites('WEBAPISITE001')/Plants('PLANT001')/
  Vessels('95A884DDC4714DF0FF30A6ABA5F869F2')?$expand=Nozzles

  

  In the payload, search for the string: ‘PLANT001.Nozzle’. The number of occurrences of this string corresponds to the number of nozzles attached to the specified vessel.

Nozzles + count + selected properties for specific vessel

This request uses the same vessel Id as the previous request and a similar syntax to the request 03.03 Vessels + count + selected properties to count the number of nozzles and display selected properties of those nozzles. Unlike the previous request, the $expand function is not used and so the properties of the vessel are not shown in the payload.

• Select the 03.09 Nozzles + count + selected properties and click Send.

  https://apiservername.domain.com/WebApi/SPID/V2/Sites('WEBAPISITE001')/Plants('PLANT001')/
  Vessels('95A884DDC4714DF0FF30A6ABA5F869F2')/Nozzles/Com.Ingr.SPID.V2.WEBAPISITE001.PLANT001.
  Nozzle/?$count=true&$select=Id,NozzleType,aabbcc_code,SP_EquipmentID,SP_PipeRunID