As you probably know, Box.com released a new API last december. And as you also probably know, we’re old fans of everything Box (you might remember prior posts about how to move Salesforce files into Box and how to move your Facebook pics to Box). That’s why when we heard about this new API we couldn’t wait to start playing with it, so that now we proudly announce the new Box Connector v2.0!
This new V2 connector features 100% API coverage including new features such us:
- OAuth 2 authentication
- Improved support for handling files, folders, collaborations, sharing and comments
- New search functionality
- Enhanced user management functionality
- Enhanced collaboration functionality
- Events long polling, you can now have the Box platform to notify you of new events at Box
- Many more things you can check out at this link!
So, as usual in our posts, let’s show it with an example app. I think we’ve wrote enough about handling files at Box, so let’s focus on a different kind of use case leveraging what in my humble opinion is one of the greatest features added to this new API: the events long polling. In case you’re not familiar with long polling, it is a technique in which you subscribe to a notification list by making an http request. The special thing about this is that in case that there’re no new notifications for you, the connection is maintained until it times out and then replaced with a new one. The end result is that you no longer need to be constantly polling the endpoint asking “Do you have any packages for me?”. Instead, you can now follow the Hollywood principle (don’t call us, we’ll call you) and Box will send you a message whenever it has something to tell you, which results in simpler code and more efficient resource usage. If you want to get more information on long polling there’s plenty of resources available on the internet. However, for the sake of this example you don’t need to worry about the internals of it since the connector handles all of that for you.
The Tracking Brochure
So suppose that you’re in the business of selling stuff and you email your top clients about your new hot offerings. This email can include a link saying “for more information, download our brochure”. Since you’re an avid user of Box, you can have this brochure be hosted at it. Let’s now build a very simple mule application that lets you know which of your clients (who are also avid Box users) have seen or downloaded your brochure.
So first, let’s install the connector in Studio. Head to the Help menu and click on install new software. Then select the Mule Cloud Connectors update site:
Then select the Box cloud connector. This will install the connector or update it if you had a prior version installed:
Welcome to OAuth
The first step is to get authenticated into Box. One of the greatest additions to this connector is that the old Box authentication mechanism has been replaced with old standard OAuth2, which as you know is a first class citizen in Mule connectors world. So, setup a new project and throw an http connector into it. Double click to access its properties editor and set its path to “auth”:
Next, go to the palette and drop a Box connector next to the Http one. The end flow should look as follows:
Now let’s configure the Box connector! Double click on it and create a new config. Make it look as follows:
Press ok, and then select the Authorize operation on the connector:
That’s it, you have set the authorization flow. However the question you should be asking yourself is “which values should I use for client id and client secret?”. Good questions, details on how to register your app at Box and get your secrets can be found at this page.
Please Call Me!
ATTENTION: Before continuing, we recommend to take a sneak peak at how events work at Box by reading the events section on this link.
We said earlier that the beauty of long polling (and other kinds of streaming) is that you can get notified of when events happen. So, go to the palette, grab the Box connector and drop it into the canvas creating a new flow. The result should be a new flow in which Box is the message source. Double click on it, select the config you created before and use the Listen Events operation:
So each time there’s a new event in your account, the flow above will get a new message. Something important to notice is that the message will not carry the generated events, it will just carry the notification of new events being ready for you to consume.
Something we don’t want to happen is the same events coming over and over again. This is when stream positions come handy. You probably read it at Box doc, but a stream position is a marker that points to the last read event. So each time you want to read events, you can use the stream position as an offset that skips already received ones. Therefore, it’s important then to be able to remember which is the next stream position to be read. We’ll use object stores to remember the last used stream position. In case this is the first time we get an event, we need to setup a default value which we do by setting up a flow variable. Head to the palette again and drop a variable component. Then configure it as follows:
After, drop an object store component and create a new configuration that looks like this:
As you can see, for the sake of the example we’re using an “in memory” object store implementation. For real apps, you need to set up a persistent one.
Following, configure the object store to read from the key “streamPosition” using the default value we previously set:
By now we now that there’re new events and we have a stream position. So, let’s go for it! Drop another Box component and select the Get Events operation like this:
Woohoo! We have the events! Along with the events, the response object contains the next stream position we need to use next time. So let’s save that in the object store before continuing. Drop another Object Store component and set it like this:
Now it’s time to take a close look at the events we just got. There’s all sorts of stuff in here. Not just the info we want, so we need to filter it and we all know that Groovy is our friend when it comes to filtering collections. So, drop a Groovy transformer and let’s first ditch the events that are not about an item being downloaded or previewed:
And now let’s add another Groovy transformer but now filtering for objects of type file that happen to be on the root folder (the root folder restriction is an arbitrary one set just for the sake of the example)
And that’s it! You have just got the events using long polling! In a real life scenario, now you probably want to do something valuable with these such as integrating with your CRM application or something like that. In order to keep this example as generic as possible while still showing you how to extract valuable information out of the events, let’s just see how we can log this information. Go to the scopes section on the palette and drop a for-each scope. Inside of it, put a Logger component that setup like this:
The above logger should log the selected events each time the long polling endpoint is fired up.
Some things to keep in mind:
- Remember to first execute the authorization flow before trying this
- If the user that previewed the file was not logged into box, then you’ll get a null Box user. Not cool, but hey! This is just an example!.
So wrapping up, the final flow looks like this:
So that’s it! I hope this quick example gets your mind full with ideas of how to leverage the capabilities of the new Box connector. If you want to take a closer look, this sample application is available on the demo folder of the connector source code which you can checkout on the connector’s GitHub page.
As always, please do let us know your comments and questions.
PS: Just as a bonus, in the demo code at GitHub you’ll find an additional flow which show’s you how to use the also new search operation. Enjoy!