Running the PnID ML Pipeline
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.
Prerequisites
This tutorial assumes that you have:
- Created and configured a project. For instructions on creating a project, see Create and Query Projects. 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. Make sure that your application is associated with PnID API and has
synchronization:read synchronization:modify
scopes enabled.
Single page application
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.
Follow this article to implement the Authorization Code workflow in your application.
- 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" } } } }
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.
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" } } }
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.
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
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
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" } } }
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
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
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.