AIM API

This section describes some typical examples of using the AIM API to access data stored in AIM.

Data in AIM, which 3rd party systems might need to access, can be classified into the following categories:

• Facility Objects (Tags)

  • Attributes

  • Relationships including Document Links

• Documents

  • Attributes

• Equipment Objects

  • Attributes

  • Relationships

The AIM API calls are listed in the following table:

Notes:

• Where {dashboardUrl} has the format, https://[asset].dashboard.[account].aveva.com, or for multiportal customers the format is, https://[asset].dashboard.[account].aveva.com/?portalId=[folderId], where [folderId] is the CONNECT folder ID.

• You must have an authentication bearer token from CONNECT for the asset whose data is to be accessed.

• The API calls documented here are the only AIM API calls recommended for use with AIM-A.

  AIM API	Usage
  GET {dashboardUrl}/api/domain/authorization/issessionvalid	To check if a session is still valid and retrieve the XSRF cookie.
  POST {dashboardUrl}/api/v1/domain/searches/run	To fetch data from AIM. The request body contains information on the search parameters and data to be retrieved for the objects fulfilling the criteria.
  For Tags: GET {dashboardUrl}/api/v1/domain/dataGroup/{objecthandle} ?dataGroupNames=Main Attributes &dataGroupNames=Related Items 1 &dataGroupNames=Related Items 2 &dataGroupNames=Related Items 3 &dataGroupNames=Related Items 4 &dataGroupNames=Related Items 5	Different DataGroup names can be passed to this API. Different Related Items data group names fetch the following values (for Tag Summary views): Related Items 1: Equipment Related Items 2: Parts/Components Related Items 3: Documents and 3D Models Related Items 4: Events Related Items 5: Activities/Tasks Fetch attributes and related items for each object by passing in the object handle. This API will only return 3000 related items - for performance reasons.
  For Documents: GET {dashboardUrl}/api/v1/domain/dataGroup/{objecthandle} ?dataGroupNames=Main Attributes &dataGroupNames=Related Items 1 &dataGroupNames=Related Items 2 &dataGroupNames=Related Items 3 &dataGroupNames=Related Items 4 &dataGroupNames=Related Items 5	Different Related Items data group names fetch the following values (for Document Summary views): Related Items 1: Tags Related Items 2: Equipment Related Items 3: Documents and 3D Models Related Items 4: Events Related Items 5: Activities/Tasks
  For Equipment Objects: GET {dashboardUrl}/api/v1/domain/dataGroup/{objecthandle} ?dataGroupNames=Main Attributes &dataGroupNames=Related Items 1 &dataGroupNames=Related Items 2 &dataGroupNames=Related Items 3 &dataGroupNames=Related Items 4	Different Related Items data group names fetch the following values (for Equipment Summary views): Related Items 1: Tags Related Items 2: Documents and 3D Models Related Items 3: Events Related Items 4: Activities/Tasks

Steps

1. Call GET API and pass a bearer token for authorization to get a XSRF cookie.

   GET {dashboardUrl}/api/domain/authorization/issessionvalid

   Example: {dashboardUrl}/api/domain/authorization/issessionvalid

2. Retrieve the cookie from the above request and add it into the header of the POST API call (see Figures 1 and 2)

   POST {dashboardUrl}/api/v1/domain/searches/run

   Example: {dashboardUrl}/api/v1/domain/searches/run

   1. For full loads, pass in a request body based on the example in section Search API Request Inputs - Initial Load below.

   2. For delta loads, pass in a request body based on the example in section Search API Request Inputs - Delta Loads below.

   3. Always call issessionvalid API before getting subsequent pages.

   4. The field ‘totalNumberOfResults’ in the response gives the total number of records and is to be used to calculate the page count.

3. Call the GET API to retrieve object attributes and relationships by passing an object handle, for each object in the response from the previous POST API.

   GET {dashboardUrl}/api/v1/domain/dataGroup/{objecthandle}?dataGroupNames=Main Attributes&dataGroupNames=Related Items 1&dataGroupNames=Related Items 2

   Example: {dashboardUrl}/api/v1/domain/dataGroup/975441?dataGroupNames=Main Attributes&dataGroupNames=Related Items 1&dataGroupNames=Related Items 2

   Note: It is recommended to continue calling the above API for fetching the tag-document relationships even though the results are capped at 3000. When the tag-document relationships returned reaches 3000, then additionally call the below API to fetch all tag-document relations.

4. Call the POST API to retrieve the tag-document relationships by using a request based on the example in section Search API Request Inputs – Tag-Document relationships, and passing in the fullId as highlighted for each object in response from the POST API from point 2.

   POST {dashboardUrl}/api/v1/domain/searches/run

   Example: {dashboardUrl}/api/v1/domain/searches/run

Figure 1: Retrieving the x-xsrf cookie from the issessionvalid GET API

Figure 2: Using the retrieved cookie in the Search API

Search API Request Inputs - Initial Load

The following table shows an example request body to be used for retrieving the full set of data (not a delta) from AIM. This could be used after an initial load:

Notes:

• It is sufficient to include in the "Tags" a projection criteria of "is implemented by" to retrieve the tag-equipment relationships.

• DOCUMENT CONTENT is the parent of Document and Document Package classes. Therefore, the above call fetches both documents and document packages. However, if the call needs to be more specific, then modify the DOCUMENT CONTENT class accordingly. This change can be applied to section Search API Request Inputs - Delta Loads and section Search API Request Inputs – Tag-Document relationships.

Search API Request Inputs - Delta Loads

The following table shows an example request body to be used for retrieving a delta set of data. Update the highlighted date to retrieve the delta from a specific date:

Search API Request Inputs – Tag-Document relationships

Notes:

• It is sufficient to use Tags linked to a Document to retrieve the tag-document relationships as whenever a new link is added the "AIM Last Modified" attribute is updated for a document.

• Replace "FACILITY" with "ASSET" in the request to retrieve the document to equipment relationships.

• Replace "DOCUMENT CONTENT" with an appropriate class to retrieve the document to tag/equipment relationships.

• Replace "DOCUMENT CONTENT" with an appropriate class to retrieve the document package to tag/equipment relationships.

Example

This example shows how to retrieve Tags and their attributes and relationships from AIM.

5. Call the GET API and pass a bearer token for authorization to get the XSRF cookie.

   {dashboardUrl}/api/domain/authorization/issessionvalid

   

   

6. Retrieve cookie from the above request and add into the header of the POST API call. Fetching data for FACILITY objects i.e., Tags

   {dashboardUrl}/api/v1/domain/searches/run

   

   

   

   Use the totalNumberOfResults field to determine the number of pages. In the example above, the pageSize is 100 and the total results in AIM are 95636, so the number of pages is 957. Increment the currentPage value to retrieve subsequent pages.

   

7. Call the GET API to retrieve the object attributes and relationships by passing object handles for each object in the response from the above POST API call.

   {dashboardUrl}/api/v1/domain/dataGroup/125055?dataGroupNames=Main Attributes&dataGroupNames=Related Items 1&dataGroupNames=Related Items 2

   

8. Call the POST API to retrieve the tag-document relationships by passing in the fullId.

   {dashboardUrl}/api/v1/domain/searches/run

   

   

9. Retrieve the subsequent tag-document relationships by determining the number by pages using the totalNumberOfResults and incrementing the currentPage.

Key Points:

• The maximum number of calls for the API is 60 API calls per minute per asset.

• The request body for Tags will also give DISCIPLINES, SITES, PROCESS UNITS, AREAS etc that are in AIM.

• Refer to the class library (data model) of an asset for a list of permissible attributes.

Note: The Faceted Search API delivers comparable functionality, though with some constraints, while offering significant improvements in search performance and scalability to support higher concurrency. For further details, refer to the Faceted Search Data API topic.