13 Jul 2017

BIM 360 Docs Provisioning for Forge Apps

Default blog image

Get started with this business webinar from Jim Quanci: Integrate your apps and services with BIM 360.

To access user-level files under a BIM 360 Docs account your application can use the same Data Management API used to access BIM 360 Team (formerly A360) and Fusion 360 files. In fact, when listing Hubs, you will get some with attribute.extension.type equals hubs:autodesk.bim360:Account. This indicates a BIM 360 Docs hub. If you are implementing in NodeJS or .NET C# you can easily check it. Note the BIM 360 Hub ID represents the respective Account ID on BIM 360 Admin, an easy way to use BIM 360 Docs 2-legged APIs, but that's a topic for another post. Last, BIM 360 Docs Hub IDs starts with  b. while others start with  a. 

With initial/default user permissions, the Data Management API will not list BIM 360 Docs Hubs for the current user (on 3-legged OAuth). Why? The respective BIM 360 Docs Administrator needs to provision the app Client ID, meaning give access to that app. There is more information about this here and at this blog post.

So what this post is about?

This post will show you how to ask the user/admin to provision the Client ID. 

First: you don't want to ask to provision the client ID if is already provisioned, right? After the user signin, get all the hubs that he/she has access. If any of the hubs starts with  b.  then the user already has access. Great. Is there a source code for it? Many of my samples use jsTree to list files under an account, so here is a tree implementation that checks for that on the client-side (JavaScript). In summary, the code checks the hub type and the ID. Sure you can also implement a similar approach on the server-side.

After the above check, if the user DO NOT have access to BIM 360 Docs, you want to ask her/him to provision the key. Before going into code, here is how you can ask it:

There are many ways to implement the 2 modal dialogs from the above video. This sample uses Bootstrap Modal. The first modal can be like the following. Note it's using clipboard.js to make user's life easier. You need to fill the ClientID & AppName text areas with your Forge Client ID and app name.

  <!-- Modal Provision BIM360  -->
  <div class="modal fade" id="provisionAccountModal" tabindex="-1" role="dialog" aria-labelledby="myModalLabel">
    <div class="modal-dialog" role="document">
      <div class="modal-content">
        <div class="modal-header">
          <button type="button" class="close" data-dismiss="modal" aria-label="Cancel"><span aria-hidden="true">&times;</span></button>
          <h4 class="modal-title">Thanks for using APP NAME HERE!</h4>
        </div>
        <div class="modal-body">
          <p>To view your BIM 360 Docs files on this app please authorize my Forge Client ID with your BIM 360 Docs Account.</p>
          <p>
            <button type="button" class="btn btn-info" data-toggle="modal" data-target="#provisionAccountStepsModal">Show me the steps <span class="glyphicon glyphicon-new-window"></span></button>
          </p>
          Use this as Forge Client ID:
        <div class="input-group">
          <input type="text" readonly="true" aria-describedby="CopyClientID" id="ClientID" class="form-control" value="" />
          <span class="input-group-addon" style="cursor: pointer" data-clipboard-target="#ClientID" id="CopyClientID">Copy to clipboard</span>
        </div>
          And this App Name:
        <div class="input-group">
          <input type="text" readonly="true" aria-describedby="CopyAppName" id="AppName" class="form-control" value="Forge Tools Sample App" />
          <span class="input-group-addon" style="cursor: pointer" data-clipboard-target="#AppName" id="CopyAppName">Copy to clipboard</span>
        </div>
        </div>
        <div class="modal-footer">
          <button type="button" class="btn btn-default" data-dismiss="modal">Cancel</button>
          <button type="button" class="btn btn-primary" id="provisionAccountSave">Done</button>
        </div>
      </div>
    </div>
  </div>
  <script src="clipboard.min.js"></script>
  <script>
    new Clipboard('.input-group-addon');
  </script>

And the second modal shows the steps, again with Bootstrap modal:

  <!-- Modal Provision BIM360 Help  -->
  <div class="modal fade" id="provisionAccountStepsModal" tabindex="-1" role="dialog" aria-labelledby="myModalLabel">
    <div class="modal-dialog modal-lg" role="document">
      <div class="modal-content">
        <div class="modal-header">
          <button type="button" class="close" data-dismiss="modal" aria-label="Cancel"><span aria-hidden="true">&times;</span></button>
          <h4 class="modal-title" id="myModalLabel1">Step-by-step guide</h4>
        </div>
        <div class="modal-body">
          <p>To access your BIM 360 Docs files with this app, you need to connect your BIM 360 account with the app.</p>
          <ol>
            <li>Log in to <a href="https://bim360enterprise.autodesk.com/" target="_blank">BIM 360 Account Administration</a>. Note that you need account administrator permissions.</li>
            <li>If you have more than one account, select the account you want to integrate with the app.</li>
            <li>From the toolbar, select <strong>SETTING &gt; Apps & Integrations</strong>.<br />
              <img src="/Images/Step1.png" width="500" /></li>
            <li>Click the <strong>Add Integration</strong> button.<br />
              <img src="/Images/Step2.png" />
            </li>
            <li>Select <strong>BIM 360 Account Administration</strong> and <strong>BIM 360 Docs</strong>, and click <strong>Next</strong>.</li>
            <li>Select <strong>I’m the developer</strong>, and click <strong>Next</strong>.</li>
            <li>In the <strong>Forge Client ID</strong> and <strong>App Name</strong> fields, enter the Forge client ID and app name provided by the app retailer.</li>
            <li>Select the <strong>I have saved the Account ID information securely</strong> checkbox.</li>
            <li>Click <strong>Save</strong>.<br/>
            <img src="/Images/Step3.png" width="500" />
            </li>
            <p></p>
            <p>Congratulations! You can now access your BIM 360 Docs files.</p>
          </ol>
        </div>
        <div class="modal-footer">
          <button type="button" class="btn btn-default" data-dismiss="modal">Understood, thanks!</button>
        </div>
      </div>
    </div>
  </div>

And finally, the images, so you don't have to screen capture again.

Step1

Step2Step3

Related Article