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.

Importer is the term used for an output adapter which is most likely used at the last step of the migration process. An importer works as a job that can be run at any time and can even be executed repeatedly. For every run a detailed history and log file are created. An importer is defined by a unique name, a set of configuration parameters and an optional description.

Box Importers can be created, configured, started and monitored through migration-center Client, but the corresponding processes are executed by migration-center Job Server.

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. [e-mail];Editor or [e-mail];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.

Log files

A complete history is available for any box Importer job from the respective items’ History window. It is accessible through the History button/menu entry on the toolbar/context menu. The History window displays a list of all runs for the selected job together with additional information, such as the number of processed objects, the start and ending time and the status.

import-history

Double clicking an entry or clicking the Open button on the toolbar opens the log file created by that run. The log file contains more information about the run of the selected job:

• Version information of the migration-center Server Components the job was run with

• The parameters the job was run with

• Execution Summary that contains the total number of objects processed, the number of documents and folders scanned or imported, the count of warnings and errors that occurred during runtime.

Log files generated by the box Adapter can be found in the Server Components installation folder of the machine where the job was run, e.g. …\fme AG\migration-center Server Components <Version>\logs

The amount of information written to the log files depends on the setting specified in the ‘loggingLevel’ start parameter for the respective job.