Help Manual - Box Destination

Documentation on SSIS Box Destination component

Using the Box Destination Component

The Box Destination Component is an SSIS data flow pipeline component that can be used to write data to Box.com. You can Create, Update, or Delete objects that allow a particular action with this component. There are three pages of configuration:

  • General
  • Columns
  • Error Handling

The General page is used to specify general settings for the Box Destination Component. The Columns page allows you to map the columns from upstream components to Box fields in the destination object. The Error Handling page allows you to specify how errors should be handled when they occur.

General Page

The General page allows you to specify general settings for the component.

SSIS Box Destination Component

Connection Manager

The Box Destination Component requires a Box connection. The Connection Manager option will show all Box Connection Managers that have been created in the current SSIS package or project.

Action

The Action option allows you to specify how data should be written to Box. There are currently three (5) supported:

  • Create: Creates new record(s).
  • Delete: Deletes record(s).
  • Update: Updates existing record(s).
  • Share(since v21.1): Grants a user or group access to a file or folder
  • Unshare(since v21.1): Revoke a user or group access to a file or folder
Delete Recursive

The Delete Recursive option allows you to specify whether to delete a folder if it has an item inside of it. If you uncheck this option, an error will be thrown if the target folder is not empty.

Note: This option is only available for the Delete action and will only work when deleting folders from Box.

Input Timezone

The Input Timezone option allows you to specify the timezone of all incoming datetime fields. This will indicate whether the datetime fields should be converted from the Local System Timezone or kept in UTC format when writing to the Box.com server.

  • Connection User Timezone
  • UTC Timezone
  • Local System Timezone
Refresh Component Button

Clicking the Refresh Component button causes the component to retrieve the latest metadata and update each attribute to its most recent metadata.

Map Unmapped Fields Button

By clicking this button, the component will try to map any unmapped Box attributes by matching their names with the input columns from upstream components. This is useful when your source component has recently added more columns, in which case you can use this button to automatically establish the association between input columns and unmapped destination attributes.

Clear All Mappings Button

By clicking this button, the component will reset all your mappings in the destination component.

Expression fx Button

Clicking the fx button to launch SSIS Expression Editor to enable dynamic update of the property at run time.

Generate Documentation Button

Clicking the Generate Documentation button to generate a Word document that describes the component's metadata including relevant mapping, and so on.

Columns Page

The Columns page of the Box Destination Component allows you to map the columns from upstream components to the Box destination fields.

The Columns page displays a grid that contains four columns as shown below.

SSIS Box Destination Component - columns

  • Input Column: You can select an input column from an upstream component for the corresponding Box field.
  • Box.com Field: The Box field that you are writing data.
  • Data Type: This column indicates the type of value for the current field.
  • Unmap: This column can be used to unmap the field from the upstream input column, or otherwise it can be used to map the field to an upstream input column by matching its name if the field is not currently mapped.

Some Special fields

  • _isFolder: Specify TRUE or FALSE boolean values to indicate if a record is a file or folder. Note that if this field is not mapped, it will be treated as FALSE (meaning that the item will be considered a file).
  • file_content: Special image field where you would map the binary content to this field to upload the content of the file to Box.
  • It is necessary to map parent.id field when you want to create files under a specific folder, or you want to move files to a specific folder. The input value is the id of the target folder.

Error Handling Page

The Error Handling page allows you to specify how errors should be handled when they happen.

SSIS Box Destination Component - Error Handling

Choose error-handling mechanism

There are three options available.

  1. Fail on error
  2. Redirect rows to error output
  3. Ignore error

When the Redirect rows to error output option is selected, rows that failed to write to Box.com will be redirected to the 'Error Output' output of the Destination Component. As indicated in the screenshot below, the green output connection represents rows that were successfully written, and the red 'Error Output' connection represents rows that were erroneous. The 'ErrorMessage' output column found in the 'Error Output' may contain the error message that was reported by Box or the component itself.

SSIS Box Destination Component - Error Output

Note: Use extra caution when selecting Ignore error option, since the component will remain silent for any errors that have occurred.

Enable Columns for Default Output
BoxRecordId

Contains the newly created Box record's ID, which you can use to write to log or further process using additional data flow components.