00:02
MICHAEL KILKELLY: In this lesson,
00:04
you're going to learn how to connect to Forge using software
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: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: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: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:46
And we'll enter these into our building performance
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: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: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: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: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: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: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: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: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: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.
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: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: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: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: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: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.
AutoCAD
AutoCAD LT
Fusion
AutoCAD Revit LT Suite
Architecture, Engineering & Construction Collection
Revit
Civil 3D
BIM Collaborate Pro
Product Design & Manufacturing Collection
Maya
Inventor
Navisworks
3DS Max
Flow Production Tracking
Revit LT
Forma
Recap Pro
Alias Concept
Maya Creative
Flame
Arnold
Mudbox
Flow Capture
Media & Entertainment Collection
