Webhook now supports translation progress of BIM360 or ACC files

When a file is uploaded to BIM360 or ACC, it will be automatically translated by Model Derivative service of Forge. The generated metadata, properties (etc.) will be available for fetching and analysis or loading into the Forge Viewer. 

It takes time to process a translation. In the past, you needed to poll by calling GET:Manifest in succession until the status is complete (succeeded or failed). It is a tedious and inefficient workflow.

We have added a new feature allowing you to specify the callback endpoint when posting new item or posting new version. It works similar to working with the file in your own OSS bucket, using the callback mechanism, that has already been supported (see tutorial: Creating a Webhook of Model Derivative). The experience with file in BIM360/ACC is the same, but the schema of the payload is defined in meta. Currently, it supports two events: extraction.updated and extraction.finished.

To use it, first create a webhook with your callback endpoint and workflow id (a guid that identifies your hook). In the example, we use a public tool: RequestBin to hook the events.

POST: https://developer.api.autodesk.com/webhooks/v1/systems/derivative/events/extraction.finished/hooks

{
    "callbackUrl": "https://enkrfgclcddw.x.pipedream.net",
    "scope": {
        "workflow": "af077966-0701-40b4-abfa-a65c24d17cdc"
    }
}

Follow the tutorial to upload file to BIM360/ACC. Note: now S3 signed url uploading is the recommended way. In step 9 or step 10, specify the payload with meta attributes and input the workflow id.

{
    "jsonapi": {
      "version": "1.0"
    },
    "data": {
      <…>
    },
    "included": [
      <…>
    ], 
    "meta":{
        "workflow":"af077966-0701-40b4-abfa-a65c24d17cdc"
    }
  }

Additionally, you may input custom attributes for the webhook, e.g.

"meta":{
        "workflow":"af077966-0701-40b4-abfa-a65c24d17cdc",
        "workflowAttribute": {
            "myfoo": 12345,
            "projectId": "<my project id>",
            "myobject": {
              "nested": true
        }
    }

When the translation process starts, it will notify the callback of extraction.updated with the progress. A series of events will be received. If extraction.finished, it will only notify one time when the process is done (either succeeded or failed). The screenshot below is the scenario of of extraction.updated.

In the callback payload, it will tell which urn, extraction status, event type, and progress (if extraction.updated). With this information, you can proceed with further workflows as needed.

In addition, when a model is uploaded to BIM360/ACC, it will be translated to SVF and re-translated to SVF2 (formerly called OTG). So the extraction.finished callback will be notified twice. The one for SVF2 includes pharos:otg in payload.

We also provided a sample to demonstrate the workflow in .NET. It will allow you to create webook and monitor the progress of extraction of an uploading. When the extraction is completed successfully, the model will be loaded in Forge Viewer automatically. Check the repository for more details: https://github.com/Autodesk-Forge/forge-viewhubs