Box Integrations Lessons Learned
After implementing box integrations by using Box service accounts and also having used developer tokens to build solutions around Box, we want to share some lessons learned.
Try to avoid the Box developer token
The Box developer token is an quick and easy way to have a valid authentication token to use the REST api.
The developer token can be generated in the configuration page of a service account and expires after 1 hour- a good security setting.
Additionally you could carefully read the description of the developer token- the developer token has the scope your normal user account and is not connected to the service account!!
We can proof that by using the tool postman with the developer token and invoking the /users/me endpoint and get the current managed user information.
In the end, using the developer token with the user scope and the full integration with the service scope can bring some confusion during development.
Example: Trash
Each user has its own trash- so deleting a file with the developer token does not mean that the service account sees the document in the trash and otherwise too. Trashed files can only be seen by the user who has deleted the document and the owner of the previous folder location.
Example: Webhooks
We had to learn that each user has its own webhook configurations. An admin user can create webhooks which cannot be seen by other users like our service account.
This was a big surprise for us, but brings more flexbility into the integrations. The box documentation says that you cannot create a webhook for one folder/file more than once, but you can set multiple webhook configurations on the same folder or file with different users!
Example: Files and Folders
Each user in Box has its own view on documents and folders. The service account is no admin user, so the service account cannot see the content of all users. The service account cannot be invited to folders, so it is good to use the app users for that purpose.
Webhooks can be hard to handle
We have blogged a lot about webhooks in our previous posts. I hope, you will see that webhooks as a concept (not only related to Box) are not a no brainer!
We have used a simplified architecture to handle the webhook requests by configure a lambda with an api gateway to handle all webhook messages from Box. This is the most simplified form and is used in all found Box-AWS examples like https://github.com/box/samples/tree/master/box-node-webhook-to-lambda-sample
In case of simple events like FOLDER.CREATED this works very well. Box will send exactly one event to the AWS Lambda and you can easily execute your business logic.
We have further noticed that scenarios like moving (webhook event FOLDER.MOVED) or copying a folder (FOLDER.COPIED) which includes a location change behaves differently. The reason is that the box platform will send exactly two independent messages which are considered as separate events.
You may think “why 2 messages?” There is an simple answer.
- The first event FOLDER.COPIED relates to the old location of the folder.
- The second event FOLDER.CREATED relates to the new location where the folder was copied to.
Due to this reason you cannot easily correlated these 2 events together if you get the messages separately in a lambda function. For more complex scenarios you have to queue the messages coming from Box and process them in intervals, so that you can correlate these messages yourself.
An alternative to process events is to use the events API of Box. The events api itself allows to filter for a certain date period, so that you are able to periodically get events.
The challenge with this approach is to filter the events which are interesting for you- this can result in a lot of box requests to find this out. Additionally you will create a lot more traffic because the event log contains every single event.
With these experiences in mind you have to carefully design your application. In complex cases the eventlog maybe better, in simple scenarios a lambda to process a single message can be enough — the architecture depends on the business problem you want to solve.
