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.

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. Make sure that your application is associated with PnID API and has synchronization:read synchronization:modify scopes enabled.

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.

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

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.

Use user token to replace the “JWT_TOKEN” placeholder parameter in the next steps.

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.

We recommend using the latest model version; however, if backward compatibility is required, use the appropriate version of the model.

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.

Note the inference ID that is returned when creating a Inference will be needed in later steps.

Request Syntax

HTTP

POST https://api.bentley.com/synchronization/pnidtoitwin/inferences HTTP/1.1

Request Headers

HTTP

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

Request Body

JSON

{
  "modelVersion":"1.3",
  "iTwinId":"ea9cb5ab-22c5-4cef-807a-df47f07b01f3",
}

Response Headers

HTTP

Content-Type: application/json

Response Body

JSON

{
    "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

HTTP

POST https://api.bentley.com/synchronization/pnidtoitwin/inferences/INFERENCE_ID/inputs HTTP/1.1

Request Headers

HTTP

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

HTTP

Content-Type: application/json

Response Body

JSON

{
    "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.

Run status may be Queued for a short time while the process kicks off.

Request Syntax

HTTP

POST https://api.bentley.com/synchronization/pnidtoitwin/inferences/INFERENCE_ID/run HTTP/1.1

Request Headers

HTTP

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

Response Headers

HTTP

Content-Type: application/json

Response Body

JSON

{
    "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

HTTP

GET https://api.bentley.com/synchronization/pnidtoitwin/inferences/INFERENCE_ID/run HTTP/1.1

Request Headers

HTTP

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

Response Headers

HTTP

Content-Type: application/json

Response Body

JSON

{
      "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

HTTP

GET https://api.bentley.com/synchronization/pnidtoitwin/inferences/INFERENCE_ID/run/results HTTP/1.1

Request Headers

HTTP

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

Response Headers

HTTP

Content-Type: application/json

Response Body

JSON

{
    "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

HTTP

GET https://api.bentley.com/synchronization/pnidtoitwin/inferences/{inferenceId}/run/results/FILE_ID/content HTTP/1.1

Request Headers

HTTP

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

HTTP

GET https://api.bentley.com/synchronization/pnidtoitwin/inferences?iTwinId=ITWIN_ID HTTP/1.1

Request Headers

HTTP

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

Response Headers

HTTP

Content-Type: application/json

Response Body

JSON

{
    "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

HTTP

DELETE https://api.bentley.com/synchronization/pnidtoitwin/inferences/INFERENCE_ID/run HTTP/1.1

Request Headers

HTTP

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.

Only completed Runs can be deleted. Completed Run statuses: Failed, Canceled, Finished.

Request Syntax

HTTP

DELETE https://api.bentley.com/synchronization/pnidtoitwin/inferences/INFERENCE_ID HTTP/1.1

Request Headers

HTTP

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

HTTP

GET https://api.bentley.com/synchronization/pnidtoitwin/inferences/INFERENCE_ID/inputs HTTP/1.1

Request Headers

HTTP

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

Response Headers

HTTP

Content-Type: application/json

Response Body

JSON

{
    "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

HTTP

GET https://api.bentley.com/synchronization/pnidtoitwin/inferences/INFERENCE_ID/inputs/FILE_ID/content HTTP/1.1

Request Headers

HTTP

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

Response Headers

HTTP

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

HTTP

DELETE https://api.bentley.com/synchronization/pnidtoitwin/inferences/INFERENCE_ID/inputs/FILE_ID HTTP/1.1

Request Headers

HTTP

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

HTTP

GET https://api.bentley.com/synchronization/pnidtoitwin/inferences/INFERENCE_ID HTTP/1.1

Request Headers

HTTP

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

Response Body

JSON

{
      "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.

More resources that you may like

Reporting & Insights

An overview and detailed Reporting & Insights API group documentation.