Adding Actions to Your OpenBox Service
Actions give your OpenBox service the ability to manipulate files stored on Box.net. Every OpenBox service must have at least one action, defined by you. If your web application has a web services API already, you should be able to make it into an OpenBox service with minimal effort by adding actions.
General Information
You specify the definition of an action when you configure your OpenBox service. Some of the attributes you'll need to specify when you configure an action include:
| Name |
When a user right-clicks on a Box.net file, this is the text they will see for your action. Examples include "Create ringtone," "Send to Twitter," "Edit image," and so on. |
| Description |
Appears next to your action in the public OpenBox Service Directory. |
| Supported extensions |
Your action will only show up in the drop down menus of files which have the extensions that you list here. If you leave it blank, your action will appear in the the drop down menu of all files. For example, if your OpenBox service only works with Excel spreadsheets, you'll want to specify the extension ".xls". |
| Category |
Helps sort your action in the public directory (if you chose for your service to be listed there). |
| Filetype Category |
Helps sort your action in the public directory (if you chose for your service to be listed there). |
| Action status |
There are three options for this setting:
- Development - The action will only be visible and executable by the developers assigned to the service. Best to leave this setting on until you are ready for your action to be used by others.
- Online - After you have finished development on your action, put it in Online mode so all Box.net users can see it and work with it.
- Maintenance - If you ever have trouble with your action after it has already gone live, or you need to perform maintenance on your website, you can put your action in to Maintenance mode and it will temporarily go offline for everyone except the developers of the service.
|
Prompt Parameters
The prompt is the dialog box that appears when a user clicks on your action in the drop down menu. The prompt gets data from the user pertaining to the action the user chose. This data can include login information, whether to overwrite the file or create a new one, and so on. In this section you specify the parameters you want the user to fill in.
By specifying parameters here you are not automatically guaranteeing that those parameters are sent to you. You must specify these parameters when you configure the callback parameters. More information on that below.
Most prompt parameters, with the exception of Prompt Message, are optional.
| Prompt Message |
This message appears in the prompt above all the parameters. It is important to supply this parameter even if you have no prompt parameters because it is all the user will see before they execute your action. |
| Data Type |
The parameters you specify here will appear as form elements on the prompt. This determines which form element to use for the parameter. |
| Parameter Name |
This specifies the name of the parameter to be sent to your OpenBox service in the Callback Parameters section. |
| Label |
The text description the user sees next to the form field in the prompt. |
| Default Value |
Supplies a default value for this parameter. |
| Remember |
Specifies that this parameter should be stored and automatically filled in when the action is executed by the user in the future. Recommended for parameters that are common to the user, such as login information. |
| Section Break |
You may add a section break if you have too many parameters, or to separate required parameters from optional parameters. The parameters below the section break will not appear automatically; the user must click to see them. |
Callback Configuration
This section specifies what happens when the user clicks OK in the prompt.
| User experience |
Specifies whether your action is server-side or should run in a popup window. For details, see Request Workflow. |
| Method |
The method and format to receive the Callback Parameters. (see the next section below) |
| Preliminary Callback URL (optional) |
When the user clicks OK, a request with all the parameters specified in Callback Parameters is made to this URL. It will typically be a URL to an API method on your server, but can be any endpoint configured to accept an HTTP request. |
| Final Callback URL |
For server-side actions only. If a preliminary callback URL is specified, the response of that call is sent to this URL. The response of the Final Callback URL is used as the confirmation message. This enables OpenBox to communicate with an existing API on your site. Instead of changing your API signature to accommodate OpenBox, you can just add a new one that resolves existing responses (such as a status code like 'success') into an OpenBox-friendly message (such as "Your Twitter status has been updated."). |
| Client Callback URL |
For popup actions only. In a popup action, if you use XML or SOAP as your method, or if in the REST method you ask for a File parameter, then the Initial Callback URL cannot come from the client. Therefore a second request must be made from the client to your server for the server to send back the interface necessary for the user. More information is available on the Client Callback URL page. |
Callback Parameters
Select the parameters and the names of those parameters that you want sent to the callback URL during the initial request when the user clicks Okay on the prompt. If you do not specify parameters here, you will not receive any parameters at all.
You can choose parameters from Box Parameters or from the Prompt Parameters as described above. Parameters are delimited with the pound sign (#). So if you have a parameter named "login" that you configured in the Prompt Parameters section, you can use it here by entering #login#.
| If, for the Callback configuration Method, you clicked REST... |
Click "add callback parameter" to add each parameter to be sent to the callback URL of your service. You may choose from Box Parameters or from your Prompt Parameters. You may also specify formatting for the variable. For example, if you have the following parameters:
If "title" is a Prompt Parameter, the file extension and the content of the file will be POSTed under the name's extension and posted_file respectively to the following URL:
http://your-callback-url.com/?url=
&title=
|
| If, for the Callback configuration Method, you clicked XML or SOAP... |
Click the parameters on the right to format the callback URL.
|
Authentication
| HTTP Basic Authentication |
If your initial callback URL requires Basic Auth, you may specify a login and password here. Keep in mind you can use both Prompt Parameters and Box Parameters in the login and password fields. |
Next Steps
Now that you've mastered OpenBox Actions, you can learn more about the Box Parameters available to you.
Need additional assistance? Please feel free to Contact us
