/aps-bim360-issues-api-postman.collection

This repository provides a postman collection that demonstrates the usage of Issues API for BIM 360.

MIT LicenseMIT

Postman Collection for BIM 360 Issues API

Postman

Issue API of BIM 360 Version 2

Beginner License

Description

This repository provides a postman collection that demonstrates the usage of BIM360 Issues Version 2 (v2) .

The API supports 3 legged token only. This collection takes Inheriting auth to apply 3-legged token to every endpoint in the collection automatically

Setup

  1. Autodesk Platform Services (APS) Account: Learn how to create an APS Account, activate the subscription and create an app by this tutorial. Ensure to select API Type BIM 360. Get APS client id, client secret and callback url. Please register APS app with the callback url as

    https://www.getpostman.com/oauth2/callback

  2. BIM 360 account and project: must be an Account Admin to add the app integration. Learn about provisioning. Make a note of the account name

  3. Create a project in BIM 360 or reuse existing project. Make a note of the project name

  4. Follow the product help document of BIM 360 to create some test entities, e.g.

    • common issues
    • pushpin issues with document
    • create some custom attributes definitions and attach them to issues.
    • create some comments with issues
    • add some attachments to issues (either with documents from visible folder or from a local uploaded file)
    • create some custom issue types and root causes. specify them with issues

  5. (Optional) Create a couple of assets in Assets module. This is to test fetching/creating reference with Issues and Assets.

  6. Clone this repository or download it. We recommend to install GitHub Desktop. To clone it via a command line, use the following in (Terminal on MacOSX/Linux, and Git Shell on Windows):

    git clone https://github.com/Autodesk-Forge/forge-autodesk.docs.issue.api-postman.collection

  7. Import the collection and environment files to Postman

  8. In environment, input client id, client secret, account name and project name.

  9. In the context menu of collection >> select Edit, switch to the tab Authorization, click Get New Access Token, and input the variables as below:

    • Grant Type: Authorization Code

    • Callback URL: https://www.getpostman.com/oauth2/callback

    • Auth URL: https://developer.api.autodesk.com/authentication/v1/authorize

    • Access Token URL: https://developer.api.autodesk.com/authentication/v1/gettoken

    • Client ID: {{client_id}}

    • Client Secret: {{client_secret}}

    • Scope: data:read data:write

    • Client Authentication: Send client credentials body

  10. Click Get New Access Token. It will direct to login Autodesk user account login. After it succeeds, the token will be generated. Click Use Token.

API Test

API References

Assume the steps to Setup above have been followed and the access token is successfully generated. Run the scripts in Run First. It will get account (hub) id, project id and one user id (for an assignee), location id, one document urn (to attachan issue). Run the endpoints under API References folder in Postman collection. Follow API References to verify if the APIs work well. Try to change the parameters in various scenarios to see how it works. Check UI if it works well with items created or updated using API. For example, creating/patching new issues and adding new comments.

Download Attachment

To test downloading attachment files, run scripts in Download Attachment. It assumes one issue is available with a few attachments.

  • Step-01 will return information of the first attachment. If urnType is dm, the urn pattern is like a base64 encoded string. The post script will transform it to a version urn. If the urnType is oss, it is a storage urn already. The post script will get bucket key and object key directly.
  • if urnType is dm, run step-02 to get a storage urn by Data Management API. Finally get bucket key and object key.
  • Step-03 is to get S3 signed url
  • Step-04 is to download the file by the signed url

Upload Local Attachment

To test uploading local files as attachments, run scripts in Upload Local Attachment. It assumes at least one issue is available.

  • Step-01 creates an attachment to the issue with urnType = oss. It will create the storage in the invisible folder for the issue in Docs
  • Step-02 will generate S3 signed url for uploading by Data Management API
  • Step-03 is to upload the local binary file by the signed url
  • Step-04 is to complete the uploading by Data Management API
  • Step-05 is to notify the server to associate the file with the issue.

To verify if the attachment is attached successfully, follow the steps in Test R.

Test Reference by Relationship API

In BIM 360, the reference of issue with assets or rfis is managed by Relationships API, which is a common component across different modules in BIM 360. To work with Issue>>References, you can use Relationship API. This sample Postman collection includes one sample usage. For more detail about Relationships API, please take a look at this blog.

  • Step-01 is to get supported Relationships. You can use this stop to check entity types that you can set relationships with BIM 360 issues.
  • Step-02 is to get one asset id by Asset API
  • Step-02 is add a reference between one issue and one asset
  • Step-04 gets all referenced assets of one issue

Documentaions

Blogs

License

This sample is licensed under the terms of the MIT License. Please see the LICENSE file for full details.

Written by

Xiaodong Liang @coldwood, Developer Advocate and Support team