Connect to Forge Using Postman

00:02

MICHAEL KILKELLY: In this lesson,

00:04

you're going to learn how to connect to Forge using software

00:07

called Postman.

00:09

Here we are in the space planning for new health

00:14

guidelines learning path.

00:16

And this is the second lesson in our workflow.

00:21

In this lesson, we're going to learn how to connect to Forge.

00:25

Now there are many different ways we can connect to Forge.

00:28

We can do it through a website.

00:29

We could do it through a Revit add-in

00:32

or we could use a standalone or third party application.

00:36

But today, we're going to look at using

00:38

a standalone application called Postman.

00:41

It's available as a free download.

00:43

And Postman is really interesting

00:45

because you can send and receive data

00:47

to and from REST APIs like Forge.

00:50

Makes it really easy to make those connections

00:53

to web applications.

00:56

So here I am at the postman.com website.

01:00

And if I go to the download section,

01:03

I can click on this link here to download

01:06

a Windows version of Postman.

01:09

So I'm going to click on that link.

01:11

And then I see the installer right down here.

01:14

Just double click the installer to install the software.

01:17

Postman allows you to make calls to websites like Forge using

01:22

GET, PUT, or POST methods.

01:26

And we provide data in the header, in the body,

01:29

or through URL parameters.

01:33

And we get the results back in JSON format,

01:36

which is a standard format for data transfer.

01:39

And it's very easy to use it and requires

01:42

not a lot of programming or programming knowledge.

01:46

Now one of the benefits to Postman,

01:48

too, is that you can use pre-configured collections.

01:51

So collections contain these series of POST, GET, PUT calls

01:57

or tasks.

01:58

And I've provided a collection that's

02:01

we're going to use to step through all the tasks

02:03

to connect to Forge.

02:05

You can import this directly into Postman.

02:08

Now you can also use pre-configured environments

02:11

in Postman.

02:12

And these are lists of variables that you

02:14

use when making these POST, GET, or PUT calls.

02:18

Now some of these variables will need to be entered manually,

02:21

but this they are structured in the environment.

02:24

So it's very easy to see where to input that data.

02:27

Now I've also provided an environment specifically

02:30

for this course, and I'm going to show you how to import that

02:34

into Postman as well.

02:37

Now here I am inside of Postman.

02:40

And I want to click on the Collections tab

02:43

here in the left-hand side of the screen.

02:46

Once I click on Collections I want

02:48

to click on the Import button.

02:50

So we're going to import our collection of tasks.

02:54

So in the import window, I'm going to click the Upload Files

02:58

button, and you want to select the Forge Building

03:01

Performance.postman collection.json file

03:06

that you downloaded as part of the sample

03:08

files for this course.

03:12

So once I click on that and load the file,

03:15

I can see my collection right here called

03:18

Forge Building Performance.

03:20

So I'm going to click the Import button,

03:23

and then I see that collection here on the left-hand side.

03:29

Now my next step what I want to do

03:31

is I want to import the environment.

03:33

And again, the environment contains all the variables

03:35

that we're going to use when we're

03:37

making our connection to Forge.

03:39

So I'm going to click on the Manage Environments button

03:41

here in the upper right-hand corner.

03:44

And in this dialogue, I'm going to click on the Import button.

03:49

And then I'm going to click Choose Files

03:51

and select the Forge Building Performance.postman

03:55

environment.json file.

04:00

And now I can see the Forge Building Performance

04:04

environment here.

04:06

And then I just click the Import button to bring it in

04:10

and loaded into my Postman.

04:13

If I open up that environment, I can see

04:15

this whole series of variables.

04:18

And again, a lot of these are pre-configured.

04:20

A couple of these will have to add because they're

04:22

going to be unique to you.

04:23

But we're going to use these variables

04:25

throughout all of our Postman collection tasks.

04:29

Now just scroll down to the bottom of this dialog box

04:32

and I click the Update button.

04:34

And now I'm back in my main Postman dialog box.

04:39

Now in the upper right-hand corner,

04:41

this is where I'm going to choose

04:42

what the active environment is.

04:44

So I click this Dropdown, right now it says, no environment.

04:48

And then I'm going to click on the Forge Building Performance

04:51

environment, the one that we just imported.

04:54

So now that's my current environment,

04:56

and that's where Postman is going to look for variables.

05:02

Now in the left-hand side, I'm going to click down

05:05

this arrow in my collection.

05:07

Now I can see all of the steps in this collection.

05:10

And each step contains a series of tasks

05:13

that I'm going to use to connect to Forge.

05:18

So our first step is we're going to obtain an access token.

05:23

Now the access token is used to link any requests

05:27

that I'm making through Postman to my Forge account.

05:30

And if you remember Forge uses credits,

05:32

so Forge needs to know who is making that request,

05:35

so that they can charge and use the right amount of credits.

05:39

Now in order to make and get this access token,

05:42

we're going to use your Forge client ID and your client

05:45

secret.

05:46

And we'll enter these into our building performance

05:50

environment.

05:51

So let me show you how to do that.

05:53

So first, I'm going to click on the Step 1 folder here,

05:58

and I click that down.

05:59

And I see this first task one get access token.

06:03

So I click on that task, and now I'm inside the task.

06:08

And I can see here, this is a post operation.

06:11

So we're going to post this all the data

06:13

here to a particular URL.

06:16

Now the first part of that URL you'll see in double curly

06:19

brackets is called base URL.

06:21

And when you see text that's orange

06:24

and in those double curly brackets,

06:26

that means it's referring to an environment variable.

06:30

Now I'm going to click on this body tab here.

06:33

And then inside the body, I can see two more variables

06:36

are being called.

06:37

I see client ID and client secret.

06:40

So if I click on Manage Environments

06:43

in the upper right-hand corner, and I open up my environments

06:47

and then choose the Forge Building Performance

06:50

environment, I can see all of the variables.

06:54

So the two variables that are being referred to by this task

06:57

are the client ID and the client secret.

07:00

Now if you recall, we actually generated these variables

07:05

when we first set up our app on the Forge website.

07:08

So let me switch over to the Forge website

07:12

and I'm already logged in, so I'm just

07:14

going to click on My Profile picture in the upper right.

07:17

And I'm going to choose the My Apps option.

07:21

So I only have one app set up right now, which

07:24

again is the building performance app

07:25

that I created previously.

07:27

So I click on My App, and in the app page,

07:31

I can see my client ID and my client secret right here.

07:35

So this is the information that I need to provide to Postman.

07:39

So first I'm going to copy my client ID

07:43

and I'm going to copy it to the clipboard.

07:45

I'm going to switch back to Postman,

07:48

and then going to paste that client ID into this field

07:52

here under initial value.

07:54

I'm going to switch back to the Forge site for my app,

07:58

and I'm going to click on this little eyeball

08:01

next to the client secret.

08:02

And that's going to show me my client secret.

08:05

And your client secret is like a password.

08:08

So I'm going to copy that client secret.

08:11

I'm going to go back into Postman,

08:13

and I'm going to paste that data in the client secret field

08:18

right here.

08:19

Now once I've done that, the next thing I want to do

08:21

is just click this Reset All button.

08:23

And what that's going to do is it's

08:25

going to take those initial values

08:26

and it's going to paste them into the current value column

08:29

here.

08:31

And I can scroll down to the bottom of this dialogue,

08:34

and then I just click the Update button.

08:38

And then I can just close out of managed environments

08:41

and now I'm back into Postman.

08:43

So I've defined the client ID and the client secret.

08:46

Now all I need to do is I click the Send button.

08:49

So that's going to send that request out to Forge,

08:53

and then I'm going to get this information back here.

08:55

You can see down at the bottom.

08:57

This is the return screen.

08:59

So this is what I'm getting back from Forge.

09:02

And the most important thing I'm getting here

09:03

is this access token.

09:06

So that's a really long string of letters and numbers.

09:10

I don't have to write that down.

09:11

I don't have to remember it.

09:12

If I go into the manage environments again,

09:15

I can see that this task automatically

09:18

copied that response into the API token variable.

09:23

So I don't have to remember this,

09:25

Postman is going to remember it for me.

09:28

All right, our next step is we're

09:30

going to create a nickname.

09:32

So a nickname is an easy way to reference the Forge app.

09:35

And again, this is going to be saved as a variable.

09:39

So I'm going to click on step two in my collection

09:43

and then click the Task to create nickname.

09:47

And this is pretty straightforward,

09:48

all I'm going to do is I'm going to send a patch

09:51

request to the Forge apps website,

09:54

and I'm just going to define the nickname.

09:58

So I go to manage environments, and I

09:60

can see I have a variable here called nickname.

10:02

And I'm going to give this app a nickname of performance app.

10:07

So now I can refer to it in that shorthand

10:10

rather than having to use a whole long client

10:14

ID, client secret, so forth.

10:16

So I click on the Send button and then I get my response

10:20

down here, and it's just indicates

10:22

a number one meaning that the response was-- the send

10:25

was successful.

10:28

So our next step is we're going to upload the app bundle.

10:32

Now the app bundle is basically the collection

10:35

of files that make up the Revit add-in.

10:37

So this is what we're going to run on the Forge platform.

10:41

Then the app bundle is packaged together as a zip file,

10:44

and it contains DLL files.

10:46

It contains all of the setup and configuration

10:49

that Forge needs to run the code that's going

10:52

to extract the parameter data.

10:54

So there is an app bundle that's provided with this course.

10:58

And again, the add-in is going to extract parameter data

11:01

from wall, window, and roof instances in a model.

11:05

And it's going to output the element ID, the unique ID,

11:08

the category, family name, type name, and area.

11:12

It's going to output that data to a CSV file.

11:14

We're going to take that data and then

11:16

we're going to visualize it using Power BI.

11:19

But that all comes from this collection of files that

11:21

are known as the app bundle.

11:25

So there's three tasks in this step.

11:27

First, we're going to register the app bundle,

11:30

then we're going to upload it.

11:31

We're going to upload that zip file,

11:33

and then we're going to create an alias for it.

11:36

So let's switch into Postman.

11:38

And under step 3, I'm going to click on Task 3.A,

11:41

register the app bundle.

11:44

So in the body tab, I can see here

11:47

that by registering the app bundle,

11:49

I'm giving it an ID call performance app.

11:52

I'm specifying the engine, which is Revit 2020,

11:55

and I just give it a brief description.

11:58

Now if I click on the Tests tab, I

12:00

can see that these are a whole series of variables

12:04

that are going to get set based on the response to this task.

12:08

So when I send this task, it's going

12:10

to set all of these variables after that.

12:12

And I'm going to use these variables

12:14

in the next steps or the next tasks,

12:18

as I upload the app bundle.

12:20

So I'm going to go ahead and I'm going to click Send.

12:22

And this is the data I'm getting back.

12:24

And again, these are being set in these temporary variables.

12:29

So I've registered the app bundle,

12:31

now I'm going to click on Task 3.B

12:33

I'm going to upload the app bundle.

12:35

So in the body tab, I'm going to click on this Select files

12:40

button.

12:42

And I'm going to browse to my course files,

12:44

and I'm going to choose the PerformanceApp.zip.

12:47

And again, this zip file contains

12:49

all of the setup and DLLs and all the things

12:53

I need to run the app on Forge.

12:55

So I click that file, and then I'm

12:58

going to go up to the Send button.

13:01

And I'm going to send that file up to Forge.

13:03

And again, I just get a response of one

13:05

indicating that it was successful.

13:08

So lastly, I'm going to create an alias for this app bundle.

13:11

So I click on the Alias tab.

13:15

And you can see here that all I'm doing in the body section

13:19

is I'm defining a version, and I'm giving it an ID.

13:23

So that is the alias.

13:24

So click Send.

13:26

And down here, it's telling me the version is one,

13:28

and here's my idea, just parrots that back to me.

13:32

OK, so now we've uploaded the app,

13:34

and now we're ready to publish an activity.

13:37

Now, an activity is an action that's

13:39

going to be executed in Forge.

13:41

So it references the app bundle, but it also

13:44

specifies input parameters.

13:46

So in our case, there's a input file, an RVT file,

13:50

and then there's an output file, the CSV file.

13:53

So we're going to upload a Revit file

13:56

and we're going to get back a CSV file.

13:59

So we're going to create the activity

14:00

and then we'll create an alias for it as well.

14:04

So now in step 4, I'm going to click on the 4.A

14:07

Create a New Activity Task.

14:10

And in the body section, I can see all this information

14:13

that I'm going to provide.

14:14

I'm going to provide the parameters, which

14:17

are in our RVT file.

14:19

And as well as a results file, I'm

14:21

going to give those files names and descriptions as well.

14:25

So go ahead and if I click on the Test tab,

14:28

I can see what is going to return back

14:30

and what we're going to set is this performance activity

14:33

version variable.

14:36

So go ahead and I click on Send.

14:38

And this is the return I'm getting from Forge.

14:42

And it's just telling me the command line

14:45

path and the parameters that I've set.

14:48

Now I can go ahead in step

14:52

to this activity.

14:53

And again, like I did for the app bundle,

14:56

I'm just going to provide an ID and a version.

15:00

So I can click Send, and then here it is version one ID test.

15:08

All right, for our fifth step, what we're going to do

15:10

is prepare cloud storage, so we want

15:12

to make a space on the cloud for our input

15:16

and for our results file.

15:18

Now I can use any cloud storage service with Forge.

15:21

I could use Dropbox.

15:22

I could use Google Drive.

15:24

In this case, though, we're going to use Forge's own object

15:27

storage service.

15:28

So we're going to keep everything

15:29

on the Forge platform.

15:31

Now the first thing we need to do

15:33

is we need to create what's called a bucket,

15:35

and that's our file storage location.

15:38

Buckets must have unique names and you

15:41

can't use capital letters.

15:43

Then once we've created the bucket,

15:45

we're going to upload the input file.

15:48

And then we're going to get temporary URLs

15:51

to that import file, as well as to our results file.

15:55

So let's go ahead switch over to Postman and do that.

15:59

So the first task

16:02

I'm going to specify a bucket key or a bucket name.

16:06

And I'm going to just click on my manage environments

16:10

icon here.

16:11

And in the Forge Building Performance environment,

16:14

I can see I have a variable called OSS bucket key.

16:18

So this is where I specify the name of my bucket.

16:21

And if you run into issues on this step,

16:24

you might get an error, and it could

16:26

be that bucket name is already in use.

16:28

So if that happens, just change from 9999 to 9998 or 7.

16:35

Try some different combinations of bucket key names

16:39

to get one that works.

16:40

And again, once you enter the value

16:42

into the initial value, so just click

16:45

that Reset All button to copy that over to the current value.

16:51

So now I've defined that bucket key.

16:53

I'm going to click on the Send button.

16:56

And here's my return results at the bottom.

16:59

So it's just telling me the actual bucket

17:01

key, who the owner is when it was created and so forth.

17:05

So next, I've created the bucket now,

17:07

I can upload the input file on task 5.B

17:11

So I'm going to click on the Body tab.

17:14

And now because of this type of operation,

17:18

I'm going to just click the Select File button.

17:20

I'm going to browse to the files I've downloaded for the course.

17:24

And there's a sample file here called Medical Center 2020.

17:27

So I'm going to select that RVT file, and then I'm just going

17:32

to go ahead and click Send.

17:34

So it may take a few moments depending

17:36

on the size of the file, but this operation I'm uploading it

17:40

to the cloud storage to my bucket.

17:43

So again, it's a big file.

17:45

It may take a minute or so to upload it.

17:48

But once it's complete, I'm going

17:49

to get this response telling me the object key, the object

17:53

ID, the size, and so forth.

17:55

So this is telling me that upload was complete.

17:59

So now I'm going to just get temporary URLs to the input

18:02

file into our results file.

18:04

And again, these are URLs that will link to that bucket.

18:08

So to get the URL to the input file,

18:12

I'm going to use this task

18:16

in the parameters tab, there is a variable called

18:20

OSS file input file object key.

18:24

So I'm going to go and click on Manage Environments.

18:27

And if I go in here, I can see that value, the value

18:30

of that variable right here.

18:31

So it's called testfile.rvt.

18:33

And that's the name of the file that Revit

18:37

is going to refer to on the Forge platform.

18:42

So I go ahead and click Send, and here is the URL.

18:46

So if I want to download that file, I can just click

18:50

or I can copy and paste that URL and it will

18:52

download that file directly.

18:54

So the same thing goes for the temporary URL

18:57

to the results file.

18:59

So I have another variable here that refers to the object key.

19:03

If I go into manage environments,

19:05

I can see that that object is referring to a file called

19:10

resultsfile.csv.

19:11

So this is the results file that I'm

19:13

going to download once Forge has run through this operation.

19:19

So I can go ahead and click Send.

19:21

And I get the signed URL back here.

19:24

Again, this is the URL I can use to download the results.

19:29

So our last step, we're going to submit a work orders.

19:32

We've uploaded our app bundle.

19:35

We've published our activity.

19:36

We've uploaded our files, so now we're

19:38

ready to actually do the work.

19:41

And the work item actually just executes

19:45

the activity defines the job, the work item runs the job.

19:49

It does the work.

19:50

So we're going to take the parameters that

19:52

were defined in the activity, and they're

19:54

going to become the arguments in the work item.

19:57

So there's two tasks to this step first we're

19:60

going to create a work item, and then we're going

20:03

to check the status of it.

20:04

So the work item once we create it, it sort of begins the job

20:08

and then we can check back to see if it's complete.

20:12

So I'm going to click on this task say, creative work item.

20:16

And in the body tab, I can see here I'm defining the activity

20:21

ID that I've already created.

20:23

I have the URLs for the input file,

20:26

as well as for the output file.

20:29

And I just go ahead and I click Send, simple as that.

20:32

And I get back immediately that it is in process.

20:36

So the status is pending it's doing the work.

20:40

I can go to my next task 6.B and I can check the status of it.

20:44

So if I go ahead and I just click the Send button,

20:48

I can see that right now my status is in progress.

20:50

So it is processing.

20:52

It's not ready yet.

20:53

But you may want to come back in a minute

20:55

or so, I click Send again.

20:57

And now it tells me that it was successful.

20:60

So that work item has completed processing.

21:03

I can click on this Report URL to get a summary of everything

21:06

that happened, or I can just go back to our task

21:13

So I'm going to go ahead and do that.

21:15

I'm going to copy that URL.

21:18

I'm going to switch over to my browser.

21:20

I'm going to paste the URL into the browser.

21:23

I hit Return, and then I see that it automatically

21:27

downloads my results file.

21:29

So I can double click on that results file, and here

21:32

is my spreadsheet.

21:34

So here are a collection of parameters from the model.

21:37

I have the element ID, the unique ID, the category,

21:40

the family name, family type, and area.

21:42

So I've uploaded the file to Forge, Forge has processed.

21:45

It's run it the add-in and it's return

21:48

me back this spreadsheet of data.