OpenBox Request Workflow

The OpenBox workflow begins when a user initiates an action on a file in the My Files view in Box.net. The user first clicks the drop-down menu for a file, then selects an action (such as "Edit image") to perform on that file. The prompt is then displayed.

The Prompt

The prompt is fully customizable by the service developer. It can be customized for each action. The developer of the OpenBox service can specify the information the service requires from the user; these are known as parameters.

Here are some examples of existing services' prompts:

	Picnik's prompt (a pop-up action)
	Twitter's prompt (a server-side action)

When the user clicks OK, one of two things happen, depending on whether the action is a popup action or a server-side action. Pop-up actions (such as Zoho and Picnik) open a new window for the user to complete the action. Server-side actions make a direct request to the initial callback URL then show the result of the request to the user.

Pop-up action

1. A popup window opens and loads the initial callback URL, passing the parameters defined by the developer and populated by the user. If there are GET parameters, they are appended to the URL, but if there are POST parameters, the popup window makes an additional POST to the initial callback URL in the background.   Upon receiving this request, the callback URL then displays a user interface for the action. For example, with Picnick (an image editing service) a user can rotate, crop, or resize their photo in the user interface window.   If the initial callback request is defined by the developer to be XML or SOAP, or if it's specified as REST but asks for the file itself as a POST parameter, then the request must be made by the Box.net server. In this case, a second client callback is placed to display the interface to the user.

2. At this point, the service can perform API calls to Box.net, such as downloading the file to the server to display to the user, sending a modified file to overwrite the file, sharing a file, or any other API call. After the service has finished, it should redirect the user to the redirect_to_box_url (with a confirmation message appended to the URL).

3. The redirect_to_box_url contains some Javascript which closes the new window, saves the confirmation message and writes the message to the window.

Authentication

Authentication is necessary in situations where a user name and password is required to use your OpenBox service.

In a pop-up action, authentication with your service can be done in a number of ways. One option is to create prompt parameters such as username and password (as in the Twitter prompt above). Your OpenBox service can then get those parameters as part of the initial request to the callback URL, and authenticate the user on your server. The other option is to send the user's ID in the initial request, then ask the user to login inside the pop-up. After the user logs in, you can store the relationship between the user's account on your site and their Box user ID. Subsequent OpenBox requests can automatically authenticate the user with their user ID without requiring them to supply their credentials again.

 Server-Side Actions

1. After the user clicks OK in the prompt, a request (the initial callback request) is made to the callback URL with the parameters and formats specified in the creation of the action.

2. After your server receives the initial request, it can place calls to the Box.net API with the file auth token that it was given. The response is then used as the confirmation message, except in the case that a response formatting URL is specified. This option is provided to enable OpenBox to work with existing APIs on your side without changing your API methods -- you can just add a new one which resolves your existing responses (such as a status code like 'success') into an OpenBox-friendly message (such as "Your Twitter status has been updated.").   If the response formatting URL is specified, a request is made to that URL with the status message received from the callback URL. The response is then used as the confirmation message.

Next Steps

Now that you have an understanding of the OpenBox request workflow, continue to OpenBox Services.