Box Skills is a framework that was designed as an easier way for partners that are interested in content changes and updates to be notified of any revisions of content in Box. If you are familiar with webhooks, they work in a very similar way. Instead of a polling strategy, where you may collect events from Box and analyze them, we will send a notification to a customizable endpoint about the most critical changes that happen to content in an enterprise.
In general, Box Skills focuses on a few key aspects of relevant content changes including, uploads or updates to existing content within Box, and Box Skills will alert your system if any of these events are happening. If your company focuses on extracting additional context or information from files such as audio, video, or images, then Box Skills may be the right solution. As you are extracting this information, you can add it as metadata or one of the Skills Cards to content within Box to make it easier to find relevant content as well as parse through potentially time consuming file types such as videos or audio recording in order to locate the pieces that are most relevant to your day to day work. You can find more information about Box Metadata in this article.
Functionality
Box Skills works on a push-notification paradigm, where Box will proactively send you a notification of a subset of event types in an enterprise. If you have worked with webhooks before in any other system, this will look very familiar. Note that the only difference is that while Box Skills has a very similar framework to Box Webhooks, it will include an additional piece in the payload that can help streamline the process of downloading the new or edited piece of content as well as applying the extracted metadata to the content itself.
With any API call you make to Box, there is a need for an Access Token in the header, which is how we check whether the specific user is allowed to act on a piece of content and whether they have the required permissions to make the changes you are trying to make. Box Skills simplifies this by utilizing an Automation User, which is a user behind the scenes acting on behalf of both your partner application and the enterprise that has authorized it. The Box Skills payload will include two types of downscoped tokens, one to download the relevant content that you are receiving notifications about and one to apply metadata to that specific file.
Creating a Box Skills Application
If you are new to creating applications, refer to our guides on setting up your Box developer account and creating your first application. Note that while most of the other articles in this section refer to creating an application under the “Custom App” designation, this one will utilize the “Box Custom Skill” application type.
Once you select the correct application type, you will notice that the configuration is much more simplistic than the other application types. Since Box Skills has a very narrow and defined use case, you do not need to worry about specific scopes when creating the application. The most important step to check is that the “Invocation URL” that you specify in the application is a publicly reachable URL endpoint, as the webhook notifications that we send are not able to reach private or authenticated network endpoints.
Within the configuration, you are also able to specify a subset of file extensions if you only want to be notified about updates from a specific file type. Some partners focus on audio files to extract a transcript, while others may want to focus on video or still images, so you can customize the notifications to only the filetypes that best suit your application.
Once your application is set up, there is also a built-in way to make sure that Box is able to deliver the notifications to your specified endpoint. While we do some validation when you are setting up the endpoint, double checking with a test file is often the best way to make sure that you are able to receive the information payload to your application.
Authorizing your Application
Since Box Skills is deployed at the enterprise level, it requires a slightly different authentication flow than what you may be used to with other types of Box applications. For your application to begin receiving updates, an admin of the enterprise would need to authenticate your application within the admin console. We have a guide from both the developer as well as the admin perspective on how you could do this here.
Utilizing Skills
Once your application is approved, behind the scenes there will be an Automation User created in the enterprise that is related to your Skills application. To make this process easier and as programmatic as possible, you will not need to log into that account or authenticate it directly. The Box Skills payload that you will receive delivered to your Invocation URL will include all the relevant content and context to speed up the process of scanning the file.
As mentioned before, the payload that Box will send to your endpoint will include the Access Token, but it will also include information such as the id of the file in the Box system. After receiving that notification, the first step will be to capture the token and file id, and then make an API call to grab the file from Box. This will utilize the download token that is provided within the information delivered from Box and the file id from the info.
From there, Box is acting as a listening party, as we’re generally not going to be aware of the processing that your partner application is doing to the file. Box currently does not host any code or execute any custom programs within our ecosystem, so it’s important that the application on your side is set up well to handle any potential errors and make sure that the extracted information is correct.
One you are done scanning the file, it’s time to utilize the other token that is sent with the payload that will permit you to apply metadata back to the original file living in Box. Whether you are applying one of the Skills Cards or you are looking to apply more generic metadata, this additional information will make the files searchable and easier to utilize in daily work.
Overall, Box Skills can simplify the flow of extracting content from Box as it gets uploaded, as well as extracting context from those same files, letting it live adjacent to the file directly in the system that people are working in on a daily basis.