Introduction
Use this quick start to help you understand how to create a PnID inference run and retrieve its results.
By the end of this walk-through, you will have all the tools you need to take any PnID drawings with piping components and run it through the PnID interface. You will gain familiarity with the workflow and all APIs involved and be able to integrate the PnID model into your iTwin-Powered applications.
Info
Skill level:
Basic
Duration:
15 minutes
Prerequisites
This tutorial assumes that you have:
- Created and configured a project iTwin. For instructions on creating a project iTwin, see Create and Query iTwins. You can use an existing Project if you have access to one.
- Prepared PnID drawings with piping components.
1. Register an Application
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
To make requests to this APIs a valid user token is required. There are several ways to get one.
Implement Authorization Code Flow in the application
Follow this article to implement the Authorization Code workflow in your application.
Grab a user token from Api reference "Try it" Section
- Go to the API Documentation.
- Click the "Try it" button.
- For Authorization section select "AuthorizationCode".
- After the login popup closes, the Authorization header with your user token value should be visible.
- Save your user token value to reuse later.
3. Choose available PnID Model versions
Select an existing model version to use for your inference Run. See Model versions to view the supported PnID model versions.
4. Create a new PnID inference
Use the Create Inference API to create PnID inference for the provided project.
You have a couple of parameters available for configuring the PnID:
- modelVersion - PnID Model version chosen from step 3.
- iTwinId - Id of the iTwin that created the PnID Inference.
Request Syntax
POST https://api.bentley.com/synchronization/pnidtoitwin/inferences HTTP/1.1
Request Headers
Accept: application/vnd.bentley.itwin-platform.v2+json
Authorization: Bearer JWT_TOKEN
Content-Type: application/json
Request Body
{
"modelVersion":"1.3",
"iTwinId":"ea9cb5ab-22c5-4cef-807a-df47f07b01f3",
}
Response Headers
Content-Type: application/json
Response Body
{
"inference": {
"id": "bcbc71d4-c4d8-4cf7-b1fe-aaa194cd61c3",
"modelVersion": "1.3",
"lastModifiedDateTime": "2022-01-20T14:45:47.073Z",
"createdDateTime": "2022-01-20T14:45:47.073Z",
"_links": {
"iTwin": {
"href": "https://api.bentley.com/itwins/ea9cb5ab-22c5-4cef-807a-df47f07b01f3"
},
"run": {
"href": "https://api.bentley.com/synchronization/pnidtoitwin/bcbc71d4-c4d8-4cf7-b1fe-aaa194cd61c3/run"
},
"inputs": {
"href": "https://api.bentley.com/synchronization/pnidtoitwin/bcbc71d4-c4d8-4cf7-b1fe-aaa194cd61c3/inputs"
},
"results": {
"href": "https://api.bentley.com/synchronization/pnidtoitwin/bcbc71d4-c4d8-4cf7-b1fe-aaa194cd61c3/run/results"
}
}
}
}
5. Upload data to PnID Inference Input.
Use the Upload Inference Input Content API to create or replace one of the PnID Inference Input files on which inference will run.
Request Syntax
POST https://api.bentley.com/synchronization/pnidtoitwin/inferences/INFERENCE_ID/inputs HTTP/1.1
Request Headers
Accept: application/vnd.bentley.itwin-platform.v2+json
Authorization: Bearer JWT_TOKEN
Content-Type: application/pdf
Content-Dispposition: attachment; filename="pnid_1.pdf"
Response Headers
Content-Type: application/json
Response Body
{
"input": {
"id": "cG5pZC5wZGY-",
"filename": "pnid.pdf",
"size": 100,
"_links": {
"inputs": {
"href": "https://api.bentley.com/synchronization/pnidtoitwin/inferences/bcbc71d4-c4d8-4cf7-b1fe-aaa194cd61c3/inputs"
},
"inference": {
"href": "https://api.bentley.com/synchronization/pnidtoitwin/inferences/bcbc71d4-c4d8-4cf7-b1fe-aaa194cd61c3"
}
}
}
}
6. Starts PnID Inference Run after all inputs are uploaded.
Use the Create Inference Run API to start PnID inference Run after all inputs are uploaded.
Request Syntax
POST https://api.bentley.com/synchronization/pnidtoitwin/inferences/INFERENCE_ID/run HTTP/1.1
Request Headers
Accept: application/vnd.bentley.itwin-platform.v2+json
Authorization: Bearer JWT_TOKEN
Content-Type: application/json
Response Headers
Content-Type: application/json
Response Body
{
"run": {
"status": "inProgress",
"duration": "PT10M",
"progress": 0.1,
"createdDateTime": "2022-01-20T14:45:47.073Z",
"_links": {
"inputs": {
"href": "https://api.bentley.com/synchronization/pnidtoitwin/bcbc71d4-c4d8-4cf7-b1fe-aaa194cd61c3/inputs"
},
"results": {
"href": "https://api.bentley.com/synchronization/pnidtoitwin/bcbc71d4-c4d8-4cf7-b1fe-aaa194cd61c3/results"
},
"inference": {
"href": "https://api.bentley.com/synchronization/pnidtoitwin/bcbc71d4-c4d8-4cf7-b1fe-aaa194cd61c3"
}
}
}
}
Query status
To check the status of a run, use Get Inference Run Status.
- Finished - Run has successfully completed. Results are ready to be used.
- Canceled - Run was canceled by user.
- Failed - Run failed to complete.
- NotStarted - Run has not been triggered.
- Queued - Run was created, but has not started.
- InProgress - Run was created and has started. Waiting for completion.
Request Syntax
GET https://api.bentley.com/synchronization/pnidtoitwin/inferences/INFERENCE_ID/run HTTP/1.1
Request Headers
Accept: application/vnd.bentley.itwin-platform.v2+json
Authorization: Bearer JWT_TOKEN
Response Headers
Content-Type: application/json
Response Body
{
"run": {
"status": "inProgress",
"duration": "PT10M",
"progress": 0.1,
"createdDateTime": "2022-01-20T14:45:47.073Z",
"_links": {
"inputs": {
"href": "https://api.bentley.com/synchronization/pnidtoitwin/bcbc71d4-c4d8-4cf7-b1fe-aaa194cd61c3/inputs"
},
"results": {
"href": "https://api.bentley.com/synchronization/pnidtoitwin/bcbc71d4-c4d8-4cf7-b1fe-aaa194cd61c3/results"
},
"inference": {
"href": "https://api.bentley.com/synchronization/pnidtoitwin/bcbc71d4-c4d8-4cf7-b1fe-aaa194cd61c3"
}
}
}
}
7. Retrieve Run output
Download the results once a PnID Run has successfully completed.
Get Inference Run Results
Fetch a list of all pipeline results using the Get Inference Run Results API.
Request Syntax
GET https://api.bentley.com/synchronization/pnidtoitwin/inferences/INFERENCE_ID/run/results HTTP/1.1
Request Headers
Accept: application/vnd.bentley.itwin-platform.v2+json
Authorization: Bearer JWT_TOKEN
Response Headers
Content-Type: application/json
Response Body
{
"results": [{
"id": "cG5pZF9wZGZfcDAwMDAxLmpzb24-",
"filename": "pnid_pdf_p00001.json",
"size": 100,
"_links": {
"content": {
"href": "https://api.bentley.com/synchronization/pnidtoitwin/inferences/bcbc71d4-c4d8-4cf7-b1fe-aaa194cd61c3/run/results/cG5pZF9wZGZfcDAwMDAxLmpzb24-/content"
}
}
}],
"_links": {
"self": {
"href": "https://api.bentley.com/synchronization/pnidtoitwin/inferences/bcbc71d4-c4d8-4cf7-b1fe-aaa194cd61c3/run/results"
},
"inference": {
"href": "https://api.bentley.com/synchronization/pnidtoitwin/inferences/bcbc71d4-c4d8-4cf7-b1fe-aaa194cd61c3"
}
}
}
Get Inference Run Result Content
To download a specific file from the Results, use the Get Inference Run Result Content API.
Request Syntax
GET https://api.bentley.com/synchronization/pnidtoitwin/inferences/{inferenceId}/run/results/FILE_ID/content HTTP/1.1
Request Headers
Accept: application/vnd.bentley.itwin-platform.v2+json
Authorization: Bearer JWT_TOKEN
8. Get previous inferences in a iTwin
All PnID Runs are associated with a iTwin. To get a history of all Runs you can call the Get iTwin Inferences API.
Request Syntax
GET https://api.bentley.com/synchronization/pnidtoitwin/inferences?iTwinId=ITWIN_ID HTTP/1.1
Request Headers
Accept: application/vnd.bentley.itwin-platform.v2+json
Authorization: Bearer JWT_TOKEN
Content-Type: application/json
Response Headers
Content-Type: application/json
Response Body
{
"inferences": [{
"id": "bcbc71d4-c4d8-4cf7-b1fe-aaa194cd61c3",
"modelVersion": "1.3",
"lastModifiedDateTime": "2022-01-20T14:45:47.073Z",
"createdDateTime": "2022-01-20T14:45:47.073Z",
"_links": {
"iTwin": {
"href": "https://api.bentley.com/itwins/ea9cb5ab-22c5-4cef-807a-df47f07b01f3"
},
"run": {
"href": "https://api.bentley.com/synchronization/pnidtoitwin/inferences/bcbc71d4-c4d8-4cf7-b1fe-aaa194cd61c3/run"
},
"inputs": {
"href": "https://api.bentley.com/synchronization/pnidtoitwin/inferences/bcbc71d4-c4d8-4cf7-b1fe-aaa194cd61c3/inputs"
},
"results": {
"href": "https://api.bentley.com/synchronization/pnidtoitwin/inferences/bcbc71d4-c4d8-4cf7-b1fe-aaa194cd61c3/run/results"
}
}
}],
"_links": {
"next": {
"href": "https://api.bentley.com/synchronization/pnidtoitwin/inferences?iTwinId=ea9cb5ab-22c5-4cef-807a-df47f07b01f3&$top=100&$continuationToken=eyJOZXh0UGFydGl0aW9uS2V5IjoiMSExMDAhT0RnMll6TmlOMlF0TnpNM1pDMDBOakUwTFRsaE4yTXROV1JsTlRobE5qTm1OVGc0WHpBNFlqZzROVEV3TFdNek1tTXRORGt4WWkwNVpqZGhMVEZpTXpBd016azFPV1F6TlEtLSIsIk5leHRSb3dLZXkiOiIxASD4IU56Y3dNREU1T1RFdFl6UmpZeSAbTUdKaUxUa3dOMlV0WXpPrewtSmhZV0k0WlRBMSIsIk5leHRUYWJsZU5hbWUiOm51bGwsIlLncmdldExvY2F0aW9uIjowfQ--"
},
"self": {
"href": "https://api.bentley.com/synchronization/pnidtoitwin/inferences?iTwinId=ea9cb5ab-22c5-4cef-807a-df47f07b01f3&$top=100"
}
}
}
9. Advanced
We provide some additional APIs that provide a little more control and management over your PnID Inferences Runs.
Cancel execution of PnID Inference Run.
PnID Runs are complex and can take a long time to complete. Runs can be cancelled using the Delete Inference Run API so you don't have to waste time waiting for Runs to naturally fail or complete when unnecessary.
Request Syntax
DELETE https://api.bentley.com/synchronization/pnidtoitwin/inferences/INFERENCE_ID/run HTTP/1.1
Request Headers
Accept: application/vnd.bentley.itwin-platform.v2+json
Authorization: Bearer JWT_TOKEN
Delete PnID Inference
We strongly recommend deleting canceled Runs. You might also want to clean up a Project of stale or unnecessary historical Runs. Use the Delete Inference API for this.
Request Syntax
DELETE https://api.bentley.com/synchronization/pnidtoitwin/inferences/INFERENCE_ID HTTP/1.1
Request Headers
Accept: application/vnd.bentley.itwin-platform.v2+json
Authorization: Bearer JWT_TOKEN
Get PnID Inference Inputs
Inference can contain several input files. To see the list of added inputs files use the Get Inference Inputs API.
Request Syntax
GET https://api.bentley.com/synchronization/pnidtoitwin/inferences/INFERENCE_ID/inputs HTTP/1.1
Request Headers
Accept: application/vnd.bentley.itwin-platform.v2+json
Authorization: Bearer JWT_TOKEN
Content-Type: application/json
Response Headers
Content-Type: application/json
Response Body
{
"inputs": [{
"id": "cG5pZC5wZGY-",
"filename": "pnid.pdf",
"size": 100,
"_links": {
"input": {
"href": "https://api.bentley.com/synchronization/pnidtoitwin/inferences/bcbc71d4-c4d8-4cf7-b1fe-aaa194cd61c3/inputs/cG5pZC5wZGY-"
},
"content": {
"href": "https://api.bentley.com/synchronization/pnidtoitwin/inferences/bcbc71d4-c4d8-4cf7-b1fe-aaa194cd61c3/inputs/cG5pZC5wZGY-/content"
}
}
}],
"_links": {
"self": {
"href": "https://api.bentley.com/synchronization/pnidtoitwin/inferences/bcbc71d4-c4d8-4cf7-b1fe-aaa194cd61c3/inputs"
},
"inference": {
"href": "https://api.bentley.com/synchronization/pnidtoitwin/inferences/bcbc71d4-c4d8-4cf7-b1fe-aaa194cd61c3"
}
}
}
Get PnID Inference Input Content
If there is a need to download the contents of a previously uploaded input file, use the Get Inference Input Content API.
Request Syntax
GET https://api.bentley.com/synchronization/pnidtoitwin/inferences/INFERENCE_ID/inputs/FILE_ID/content HTTP/1.1
Request Headers
Accept: application/vnd.bentley.itwin-platform.v2+json
Authorization: Bearer JWT_TOKEN
Content-Type: application/json
Response Headers
Content-Type: application/json
Delete PnID Inference Input
If an invalid file was uploaded for inference, it is possible to remove that file. Use the Delete Inference Input API for this.
Request Syntax
DELETE https://api.bentley.com/synchronization/pnidtoitwin/inferences/INFERENCE_ID/inputs/FILE_ID HTTP/1.1
Request Headers
Accept: application/vnd.bentley.itwin-platform.v2+json
Authorization: Bearer JWT_TOKEN
Get PnID Inference by specified Id
In order to get some information about already created inference you should use the Get Inference API for this.
Request Syntax
GET https://api.bentley.com/synchronization/pnidtoitwin/inferences/INFERENCE_ID HTTP/1.1
Request Headers
Accept: application/vnd.bentley.itwin-platform.v2+json
Authorization: Bearer JWT_TOKEN
Response Body
{
"inference": {
"id": "bcbc71d4-c4d8-4cf7-b1fe-aaa194cd61c3",
"modelVersion": "1.3",
"lastModifiedDateTime": "2022-01-20T14:45:47.073Z",
"createdDateTime": "2022-01-20T14:45:47.073Z",
"_links": {
"iTwin": {
"href": "https://api.bentley.com/projects/ea9cb5ab-22c5-4cef-807a-df47f07b01f3"
},
"run": {
"href": "https://api.bentley.com/synchronization/pnidtoitwin/bcbc71d4-c4d8-4cf7-b1fe-aaa194cd61c3/run"
},
"inputs": {
"href": "https://api.bentley.com/synchronization/pnidtoitwin/bcbc71d4-c4d8-4cf7-b1fe-aaa194cd61c3/inputs"
},
"results": {
"href": "https://api.bentley.com/synchronization/pnidtoitwin/bcbc71d4-c4d8-4cf7-b1fe-aaa194cd61c3/run/results"
}
}
}
}
Conclusion
Congratulations on completing this tutorial, at this point you should have been able to create PnID run for PnID drawings with piping components, query run status and finally download run results.