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

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.

Here you can use the Client ID generated from previous application registration step.
  1. Go to the API Documentation.
  2. Click the “Try it” button.
  3. For Authorization section select “AuthorizationCode”.
  4. After the login popup closes, the Authorization header with your user token value should be visible.
  5. 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.
  • projectId - Id of the project 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.v1+json
Authorization: Bearer JWT_TOKEN
Content-Type: application/json

Request Body


JSON
{
  "modelVersion":"1.1",
  "projectId":"ea9cb5ab-22c5-4cef-807a-df47f07b01f3",
}

Response Headers


HTTP
Content-Type: application/json

Response Body


JSON
{
    "inference": {
        "id": "bcbc71d4-c4d8-4cf7-b1fe-aaa194cd61c3",
        "modelVersion": "1.1",
        "lastModifiedDateTime": "2022-01-20T14:45:47.073Z",
        "createdDateTime": "2022-01-20T14:45:47.073Z",
        "_links": {
            "project": {
                "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"
            }
        }
    }
}

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.v1+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": {
        "filename": "pnid_1.pdf",
        "size": 100,
        "_links": {
            "inputs": {
                "href": "https://api.bentley.com/synchronization/pnidtoitwin/bcbc71d4-c4d8-4cf7-b1fe-aaa194cd61c3/inputs"
            },
            "inference": {
                "href": "https://api.bentley.com/synchronization/pnidtoitwin/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 might be NotStarted 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.v1+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"
            }
        }
    }
}

To check the status of a run, use Get Inference Run.

  • Finished - Run has successfully completed. Results are ready to be used.
  • Canceled - Run was canceled by user.
  • Failed - Run failed to complete.
  • NotStarted - Run was created, but has not started yet.
  • 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.v1+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.

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.v1+json
  Authorization: Bearer JWT_TOKEN

Response Headers


HTTP
Content-Type: application/json

Response Body


JSON
{
      "results": [{
          "filename": "pnid_pdf_p00001.json",
          "size": 100,
          "_links": {
              "content": {
                  "href": "https://api.bentley.com/synchronization/pnidtoitwin/inferences/bcbc71d4-c4d8-4cf7-b1fe-aaa194cd61c3/run/results/pnid_pdf_p00001.json/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


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

Request Headers


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

8. Get previous inferences in a Project

All PnID Runs are associated with a Project. To get a history of all Runs you can call the Get Project Inferences API.

Request Syntax


HTTP
GET https://api.bentley.com/synchronization/pnidtoitwin/inferences?projectId=PROJECT_ID HTTP/1.1

Request Headers


HTTP
Accept: application/vnd.bentley.itwin-platform.v1+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.1",
        "lastModifiedDateTime": "2022-01-20T14:45:47.073Z",
        "createdDateTime": "2022-01-20T14:45:47.073Z",
        "_links": {
            "project": {
                "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"
            }
        }
    }],
    "_links": {
        "self": {
            "href": "https://api.bentley.com/synchronization/pnidtoitwin/inferences?projectid=ea9cb5ab-22c5-4cef-807a-df47f07b01f3"
        }
    }
}

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


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

Request Headers


HTTP
Accept: application/vnd.bentley.itwin-platform.v1+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.

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.v1+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


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

Request Headers


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

Response Headers


HTTP
Content-Type: application/json

Response Body


JSON
{
      "inputs": [{
          "filename": "pnid.pdf",
          "size": 100,
          "_links": {
              "content": {
                  "href": "https://api.bentley.com/synchronization/pnidtoitwin/inferences/bcbc71d4-c4d8-4cf7-b1fe-aaa194cd61c3/inputs/pnid.pdf/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


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

Request Headers


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

Response Headers


HTTP
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


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

Request Headers


HTTP
Accept: application/vnd.bentley.itwin-platform.v1+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


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

Request Headers


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

Response Body


JSON
{
      "inference": {
          "id": "bcbc71d4-c4d8-4cf7-b1fe-aaa194cd61c3",
          "modelVersion": "1.1",
          "lastModifiedDateTime": "2022-01-20T14:45:47.073Z",
          "createdDateTime": "2022-01-20T14:45:47.073Z",
          "_links": {
              "project": {
                  "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

An overview of Design Element Classification APIs and Machine Learning model.
An overview and detailed Reporting & Insights API group documentation.