Cloud and Mobile

Forge Data Management API: [Upload, Download, Manage] your Design Data on the Autodesk Cloud

By Philippe Leefsma (@F3lipek)

    My previous Forge-focused blog last week was dealing with the OAuth authentication workflow, in case you missed it here it is:

Landing your Forge OAuth authentication workflow

    If you practiced it a bit, authenticating through the Autodesk OAuth server should now be a breeze for you ;) ... This time we can start having some real fun because we are going to use the actual Forge API's !

    Most likely, the first thing you may want to do is to upload your own models to the Autodesk Cloud, in order to load them at a later time into the viewer or extract some metadata. If for some reason you've got no design data at all, keep reading we've got you covered with a bunch of free sample models ...

I - OSS: Autodesk Object Storage Service

    Let's get started with the easiest part, OSS API. What we now call the Forge Data Management API (see official documentation here) is actually a set of two distinct API's which may be used independently based on what you need to do. If you used the View & Data API in the past, chances are you're probably already familiar with OSS.

    It is a rather basic file storage REST API that lets you host securely any data on the Autodesk Cloud. Typically that's an App-context API, which means you need a 2-legged OAuth token to use it. But for some workflows that we are going to cover in section II of this article, you may use a 3-legged token. The way OSS API works is pretty straightforward:

1. Obtain a valid OAuth token in order to perform authorized REST API calls
2. Create a bucket: a logical storage unit like a folder
3. Upload any file to the bucket (a file is called an object)
4. Download your objects if needed 

    Now here are the tricks: a bucket is created with a specific policy, this defines how long the files are being kept on that bucket.  For info:

• transient: your file remains 24h on the bucket
• temporary: 1month
• persistent: until you decide to delete them 

The bucket itself is never deleted, I just need to emphasis on it because this has been a common misunderstanding in the past! 

    The bucket name has to be lower case, with no special characters and has to be unique service-wide, across ALL the users of the service, not just you. So if you first try the API and attempt to create a bucket named "bucket1" ... unfortunately there are chances that some other developer already owns that name (you will get a 409 - conflict error in such case). So you can either come up with really fancy names or append some guid-like prefix/suffix to your bucket names in order to avoid collisions.

    The object keys can be anything - no special characters though - but need to be unique on a per-bucket basis, otherwise uploading an object with a name that already exists on the same bucket will simply override the resource.

    There also has been often requested how many buckets you can create, how many objects a bucket can contain, how large can be each object... there are no theoretical bounds to the API, sky's the limit. We could advise you create just three buckets (1 transient, 1 temporary and 1persistent) but that's really up to you. If you plan to create multiple buckets based on some workflow, just think about how your logic will scale: creating one bucket per user may not scale nicely once you get a large customer base... 

    If you used the OSS API version1, here are the enhancements for the v2:

• You can now delete an object on a bucket
• Deleting a bucket is doable but NOT for everybody, because that's a dangerous operation, we decided to whitelist users who can do that.
• You can iterate the list of buckets you created from your set of API keys
• Similarly you can iterate the objects stored in each bucket
• You can create signed resources, but I will tackle that in another post (can't get all the fun at once!)

    Below is the implementation of my server-side node service that wraps the OSS API calls. It's pretty straightforward and doesn't do anything fancy. At the time of the writing, I didn't implemented yet the resumable upload that allows you to upload large files by multiple chucks. The reason is that we are working on auto-generated API wrappers for our REST APIs, so I'm waiting for that to be ready. Once the wrapper is available, I simply replace the request calls by the wrapper methods inside the service. The impact on the rest of my server code will be inexistent.

    Using that, the REST API exposed by my server for its client application is just a thin Express wrapper around the service methods. For example below is the "GET /buckets" implementation. For full implementation, take a look there: oss endpoint 

 1 var router = express.Router()
 2 
 3 /////////////////////////////////////////////////////////////////////////////
 4 // GET /buckets
 5 //
 6 //
 7 /////////////////////////////////////////////////////////////////////////////
 8 router.get('/buckets', async (req, res) =>{
 9 
10   try {
11 
12     // obtain forge service
13     var forgeSvc = ServiceManager.getService(
14       'ForgeSvc')
15 
16     // request 2legged token
17     var token = await forgeSvc.getToken('2legged')
18 
19     // obtain oss service
20     var ossSvc = ServiceManager.getService('OssSvc')
21 
22     // get list of bucket by passing valid token
23     var response = await ossSvc.getBuckets(
24       token.access_token)
25 
26     // send json-formatted response
27     res.json(response)
28 
29   } catch (ex) {
30     
31     res.status(ex.statusCode || 500)
32     res.json(ex)
33   }
34 })

You can refer to this page for the official documentation to see how to create a bucket and upload a file to it.

II - A360 Data Management API

    The second set of endpoints within the DataManagement API provides a programmatic access to A360, the Autodesk Cloud at https://a360.autodesk.com. That's a 3-legged OAuth API that let's your application access and manage files of a user once it has been authorized through a web interface. 

    If you don't have an A360 account yet, you will need to signup for one in order to test the API with your data. A set of basic design files will be provisioned automatically to your account upon first sign in.

    The underlying file storage system is based on the OSS API described above but A360 adds an extra layer of features on top of it, such as sharing your data with other users, versioning your files, attaching metadata to it, and many more features to come... It is therefore more complex to use than OSS.

Your data is organized as follow inside A360:

• Hubs: the highest logical data storage on A360. Each user has it's own hub by default but you ca n create additional team hubs and share that with other users
• Projects: under each hub, you have projects, which can be seen as root folders containing your data
• Folders: A logical sub-folder inside a project or another folder
• Items: a file that you uploaded to a project or folder
• Versions: each item may contain one or multiple versions of the file. You can then select programmatically which version you want to access, download or load in the viewer

In order to upload a file to an A360 user account, you have to follow several steps:

1. Your web application needs to obtain a valid 3-legged token by requesting user approval
2. Determine projectId and folderId which identify where on A360 you want to upload the data
3. Create a storage location: basically the API will determine the underlying OSS bucketKey and objectKey you have to use to upload the file
4. Upload the data using OSS API
5. If the file doesn't exist create a new item, otherwise create a new version and add it to the corresponding item

Here is how the implementation of that workflow looks like in my service:

 1 /////////////////////////////////////////////////////////////////
 2 // Upload file to create new item or new version
 3 //
 4 /////////////////////////////////////////////////////////////////
 5 upload (token, projectId, folderId, file, displayName = null) {
 6 
 7   return new Promise(async(resolve, reject) => {
 8 
 9     try {
10 
11       var filename = file.originalname
12 
13       var storage = await this.createStorage(
14         token, projectId, folderId, filename)
15 
16       var ossSvc = ServiceManager.getService('OssSvc')
17 
18       var objectId = ossSvc.parseObjectId(storage.id)
19 
20       var object = await ossSvc.putObject(
21         token,
22         objectId.bucketKey,
23         objectId.objectKey,
24         file)
25 
26       // look for items with the same displayName
27       var items = await this.findItemsWithAttributes(
28         token,
29         projectId,
30         folderId, {
31           displayName: filename
32         })
33 
34       if(items.length > 0) {
35 
36         var item = items[0]
37 
38         var version = await this.createVersion(
39           token,
40           projectId,
41           item.id,
42           storage.id,
43           filename)
44 
45         var response = {
46           version,
47           storage,
48           object,
49           item
50         }
51 
52         resolve(response)
53 
54       } else {
55 
56         var item = await this.createItem(
57           token,
58           projectId,
59           folderId,
60           storage.id,
61           filename,
62           displayName)
63 
64         var response = {
65           storage,
66           object,
67           item
68         }
69 
70         resolve(response)
71       }
72 
73     } catch (ex) {
74 
75       reject(ex)
76     }
77   })
78 }

    The complete implementation is available there: DM Service

    In order to download a file, you first need to determine the available versions and select the version you want, then obtain the OSS objectId of that version and download the file using OSS API.

    Here is how an item versions response may look like, the OSS objectId we are interested is available in relationships.storage.data.id (Line #66). The bucketKey to use would be "wip.dm.prod" and the objectKey "3d249b40-b15d-46a2-b684-001d4534129f.dwfx" 

III - Implementing the UI

    Implementing a good web UI that interacts with your server in order to let your users upload, download and visualize their data is not straightforward at all. I spent a large portion of the development time working on the following control panel that displays the list of all the hubs/projects/folders/items for the signed-in user, the OSS buckets & objects linked to my app account and also lets the user download or upload files either by drag and drop or file picking. Each item in the treeview has also a context menu that provides some actions based on the type of the item. If the item is a design data supported by the viewer, you can double click on it to import it into the viewer.

    I used the following libraries to achieve this control:

• DropzoneJS on the client side  + Multer npm package for node. The setup is very easy and they offer flexible options for customization. For having tried multiple other libraries, I highly recommend this combination!

• The treeview is the one provided by the viewer API: Autodesk.Viewing.UI.Tree and Autodesk.Viewing.UI.TreeDelegate objects. It's a pretty interesting component because it allows to load the data associated with each hub/folder/item asynchronously so you can see the tree will populate progressively but you can start interacting with it directly. You don't have to wait for a huge payload of all your items to initialize the whole tree or load the subfolder only once the user expands them. It would deserve a blogpost on its own to explain all the tricks you can achieve with that control ... You can find the implementation of the tree in Viewing.Extension.Storage.Panel.js

• The TabManager that lets you switch between hubs is a complete custom control. You can find it's implementation in here.

• You can reorder the Tabs by simple drag and drop, this feature is using the dragula library, a must!

• Complete code for that panel is packed into a viewer extension: Viewing.Extension.Storage

    That's it for today! The DataManagemt API official documentation is available here, the complete source code of my ongoing project is there and the live sample runs pretentiously at https://forge.autodesk.io ;) Feel free to try it today with your own A360 account!

    In a next post I will described the work I did with the Model Derivative API which lets you access metadata and properties of your model, convert design data into viewables that can be loaded into the viewer, or export the geometry to different CAD formats.

Landing your Forge OAuth authentication workflow

By Philippe Leefsma (@F3lipek)

    Now that our Forge APIs are available it's time to play with them! But after the initial euphoria is behind, you should think about implementing secure applications in order to protect your resources but also the ones of customers logging to your web application. This starts by getting your OAuth authentication workflow right.

    Before we start I need to mention that I'm far from being a security expert, the information exposed in that blog post is purely extracted from my own experience and the advice I could collect when writing my samples, this should be considered in no way as a recommended approach but rather a suggestion. With that being said, let's get started!

    Our web APIs are using OAuth as authentication mechanism, nothing really fancy here. There are two types of OAuth authentication contexts:

• 2-legged: also called "app-context" where your application (a server, desktop or mobile app) directly request an access token from the Autodesk server and can invoke the APIs with no user intervention. This is the case for the OSS API. Your app can for example create a bucket and start uploading some design there

• 3-legged: also called "user-context" where your app will request explicitly through a web interface (could be a WebView on a mobile or desktop app) a set of permissions from a user in order to access and potentially manipulate his data

    Based on the kind of features you want to provide, you may want one or the other, or both, potentially mixing each approaches. There are however some subtleties in the way you have to request tokens and especially expose that to your client application.

I  2-Legged Token

    Let's start with 2-legged because it's more straightforward: here your app has access to clientId and clientSecret credentials - requested through our dev portal - which have to remain protected on your server or secured within the App - understand some kind of encryption and/or some custom obfuscation. You can share the clientId but may the clientSecret be compromised, another developer would have full access to your data. In such a case you can regenerate a secret on our API portal. Your app will use those credentials to issue a valid token, you also have to pass the scope which can be a single value or a space-separated, url-encoded string in case you request multiple scopes, eg data:read data:write (see my method requestToken in the sample below). Once a token is acquired, you may use it on your server to access the API or expose your own API endpoints for your client app, so a user will be able for example to upload his file to a bucket. In that case it's important that this data:write token remains hidden on your server because otherwise you expose the possibility to a bad intentioned user to mess up with all your data.

    If you want to let a user load his model in the viewer on a web page, you need to expose an endpoint that returns a data:read token, so in that case you can request a new token with only data:read scope and expose that as an endpoint, in the case of my sample this is /api/forge/token/2legged 

    A 2-legged token expires after a certain time - expires_in field of the response - you can either keep refreshing the token and always keep a valid token on your server, or request a fresh token for each new operation. Alternatively implement a retry mechanism that will request a token only if the current one is expired at at the time of the call - if you get an 'Unauthorized' error basically. All approaches are valid and depend on the kind of feature you are providing and how often your app is going to require tokens I would say.

II  3-legged Token

    3-legged is a bit more tricky because here issuing a valid token depends on user authentication so at some point you need to prompt the user for his Autodesk credentials in conjunction of the API keys that you have stored on the server. You also need to specify scopes and this will explicitly be shown to user on the login page so he knows the extends of the permissions granted to your app. 

 

    A 3-legged token also has an expiry period, but unlike the 2-legged workflow where you can simply request a new token, in 3-legged you would need to request user credentials again to issue a brand new token. For that reason each token response contains a refresh_token field that is a code you can use with a specific endpoint to request a new valid 3-legged token without user interaction. For that reason it is very important that you keep that refresh code securely on your server and do not share it with the users or expose it in any way to the outside. 

    Similarly to a 2-legged token, in case you want to use the viewer to load user models, you need to expose an endpoint that would let you client application obtain a data:read token, without exposing a full-privilege token. You do not want to ask a user to log twice in order to obtain a second read-only token, so in that case you need to use the refresh_token field of the initial response in order to request what we can call a "downgraded token" that's a token that is requested from the refresh code but with a reduced set of scopes. The reduced scopes can only be a subset of the initial token scopes. The downgraded token response will also contain a new refresh_token code, you need to carefully store that because each refresh code can only be used once. You need to use that refresh code also to refresh the full-privilege token.

    Below is the implementation of my Forge sample relevant to OAuth workflow and tokens management. I am splitting the code into the implementation of the endpoints and a utility called ForgeSvc (Forge Service) which allows some decoupling and flexibility in case the service has to be used by other endpoints or other services within the App. I find the approach pretty convenient even if it requires more files and more code than direct implementation in the endpoints. It definitely scales better once the codebase grows and the app becomes more complex.

Here is the OAuth workflow and secure forge token endpoints: 

    And here is the implementation of the Forge Service which keeps tracks of 3-legged and 2-legged tokens. It worth mentioning that it is NOT a good idea or secure approach to store tokens into the session properties (in your node.js code for example: req.session.token = 'xxxxxxx') because this can be hacked easily. At the moment my service is using a simple in-memory storage which can be replaced by a more sophisticated persistence mechanism later on without breaking the endpoints:

    The complete source code of that sample is available there but keep in mind that, like our Forge API's, it is a work in progress... A live sample is available at https://forge.autodesk.io

Finally for more info and step-by-step tutorials on Forge OAuth, please refer to the official documentation.

View and Data API Tips: Hide elements in viewer completely

By Daniel Du

With View and Data API, you can hide some elements in viewer by calling “viewer.hide(dbIds)”, when the elements are hided, it actually make it transparent with a shallow mark to it, or make it ghosted. It is a nice feature as user probably need to know the existence of these elements even they are hided.  But you may want to hide elements completely instead of ghosting some times. Here are a code snippet you can use if you want to hide some elements totally.

    Autodesk.Viewing.Viewer3D.prototype.turnOff = function(dbIds){

        var node ;

        if (Array.isArray(dbIds)) {
            for (var i = 0; i < dbIds.length; i++) {
                var id = dbIds[i];

                node = viewer.model.getData().instanceTree.dbIdToNode[id];
                //hide the node completedly
                viewer.impl.visibilityManager.setNodeOff(node, true);

            }
            
        }
        else
        {
            node = viewer.model.getData().instanceTree.dbIdToNode[dbIds];
            //hide the node completedly
            viewer.impl.visibilityManager.setNodeOff(node, true);
         
        }
      
    };

    Autodesk.Viewing.Viewer3D.prototype.turnOn = function(dbIds) {

        var node ;

       if (Array.isArray(dbIds)) {
            for (var i = 0; i < dbIds.length; i++) {
                var id = dbIds[i];

                node = viewer.model.getData(). instanceTree.dbIdToNode[id];
                //show the node
                viewer.impl.visibilityManager.setNodeOff(node, false);
            }
            
        }
        else
        {
            node = viewer.model.getData(). instanceTree.dbIdToNode[dbIds];
            //show the node
            viewer.impl.visibilityManager.setNodeOff(node, false);

        }

    };

 

The usage is very simple, just call “viewer.turnOff(arrayOfDbIds)” or “viewer.turnOf(arrayOfDbIds)”. Hope it helps.

Automated browser testing with Node.js + Selenium

By Philippe Leefsma

SeleniumHQ is a free set of tools and APIs that allow you to simulate user actions in a browser, locate html elements such as buttons, inputs, send clicks and so on... This is what our development team is using, among other tools, to automate tests with the viewer.

I gave a quick shot at it and it looks promising: Selenium API can be invoked with no less than seven programming languages! Java, C#, Python, Ruby, PHP, Perl, JavaScript (node.js).

I'm a big Node.js addict, so I tested again Node. The steps involved to set it up on your machine are very easy:

1/ Download the Selenium server from their download section

2/ The version at the time of this writing (2.48.2) requires Java SDK7 to be installed, so you may need to update your Java setup

3/ Run the Selenium server: Java -jar path-to-selenium-srv.jar

4/ Write your test and run it based on the framework you selected. If you are using Node, an npm package is available: selenium-webdriver

I created a basic test which already does a bit of work:

- It will start a web browser using the url of my gallery at http://gallery.autodesk.io.  My test supports firefox and chrome (an additional chromedriver package is required for chrome and the setup is slightly different).

- It will then wait for the model buttons to appear and will open a specific one: Engine

- Once the model is loaded, it will open the extension manager dialog and successively toggle each extension On and OFF. Some extensions are displaying an alert dialog, so a specific handling in that case is needed

That's it. Obviously each extension would require to write a specific test in order to be tested properly and some maybe tricky, but this is already a decent start. I'm also attempting to access the browser console output but I couldn't get it to work properly so far... Work in progress.

Here is the full node.js script of my selenium test:

TypeScript Sample for View & Data API

By Philippe Leefsma

It's been a while I wanted to play with TypeScript as the technology seems to get a descent traction from the web development community. So here it is! You can check it out on the following github repository: TypeView

It's live version can be tested here. Don't expect anything crazy yet, it's simply loading a predefined model.

Big thanks to Jan Liska, my colleague from Autodesk Consulting, who put together the initial version of that sample. The View & Data client side API is rather big already so Jan created the type definition file only for the few methods that were needed in that specific sample. Hopefully over the time we will make that file bigger adding some more declarations to it. You could also use it as a boiler plate if you decide to start a Node.js + View & Data project or simply experiment on TypeScript as I did.

I am using WebStorm for my web projects which has some level of TypeScript support. However I find the file watcher approach not really flexible, without saying that it won't help you if you are not using WebStorm obviously. So I added to the project a gulp file that will automatically handle the transpiling of .ts files. All you have to do to build the project is a "npm install" followed by "gulp" commands. The gulp task also generates the sourcemaps, so it looks better in my WebStorm IDE: it will automatically gather generated files .js and .js.map files under the .ts so it reduces the mess:

After running command npm install for the required node modules, running gulp or gulp ts-build should automatically build the project, ready to run through your IDE or using start server.js from the app directory. Run ts-clean to remove all typescript generated files (.js and .js.map):

Become a Java EE developer - Part III: : RESTful API with Jersey

By Philippe Leefsma

Here is the third part of my Java EE series and this week it's time to tackle how to create a REST API using a proper framework. There are many existing Java frameworks that would help you achieve that, some of the most popular are Spark, RESTEasy, RESTX or Jersey. As I have no experience with any of them and no specific constraint, I picked up Jersey which seems to have a good API, descent support from the community and it's an implementation of the JAX-RS reference. So let's get started!

If you missed the two previous chapters, here are the links as I'm reusing the same project rather than starting one from scratch: 

Become a Java EE developer - Part I: Tomcat setup and my first servlet

Become a Java EE developer - Part II: Basic RESTful API from a servlet

The first thing I'm going to do is to convert my project to a Maven project (obviously a prerequisite is to have Maven installed): Right-click your Eclipse project > Configure > Convert to Maven Project

This will generate a pom.xml file at the project root. Just copy all the Jersey dependencies (<dependencies> section) similarly to my pom.xml:

Then Right-click your Eclipse project > Maven > Update Project ... This should download locally all the Jersey dependencies defined in the pom.xml, sweet! ...

Make also sure those dependencies are part of the deployment package:

Right-click project > Properties > Java Build Path > Order and Export > Check Maven Dependencies

Then still from Properties > Deployment Assembly > Java Build Path Entries > Maven Dependencies

My Deployment package looks as follow:

Next we need to define a Servlet mapping, this is done by editing the web.xml. If you created a dynamic web project with module version 3.0, there are chances you don't have a web.xml, so Right-click project > Java EE Tools > Generate Deployment Descriptor Stub

From there we define a url mapping that will be redirected to the Jersey server and also a provider package: in my case all the classes part of "com.autodesk.adn.viewanddata.api" package will be considered as resource for the Jersey server.

The last step is the implementation of the API itself and if you take a look at Part II, you will notice that it is significantly more straightforward when using Jersey as it handles parsing of the url and parameters nicely:

You can then run your project from Eclipse which should launch the Tomcat server and let you test the API using a Rest client as described in Part II.

The implementation still relies on a clunky hashmap, so next time I will take a look at how to use a mongoDB connector so it will fetch the records from a real database... stay tuned!

Related articles

Become a Java EE developer - Part II: Basic RESTful API from a servlet

Become a Java EE developer - Part I: Tomcat setup and my first servlet

By Philippe Leefsma

Being a complete newbie when it comes to web development in Java, I decided to take a step forward and build some expertise around JEE servers and web services. Another motivation is that we have some web technology coming up at Autodesk - more about that when it will turn public - that can be leveraged by, among other things, Java web services, so it makes sense to become a bit more familiar with it. 

I'm starting this series of posts where I will report my progresses as I learn along the path. To get started, let's take a look at running a local Tomcat server and deploy our first Java servlet.

Prerequisites:

- Java EE SDK  

- Eclipse IDE for Java EE developers

- Apache Tomcat 7

Let's start with installing the Tomcat server. I'm assuming you are running a Linux based system. I found that this blog post was very straightforward and easy to follow, so I'm simply going to copy the detailed steps, you should be able to install Tomcat on your system without pain:

1. Download a binary distribution of the core module: apache-tomcat-7.0.47.tar.gz from here. I picked the tar.gz in Binary Distributions / Core section.
2. Unarchiving the archive will create a folder structure in your Downloads folder:
   ~/Downloads/apache-tomcat-7.0.47
3. Open to Terminal app to move the unarchived distribution to /usr/local
   sudo mkdir -p /usr/local
sudo mv ~/Downloads/apache-tomcat-7.0.47 /usr/local
4. To make it easy to replace this release with future releases, we are going to create a symbolic link that we are going to use when referring to Tomcat (after removing the old link, you might have from installing a previous version):
   sudo rm -f /Library/Tomcat
sudo ln -s /usr/local/apache-tomcat-7.0.47 /Library/Tomcat

5. Change ownership of the /Library/Tomcat folder hierarchy:
   sudo chown -R <your_username> /Library/Tomcat
6. Make all scripts executable:
   sudo chmod +x /Library/Tomcat/bin/*.sh

Here is a tutorial that looks descent for Windows users.

Issue a /Library/Tomcat/bin/startup.sh from a terminal to start the server and open the following url in your browser: http://localhost:8080

You should see the Tomcat homepage:

If you try to take a look at the "Server Status" or "Manager App", it will prompt you for login and password: by default Tomcat is installed without user, so you need to create at least one to administrate your server.

Go to the "conf" folder inside Tomcat install, if you followed the tutorial "/Library/Tomcat/conf" and open "tomcat-users.xml", then add the following user, for example:  

1 <tomcat-users>
2 <rolerolename="manager-gui"/>
3 <rolerolename="manager-script"/>
4 <rolerolename="manager-jmx"/>
5 <rolerolename="manager-status"/>
6 <userusername="your-admin-name"7 password="your-admin-pass"8 roles="manager-gui,manager-script,manager-jmx,manager-status"/>
9 </tomcat-users>

You should now be able to log with the defined credentials:

Let's now shutdown the server as it will be started automatically by Eclipse when we debug our project: /Library/Tomcat/bin/shutdown.sh

Open your Eclipse IDE, if you didn't install the Java EE version of Eclipse, no worries, you can just install the required packages later on. Go to "Help" > "Install New Software..." > set the "Work with" to your Eclipse release and select the "Web, XML, Java EE, ..." category:

Make sure you have the following packages installed:

 

Let's create our first servlet: "File" > "New Project" > "Dynamic Web Project"

Then click "New Runtime" and select the appropriate server version, fill up the "Tomcat installation directory" and create the project.

Once created, right-click on the project root in the explorer > "New" > "Servlet" > put some name for your servlet and the package, I'm naming it "HelloServlet" and edit the code as follow:

package com.autodesk.adn.viewanddata;

import java.io.PrintWriter;
import java.io.IOException;
import javax.servlet.ServletException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

/**
 * Servlet implementation class viewer
 */
@WebServlet("/hello")
public class HelloServlet extends HttpServlet {
    private static final long serialVersionUID = 1L;

    /**
     * @see HttpServlet#HttpServlet()
     */
    public HelloServlet() {
        super();
        // TODO Auto-generated constructor stub
    }

    /**
     * @see HttpServlet#doGet(
     * HttpServletRequest request,
     * HttpServletResponse response)
     */
    protected void doGet(
            HttpServletRequest request,
            HttpServletResponse response)
        throws ServletException, IOException {

          response.setContentType("text/html");

          PrintWriter out = response.getWriter();
          out.println("<h1>" + "ADN Servlet running!" + "</h1>"); 
    }

    /**
     * @see HttpServlet#doPost(
     * HttpServletRequest request,
     * HttpServletResponse response)
     */
    protected void doPost(
            HttpServletRequest request,
            HttpServletResponse response)
        throws ServletException, IOException {
        // TODO Auto-generated method stub
    }
}

Code Formatted by ToGoTutor

Once you are done, right-click the servlet in the project explorer > "Run As" > "Run on server" > open the page in a browser "http://localhost:8080/{project}/{servlet}" by replacing with the naming you used.

Using the View and Data API in your Ruby on Rails app

By Pratham Makhni Alag 

If you're planning to use the View and Data API to incorporate a 3D viewer in your Ruby on Rails app, there is a fully functional Ruby gem out, called adn_viewer. You can use it for authentication, bucket creation, uploading files and even registering your uploaded model for translation and subsequent viewing. 

The source code and documentation may be found on adn_viewer.

This gem is installed in a Ruby script or Ruby or Rails app simply by adding the gem and its gem dependencies, namely curb, curb-fu, json and gon to the gemfile and installing the bundle. 

The following functions are provided as of now: 

1. Getting an access token (required for any call to the server):

Adn_Viewer.token(key, secret)

2. Creating a bucket (required to store a model):

Adn_Viewer.create_bucket(token, name, policy)

3. Getting bucket details:

Adn_Viewer.check_bucket(token, name)

4. Getting a list of formats supported by the viewer (for pre-validification of uploaded files):

Adn_Viewer.supported_formats(token)

5. Uploading a file (replace name with name of bucket you want to upload the file to):

Adn_Viewer.upload_file(token, name, filename, filepath)

6. Register your uploaded file for translation:

Adn_Viewer.register(token, urn)

The success responses on these calls are parsed, in usable JSON format and similar to the ones on the Quickstart Tutorial.

Also, the gem documentation contains a few notes on correct formatting, as required with a few commands such as to extract the key after calling the upload_file function. 

This gem requires Ruby >= 2.0.0 and a key and secret generated from developer.autodesk.com! Finally, the current stable version of adn_viewer is 1.0.0.

 

 

Additionally, two sample apps that utilize the View and Data api are provided. 

The adn_viewer_gem_test_app is a simple app that uses all the functions of the gem. It contains a tutorial on creating an RoR app with viewer incorporated: adn_viewer_gem_test_app

The sample-ruby-on-rails-app-prototyping is a more advanced app that doesn't use the gem, but shows what you can do with the API in RoR: sample-ruby-on-rails-app-prototyping 

The app for the same is setup on viewanddata.herokuapp.com

 

RESTful website architecture with Node and Angular

By Daniel Du

As a web programmer starting from the traditional ASP/ASP.net, sometimes my mind was constricted to the old days. My understanding of web application was how asp.net works, the HTML is generated at server side, and send it to browser to render. One guy asked me how to display some data which retrieved from server during a hackathon, while I am just in the middle of something, my distinctive response is to ask him to do something like <%= something%>, like ASP/ASP.NET does. But nowadays, it has been changed a lot, we have very different architecture – RESTful, which separates the server side and client side completely, and it also makes it easy for the server to serve different clients, including browsers and mobile devices.

Here is an architecture graph I “steal” from strongloop. As you can see, with RESTful architecture, the web server exposes some REST APIs, the client communicates with the server with REST call. This make it very flexible, the client can be a browser as a common website, it also can be mobile device like iPhone/iPad or Android phone or pad. For the browser, you can user different libraries or frameworks to build your UI, you can use JQuery, Angular.Js or anything else you like.

Let’s make a simplest sample to demo the idea, a web server with Node.Js + Express, and a browser client with Angular.Js. The idea is to make a todo list. Firstly I will create a simplest web server with Node.Js and Express. The express CLI make it really easy. If you do not have express installed, install it first with help of google. And then create a simplest express web application with express generator:

mkdir simpleWebApp

cd simpleWebApp

npm install

This will create a simplest web application with node.js and express, if you run “npm start” and go to “http://localhost:3000” you will see the first welcome page of express.

Now let’s do some simple work to add a REST API:

GET /todos   - Get all todo items

Before that, we will add some test data in JSON, in practice, you will get these todo items from a database like MongoDb. For simplicity, we make it a JSON file named as “todoItems.json”

[ 
      {    
          "task": "buy milk", 
        "complete":false 
    }, 
    { 
        "task": "toast bread", 
        "complete":false 
    }, 
    { 
        "task": "pick up newspaper", 
        "complete":false 
    }, 
    { 
        "task": "water flowers", 
        "complete":false 
    }

]

Then go to /routes/index.js, add a new route, response all todo items in json:

var express = require('express');
var router = express.Router();

/* GET home page. */
router.get('/', function(req, res) {
  res.render('index', { title: 'Express' });
});


var sampleToDoItems = require('../todoTasks.json');

/* GET Todo listing. */
//GET /Todos/
router.get('/todos', function(req, res) {

  res.type('application/json');
  res.status(200);

  res.json(sampleToDoItems);
});

module.exports = router;

Now, the REST API is ready, if I start the web application, and go to postman with GET http://localhost:3000/todos, or go to the url in browser directly, I will get all todo items:

 

The server side is done, next we will do the client side. We will use Angular.JS. Actually the client does not have to be in the same project of web server, but for simplicity, I put it together. The express has already setup the structure, the /public folder contains the static contents. I create a webpage named as “index.html” in it, and then I edit “route/index.js” file to change the route so that when I go to “http://localhost:3000/” it goes to my index.html page:

/* GET home page. */
router.get('/', function(req, res) {
  //res.render('index', { title: 'Express' });
  res.redirect('/index.html');
});

 

Let’s do the angular part, in “index.html” to include the angular js library, and create our angular module and controller. It is very simple one, so I put them into a single JS file. The idea is just to send a GET request to the web server and get all todo items, the import part is to inject the $http into the controller:

var app = angular.module('myTodoApp',[]);

app.controller('myTodoCtrl', function($scope, $http){

    $http.get('/todos')
        .success(function(response){
     
            $scope.todoItems = response;
        });
 
});

And then go to the “index.html” page, I put the important port in bold so that it is easy to follow. Firstly we need an “ng-app”, otherwise angular.Js will not run. And then put the “ng-controller” to the table, and build the table with ng-repeat="todo in todoItems", please note that the “todoItems” is populated in controller by http get request, they are completed in client side already:

     $scope.todoItems = response;

The the databind can be done by “ng-bind” or “{{  something  }}”.  Here is the complete code:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8">
        <meta http-equiv="X-UA-Compatible" content="IE=edge">
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <title>Title Page</title>

        <!-- Bootstrap CSS -->
        <link href="//netdna.bootstrapcdn.com/bootstrap/3.2.0/css/bootstrap.min.css" rel="stylesheet">

        <!-- HTML5 Shim and Respond.js IE8 support of HTML5 elements and media queries -->
        <!-- WARNING: Respond.js doesn't work if you view the page via file:// -->
        <!--[if lt IE 9]>
            <script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
            <script src="https://oss.maxcdn.com/libs/respond.js/1.4.2/respond.min.js"></script>
        <![endif]-->
    </head>
    <body>
        <h1 class="text-center">Hello World</h1>

        <div class="container" ng-app="myTodoApp">
            <table class="table table-striped table-hover" ng-controller="myTodoCtrl">
                <thead>
                    <tr>
                        <th></th>
                    </tr>
                </thead>
                <tbody>
                    <tr ng-repeat="todo in todoItems">
                        <td>{{todo.task}}</td>
                        <td><div class="checkbox">
                            <label>
                                <input type="checkbox" value="" ng-model="todo.complete">
                            </label>
                        </div></td>
                    </tr>
                </tbody>
            </table>

        </div>

        <!-- jQuery -->
        <script src="//code.jquery.com/jquery.js"></script>
        <!-- Bootstrap JavaScript -->
        <script src="//netdna.bootstrapcdn.com/bootstrap/3.2.0/js/bootstrap.min.js"></script>

        <script src="//www.runoob.com/try/angularjs/1.2.5/angular.min.js"></script>

        <script src="/javascripts/myTodoApp.js"></script>
    </body>
</html>

And this is how it looks like when running the app:

 

OK, that’s the idea, very simple, of cause in practical, if will be more complex, and you can user various frameworks, like mean.io, cleverstack, sail.js.

Deploy Node.Js viewer sample to Heroku

By Daniel Du

I have been evaluating different cloud enviroment to host our viewer samples, in this post I will share my experience with Heroku, which is a Platform as a Service(PaaS) provider. The advantage of PaaS like Heroku is simplicity, we do not need to care about the infrastructure underneath, and we do not need to care about the load balance, scaling .etc. On the contrary, it gives us limited control with the infrastructure, and it only provides pre-defined hosting environments. Just in case something bad happened on the stack which our application is running, we have nothing to do it, what we can do is waiting for Heroku to fix it. Nevertheless, it is a good solution for a quick deployment and verification, and it is good enough for a simple sample application like what I did.

I am using the workflow-node.js-view.and.data.api sample which is a forked repo and I did some minor changes.

Develop and test on local machine

For view and Data API, we need a consumer key and secret key pair to do the authentication, protecting your data from being peeked by unauthorized hackers. We do not want to expose our secret keys to public right? We need to keep the keys on server side. And I am not comfortable to save the keys in source code, as I am pushing the source code to public repo of github all the time, sometime I may push the keys to public accidentally and it is not easy to clear the history, so I would prefer to set the keys at run time. In node.js, I can use process.env.variablename and pass the values to it when running the node server.

router.get('/token', function (req, res) {
    var params = {
        client_id:  process.env.ClientId , 
        client_secret:  process.env.ClientSecret, 
        grant_type: 'client_credentials'
    }

    request.post(
        process.env.BaseUrl + '/authentication/v1/authenticate',
        { form: params },

        function (error, response, body) {
            if (!error && response.statusCode == 200) {
                res.send(body);
            }
        });
});

For local testing, I can pass the parameters like "key1=value1 key2=value2 node server.js" when starting the node server. Of cause it is too long to input it all them time when running, so I put it into a shell script, name it as run.sh. It can be bat file for windows.

ClientId=replace_with_your_consumer_key \
ClientSecret=replace_with_your_secret_key \
BaseUrl=https://developer.api.autodesk.com \
node server.js

On Mac/Linux, I need to make it execuable by :

chmod +x run.sh

When I test my node server at local side, I can simplily run the script:

./run.sh

With that I can working on my node.js viewer sample and test it on my local machine.

Deploy to heroku

With that, I am OK to deploy my web site to Heroku. As we said, heroku is pretty easy to use to host a website, and it provides up to 5 free apps.

Firstly, sign up on heroku.com for a free account, and then download and install the Heroku Toolbelt , you can learn more about the Heroku Command Line Interface if you want to know detailed instruction of the usage.

Next, log in to your Heroku account and follow the prompts to create a new SSH public key.

$ heroku login
Enter your Heroku credentials.
Email: <your heroku account here>
Password (typing will be hidden): 
Authentication successful.

Create a new Heroku app through command line, it will create an app with random name if you do not give one in command line, it also add a git remote to Heroku so that you can deploy your code by git push.

$ heroku create
Creating quiet-shore-6917... done, stack is cedar-14
https://quiet-shore-6917.herokuapp.com/ | https://git.heroku.com/quiet-shore-6917.git
Git remote heroku added

Deploy your website to Heroku using Git once your are ready. Heroku will detect your app and setup the corresponding hosting environment, and then host it for you.

git push heroku master

Similarly, Heroku lets you externalise configuration - storing data such as encryption keys or external resource addresses in config vars. At runtime, config vars are exposed as environment variables to the application. Heroku will automatically setup the environment based on the contents of the .env file in your local directory, so you can create a .env with the key pair:

ClientId=replace_with_your_consumer_key 
ClientSecret=replace_with_your_secret_key 
BaseUrl=https://developer.api.autodesk.com 

Or set the config vars manualy by command:

heroku config:set ClientId=replace_with_your_consumer_key 
heroku config:set ClientSecret=replace_with_your_secret_key 
heroku config:set BaseUrl=https://developer.api.autodesk.com 

Ensure that at least one instance of the app is running(do this only once):

$ heroku ps:scale web=1

Once the deployment is done, you can open the website by following command line, it launches your website in your default web browser. You can note down the URL if you'd like to switch to another browser. "heroku open" uses HTTPS by default, you need to use HTTP instead for now due to some known issue of viewer, for example, browse to http://quiet-shore-6917.heroku.com instead of https://quiet-shore-6917.heroku.com

heroku open

If everything works fine, your website is hosted on cloud now. You can keep working on the project on your local machine, making some changes, testing on local machine and commit when the test is passed, and deploy your changes again to heroku by git push.

git push heroku master

Ok, seems easy and simple, right?