How to: Manage Data on Forge

00:00

[MUSIC PLAYING]

00:12

Hi, everyone, and welcome to our webinar on how to manage

00:15

data on Forge.

00:16

Thank you for joining, and I hope you're doing great.

00:19

My name is Namit Ranjan, and I'll

00:20

be your host and facilitator today.

00:23

Just a little bit of background of what's an accelerator.

00:26

Autodesk accelerators are designed

00:27

to help your team stay ahead of the curve with the latest

00:30

workflows.

00:31

They include courses, videos, and live coaching, which

00:34

is what we are doing today.

00:36

You can see a full list of topics on the customer Success

00:39

Hub.

00:40

Now, before we move any further, as a safe harbor statement,

00:42

we may make statements regarding future events

00:45

and regarding planned or future development efforts.

00:47

These statements are not intended

00:49

to be a promise or guarantee of future delivery of products,

00:52

services, or features, but merely

00:54

reflect our current plans, which may change.

00:58

So quick introduction about myself.

00:60

As I said, my name is Namit Ranjan.

01:01

I'm a designated support specialist with Autodesk

01:04

and based out of Bangalore, India.

01:05

It's been a little over three years for me with Autodesk now,

01:08

and I have a Civil Engineering and AEC

01:10

background with specialization in automation and computational

01:13

design.

01:15

So this is what we are planning in doing today.

01:17

In today's session, you will learn

01:19

how to set up your first Forge application.

01:21

Following that, we shall deep dive into three key APIs

01:24

within the umbrella of Forge.

01:26

We're going to start with OAuth authentication API,

01:29

and generate two-legged and three-Legged tokens, which

01:32

would allow us, and help us to use other APIs within Forge.

01:35

We're going to get into data management API, where we'll

01:38

primarily look at reading and writing data

01:40

from Autodesk cloud platforms, like BIM 360,

01:43

and also from a Forge bucket.

01:46

Next, we're going to deep-dive into BIM 360 APIs with which we

01:50

could programmatically achieve and automate

01:52

operations in BIM 360.

01:55

So this is how things will follow,

01:56

setting up Forge, procuring an access token using OAuth API,

02:00

manage data using Data Management API,

02:03

and interaction with BIM

02:08

Now, let's get started with the first section for today,

02:10

which is setting up Forge.

02:12

You need to have an Autodesk account in order for you

02:15

to be able to access Forge.

02:17

This is the same set of credentials

02:18

that you would use to access our textile products like Revit

02:22

and Navisworks, and also our web products like BIM 360 and even

02:26

Autodesk forums.

02:27

In fact, this is the same set of credentials

02:29

that you'd use to register for Autodesk conferences

02:32

like Autodesk University.

02:33

So this is that account that you need to have.

02:36

Next, you need to go to forge.autodesk.com.

02:39

When you sign in with your credentials,

02:41

you can choose to launch a free trial which

02:43

gives you some free cloud credits to burn.

02:45

Once you exhaust those cloud credits,

02:47

you can buy more from the same web page.

02:49

If you happen to be our customer who has an enterprise business

02:52

agreement with us, you may work with your Autodesk account team

02:56

to make sure that Forge is added to your token flex.

02:59

Once done, primary or secondary admin

03:02

would be able to entitle users with access to Forge.

03:06

Now, once your Forge account is all set up,

03:08

you can go to My Apps.

03:10

When you click on My Apps, you will see a list of applications

03:13

that you've created.

03:13

If you do not have one, create a new app,

03:16

and you can mark those APIs that you would need

03:18

to use in your application.

03:20

So you'll see a list of APIs.

03:21

I'm going to walk you through in a live demonstration

03:24

in a short while.

03:25

With every application, you would

03:27

get a client ID and a client secret,

03:29

which is synonymous to username and password

03:31

of that application.

03:32

So this is something that you would

03:33

be using to develop your application if you

03:35

are the developer.

03:36

Or if you have a team of developers,

03:37

then you would want to share this client ID and client

03:40

secret with them.

03:41

And as I said, you would be able to see all the applications

03:45

that you've created within My Apps.

03:48

And you can also track consumption of Forge APIs

03:50

under usage analytics.

03:52

This is pretty straightforward.

03:53

I'm going to walk you through this and everything I just

03:55

talked about live in a moment.

03:57

So now I'm going to switch to my browser.

04:00

All right, so when you go onto forge.autodesk.com,

04:03

this is what the interface would look like.

04:06

You'd need to go on the top right to sign in.

04:10

And you'd need to sign in with your Autodesk credentials.

04:16

Yep, so my credentials are already stored in the cache,

04:20

so it did not ask me for my password.

04:23

But you'd need to use your Autodesk username and password

04:27

to sign in.

04:28

Once you've done that, you can go here on My Apps,

04:37

and then you'd be able to see a list of applications

04:40

that you've created.

04:41

So at the moment, I have one application

04:44

which is called Test-1.

04:49

And as I said, with every application,

04:51

you'd get a client ID and client secret,

04:54

which is synonymous to your username and password.

04:58

It's also called app keys, and you would see your app name.

05:01

You would see the list of APIs that this application

05:05

has access to.

05:05

So make sure that you've selected all the relevant APIs

05:08

that you would be using.

05:11

And Similarly, you can go back to My Apps

05:13

and you can create another application of your own.

05:16

And when we go to usage analytics--

05:19

so when you go to usage analytics,

05:21

you'd be able to track consumption.

05:23

There are a few APIs which are free of cost, which do not

05:26

involve cloud computation.

05:28

On the other hand, we've got some APIs

05:30

like Design Automation, Model Derivative,

05:31

and Reality Capture which would incur some consumption.

05:36

So depending on what APIs you've used,

05:38

you would see cloud credits consumed reflecting over here

05:42

on this dashboard.

05:44

I'm going to get into the next section, which

05:46

is authentication API.

05:49

All right, so this is how a basic flow of authentication

05:51

happens with OAuth 2.0.

05:54

App credentials or the client ID and client

05:56

secret, which we just generated would

05:58

be sent as an HTTP request to the Forge authentication

06:01

server, and an access token is received as an HTTP response.

06:06

And for all the rest of the HTTP requests,

06:09

the access token is included in the header.

06:12

Now, just a bit of information about Oauth 2.0,

06:16

it's an industry standard protocol for authorization.

06:19

It focuses on client developer simplicity,

06:21

while providing specific authorization flows.

06:24

And it is commonly used in web applications,

06:27

desktop applications, mobile phones, and living room

06:30

devices.

06:32

So as I said, Forge uses, client ID, and client secret,

06:34

which is synonymous to your application's username

06:37

and password-- it is unique to every Forge application,

06:41

and it has flexible access control,

06:43

which means that if you want to revoke access

06:45

from an individual or from a team,

06:47

you can just go ahead and click on the Regenerate button.

06:50

Cloud credits are consumed based on these credentials.

06:54

Now, these are some OAuth

06:56

which are required in the authentication request.

06:59

Client ID is the identification of the Forge application,

07:02

and client secret that is that secret key of the Forge

07:05

application.

07:06

These are two things that we've already generated, as we set up

07:10

our first Forge application.

07:12

So after client ID and client secret, comes grant type.

07:15

Authorization is done on the basis of grant type,

07:18

then comes scope, which defines the permission

07:21

level to access actual data.

07:23

And then there's callback URL, which

07:26

is the return URL, which you'll be using

07:27

if it's a three-legged token.

07:29

So I'm going to come to that as we move forward

07:31

with the presentation.

07:33

Now, there are two types of authentication,

07:35

three-legged OAuth flow, and two-legged OAuth flow.

07:38

When we talk about a three-legged OAuth flow,

07:40

that means that with the app credentials-- which

07:43

means the client ID and client secret, which we just

07:46

created with the setting up of that application--

07:49

you would also need to add your user context, which

07:52

means the application should know which

07:54

user is using that application.

07:56

And then, both these informations

07:58

are combined and sent to the Forge authentication server,

08:01

and an access token is retrieved.

08:03

So this is a three-legged OAuth flow.

08:06

Once again, with a three-legged OAuth flow

08:08

together with app credentials, which

08:10

is app's client ID and client secret,

08:13

the user context is also required.

08:15

So whenever we are doing a three-legged OAuth flow

08:18

together with the client ID and client secret,

08:20

the user who's operating the application--

08:22

they would also need to sign in with their Autodesk

08:25

credentials, and only then, access token is retrieved.

08:28

That access token would also contain information

08:31

about the user who is using that application.

08:34

With the two-legged OAuth flow, no user context

08:37

is required, which means the client ID and client secret,

08:40

which we just generated setting up that first Forge

08:43

application, that has to be sent to the Forge authentication

08:46

server, and an access token would be retrieved.

08:49

In this kind of an OAuth flow, the application

08:52

doesn't recognize the user, and there's no user context

08:55

that is really required.

08:57

So both of these authentication types

08:59

have got their own use cases, we'll

09:02

come to that as we move forward.

09:05

Now again, one of the important components within access tokens

09:07

is type of grants.

09:09

The first one is client credentials.

09:11

It's the simplest form of authentication.

09:13

User's permission is not needed in this,

09:15

and token expires in time.

09:17

So this is the type of client that you'd

09:19

be using for a two-legged OAuth type.

09:22

When it comes to authorization code,

09:24

the first flow happens with access code.

09:26

The second flow happens with access token and refresh token.

09:29

And this is ideal for server-based applications.

09:33

The third one is implicit, where access token

09:36

is returned directly, and it's suitable for client

09:38

based applications.

09:40

And just like how it used to happen in client credentials,

09:43

token would expire in time.

09:46

Now, when we talk about scope, this

09:47

is also one of the really important components

09:50

within the access token.

09:51

Scope is the definition of permission.

09:53

The requested scopes are set as authentication parameter,

09:56

and returned access token is enabled with permissions

09:59

based on scope.

10:00

There's also an interesting link which is called jwt.io.

10:04

It's access token decoder.

10:05

It's a web application that helps you decode your access

10:08

token, and you can check for yourself

10:10

and just be double sure if it includes the correct scope

10:14

or not.

10:14

With that, we're going to dive into Postman Demo.

10:17

So I'm going to do some emulations

10:18

and live demonstrations for you.

10:20

Before I do that, I'm going to head to some documentations.

10:23

So I'm going to switch back to my browser.

10:26

And when you go to forge.autodesk.com,

10:29

you would see guided tutorials on how

10:32

to procure a two-legged token, how

10:34

to procure a three-legged token with the authorization code

10:37

grant, and getting a three-legged token

10:39

with implicit grant.

10:40

So at the moment, we'll try and create a two-legged token.

10:44

So you've got all the steps mentioned here.

10:47

Step one, use your client ID and client secret

10:49

to obtain an access token.

10:51

And within that, we can actually click on this link called

10:55

the post authenticate endpoint.

10:59

And you can see the description, get a two-legged access token

11:02

by providing your app's client ID and secret.

11:05

So client ID and secret is something

11:06

that we've already generated.

11:08

This is the URL that we will be using.

11:13

This is the data format that has to be there.

11:15

The rate limit is

11:17

so we will definitely not be crossing that rate limit.

11:21

You can set the content type from here,

11:23

and this is what the body structure should look like.

11:26

So your client ID or client secret both go in the body.

11:29

You can also put in your grant type,

11:31

and you can also specify the scope in the body itself.

11:36

And this is what the structure would look like,

11:39

and I'm going to show you some examples.

11:41

This is an example request, and this is an example response.

11:45

So you can see that this is the access

11:48

token that we just got, and this expires in these many seconds.

11:52

And I'm going to emulate the same on Postman,

11:55

so I'm going to use the same stuff and same content that's

11:58

written here in terms of method and URI and body structure.

12:02

So I'm going to replicate that in Postman.

12:05

I have launched Postman here, and I've already

12:09

prepared some collection.

12:11

Now, what I'll do is expand on to data management demo,

12:15

go inside two-legged token.

12:18

All right.

12:18

So now, let me walk you through what we've set up here.

12:21

The base URL has been set up as a variable,

12:25

so that I don't have to copy and paste this

12:27

over, and over again.

12:28

If you look at the list of variables that I have,

12:31

the base URL is already set up as https://develope

12:34

r.api.autodesk.com.

12:37

This is the same base URL that's going to be there

12:40

in all the API calls, and that's why we've

12:42

made a variable out of this.

12:44

And then I've used the same variable/ authentication/ V1/

12:46

authentication.

12:49

And this is something that we've taken directly

12:51

from the documentation.

12:53

And if you put the content type in terms of application

12:57

x-www-form-urlencoded, and this goes into the header.

13:03

And as for the documentation, we wanted

13:05

to find the body structure.

13:06

We've put in the client ID and client secret.

13:09

Now, again, these are variables, so

13:10

that I don't have to use it over and over again.

13:12

I don't have to copy and paste this over and over again.

13:16

If you look at client ID, this is my client ID,

13:19

this is my client secret.

13:21

And I've just used this variable over here,

13:24

grant type remains to be client credentials

13:26

because it's supposed to be a two-legged authentication.

13:29

And the scope, once again is available.

13:33

So if we look at scope, you'd see

13:35

that we have bucket create, bucket read, bucket update

13:39

data create viewables read, user write have

13:42

got a ton of information that's given to this particular token.

13:49

And I've just hit sent to retrieve this access token.

13:52

This is the access token, which is going

13:54

to expire in 3599 seconds.

13:57

I'm going to copy this, and I'm going to go to jwt.io.

14:03

and I'm going to paste this up here.

14:07

And as I paste this, I can see a decoded version of this.

14:12

So I can actually see the list of scope that I have.

14:16

So you get to see the client ID, the scope, and the expiry time.

14:22

So this is a good way to check if your access

14:24

token has enough permissions or enough scope or not.

14:28

This is a handy decoder that you get within jwt.io.

14:33

You can see that when we generated a two-legged token,

14:36

the token doesn't have any user context.

14:38

So it doesn't really have any user context.

14:41

The application doesn't know who is the user who's

14:44

using that application.

14:45

Now, I'm going to go ahead and move on to three-legged token.

14:49

So you can switch to three-legged context,

14:54

and you can follow this documentation.

14:56

You also have a guided tutorial, as I mentioned.

14:58

Within here, you can get into three-legged token

15:01

with the implicit grant, or three-legged token

15:03

with authorization code.

15:05

I've already set that up in Postman.

15:08

I'm going to go to authentication three-legged,

15:13

and I'm going to generate a new access token, which actually

15:16

requires me to sign in.

15:18

So I'm going to sign in with my credentials.

15:21

And that's when the application recognizes me because I'm

15:26

passing on my user context.

15:29

If you remember, we did not have to do this step in two-legged

15:33

because a two-legged token doesn't really

15:36

have a user context.

15:37

However, with this three-legged authentication,

15:40

we're going to have to put in the user context as well.

15:44

And I'm going to do this authentication.

15:49

Proceed, and this is that access token, which

15:53

is a three-legged access token.

15:55

I'm going to pass this on to a three-legged token variable.

15:58

And just to test this and decode this,

16:01

I'm going to go back to jwt.io, and now, I'm

16:04

going to put this token here.

16:07

And you can see that apart from all the things

16:11

that remain same in terms of scope, in terms of client ID,

16:15

it adds user ID.

16:17

That means that it now has user context.

16:20

So this is my username, of course, in an encoded format.

16:23

But this is the user ID who's been using that application.

16:26

Because with a three-legged token,

16:28

we had to also pass on the user context.

16:31

So this is the difference between a two-legged OAuth flow

16:33

and a three legged OAuth flow.

16:35

All right, so let's head to the next section,

16:37

which is data management API.

16:39

As we've discussed before, data management API

16:41

allows us to read and write data from Autodesk cloud platforms

16:45

like BIM 360, and also on Forge buckets.

16:49

So it allows you to access your data.

16:51

Forge already handles over $3 billion API calls per month.

16:55

It is reliable and secure.

16:57

It's hosted on AWS SOC2 Certified US and EU Data

17:01

Centers.

17:02

And it supports object storage service.

17:04

And, of course, you are not just restricted to CAD file formats.

17:08

I'm going to start with this interesting example before I

17:10

deep dive into the API.

17:12

This is a web application.

17:13

It allows the user to copy data between Autodesk cloud products

17:18

like BIM 360 Team, BIM 360 Docs, and Google Drive.

17:22

All right, so as you can see on the application,

17:24

on the left-hand side, we've got folders and files

17:27

coming in from BIM 360 Team and BIM 360 Docs.

17:31

On the right-hand side, you've got

17:33

folders and files that are coming in from Google Drive.

17:36

So the user goes on the left-hand side,

17:37

and they navigate to BIM 360 Team project

17:42

and selects a folder that needs to be

17:45

transferred to Google Drive.

17:46

And on the right-hand side, they select a destination location.

17:56

This application populates the list

17:58

of files that need to be transferred,

17:59

and the user goes ahead and clicks on Start Transfer.

18:06

And it takes a bit of time, and then it transfers the content

18:09

from the source, which is BIM

18:13

path.

18:15

And the next step is to transfer things

18:17

from Google Drive to BIM 360 Docs.

18:20

So now, picking the same location, which

18:23

was the destination earlier that's

18:25

been selected as the source, and BIM 360 Docs

18:28

has been selected as the destination location.

18:35

And the user hits transfer.

18:37

And you would see in a moment, things

18:39

would start to get transferred between Google Drive

18:42

to BIM 360 Docs.

18:49

So that transfer folder has now been

18:51

copied from Google Drive to this BIM 360 Docs project

18:55

which is called Forge demo.

18:58

All right, so we've also got linked to GitHub,

19:00

so you can actually explore this application

19:03

and you can check out the APIs that are in play.

19:06

If we needed to break this example down,

19:09

there are two important components here.

19:11

First one is transfer from Autodesk to storage.

19:14

When I say storage, I mean third party storage

19:16

like Google Drive at the moment.

19:17

And these are the steps that are involved.

19:19

So log into Autodesk cloud, select files or folders

19:22

from the Autodesk side.

19:23

Select one folder on storage site and then

19:26

start transferring.

19:27

This is how the process works.

19:29

First of all, we would register a Forge application.

19:32

This is something that we've already done.

19:34

Acquire a three-legged or two-legged token.

19:36

This is again something that we've looked

19:38

at in the previous section.

19:40

Now, the main part here is locating hub, project folder,

19:44

item, and versions.

19:45

Once we are done with this, we can go ahead

19:47

and download the object.

19:48

With every process and with every step,

19:50

we've also done a hyperlink.

19:52

So when you receive this share out,

19:54

you'll be able to click on this and get to that exact tutorial.

19:58

Now, the final download happens with this URL.

20:01

You've got the URL, you got the verb, and you got the headers.

20:04

In terms of how you do it, you can use curl,

20:06

you can use Postman, or you can use the Forge SDK.

20:09

I'm going to use Postman for this example.

20:12

Before I get into Postman really,

20:13

I just wanted to show you this documentation.

20:16

So I'm on the same web page of forge.autodesk.com,

20:19

I've gone to Solutions.

20:21

I've clicked on Data Management, and I've

20:22

clicked on API References.

20:24

And then within here, you can expand onto the API reference.

20:29

You can expand onto Data Management.

20:31

And then within Hubs, and Projects, and Folders,

20:34

you can actually find those endpoints,

20:36

and the details about those endpoints.

20:39

So we can expand onto Hubs.

20:40

We can get into GET Hubs.

20:45

And with this, we're going to get those hubs

20:47

that this application is a part of.

20:50

And then we can also retrieve projects.

20:54

And then once we retrieve projects,

20:56

we can work on getting the folders.

20:58

So now, let's get into Postman.

21:02

Now, we've already generated a two-legged token.

21:04

And this is what we're going to use for the GET Hubs

21:06

and GET Project API calls, and also for GET Folders.

21:12

So what we have done here is to transfer this token

21:15

into a variable, which is called two-legged token.

21:21

So if I show you this variable, it

21:22

has the current value as does the newly generated token

21:26

that we have here that you see on the screen.

21:28

And once we have transferred that

21:30

to the two-legged token variable,

21:32

we are all set with token.

21:34

Now, we need to get to this API call, which is GET Hubs.

21:38

And this is something that I just

21:39

showed you a minute before.

21:42

This is the URL that we need to call.

21:44

This is what the header looks like,

21:46

so we just need to pass the two-legged token that we just

21:49

generated.

21:52

And I'm going to hit send now.

21:55

And in terms of response that we get,

21:57

we're able to get the Autodesk premium support hub, which

22:01

this application has access to.

22:02

So now, at this point of time, I'm going to go inside BIM 360,

22:07

and I'm just going to show you the name of that hub.

22:10

So this is exactly the hub that Forge

22:12

has been able to retrieve, Autodesk-Premium Support Hub.

22:15

And within this, we've got a project called BIM 360 Docs

22:19

Demo-- the current project BIM 360 Docs Demo.

22:22

Within that, we've got project files, we've got WIP.

22:25

And then if I navigate further into WIP,

22:27

we've got architecture.

22:30

And then we've got all these files.

22:32

For example, we've got architecture.rbd.

22:34

So let's say, I'm looking at downloading this file

22:38

programmatically.

22:40

At the moment, I have been able to go

22:42

inside this particular hub.

22:44

I've been able to capture this hub,

22:46

and I'm going to get into this particular project.

22:48

And how do I do that?

22:50

I would take this ID of this hub, which

22:52

is also called the hub ID.

22:54

We can go to GET Project.

22:56

And this API call would actually demand the hub ID.

22:59

So I've made that hub ID as a variable.

23:02

And I've used this variable here.

23:05

And then, similarly, I have passed on the two-legged token

23:08

and header.

23:09

And I would go ahead and hit send.

23:14

And since this account has a lot of projects,

23:17

it's going to take some time.

23:18

But it's going to, at the end of the day,

23:20

retrieve all the projects that are there within this account

23:22

or within this hub.

23:24

So I'm going to look for that particular project, which

23:27

is called BIM 360 Doc's Demo.

23:30

And there we have it.

23:31

And we would similarly take the ID from here.

23:36

And we can go ahead and start retrieving folders.

23:41

So we can go ahead and retrieve the top folder.

23:45

So we've got plans and project files,

23:47

which is exactly what the top folder structure looks like.

23:50

And then within that, I'm going to enter project files now.

23:56

And under project files, you can see, 01 program.

24:04

And it exactly is the same as this, because this

24:08

is what Forge is retrieving.

24:09

Programmatically, you've got program,

24:11

you've got risk, health, safety reports.

24:13

So, now, the next task for me is to get into WIB--

24:16

get into architecture, and then retrieve

24:18

this file or this model, which is called architecture.rvt.

24:23

So I'm already inside project files.

24:25

And I'm going to get into WIP, and then, I'm

24:29

going to get into architecture.

24:34

All it takes is to just copy the ID of a folder,

24:38

and then paste it up in the next API Call for getting folders.

24:44

Now, once we have reached to that particular file,

24:47

I'm already inside the architecture folder.

24:50

I can look for that file, and it's called architecture.rvt.

24:54

I have all the details of that file, the metadata that's

24:57

associated with that file.

24:59

We've got the ID, and this ID is really useful

25:02

when we download this file.

25:04

We can optionally even go to versions.

25:07

We can look at different versions

25:08

of this file on BIM 360 Docs.

25:10

And then, finally, we can go ahead and download the file

25:15

from BIM 360.

25:17

So this time, instead of hitting send, I'm going to do a send

25:21

and download because I want this file to be downloaded.

25:29

And this is a large Revit model, so it's

25:30

going to take some time.

25:31

But finally, it's going to show me

25:34

this, which is the dialogue to save the file.

25:37

Now, this file is ready to be downloaded.

25:39

I can go ahead and save the file now.

25:41

And I was able to programmatically download

25:43

a file from BIM 360 Docs.

25:45

And that's a part of that application

25:47

that I just showed the video of.

25:50

At this point of time, we can also

25:51

connect this with a third party application like Google Drive

25:54

or OneDrive, again, subject to what the API allows.

25:59

And now, the second part is transfer from external storage

26:02

to Autodesk, which is basically transferring from a third party

26:06

external storage like Google Drive or OneDrive to Autodesk

26:10

or which may be BIM 360 Docs or BIM 360 Team.

26:14

This is what the steps would look like.

26:16

Register Forge application.

26:18

Acquired a Three-Legged or two-legged token.

26:21

Again, something which we've done.

26:23

Locate hub project, and then create a storage location,

26:27

and then upload project, and create

26:28

the first version of that file.

26:30

So these would be the steps, and this

26:33

would be the file you add into uploader file.

26:35

The verb would be PUT.

26:37

This is how you define the headers,

26:39

the content of the file would go inside the body.

26:41

And once again, just like how we did the previous exercise

26:44

in Postman, this can be done in Postman.

26:46

This can be done in curl.

26:48

This can be done in Forge SDK.

26:50

So I would definitely urge and encourage you to try this out.

26:54

There are also other automation ideas that's there

26:56

on the screen at the moment.

26:57

And the slide can build online workflows and experiences

27:00

around your design data.

27:01

You can create an attachment.

27:03

Attach an Excel spreadsheet to a DWG file.

27:05

And create an app-anaged bucket and upload

27:08

a file, which is basically a pre-requisite to view your data

27:11

and Forge viewer.

27:12

You can publish a cloud workshared Revit model

27:14

to Next Gen BIM 360 Docs.

27:17

You can also publish later synchronized cloud

27:19

worksheet Revit models to BIM 360 Docs.

27:22

You can also delete and restore files in BIM 360 Docs.

27:25

Now, in terms of tools that you need,

27:27

you can go ahead with an oasis manager.

27:30

These are all hyperlink.

27:31

You can connect your data, create buckets and more.

27:34

You can also download the Forge Visual Studio code extension,

27:38

which helps you connect to your data,

27:40

create buckets, view and more.

27:42

And finally, these are things that you should know about,

27:44

pagination, retention policy, and rate limiting.

27:47

And we have done a hyperlink to each of these items.

27:51

Now with that, I'm going to go into the final section, which

27:54

is BIM 360 API.

27:56

Now, before we start to use BIM 360 API,

27:59

a custom integration needs to be done.

28:01

And how do you do it?

28:02

You need to be an account admin to be able to do that.

28:05

If you're not an account admin, you

28:07

must contact your account admin to do that.

28:09

You need to go into your BIN 360 account admin.

28:12

If you have access to more than one account,

28:14

then select that particular account

28:16

that you need to integrate that Forge application with.

28:19

Go to Settings, and select the Custom Integration tab.

28:22

Click on Add custom Integration.

28:24

And then here, you can select what level of access

28:27

you want to provide to your Forge application.

28:29

Whether it is just BIN 360 account

28:31

admin, or document management, or both.

28:34

Now, if you are the developer, go ahead and select,

28:36

I'm the developer.

28:37

Once you hit Next, there'll be a dialog

28:39

which allows you to put in your Forge client ID and your app

28:43

name.

28:43

So make sure that you put in the correct client ID

28:45

that you've copied from the Forge portal.

28:48

And you also put in the correct app name.

28:50

And once you do that, your application

28:53

gets integrated with your BIM 360 account.

28:56

Now just a word of caution, depending

28:58

on the level of permission that you've provided from an account

29:01

admin perspective.

29:02

Your application would have access to your hub,

29:06

and all the projects within it.

29:08

So make sure that you are distributing that carefully.

29:11

Now, before I deep dive into BIM 360 APIs,

29:14

I'm going to get into this example.

29:16

We've also got a link to GET Hub.

29:18

I'm going to show you a live demonstration of this.

29:20

And this is called an issues editor.

29:23

All right.

29:24

So this is what the interface looks like.

29:26

It allows me to log in with my Autodesk account.

29:29

And this is a custom Forge application,

29:31

which basically pulls the issues information from BIM 360 Docs.

29:37

And you can see that this is a hub that I'm a part of.

29:39

So it shows Autodesk premium support hub.

29:42

I'm able to get into the projects within this hub.

29:48

And I'm able to select any project

29:50

that I want to see issues of.

29:52

So I'm going to get into Doc's Demo, View Issues,

29:58

and then it provides capabilities

29:60

that BIM 360 Docs doesn't have at the moment.

30:02

For example, it allows me to export and download

30:06

these issues.

30:07

It also allows us to import issues, export

30:10

and email issues.

30:11

These are things that are not there

30:12

out of the box in BIM 360 Docs.

30:14

But since BIM 360 is based on top of Forge,

30:17

you can pretty much build these capabilities

30:20

even before Autodesk builds them because you

30:22

are exposed to the APIs that BIM 360 users in the background.

30:25

And this application is a perfect example of doing that.

30:28

So it basically pulls all the BIM 360 issues

30:31

within this project, and allows you to export and import those

30:35

using a spreadsheet.

30:37

And you can bulk edit things.

30:38

For example, if I wanted to add something over here,

30:41

add a description, maybe change the ownership to somebody else,

30:46

and go ahead and click on Update Issues.

30:50

It has successfully updated the issues that I made changes in.

30:54

Now, with that, I'm going to go further and show you

30:57

some supported operations that BIM 360 APIs could do.

31:00

So you can play around with account admin

31:02

API, document management API, Issues API, Checklists API,

31:06

Model Coordination API, data connector API, RFIs, locations,

31:11

relationships, assets API, and cost managing API.

31:15

There are also other APIs like activities, which are

31:19

in [? beta ?] at the moment.

31:20

So when I expand onto account admin API,

31:22

these are some of the supported operations

31:24

that you can programmatically achieve using Forge.

31:26

You can create a new project.

31:28

You can get, add or modify account members.

31:30

You can create or modify a new company.

31:33

You can get, add, or modify project numbers.

31:35

You can also activate a service.

31:37

And you can create or redefine business units.

31:40

Now, let's look at a live demonstration here.

31:43

Now, if we had to add a new project

31:45

member programmatically, these are the steps that we would do.

31:48

So in terms of BIM

31:51

we would do a BIM 360 custom integration.

31:53

That's something that we've already

31:55

done and already looked at.

31:56

We'd be generating a two legged token.

31:59

And this is also something that we've already looked at.

32:02

The next step for us is to get account and the account ID,

32:05

and the project ID that we are looking at,

32:07

adding the new member too.

32:09

In terms of inputs, we need the company

32:11

that the user is assigned to.

32:13

Go for the project, the industry, roles assigned

32:15

to the user for the project, and the user's email address,

32:19

and whether or not they are an admin.

32:21

All right, so we're going to start with a two-legged token.

32:24

And then we're going to get into getting account and project ID.

32:28

This is already something that we've looked at.

32:30

We would get to that particular account,

32:32

get to that particular project.

32:33

And then, we would get the account ID and the project ID.

32:36

And once these steps are done, we

32:38

can use this URL to add the user.

32:41

The verb should be POST.

32:43

URI parameters should be account ID and the project ID.

32:46

This is something that we are already getting

32:47

from the previous steps.

32:49

And this is what the body should look like.

32:51

I'm going to show you a live demonstration.

32:53

Before I do that, I'm just going to get into the documentation,

32:57

just to make sure you are aware on where

32:59

to find the documentation from.

32:60

So you can actually go to the Forge web portal.

33:03

Go to solutions, click on BIM 360,

33:08

and then get into API reference.

33:14

Expand onto API reference, go to Account admin, project users,

33:22

and POST project_id/users/import.

33:25

And if you read through the description,

33:27

it says, adds user to a project.

33:29

You can add up to

33:31

So we are going to look at adding two

33:33

users at this point of time.

33:38

You can take in the details from here

33:40

in terms of the URL that's going to be

33:42

in use, the headers detail, the URI parameters.

33:46

And this is what the body structure in terms of request

33:49

should look like.

33:50

It should have the email, user ID services, company ID,

33:53

and industry role.

33:55

You can also find a sample request and a sample response.

33:59

I'm going to get into my BIM 360 Docs

34:02

here, just to show you the project admin part.

34:05

And then this is where I need to add the two members.

34:12

At this point of time, I have five members.

34:16

In this particular project, I'm going to programmatically add

34:19

two members to this list.

34:20

I'm going to switch back to Postman.

34:24

And I'm going to open this collection.

34:26

This is actually going to use a three-legged token.

34:34

So I'm going to make sure that I have a three-legged token

34:37

generated already.

34:39

And then once that is done, I'm going to use this token,

34:43

maybe copy this into a variable so that I can use it next time

34:47

in this particular API call.

34:51

I'm going to get into POST Users import.

34:54

So I'm just going to make sure that this particular project

34:57

ID is the same as the project that we are targeting.

35:01

For example, in this case, it's supposed

35:03

to be BIM 360 Docs Demo.

35:05

So I'm just going to make sure this is the ID that's in use.

35:08

I'm going to go back to POST Users import.

35:13

And it's actually the same.

35:17

And then, this is the information of the users

35:19

that I'm going to add.

35:20

And I haven't really assigned them a company or a role,

35:24

but I've given them and admin access in terms

35:27

of document management, and also project administration.

35:30

I'm going to hit send now.

35:35

And you can see, the 0 failure and 2 success,

35:38

that means that it has added both

35:40

these users to the project.

35:42

And I could have added

35:45

So I'm going to go back to BIM 360 Docs,

35:47

and I'm going to hit Refresh, just to make sure

35:50

that these users that I have just added have come in,

35:53

and that's correct.

35:55

All right, I'm going to get back to the presentation.

35:58

Now that we've looked at this live demonstration,

35:60

we can do similar operations using document management API.

36:03

We can export PDF files from BIM 360 document management

36:07

from the plan area.

36:08

We can also upload files to BIM 360 document management,

36:11

and we can also download files from BIM 360 document

36:14

management.

36:15

Using the Issues API in line with the live demonstration

36:18

that we just showed you, you can retrieve information

36:20

about all attachments associated with a specific issue.

36:23

You can retrieve issues, you can retrieve

36:25

issue custom attributes, map to an issue type.

36:27

You can also update issues.

36:30

You can also attach BIM 360 document management files

36:32

to issues, and add a comment to an issue.

36:36

And with checklists API, you can get template, and also

36:39

get instances of those templates and a lot more.

36:43

So in the list of operations that support it with the BIM

36:49

using the data connector API.

36:50

You can use the cost management API to get budgets.

36:54

You can retrieve location.

36:55

You can post RFI.

36:56

And you can get assets, and you can do a lot more.

36:59

If you want to get a list of operations

37:00

that you want to programmatically

37:02

achieve, using Forge, you can click on this web page.

37:05

It'll take you to the list of supported operations using

37:08

BIM 360 API.

37:10

It takes me here, where I can actually

37:13

get to see all these operations that's supported from a BIM 360

37:17

perspective.

37:18

So you can get into account admin,

37:19

you can get into issues, assets, checklists, cost management,

37:22

data connector, document management, locations,

37:25

Model Coordination, relationships, RFIs.

37:27

And as I said, there's a lot more

37:29

that's still a work in progress, and it's going to be out soon.

37:33

With that, I'd like to wrap up the session.

37:35

Thank you once again for your time.

37:37

I hope this was useful.

37:38

Take good care of yourselves.

37:40

Stay safe and healthy.

37:41

Have a great rest of your day, Bye.

Video transcript

00:00

[MUSIC PLAYING]

00:12

Hi, everyone, and welcome to our webinar on how to manage

00:15

data on Forge.

00:16

Thank you for joining, and I hope you're doing great.

00:19

My name is Namit Ranjan, and I'll

00:20

be your host and facilitator today.

00:23

Just a little bit of background of what's an accelerator.

00:26

Autodesk accelerators are designed

00:27

to help your team stay ahead of the curve with the latest

00:30

workflows.

00:31

They include courses, videos, and live coaching, which

00:34

is what we are doing today.

00:36

You can see a full list of topics on the customer Success

00:39

Hub.

00:40

Now, before we move any further, as a safe harbor statement,

00:42

we may make statements regarding future events

00:45

and regarding planned or future development efforts.

00:47

These statements are not intended

00:49

to be a promise or guarantee of future delivery of products,

00:52

services, or features, but merely

00:54

reflect our current plans, which may change.

00:58

So quick introduction about myself.

00:60

As I said, my name is Namit Ranjan.

01:01

I'm a designated support specialist with Autodesk

01:04

and based out of Bangalore, India.

01:05

It's been a little over three years for me with Autodesk now,

01:08

and I have a Civil Engineering and AEC

01:10

background with specialization in automation and computational

01:13

design.

01:15

So this is what we are planning in doing today.

01:17

In today's session, you will learn

01:19

how to set up your first Forge application.

01:21

Following that, we shall deep dive into three key APIs

01:24

within the umbrella of Forge.

01:26

We're going to start with OAuth authentication API,

01:29

and generate two-legged and three-Legged tokens, which

01:32

would allow us, and help us to use other APIs within Forge.

01:35

We're going to get into data management API, where we'll

01:38

primarily look at reading and writing data

01:40

from Autodesk cloud platforms, like BIM 360,

01:43

and also from a Forge bucket.

01:46

Next, we're going to deep-dive into BIM 360 APIs with which we

01:50

could programmatically achieve and automate

01:52

operations in BIM 360.

01:55

So this is how things will follow,

01:56

setting up Forge, procuring an access token using OAuth API,

02:00

manage data using Data Management API,

02:03

and interaction with BIM

02:08

Now, let's get started with the first section for today,

02:10

which is setting up Forge.

02:12

You need to have an Autodesk account in order for you

02:15

to be able to access Forge.

02:17

This is the same set of credentials

02:18

that you would use to access our textile products like Revit

02:22

and Navisworks, and also our web products like BIM 360 and even

02:26

Autodesk forums.

02:27

In fact, this is the same set of credentials

02:29

that you'd use to register for Autodesk conferences

02:32

like Autodesk University.

02:33

So this is that account that you need to have.

02:36

Next, you need to go to forge.autodesk.com.

02:39

When you sign in with your credentials,

02:41

you can choose to launch a free trial which

02:43

gives you some free cloud credits to burn.

02:45

Once you exhaust those cloud credits,

02:47

you can buy more from the same web page.

02:49

If you happen to be our customer who has an enterprise business

02:52

agreement with us, you may work with your Autodesk account team

02:56

to make sure that Forge is added to your token flex.

02:59

Once done, primary or secondary admin

03:02

would be able to entitle users with access to Forge.

03:06

Now, once your Forge account is all set up,

03:08

you can go to My Apps.

03:10

When you click on My Apps, you will see a list of applications

03:13

that you've created.

03:13

If you do not have one, create a new app,

03:16

and you can mark those APIs that you would need

03:18

to use in your application.

03:20

So you'll see a list of APIs.

03:21

I'm going to walk you through in a live demonstration

03:24

in a short while.

03:25

With every application, you would

03:27

get a client ID and a client secret,

03:29

which is synonymous to username and password

03:31

of that application.

03:32

So this is something that you would

03:33

be using to develop your application if you

03:35

are the developer.

03:36

Or if you have a team of developers,

03:37

then you would want to share this client ID and client

03:40

secret with them.

03:41

And as I said, you would be able to see all the applications

03:45

that you've created within My Apps.

03:48

And you can also track consumption of Forge APIs

03:50

under usage analytics.

03:52

This is pretty straightforward.

03:53

I'm going to walk you through this and everything I just

03:55

talked about live in a moment.

03:57

So now I'm going to switch to my browser.

04:00

All right, so when you go onto forge.autodesk.com,

04:03

this is what the interface would look like.

04:06

You'd need to go on the top right to sign in.

04:10

And you'd need to sign in with your Autodesk credentials.

04:16

Yep, so my credentials are already stored in the cache,

04:20

so it did not ask me for my password.

04:23

But you'd need to use your Autodesk username and password

04:27

to sign in.

04:28

Once you've done that, you can go here on My Apps,

04:37

and then you'd be able to see a list of applications

04:40

that you've created.

04:41

So at the moment, I have one application

04:44

which is called Test-1.

04:49

And as I said, with every application,

04:51

you'd get a client ID and client secret,

04:54

which is synonymous to your username and password.

04:58

It's also called app keys, and you would see your app name.

05:01

You would see the list of APIs that this application

05:05

has access to.

05:05

So make sure that you've selected all the relevant APIs

05:08

that you would be using.

05:11

And Similarly, you can go back to My Apps

05:13

and you can create another application of your own.

05:16

And when we go to usage analytics--

05:19

so when you go to usage analytics,

05:21

you'd be able to track consumption.

05:23

There are a few APIs which are free of cost, which do not

05:26

involve cloud computation.

05:28

On the other hand, we've got some APIs

05:30

like Design Automation, Model Derivative,

05:31

and Reality Capture which would incur some consumption.

05:36

So depending on what APIs you've used,

05:38

you would see cloud credits consumed reflecting over here

05:42

on this dashboard.

05:44

I'm going to get into the next section, which

05:46

is authentication API.

05:49

All right, so this is how a basic flow of authentication

05:51

happens with OAuth 2.0.

05:54

App credentials or the client ID and client

05:56

secret, which we just generated would

05:58

be sent as an HTTP request to the Forge authentication

06:01

server, and an access token is received as an HTTP response.

06:06

And for all the rest of the HTTP requests,

06:09

the access token is included in the header.

06:12

Now, just a bit of information about Oauth 2.0,

06:16

it's an industry standard protocol for authorization.

06:19

It focuses on client developer simplicity,

06:21

while providing specific authorization flows.

06:24

And it is commonly used in web applications,

06:27

desktop applications, mobile phones, and living room

06:30

devices.

06:32

So as I said, Forge uses, client ID, and client secret,

06:34

which is synonymous to your application's username

06:37

and password-- it is unique to every Forge application,

06:41

and it has flexible access control,

06:43

which means that if you want to revoke access

06:45

from an individual or from a team,

06:47

you can just go ahead and click on the Regenerate button.

06:50

Cloud credits are consumed based on these credentials.

06:54

Now, these are some OAuth

06:56

which are required in the authentication request.

06:59

Client ID is the identification of the Forge application,

07:02

and client secret that is that secret key of the Forge

07:05

application.

07:06

These are two things that we've already generated, as we set up

07:10

our first Forge application.

07:12

So after client ID and client secret, comes grant type.

07:15

Authorization is done on the basis of grant type,

07:18

then comes scope, which defines the permission

07:21

level to access actual data.

07:23

And then there's callback URL, which

07:26

is the return URL, which you'll be using

07:27

if it's a three-legged token.

07:29

So I'm going to come to that as we move forward

07:31

with the presentation.

07:33

Now, there are two types of authentication,

07:35

three-legged OAuth flow, and two-legged OAuth flow.

07:38

When we talk about a three-legged OAuth flow,

07:40

that means that with the app credentials-- which

07:43

means the client ID and client secret, which we just

07:46

created with the setting up of that application--

07:49

you would also need to add your user context, which

07:52

means the application should know which

07:54

user is using that application.

07:56

And then, both these informations

07:58

are combined and sent to the Forge authentication server,

08:01

and an access token is retrieved.

08:03

So this is a three-legged OAuth flow.

08:06

Once again, with a three-legged OAuth flow

08:08

together with app credentials, which

08:10

is app's client ID and client secret,

08:13

the user context is also required.

08:15

So whenever we are doing a three-legged OAuth flow

08:18

together with the client ID and client secret,

08:20

the user who's operating the application--

08:22

they would also need to sign in with their Autodesk

08:25

credentials, and only then, access token is retrieved.

08:28

That access token would also contain information

08:31

about the user who is using that application.

08:34

With the two-legged OAuth flow, no user context

08:37

is required, which means the client ID and client secret,

08:40

which we just generated setting up that first Forge

08:43

application, that has to be sent to the Forge authentication

08:46

server, and an access token would be retrieved.

08:49

In this kind of an OAuth flow, the application

08:52

doesn't recognize the user, and there's no user context

08:55

that is really required.

08:57

So both of these authentication types

08:59

have got their own use cases, we'll

09:02

come to that as we move forward.

09:05

Now again, one of the important components within access tokens

09:07

is type of grants.

09:09

The first one is client credentials.

09:11

It's the simplest form of authentication.

09:13

User's permission is not needed in this,

09:15

and token expires in time.

09:17

So this is the type of client that you'd

09:19

be using for a two-legged OAuth type.

09:22

When it comes to authorization code,

09:24

the first flow happens with access code.

09:26

The second flow happens with access token and refresh token.

09:29

And this is ideal for server-based applications.

09:33

The third one is implicit, where access token

09:36

is returned directly, and it's suitable for client

09:38

based applications.

09:40

And just like how it used to happen in client credentials,

09:43

token would expire in time.

09:46

Now, when we talk about scope, this

09:47

is also one of the really important components

09:50

within the access token.

09:51

Scope is the definition of permission.

09:53

The requested scopes are set as authentication parameter,

09:56

and returned access token is enabled with permissions

09:59

based on scope.

10:00

There's also an interesting link which is called jwt.io.

10:04

It's access token decoder.

10:05

It's a web application that helps you decode your access

10:08

token, and you can check for yourself

10:10

and just be double sure if it includes the correct scope

10:14

or not.

10:14

With that, we're going to dive into Postman Demo.

10:17

So I'm going to do some emulations

10:18

and live demonstrations for you.

10:20

Before I do that, I'm going to head to some documentations.

10:23

So I'm going to switch back to my browser.

10:26

And when you go to forge.autodesk.com,

10:29

you would see guided tutorials on how

10:32

to procure a two-legged token, how

10:34

to procure a three-legged token with the authorization code

10:37

grant, and getting a three-legged token

10:39

with implicit grant.

10:40

So at the moment, we'll try and create a two-legged token.

10:44

So you've got all the steps mentioned here.

10:47

Step one, use your client ID and client secret

10:49

to obtain an access token.

10:51

And within that, we can actually click on this link called

10:55

the post authenticate endpoint.

10:59

And you can see the description, get a two-legged access token

11:02

by providing your app's client ID and secret.

11:05

So client ID and secret is something

11:06

that we've already generated.

11:08

This is the URL that we will be using.

11:13

This is the data format that has to be there.

11:15

The rate limit is

11:17

so we will definitely not be crossing that rate limit.

11:21

You can set the content type from here,

11:23

and this is what the body structure should look like.

11:26

So your client ID or client secret both go in the body.

11:29

You can also put in your grant type,

11:31

and you can also specify the scope in the body itself.

11:36

And this is what the structure would look like,

11:39

and I'm going to show you some examples.

11:41

This is an example request, and this is an example response.

11:45

So you can see that this is the access

11:48

token that we just got, and this expires in these many seconds.

11:52

And I'm going to emulate the same on Postman,

11:55

so I'm going to use the same stuff and same content that's

11:58

written here in terms of method and URI and body structure.

12:02

So I'm going to replicate that in Postman.

12:05

I have launched Postman here, and I've already

12:09

prepared some collection.

12:11

Now, what I'll do is expand on to data management demo,

12:15

go inside two-legged token.

12:18

All right.

12:18

So now, let me walk you through what we've set up here.

12:21

The base URL has been set up as a variable,

12:25

so that I don't have to copy and paste this

12:27

over, and over again.

12:28

If you look at the list of variables that I have,

12:31

the base URL is already set up as https://develope

12:34

r.api.autodesk.com.

12:37

This is the same base URL that's going to be there

12:40

in all the API calls, and that's why we've

12:42

made a variable out of this.

12:44

And then I've used the same variable/ authentication/ V1/

12:46

authentication.

12:49

And this is something that we've taken directly

12:51

from the documentation.

12:53

And if you put the content type in terms of application

12:57

x-www-form-urlencoded, and this goes into the header.

13:03

And as for the documentation, we wanted

13:05

to find the body structure.

13:06

We've put in the client ID and client secret.

13:09

Now, again, these are variables, so

13:10

that I don't have to use it over and over again.

13:12

I don't have to copy and paste this over and over again.

13:16

If you look at client ID, this is my client ID,

13:19

this is my client secret.

13:21

And I've just used this variable over here,

13:24

grant type remains to be client credentials

13:26

because it's supposed to be a two-legged authentication.

13:29

And the scope, once again is available.

13:33

So if we look at scope, you'd see

13:35

that we have bucket create, bucket read, bucket update

13:39

data create viewables read, user write have

13:42

got a ton of information that's given to this particular token.

13:49

And I've just hit sent to retrieve this access token.

13:52

This is the access token, which is going

13:54

to expire in 3599 seconds.

13:57

I'm going to copy this, and I'm going to go to jwt.io.

14:03

and I'm going to paste this up here.

14:07

And as I paste this, I can see a decoded version of this.

14:12

So I can actually see the list of scope that I have.

14:16

So you get to see the client ID, the scope, and the expiry time.

14:22

So this is a good way to check if your access

14:24

token has enough permissions or enough scope or not.

14:28

This is a handy decoder that you get within jwt.io.

14:33

You can see that when we generated a two-legged token,

14:36

the token doesn't have any user context.

14:38

So it doesn't really have any user context.

14:41

The application doesn't know who is the user who's

14:44

using that application.

14:45

Now, I'm going to go ahead and move on to three-legged token.

14:49

So you can switch to three-legged context,

14:54

and you can follow this documentation.

14:56

You also have a guided tutorial, as I mentioned.

14:58

Within here, you can get into three-legged token

15:01

with the implicit grant, or three-legged token

15:03

with authorization code.

15:05

I've already set that up in Postman.

15:08

I'm going to go to authentication three-legged,

15:13

and I'm going to generate a new access token, which actually

15:16

requires me to sign in.

15:18

So I'm going to sign in with my credentials.

15:21

And that's when the application recognizes me because I'm

15:26

passing on my user context.

15:29

If you remember, we did not have to do this step in two-legged

15:33

because a two-legged token doesn't really

15:36

have a user context.

15:37

However, with this three-legged authentication,

15:40

we're going to have to put in the user context as well.

15:44

And I'm going to do this authentication.

15:49

Proceed, and this is that access token, which

15:53

is a three-legged access token.

15:55

I'm going to pass this on to a three-legged token variable.

15:58

And just to test this and decode this,

16:01

I'm going to go back to jwt.io, and now, I'm

16:04

going to put this token here.

16:07

And you can see that apart from all the things

16:11

that remain same in terms of scope, in terms of client ID,

16:15

it adds user ID.

16:17

That means that it now has user context.

16:20

So this is my username, of course, in an encoded format.

16:23

But this is the user ID who's been using that application.

16:26

Because with a three-legged token,

16:28

we had to also pass on the user context.

16:31

So this is the difference between a two-legged OAuth flow

16:33

and a three legged OAuth flow.

16:35

All right, so let's head to the next section,

16:37

which is data management API.

16:39

As we've discussed before, data management API

16:41

allows us to read and write data from Autodesk cloud platforms

16:45

like BIM 360, and also on Forge buckets.

16:49

So it allows you to access your data.

16:51

Forge already handles over $3 billion API calls per month.

16:55

It is reliable and secure.

16:57

It's hosted on AWS SOC2 Certified US and EU Data

17:01

Centers.

17:02

And it supports object storage service.

17:04

And, of course, you are not just restricted to CAD file formats.

17:08

I'm going to start with this interesting example before I

17:10

deep dive into the API.

17:12

This is a web application.

17:13

It allows the user to copy data between Autodesk cloud products

17:18

like BIM 360 Team, BIM 360 Docs, and Google Drive.

17:22

All right, so as you can see on the application,

17:24

on the left-hand side, we've got folders and files

17:27

coming in from BIM 360 Team and BIM 360 Docs.

17:31

On the right-hand side, you've got

17:33

folders and files that are coming in from Google Drive.

17:36

So the user goes on the left-hand side,

17:37

and they navigate to BIM 360 Team project

17:42

and selects a folder that needs to be

17:45

transferred to Google Drive.

17:46

And on the right-hand side, they select a destination location.

17:56

This application populates the list

17:58

of files that need to be transferred,

17:59

and the user goes ahead and clicks on Start Transfer.

18:06

And it takes a bit of time, and then it transfers the content

18:09

from the source, which is BIM

18:13

path.

18:15

And the next step is to transfer things

18:17

from Google Drive to BIM 360 Docs.

18:20

So now, picking the same location, which

18:23

was the destination earlier that's

18:25

been selected as the source, and BIM 360 Docs

18:28

has been selected as the destination location.

18:35

And the user hits transfer.

18:37

And you would see in a moment, things

18:39

would start to get transferred between Google Drive

18:42

to BIM 360 Docs.

18:49

So that transfer folder has now been

18:51

copied from Google Drive to this BIM 360 Docs project

18:55

which is called Forge demo.

18:58

All right, so we've also got linked to GitHub,

19:00

so you can actually explore this application

19:03

and you can check out the APIs that are in play.

19:06

If we needed to break this example down,

19:09

there are two important components here.

19:11

First one is transfer from Autodesk to storage.

19:14

When I say storage, I mean third party storage

19:16

like Google Drive at the moment.

19:17

And these are the steps that are involved.

19:19

So log into Autodesk cloud, select files or folders

19:22

from the Autodesk side.

19:23

Select one folder on storage site and then

19:26

start transferring.

19:27

This is how the process works.

19:29

First of all, we would register a Forge application.

19:32

This is something that we've already done.

19:34

Acquire a three-legged or two-legged token.

19:36

This is again something that we've looked

19:38

at in the previous section.

19:40

Now, the main part here is locating hub, project folder,

19:44

item, and versions.

19:45

Once we are done with this, we can go ahead

19:47

and download the object.

19:48

With every process and with every step,

19:50

we've also done a hyperlink.

19:52

So when you receive this share out,

19:54

you'll be able to click on this and get to that exact tutorial.

19:58

Now, the final download happens with this URL.

20:01

You've got the URL, you got the verb, and you got the headers.

20:04

In terms of how you do it, you can use curl,

20:06

you can use Postman, or you can use the Forge SDK.

20:09

I'm going to use Postman for this example.

20:12

Before I get into Postman really,

20:13

I just wanted to show you this documentation.

20:16

So I'm on the same web page of forge.autodesk.com,

20:19

I've gone to Solutions.

20:21

I've clicked on Data Management, and I've

20:22

clicked on API References.

20:24

And then within here, you can expand onto the API reference.

20:29

You can expand onto Data Management.

20:31

And then within Hubs, and Projects, and Folders,

20:34

you can actually find those endpoints,

20:36

and the details about those endpoints.

20:39

So we can expand onto Hubs.

20:40

We can get into GET Hubs.

20:45

And with this, we're going to get those hubs

20:47

that this application is a part of.

20:50

And then we can also retrieve projects.

20:54

And then once we retrieve projects,

20:56

we can work on getting the folders.

20:58

So now, let's get into Postman.

21:02

Now, we've already generated a two-legged token.

21:04

And this is what we're going to use for the GET Hubs

21:06

and GET Project API calls, and also for GET Folders.

21:12

So what we have done here is to transfer this token

21:15

into a variable, which is called two-legged token.

21:21

So if I show you this variable, it

21:22

has the current value as does the newly generated token

21:26

that we have here that you see on the screen.

21:28

And once we have transferred that

21:30

to the two-legged token variable,

21:32

we are all set with token.

21:34

Now, we need to get to this API call, which is GET Hubs.

21:38

And this is something that I just

21:39

showed you a minute before.

21:42

This is the URL that we need to call.

21:44

This is what the header looks like,

21:46

so we just need to pass the two-legged token that we just

21:49

generated.

21:52

And I'm going to hit send now.

21:55

And in terms of response that we get,

21:57

we're able to get the Autodesk premium support hub, which

22:01

this application has access to.

22:02

So now, at this point of time, I'm going to go inside BIM 360,

22:07

and I'm just going to show you the name of that hub.

22:10

So this is exactly the hub that Forge

22:12

has been able to retrieve, Autodesk-Premium Support Hub.

22:15

And within this, we've got a project called BIM 360 Docs

22:19

Demo-- the current project BIM 360 Docs Demo.

22:22

Within that, we've got project files, we've got WIP.

22:25

And then if I navigate further into WIP,

22:27

we've got architecture.

22:30

And then we've got all these files.

22:32

For example, we've got architecture.rbd.

22:34

So let's say, I'm looking at downloading this file

22:38

programmatically.

22:40

At the moment, I have been able to go

22:42

inside this particular hub.

22:44

I've been able to capture this hub,

22:46

and I'm going to get into this particular project.

22:48

And how do I do that?

22:50

I would take this ID of this hub, which

22:52

is also called the hub ID.

22:54

We can go to GET Project.

22:56

And this API call would actually demand the hub ID.

22:59

So I've made that hub ID as a variable.

23:02

And I've used this variable here.

23:05

And then, similarly, I have passed on the two-legged token

23:08

and header.

23:09

And I would go ahead and hit send.

23:14

And since this account has a lot of projects,

23:17

it's going to take some time.

23:18

But it's going to, at the end of the day,

23:20

retrieve all the projects that are there within this account

23:22

or within this hub.

23:24

So I'm going to look for that particular project, which

23:27

is called BIM 360 Doc's Demo.

23:30

And there we have it.

23:31

And we would similarly take the ID from here.

23:36

And we can go ahead and start retrieving folders.

23:41

So we can go ahead and retrieve the top folder.

23:45

So we've got plans and project files,

23:47

which is exactly what the top folder structure looks like.

23:50

And then within that, I'm going to enter project files now.

23:56

And under project files, you can see, 01 program.

24:04

And it exactly is the same as this, because this

24:08

is what Forge is retrieving.

24:09

Programmatically, you've got program,

24:11

you've got risk, health, safety reports.

24:13

So, now, the next task for me is to get into WIB--

24:16

get into architecture, and then retrieve

24:18

this file or this model, which is called architecture.rvt.

24:23

So I'm already inside project files.

24:25

And I'm going to get into WIP, and then, I'm

24:29

going to get into architecture.

24:34

All it takes is to just copy the ID of a folder,

24:38

and then paste it up in the next API Call for getting folders.

24:44

Now, once we have reached to that particular file,

24:47

I'm already inside the architecture folder.

24:50

I can look for that file, and it's called architecture.rvt.

24:54

I have all the details of that file, the metadata that's

24:57

associated with that file.

24:59

We've got the ID, and this ID is really useful

25:02

when we download this file.

25:04

We can optionally even go to versions.

25:07

We can look at different versions

25:08

of this file on BIM 360 Docs.

25:10

And then, finally, we can go ahead and download the file

25:15

from BIM 360.

25:17

So this time, instead of hitting send, I'm going to do a send

25:21

and download because I want this file to be downloaded.

25:29

And this is a large Revit model, so it's

25:30

going to take some time.

25:31

But finally, it's going to show me

25:34

this, which is the dialogue to save the file.

25:37

Now, this file is ready to be downloaded.

25:39

I can go ahead and save the file now.

25:41

And I was able to programmatically download

25:43

a file from BIM 360 Docs.

25:45

And that's a part of that application

25:47

that I just showed the video of.

25:50

At this point of time, we can also

25:51

connect this with a third party application like Google Drive

25:54

or OneDrive, again, subject to what the API allows.

25:59

And now, the second part is transfer from external storage

26:02

to Autodesk, which is basically transferring from a third party

26:06

external storage like Google Drive or OneDrive to Autodesk

26:10

or which may be BIM 360 Docs or BIM 360 Team.

26:14

This is what the steps would look like.

26:16

Register Forge application.

26:18

Acquired a Three-Legged or two-legged token.

26:21

Again, something which we've done.

26:23

Locate hub project, and then create a storage location,

26:27

and then upload project, and create

26:28

the first version of that file.

26:30

So these would be the steps, and this

26:33

would be the file you add into uploader file.

26:35

The verb would be PUT.

26:37

This is how you define the headers,

26:39

the content of the file would go inside the body.

26:41

And once again, just like how we did the previous exercise

26:44

in Postman, this can be done in Postman.

26:46

This can be done in curl.

26:48

This can be done in Forge SDK.

26:50

So I would definitely urge and encourage you to try this out.

26:54

There are also other automation ideas that's there

26:56

on the screen at the moment.

26:57

And the slide can build online workflows and experiences

27:00

around your design data.

27:01

You can create an attachment.

27:03

Attach an Excel spreadsheet to a DWG file.

27:05

And create an app-anaged bucket and upload

27:08

a file, which is basically a pre-requisite to view your data

27:11

and Forge viewer.

27:12

You can publish a cloud workshared Revit model

27:14

to Next Gen BIM 360 Docs.

27:17

You can also publish later synchronized cloud

27:19

worksheet Revit models to BIM 360 Docs.

27:22

You can also delete and restore files in BIM 360 Docs.

27:25

Now, in terms of tools that you need,

27:27

you can go ahead with an oasis manager.

27:30

These are all hyperlink.

27:31

You can connect your data, create buckets and more.

27:34

You can also download the Forge Visual Studio code extension,

27:38

which helps you connect to your data,

27:40

create buckets, view and more.

27:42

And finally, these are things that you should know about,

27:44

pagination, retention policy, and rate limiting.

27:47

And we have done a hyperlink to each of these items.

27:51

Now with that, I'm going to go into the final section, which

27:54

is BIM 360 API.

27:56

Now, before we start to use BIM 360 API,

27:59

a custom integration needs to be done.

28:01

And how do you do it?

28:02

You need to be an account admin to be able to do that.

28:05

If you're not an account admin, you

28:07

must contact your account admin to do that.

28:09

You need to go into your BIN 360 account admin.

28:12

If you have access to more than one account,

28:14

then select that particular account

28:16

that you need to integrate that Forge application with.

28:19

Go to Settings, and select the Custom Integration tab.

28:22

Click on Add custom Integration.

28:24

And then here, you can select what level of access

28:27

you want to provide to your Forge application.

28:29

Whether it is just BIN 360 account

28:31

admin, or document management, or both.

28:34

Now, if you are the developer, go ahead and select,

28:36

I'm the developer.

28:37

Once you hit Next, there'll be a dialog

28:39

which allows you to put in your Forge client ID and your app

28:43

name.

28:43

So make sure that you put in the correct client ID

28:45

that you've copied from the Forge portal.

28:48

And you also put in the correct app name.

28:50

And once you do that, your application

28:53

gets integrated with your BIM 360 account.

28:56

Now just a word of caution, depending

28:58

on the level of permission that you've provided from an account

29:01

admin perspective.

29:02

Your application would have access to your hub,

29:06

and all the projects within it.

29:08

So make sure that you are distributing that carefully.

29:11

Now, before I deep dive into BIM 360 APIs,

29:14

I'm going to get into this example.

29:16

We've also got a link to GET Hub.

29:18

I'm going to show you a live demonstration of this.

29:20

And this is called an issues editor.

29:23

All right.

29:24

So this is what the interface looks like.

29:26

It allows me to log in with my Autodesk account.

29:29

And this is a custom Forge application,

29:31

which basically pulls the issues information from BIM 360 Docs.

29:37

And you can see that this is a hub that I'm a part of.

29:39

So it shows Autodesk premium support hub.

29:42

I'm able to get into the projects within this hub.

29:48

And I'm able to select any project

29:50

that I want to see issues of.

29:52

So I'm going to get into Doc's Demo, View Issues,

29:58

and then it provides capabilities

29:60

that BIM 360 Docs doesn't have at the moment.

30:02

For example, it allows me to export and download

30:06

these issues.

30:07

It also allows us to import issues, export

30:10

and email issues.

30:11

These are things that are not there

30:12

out of the box in BIM 360 Docs.

30:14

But since BIM 360 is based on top of Forge,

30:17

you can pretty much build these capabilities

30:20

even before Autodesk builds them because you

30:22

are exposed to the APIs that BIM 360 users in the background.

30:25

And this application is a perfect example of doing that.

30:28

So it basically pulls all the BIM 360 issues

30:31

within this project, and allows you to export and import those

30:35

using a spreadsheet.

30:37

And you can bulk edit things.

30:38

For example, if I wanted to add something over here,

30:41

add a description, maybe change the ownership to somebody else,

30:46

and go ahead and click on Update Issues.

30:50

It has successfully updated the issues that I made changes in.

30:54

Now, with that, I'm going to go further and show you

30:57

some supported operations that BIM 360 APIs could do.

31:00

So you can play around with account admin

31:02

API, document management API, Issues API, Checklists API,

31:06

Model Coordination API, data connector API, RFIs, locations,

31:11

relationships, assets API, and cost managing API.

31:15

There are also other APIs like activities, which are

31:19

in [? beta ?] at the moment.

31:20

So when I expand onto account admin API,

31:22

these are some of the supported operations

31:24

that you can programmatically achieve using Forge.

31:26

You can create a new project.

31:28

You can get, add or modify account members.

31:30

You can create or modify a new company.

31:33

You can get, add, or modify project numbers.

31:35

You can also activate a service.

31:37

And you can create or redefine business units.

31:40

Now, let's look at a live demonstration here.

31:43

Now, if we had to add a new project

31:45

member programmatically, these are the steps that we would do.

31:48

So in terms of BIM

31:51

we would do a BIM 360 custom integration.

31:53

That's something that we've already

31:55

done and already looked at.

31:56

We'd be generating a two legged token.

31:59

And this is also something that we've already looked at.

32:02

The next step for us is to get account and the account ID,

32:05

and the project ID that we are looking at,

32:07

adding the new member too.

32:09

In terms of inputs, we need the company

32:11

that the user is assigned to.

32:13

Go for the project, the industry, roles assigned

32:15

to the user for the project, and the user's email address,

32:19

and whether or not they are an admin.

32:21

All right, so we're going to start with a two-legged token.

32:24

And then we're going to get into getting account and project ID.

32:28

This is already something that we've looked at.

32:30

We would get to that particular account,

32:32

get to that particular project.

32:33

And then, we would get the account ID and the project ID.

32:36

And once these steps are done, we

32:38

can use this URL to add the user.

32:41

The verb should be POST.

32:43

URI parameters should be account ID and the project ID.

32:46

This is something that we are already getting

32:47

from the previous steps.

32:49

And this is what the body should look like.

32:51

I'm going to show you a live demonstration.

32:53

Before I do that, I'm just going to get into the documentation,

32:57

just to make sure you are aware on where

32:59

to find the documentation from.

32:60

So you can actually go to the Forge web portal.

33:03

Go to solutions, click on BIM 360,

33:08

and then get into API reference.

33:14

Expand onto API reference, go to Account admin, project users,

33:22

and POST project_id/users/import.

33:25

And if you read through the description,

33:27

it says, adds user to a project.

33:29

You can add up to

33:31

So we are going to look at adding two

33:33

users at this point of time.

33:38

You can take in the details from here

33:40

in terms of the URL that's going to be

33:42

in use, the headers detail, the URI parameters.

33:46

And this is what the body structure in terms of request

33:49

should look like.

33:50

It should have the email, user ID services, company ID,

33:53

and industry role.

33:55

You can also find a sample request and a sample response.

33:59

I'm going to get into my BIM 360 Docs

34:02

here, just to show you the project admin part.

34:05

And then this is where I need to add the two members.

34:12

At this point of time, I have five members.

34:16

In this particular project, I'm going to programmatically add

34:19

two members to this list.

34:20

I'm going to switch back to Postman.

34:24

And I'm going to open this collection.

34:26

This is actually going to use a three-legged token.

34:34

So I'm going to make sure that I have a three-legged token

34:37

generated already.

34:39

And then once that is done, I'm going to use this token,

34:43

maybe copy this into a variable so that I can use it next time

34:47

in this particular API call.

34:51

I'm going to get into POST Users import.

34:54

So I'm just going to make sure that this particular project

34:57

ID is the same as the project that we are targeting.

35:01

For example, in this case, it's supposed

35:03

to be BIM 360 Docs Demo.

35:05

So I'm just going to make sure this is the ID that's in use.

35:08

I'm going to go back to POST Users import.

35:13

And it's actually the same.

35:17

And then, this is the information of the users

35:19

that I'm going to add.

35:20

And I haven't really assigned them a company or a role,

35:24

but I've given them and admin access in terms

35:27

of document management, and also project administration.

35:30

I'm going to hit send now.

35:35

And you can see, the 0 failure and 2 success,

35:38

that means that it has added both

35:40

these users to the project.

35:42

And I could have added

35:45

So I'm going to go back to BIM 360 Docs,

35:47

and I'm going to hit Refresh, just to make sure

35:50

that these users that I have just added have come in,

35:53

and that's correct.

35:55

All right, I'm going to get back to the presentation.

35:58

Now that we've looked at this live demonstration,

35:60

we can do similar operations using document management API.

36:03

We can export PDF files from BIM 360 document management

36:07

from the plan area.

36:08

We can also upload files to BIM 360 document management,

36:11

and we can also download files from BIM 360 document

36:14

management.

36:15

Using the Issues API in line with the live demonstration

36:18

that we just showed you, you can retrieve information

36:20

about all attachments associated with a specific issue.

36:23

You can retrieve issues, you can retrieve

36:25

issue custom attributes, map to an issue type.

36:27

You can also update issues.

36:30

You can also attach BIM 360 document management files

36:32

to issues, and add a comment to an issue.

36:36

And with checklists API, you can get template, and also

36:39

get instances of those templates and a lot more.

36:43

So in the list of operations that support it with the BIM

36:49

using the data connector API.

36:50

You can use the cost management API to get budgets.

36:54

You can retrieve location.

36:55

You can post RFI.

36:56

And you can get assets, and you can do a lot more.

36:59

If you want to get a list of operations

37:00

that you want to programmatically

37:02

achieve, using Forge, you can click on this web page.

37:05

It'll take you to the list of supported operations using

37:08

BIM 360 API.

37:10

It takes me here, where I can actually

37:13

get to see all these operations that's supported from a BIM 360

37:17

perspective.

37:18

So you can get into account admin,

37:19

you can get into issues, assets, checklists, cost management,

37:22

data connector, document management, locations,

37:25

Model Coordination, relationships, RFIs.

37:27

And as I said, there's a lot more

37:29

that's still a work in progress, and it's going to be out soon.

37:33

With that, I'd like to wrap up the session.

37:35

Thank you once again for your time.

37:37

I hope this was useful.

37:38

Take good care of yourselves.

37:40

Stay safe and healthy.

37:41

Have a great rest of your day, Bye.

Was this information helpful?