Box Importer

Introduction

The box importer takes files processed in migration-center and imports them into the target box site.

Starting with migration-center 23.2, the box Importer uses the box API 4.2.1 to communicate with the box cloud through the respective box web services.

Limitations and Known Issues

• The character \ is not recognized as a path delimiter

• The folder_path system attribute must start with /

• Sometimes a newly created folder cannot be found by the importer in the first 10 minutes after creation

Prerequisites

In order to use the Box Importer it is necessary to create a Box Application within the developer console because the adapter uses the JWT authentication.

More about JWT with SDKs at https://developer.box.com/guides/authentication/jwt/with-sdk/

Create a Box Application

In order to create a Box Application that can be used with Migration-Center Box Importer, please follow the steps:

• Log into Box and go to the Developer Console(https://app.box.com/developers/console)

• Select Create New App

• Choose Custom App

• Set the App Name and Purpose to Automation

• Optional: Set the Description and Who is building this application

• Click Next and choose Server Application (with JWT) as Authentication Method in the next Dialog.

• Click Create App

Now the application is created and some additional configurations must be done:

• On the Configuration tab go to App Access Level and choose App Access Only

• On the Configuration tab go to Application Scopes and under Content Actions section select Read all files and folders stored in Box

• On the Configuration tab go to Advance Features and select Make API calls using the as-user header and Generate user access tokens

Create configuration file

The Box Importer needs some information about the Box Application in a JSON file. To generate this file the following steps are necessary:

• On Configuration tab go to Add and Manage Public Keys and click on Generate a Public/Private Keypair. Note: The logged in user is required to have MFA authentication setup on his account

• After security check, a JSON file containing authentication data is downloaded in the browser

• Save this file, it will be used by Migration-Center Box Importer to connect to the Box API

• Ensure the both checkboxes on Advanced Feature are still checked

• Click on Save Changes

Approve Box Application for usage within your enterprise

• On the Authorization tab click Review and Submit

• Click Submit on the new the Review App Authorization Submission tab

• After submitting the Application needs to be Authozired by an admin (or co-admin) account

• Before the application can be used, a Box Admin needs to authorize the application within the Box Admin Console.

  • If not already connected, login to Box with an admin or co-admin account

  • Open Admin Console -> Apps -> Custom Apps Manager

  • The previously created app is pending authorization approval

  
• Click on the three dots and select Authorize App

• Verify Application Scopes and confirm by clicking on Authorize.

Working with documents

The box importer can import files to Box. All files imported to box will have their own permissions, so only the box user whose credentials were used for the import can access the imported files on the box site.

Migration Sets

Documents targeted at a box site will have to be added to a migration set. Create a new migration set and set the <source object type>ToBox(document) object type in the Type drop-down. This is set in the -Migration Set Properties- window which appears when creating a new migration set (the type of object can no longer be changed after a migration set has been created).

The migration set is now set to work with box documents.

Transformation Rules

As with other target systems, migration-center objects targeted at box have some predefined system rules available in Transformation Rules. For box, these are “file_name”, “folder_path”, "mc_content_location" and “target_type”. Additional transformation rules for other box document attributes can of course be defined by the user.

If rules for specific attributes are defined, the values need to be associated with the target attributes of a box_document. This is done on the Associations tab of the –Transformation Rules- window by selecting the box_document object type and pointing the target_type rule at it. In this case the value output by the target type rule should be “box_document”, as it must match the object type selected below.

Working with rules and associations is a core product functionality and is described in detail in the Client User Guide.

Object Type definition

If the object type “box_document” mentioned above is not available, it can be created from <Manage>, <Object Types…> with specific box attributes:

Collaborators

Collaborators can be set by making a transformation rule with the following format <emailaddress>;<role>.

i.e. [e-mail];Editor or [e-mail];Viewer.

This transformation rule needs to be associated to the collaborators attribute of the box_document object type.

Comments

Comments can be set by associating a multi-value rule to the comments attribute of the box_document object type.

The user is allowed to set multiple values to comments, the attribute is defined as repeating.

The following format should be used @[user_id:name] to mention a user in a comment.

Tags

Tags can be set by associating a multi-value rule to the tags attribute of the box_document object type.

The user can set multiple values as tags, the attribute is defined as repeating.

Tasks

Tasks can be set by associating valid rules for the following target attributes:

• task_users: needs to contain the valid email of a user

• task_comment: needs to contain a valid text comment

• task_date: (optional) a valid future date for when the task should finish

Multiple tasks can be set by having repeating values on the 3 attributes. All 3 attributes will need to contain the same number of repeating values for the import to succeed.

Note that if the task_users attribute is set, then task_comment needs to be set as well for the task to be successfully imported.

Template metadata

Template metadata can be set using Box Importer.

The user should define a new object type having the same name as the Template Key on Box.

The Template Name can differ from the Template Key.

The Template Key can be found in the URL of the template page.

The template metadata fields are defined as object type attributes having the name as the one on Box and the type mapped to the ones available on Migration-Center.

The dropdown field will be mapped to a String attribute.

The dropdown multivalue field will be mapped to a repeating String attribute.

After the object is defined, it should be added to the target_type system attribute after box_document value and associated in the Association tab similar to box_document.

Custom metadata

Setting custom metadata is possible by adding the metadata name as an attribute to the box_document object type.

The metadata value will be specified using a rule in the migset.

The last step is to associate the attribute from box_document with the rule defined in migset.

Migrating Updates (“Update” or “Delta” Migration)

Objects that have changed in the source system since the last scan, are (re-)scanned as update objects. Whether an object in a migration set is an update or not can be seen by checking the value of the Is_update column – if it’s 1, the current object is an update to a previously scanned object (the base object). There are some things to consider when working with the update migration feature:

• An update object cannot be imported unless its base object has been imported previously.

• Objects deleted from the source after having been migrated are not detected and will not be deleted in the target system. This is by design (due to the added overhead, complexity and risk involved in deleting customer data).

• Updates/changes to primary content will be detected and updated accordingly.

Box Importer Properties

To create a new box Importer job, specify the respective adapter type in the Importer Properties window – from the list of available connectors “Box” must be selected. Once the adapter type has been selected, the Parameters list will be populated with the parameters specific to the selected adapter type.

The Properties window of an importer can be accessed by double-clicking an importer in the list or by selecting the Properties button or entry from the toolbar or context menu.

Common importer parameters

Configuration parameters	Values
Name	Enter a unique name for this scanner Mandatory
Adapter type	Select the “Box” connector from the list of available connectors Mandatory
Location	Select the Job Server location where this job should be run. Job Servers are defined in the Jobserver window. If no Job Server migration-center will prompt the user to define a Job Server Location when saving the Importer. Mandatory
Description	Enter a description for this job (optional)

Box importer parameters

Configuration parameters	Values
configFileJson*	File containing the Box Application's private key and other details. Those details are obtained when the application is created. JSON file containing clientID, clientSecret and appAuth(publicKeyID, privateKey, passphrase) Mandatory
userIds*	The Box user ids used to establish the API connections. It is possible to use multiple users in order to improve the import performance. Mandatory
numberOfThreadsPerUser	Maximum number of parallel threads allowed to use simultaneous the same Box API user connection. The allowed values are between 1 and 4. The importer working threads number will be equal to numberOfThreadsPerUser*count(userIds)
importLocation	Box folder path where documents will be imported. This must start with '/' The value from the folder_path attribute will be concatenated at the end of this path.
autoCreateFolders	Flag indicating if the missing folders will be created automatically based on the values provided in the system rule folder_path.
checkContentHash	Requests the checksum computed by Box when the file is imported to be compared with the checksum computed by mc before import. The checksum must be computed using the SHA-1 algorithm because it is the algorithm used by Box. If the checksum was not computed before, at the scanning phase, the importer will compute the file checksum before importing it. If the two checksums do not match, an appropriate error will be logged, and the affected documents will be moved to the “Import error” state.
loggingLevel*	Sets the verbosity of the log file. Values: 1 - logs only errors during import 2 - is the default value reporting all warnings and errors 3 - logs all successfully performed operations in addition to any warnings or errors 4 - logs all events (for debugging only, use only if instructed by fme product support since it generates a very large amount of output. Do not use in production) Mandatory

On the | Migsets | tab, the user can select the migration sets to be imported with this importer. Depending on the chosen Adapter Type only the migration sets compatible with this type of importer will be displayed and can be selected for import. Also, only migration sets containing at least one object in a validated state will be displayed (since objects which haven’t been validated cannot be imported).

Available migration sets can be moved between the two columns by double clicking or using the arrows buttons.