Box Importer

Introduction

The box importer takes files processed in migration-center and imports them into the target box site.
Starting with migration-center 3.2.6, the box Importer uses the box API 2.0 to communicate with the box cloud through the respective box web services.

Prerequisites

Before being able to import into BOX there are some extra steps that need to be done:
  • Install the provided certificate
  • Authorize the Job Server machine from BOX

Installing the certificate

In the Job Server install location, under ../lib/mc-box-importer there is a file called myKeystore.p12. This file needs to be installed under the Trusted Root Certification Authorities in Windows. The certificate password is fmefme.
Depending on which browser you use for step 2, it might also be necessary to install this certificate in the browser you are using as well.
Please restart your Job Server after installing the certificate.

Authorizing the Job Server machine

When you try to perform a BOX import for the first time on a specific Job Server, you will receive an error with a Box URL:
On the machine with the Job Server, access the provided link in the browser of your choice and give authorization to the Job Server to import into Box.
After the user successfully authenticated migration-center, the importer job can be started successfully.
If the Job Server is to be restarted then the importer will give this error again with a new link, and the machine needs to be provided authorization again.

Migrating documents and folders to box

The box importer can import files to box.net and can also create folders. All folders and 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 folders and 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” 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. [email protected];Editor or [email protected];Viewer.
This transformation rule needs to be associated to the collaborators attribute of the box_document object type.

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.

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 adapters “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” adapter from the list of available adapters
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
box_username*
User name for connecting to the target box site.
Mandatory
box_password*
The user’s password.
Mandatory
box_import_location*
The path inside the target box site where objects are to be imported. It must be a valid box path. This path will be appended in front of each folder_path before importing documents if both the box_import_location parameter and the folder_path attribute value are set.
number_of_threads
Number of documents that can be imported simultaneous (optional).
In order to optimize performance, the Box importer supports a multi-threading feature which assures that at the same time a fixed number of documents will be imported.
This parameter is optional, however if no value, non-integer value or a value less than 1 is provided, the importer will use its default value (5) for multi-threading.
Although there is no upper limit for the number of threads that can be configured, setting a high number can overload the system’s CPU and memory.
check_content_hash
Requests a checksum to be computed by box upon import, and compare this checksum against the checksum computed by mc before import. Should the two checksums not match, box returns an appropriate error causing mc to transition the affected documents to the “Import error” state.
loggingLevel*
Sets the verbosity of the log file.
Values:
1 - logs only errors during scan
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.