Create and Query iTwin Entities

Introduction

This tutorial will take you through the process of creating and querying an iTwin entity.

By the end of this walk-through, you will be able to utilize the API endpoints to create or query entities.

Info

Skill level:

Basic

Duration:

20 minutes

Prerequisites

This tutorial assumes that you already have:

A tool, such as Postman that can be used to execute HTTP calls. These calls can also be made using the Try it out button in the API documentation.
The user should be a member of the iTwin for which they want to create an entity. You would need to know the iTwin id GUID for the iTwin. If you don't have an iTwin to work with, you can create one using the instructions Create and Query an iTwin.

Postman

Get

You will need to register an application to use the iTwin Platform APIs. You can use the Register button to automatically create your first single page application (SPA). This will allow you to configure Authorization Code Flow for your SPA application and get the correct access token.

Once generated, you will be shown a few lines of code under the button.

IMJS_AUTH_CLIENT_CLIENT_ID - this is the unique identifier for your application. Displayed on application details page as Client ID.
IMJS_AUTH_CLIENT_REDIRECT_URI - specifies where users are redirected after they have chosen whether or not to authenticate your app. Displayed on application details page as one of Redirect URIs.
IMJS_AUTH_CLIENT_LOGOUT_URI - specifies where users can be returned to after logging out. Displayed on application details page as one of Post logout redirect URIs.
IMJS_AUTH_CLIENT_SCOPES - list of accesses granted to the application. Displayed on application details page as Scopes.

Or optionally: Register and configure your application manually following instructions in Register and modify an Application tutorial.

Register a basic SPA App for this tutorial

Requires you to sign in. Will automatically generate a Single page application (SPA) that is required to complete this tutorial. You will be able to manage your SPA from your My apps page.

2. Get a token

Before you can make a request to the APIs, a user token is needed. There are several ways to get it.

Implement Authorization Code Flow in the application

Follow this article to implement Authorization code workflow in your application.

Here you can use Client ID generated from previous registration step.

Grab a user token from the iTwin Entities documentation page

Go here
Click Try it out button.
Under the Authorization section, select authorizationCode from the dropdown.
After the sign in popup closes, the Authorization header with token value should be visible beneath the HTTP request dropdown.
Copy & paste the Authorization value for this tutorial.

Use user token to replace JWT_TOKEN dynamic parameter in the next steps.

3. Create a new entity

The iTwin Entities API is used to create and manage entities. A POST call to the entities endpoint will create a new entity for the iTwin specified by the iTwinId. You need to replace the ITWIN_ID with the your iTwinId in the request as mentioned in the Prerequisites section.

At minimum, class and code are required for creating a new entity. The code property should be unique. If you already have a federationId for the entity also specify it. Otherwise, a new federationId would be auto-generated for the new entity. If you get a conflict error, then you must replace the federationId with a unique value. See the iTwin Entities API documentation for descriptions of the different properties, including default values.

The POST call will return a new entity instance. The federationId can be used to query for the entity. The federationId is also used by in many other iTwin-Entities APIs. You may want to save this federationId to use in other tutorials.

Request Syntax

http

POST https://api.bentley.com/itwin-entities/iTwins/{ITWIN_ID}/entities/ HTTP/1.1

Request Headers

http

Accept: application/vnd.bentley.itwin-platform.v1+json
Content-Type: application/json
Authorization: Bearer JWT_TOKEN

Request Body

json

{
  "class": "CentrifugalPump",
  "classification": "CentrifugalPump",
  "bisClassPath": "bis:Element;bis:RoleElement;func:FunctionalElement;func:FunctionalComponentElement;pfunc:PLANT_BASE_OBJECT;pfunc:NAMED_ITEM;pfunc:DEVICE;pfunc:EQUIPMENT;pfunc:ROTATING_EQUIPMENT;pfunc:PUMP;pfunc:DYNAMIC_PUMP;pfunc:CENTRIFUGAL_PUMP",
  "code": "CodeSpecId:CodeScopeId:P-101",
  "name": "P-101",
  "type": "GE CP T22a",
  "geospatialLocation": {
      "type": "Point",
      "coordinates": [
          12.1,
          13.2
      ]
  },
  "tags": [
      "Pump"
  ],
  "federationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Response Headers

http

HTTP/1.1 201 Created
content-length: 937
content-type: application/json
date: Thu, 24 Jun 2021 14:44:18 GMT
request-context: appId=cid-v1:7a353d36-9a8b-423e-965e-9d7f51324584
x-correlation-id: 5262b13f-394e-49b8-95ea-a5361d2513a3
x-itwinplatform-media-type: bentley.itwin-platform.v1
x-itwinplatform-region: East US

Response Body

json

{
  "entity": {
      "class": "CentrifugalPump",
      "classification": "CentrifugalPump",
      "bisClassPath": "bis:Element;bis:RoleElement;func:FunctionalElement;func:FunctionalComponentElement;pfunc:PLANT_BASE_OBJECT;pfunc:NAMED_ITEM;pfunc:DEVICE;pfunc:EQUIPMENT;pfunc:ROTATING_EQUIPMENT;pfunc:PUMP;pfunc:DYNAMIC_PUMP;pfunc:CENTRIFUGAL_PUMP",
      "code": "CodeSpecId:CodeScopeId:P-101",
      "name": "P-101",
      "type": "GE CP T22a",
      "geospatialLocation": {
          "type": "Point",
          "coordinates": [
              12.1,
              13.2
          ]
      },
      "tags": [
          "Pump"
      ],
      "federationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "links": [],
      "createdDateTime": "2023-01-18T21:03:00.3704659",
      "createdByUser": "user@bentley.com",
      "LastModifiedDateTime": "2023-01-18T21:03:00.3704659",
      "LastModifiedByUser": "user@bentley.com"
  }
}

4. Query for an entity using the federationId

The federationId of an entity can be used to query for a specific entity. In addition to the federationId, you need to know the iTwinId for the iTwin to which the queried entity belongs.

Request Syntax

http

GET https://api.bentley.com/itwins/{ITWIN_ID}/entities/3fa85f64-5717-4562-b3fc-2c963f66afa6 HTTP/1.1

Request Headers

http

Accept: application/vnd.bentley.itwin-platform.v1+json
Authorization: Bearer JWT_TOKEN

Response Headers

http

HTTP/1.1 200 OK
content-length: 936
content-type: application/json
date: Thu, 24 Jun 2021 18:10:04 GMT
request-context: appId=cid-v1:7a353d36-9a8b-423e-965e-9d7f51324584
x-correlation-id: fed95960-ea7c-43b5-a9af-66ab5353d073
x-itwinplatform-media-type: bentley.itwin-platform.v1
x-itwinplatform-region: East US

Response Body

json

{
  "entity": {
      "class": "CentrifugalPump",
      "classification": "CentrifugalPump",
      "bisClassPath": "bis:Element;bis:RoleElement;func:FunctionalElement;func:FunctionalComponentElement;pfunc:PLANT_BASE_OBJECT;pfunc:NAMED_ITEM;pfunc:DEVICE;pfunc:EQUIPMENT;pfunc:ROTATING_EQUIPMENT;pfunc:PUMP;pfunc:DYNAMIC_PUMP;pfunc:CENTRIFUGAL_PUMP",
      "code": "CodeSpecId:CodeScopeId:P-101",
      "name": "P-101",
      "type": "GE CP T22a",
      "geospatialLocation": {
          "type": "Point",
          "coordinates": [
              12.1,
              13.2
          ]
      },
      "tags": [
          "Pump"
      ],
      "federationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "links": [],
      "createdDateTime": "2023-01-18T21:03:00.3704659",
      "createdByUser": "user@bentley.com",
      "LastModifiedDateTime": "2023-01-18T21:03:00.3704659",
      "LastModifiedByUser": "user@bentley.com"
  }
}

5. Query for entities using code (or name, class etc.)

The code query parameter can be used to find entities. Because this is a query, the response will be a list of entities that will usually contain only one element. The code value should ideally be unique within an iTwin, however, this is not strictly enforced and you can theoratically get multiple entities with the same code value. Again, the iTwinId must to be specified in the request.

Similarly you can use the name or class paramaters (or a combination of any of the rest of the query parameter listed for the get entities API) to search for entities by these values.

Request Syntax

http

GET https://api.bentley.com/itwins/{ITWIN_ID}/entities?code=CodeSpecId:CodeScopeId:P-101 HTTP/1.1

Request Headers

http

Prefer: return=representation
Accept: application/vnd.bentley.itwin-platform.v1+json
Authorization: Bearer JWT_TOKEN

Response Headers

http

HTTP/1.1 200 OK 
cache-control: must-revalidate, no-cache, private
content-encoding: gzip
content-type: application/json
date: Thu, 24 Jun 2021 18:20:43 GMT
request-context: appId=cid-v1:7a353d36-9a8b-423e-965e-9d7f51324584
x-correlation-id: dd4d68c9-614d-4d67-8e51-7147c18513f8
x-itwinplatform-media-type: bentley.itwin-platform.v1
x-itwinplatform-region: East US

Response Body

json

{
  "entities": [{
      "class": "CentrifugalPump",
      "classification": "CentrifugalPump",
      "bisClassPath": "bis:Element;bis:RoleElement;func:FunctionalElement;func:FunctionalComponentElement;pfunc:PLANT_BASE_OBJECT;pfunc:NAMED_ITEM;pfunc:DEVICE;pfunc:EQUIPMENT;pfunc:ROTATING_EQUIPMENT;pfunc:PUMP;pfunc:DYNAMIC_PUMP;pfunc:CENTRIFUGAL_PUMP",
      "code": "CodeSpecId:CodeScopeId:P-101",
      "name": "P-101",
      "type": "GE CP T22a",
      "geospatialLocation": {
          "type": "Point",
          "coordinates": [
              12.1,
              13.2
          ]
      },
      "tags": [
          "Pump"
      ],
      "federationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "links": [],
      "createdDateTime": "2016-01-18T21:03:00.3704659",
      "createdByUser": "user@bentley.com",
      "LastModifiedDateTime": "2016-01-18T21:03:00.3704659",
      "LastModifiedByUser": "user@bentley.com"
  }]
}

6. Query for entities using partial code

The partialMatchFiltersList query parameter can be used to find entities using a query string that will return entities for which the property values partially match the provided filter. For example, if we provide a code value of "P-1" in the query parameter and specify the value "code" in the PartialMatchFiltersList query parameter, then we can search for all entities that have the property code with a value that contain the substring "P-1". So, the entity that we created in the step 3 with code value "CodeSpecId:CodeScopeId:P-101" should be returned in this example. This example is the SQL equivalent of code like '%P-1%'. The query is not case sensitive and you should not add wildcard characters to the query string.

Because this is a query, the response will be a list that could contain many entities.

Similary, the partiamMatchFiltersList can be used for other properties of entities. See the get entities API for details.

Request Syntax

http

GET https://api.bentley.com/itwins/{ITWIN_ID}/entities?code=P-1&partialMatchFiltersList=code HTTP/1.1

Request Headers

http

Prefer: return=minimal
Accept: application/vnd.bentley.itwin-platform.v1+json
Authorization: Bearer JWT_TOKEN

Response Headers

http

HTTP/1.1 200 OK 
cache-control: must-revalidate, no-cache, private
content-encoding: gzip
content-type: application/json
date: Thu, 24 Jun 2021 18:40:47 GMT
request-context: appId=cid-v1:7a353d36-9a8b-423e-965e-9d7f51324584
x-correlation-id: 86bc760f-d0c4-4292-b72d-97a078ce1c7a
x-itwinplatform-media-type: bentley.itwin-platform.v1
x-itwinplatform-region: East US

Response Body

json

{
  "entities": [{
      "class": "CentrifugalPump",
      "classification": "CentrifugalPump",
      "bisClassPath": "bis:Element;bis:RoleElement;func:FunctionalElement;func:FunctionalComponentElement;pfunc:PLANT_BASE_OBJECT;pfunc:NAMED_ITEM;pfunc:DEVICE;pfunc:EQUIPMENT;pfunc:ROTATING_EQUIPMENT;pfunc:PUMP;pfunc:DYNAMIC_PUMP;pfunc:CENTRIFUGAL_PUMP",
      "code": "CodeSpecId:CodeScopeId:P-101",
      "name": "P-101",
      "type": "GE CP T22a",
      "geospatialLocation": {
          "type": "Point",
          "coordinates": [
              12.1,
              13.2
          ]
      },
      "tags": [
          "Pump"
      ],
      "federationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "links": [],
      "createdDateTime": "2016-01-18T21:03:00.3704659",
      "createdByUser": "user@bentley.com",
      "LastModifiedDateTime": "2016-01-18T21:03:00.3704659",
      "LastModifiedByUser": "user@bentley.com"
  }]
}