Box

Box provides online file sharing and content management services, used primarily by enterprise and business clients to enable team collaboration and shared file storage. With Skuid’s pre-configured data source type, you can both upload to and access files stored on Box.

To use Box with Skuid, you’ll need to complete the following three steps:

  1. Create an app within Box that allows access to its API.
  2. Create a Box authentication provider within Skuid.
  3. Create a Box data source within Skuid.

Configuration

In Box

Create the app:

  1. Log into Box and navigate to app.box.com/developers/services.

  2. If this is your first app, Box will take you to the Create Your first App in Box page. Click Get Started to get to Create a Box Application.

    • If you’ve already created an app, Box navigates to your app list. Click Create a Box Application.
  3. Name your app and click Create Application.

  4. Under General Information, add:

    • An app description (optional)

    • Support email

      • This will default to your Box account’s email address.
    • In the Redirect URLs field, enter the the redirect URI for your Skuid instance.

      When using Skuid on Salesforce, the callback URL will depend on several things:

      • Whether or not the Remove Instance Names from URLs critical update is activated
        • If the above critical update is not activated, then the Salesforce org’s instance
      • If set, the Salesforce org’s My Domain
      • Whether the org is a developer edition or sandbox org

      Each of these variables will change parts of the callback URL.

      There are also different URLs needed based on whether the Skuid page is deployed using the Redirect or skuid:page Visualforce component override method. Because of this, it’s best to enter two callback URLs for Skuid on Salesforce orgs.

      To ensure the accuracy of your callback URLs, fill out the form below to generate the appropriate Salesforce callback URLs for your org:

      Note

      Unsure what your instance and My Domain are? The URL of the Skuid Pages list within the Salesforce Classic layout is a quick way to find the information needed for callback URLs. For example:

      https://customMyDomain-dev-ed--skuid.na30.visual.force.com/apex/PageList

      From the above URL you can deduce the following:

      • customMyDomain is the My Domain
      • -dev-ed indicates this is likely a developer’s edition org
      • na30 is the instance.

      How these URLs are formed [[]]

      If the Remove Instance Names critical update is activated, and the org’s My Domain is configured, the callback URLs should be:

      • https://<myDomain>--skuid.visualforce.com/apex/skuid__oauthcallback
      • https://<myDomain>--c.visualforce.com/apex/oauthcallback

      If the org’s My Domain is configured, their format should be:

      • https://<myDomain>--skuid.<Instance>.visual.force.com/apex/skuid__oauthcallback
      • https://<myDomain>--c.<Instance>. visual.force.com/apex/oauthcallback

      If the org’s My Domain is not configured, then the URLs will be:

      • https://skuid.<Instance>.visual.force.com/apex/skuid__oauthcallback
      • https://c.<Instance>.visual.force.com/apex/oauthcallback

      If the org is a developer’s edition or sandbox, the skuid/c section of the URL will be prepended with -dev-ed– or –sandboxName– respectively.

Credentials

The OAuth2Parameters section displays two credentials needed for the Skuid authentication provider, the client_Id and the the client_secret.

Note

Copy these down for the next section.

If you need to locate these later:

  1. Navigate back to the My Applications
  2. Click Edit Application.
  3. Navigate to OAuth2Parameters.

CORS Allowed Origins

When uploading files through the File Upload component, Skuid bypasses any proxies and uploads files directly to Box. For this to work correctly, you’ll need to whitelist your Skuid site in the newly created Box app to enable cross-domain data transfers (such as transfers between Box and Skuid servers). Do this by setting the Skuid site as a Cross-Origin HTTP request site (CORS).

  1. In CORS Allowed Origins, add the base URL for your Skuid site using the following format:

    With the Remove Instance Name Critical Update deactivated:

    https://[your_Salesforce_My_Domain].[Salesforce_instance].visual.force.com

    With the Remove Instance Name Critical Update activated:

    https://[your_Salesforce_My_Domain].visualforce.com

    Warning

    Check the Skuid on Salesforce dropdown in the previous section regarding the Remove Instance Name Critical Update. As noted, the status of this update (activated or not activated) will affect the form of the URL.

    For example, if your My Domain is companyco and your Salesforce instance is na36, then your URL would be:

    https://companyco.na36.visualforce.com

    On the other hand, if your My Domain is companyco and you have the Remove Instance Names update activated, then your URL would be:

    https://companyco.visualforce.com

In Skuid

Create an authentication provider

Once you’ve got the app set up, use the credentials you copied down in the previous step to create your Skuid authentication provider for Box.

  1. Navigate to Configure > Data Sources > Authentication Providers.
  2. Click New Authentication Provider.
  3. Fill out the necessary fields:
    • Name: Enter a unique name, such as BoxAuth.
    • Authentication Method: OAuth 2.0 / OpenID
    • Provider Type: Box
    • Grant Type: Authorization Code
    • The Authorize and Token Endpoint URLs will be set automatically by the provider type.
    • Default Scopes: leave blank.
    • Client ID: Enter your app’s client_id from the previous section.
    • Client Secret: Enter your app’s client_secret from the previous section.
  4. Click Save.
  5. If Skuid asks you to create a Remote Site Setting, click OK.

Create a data source

With the authentication provider configured, create a data source that uses it to authenticate and gain access to Box files.

  1. Navigate to Configure > Data Sources > Data Sources.
  2. Click New Data Source.
  3. Select the Box data source type.
  4. Enter a unique name for your data source, such as Box.
  5. Click Next Step.
  6. In Configure Connection and Authentication, make the following edits:
    • URL / Endpoint: https://api.box.com/2.0
    • Use Apex Proxy: Checked.
    • Authentication Method: Authentication Provider (OAuth, Custom, etc.)
    • Authentication Provider: Select the authentication provider you created in the previous section.
  7. Click Save.
  8. If Skuid asks to create a Remote Site Setting, click OK.

You can now select your Box data source within a model in the App Composer.

Use the Box data source

Box has one model entity, File. All files and folders are accessible through this entity.

Fields

Some commonly-used, standard fields include:

  • Name: The name of the file.
  • Id: The unique alphanumeric identifier assigned to the file
  • Parent: The absolute path to the directory in which the file exists. You can update this field in Skuid and save the change to move files.
  • Size (in bytes): The size of the file, listed in bytes.
  • Type: indicates whether the item displayed is a folder or a file.

This model entity can access a wide variety of additional fields, such as Created By, Modified by, etc.. Select the fields needed for your use case.

While all these fields are relevant for files, they may not be for folders. If a list of folders is queried, some fields will be empty, potentially loading later in the page load process. This is a normal behavior for the Box API.

Conditions

The Box File entity has one default condition, folder ID which determines which folder to load files from.

This condition can be modified with the following values:

  • The default value is 0; this returns a list of all files in the root directory.

  • [the Box folder ID] returns a list of all files in a specified folder. To locate the folder ID:

    • In your Box account, navigate to the desired folder and click it. The browser will display the specific URL for the folder. The folder ID is an 11-digit number in the URL:

      app.box.com/files/0/f//[ID number]/[the folder's name]

  • [the Box folder ID]/[the Box file ID] returns a specific file in a specific folder. To locate the file ID:

    • In your Box account, navigate to the desired file and click it. The browser will display the specific URL for the file. The file ID is a 12-digit number in the URL:

      app.box.com/files/0/f//[ID number]/1/f_[the file's ID]

Using Box with the File Upload component

You may use the File Upload component with any Box model to upload files to Box storage.

Parent Model = Box Model

Select a Box model for your File Upload component’s Parent Model property, and the following fields appear in the file properties:

  • File Storage Location: Direct Upload
    • This default value simply means files will be placed within the directory of the Parent Model. This value the cannot be changed.
  • Label: Enter a label to insert custom text for the upload button. If you leave this field blank, the upload button will be labeled “Upload.”
  • Snippet to Run on Completion: Enter the name of any JavaScript snippets you wish to run once a file has been uploaded to Box.

Files will be uploaded into the Box directory set by the Parent Folder condition on the Parent Model.

Note

When using the Box data source type with the File Upload component, Skuid bypasses any proxies and uploads its files directly to Box. While this may have no impact on the end-user’s experience, certain firewall settings can cause issues. If you notice that the Box data source isn’t performing as expected, talk to your IT administrator.

Warning

While some the File Upload component offers a second option (Parent Model = None) with some data source types, this feature is currently not available with Box.

Troubleshooting

API Keys

If you need to contact Box to file a troubleshooting request, they will ask for the API key for the app. Here’s where to find it:

  1. Log into Box and navigate to app.box.com/developers/services.
  2. In My applications, click Edit Application next to the specific app.
  3. The apps API key is located at the very bottom under Backend Parameters.