The TrackWise Importer allows migrating documents to TrackWise Platform offering the following features:
Import corporate documents to TrackWise Platform
Set values for any columns in TrackWise Platform, including user-defined columns
TrackWise Importers can be created, configured, started, and monitored through migration-center Client, while the corresponding processes are executed by migration-center Job Server and the migration-center TrackWise Importer respectively.
The term importer is used in migration-center for describing a component that imports processed data from migration-center to another system.
Scanners and importers work as jobs that can be run at any time and can even be executed repeatedly. For every run, a detailed history and log file are created. Multiple scanners and import jobs can be created or run at a time, each being defined by a unique name, a set of configuration parameters and a description (optional).
Features, Limitations, and Known Issues
The TrackWise Importer comes with the following features, limitations, and known issues:
The importer only supports
import of documents with metadata
The following column/field types are currently supported by the importer:
The documents can be imported only in Draft status or Effective status.
The TrackWise Importer does currently not support delta migration.
The TrackWise Importer is not able to import document versions.
The TrackWise Importer does not validate for nonexistent values or inactive fields for system rules.
The error message is not clear when setting nonexistent values for fields that could not be validated.
The documents will not be deleted from TrackWise if something goes wrong during the import (no rollback).
Importing documents with content over 800 MB on multi-threading at the same time may produce some errors.
Working with the Importer
In this chapter, you will learn to work with the TrackWise Importer. Specifically, you will see how to import documents with metadata in the TrackWise Platform.
Before you can start working with the importer, you need to configure a Connected App for the migration-center that is used for authentication with TrackWise Platform. The Connected App is the recommended solution to integrate an external application with your Salesforce API.
Please follow these steps in order to setup your migration-center application in your TrackWise Platform.
Select the Access and manage your data (api) and Access your basic information (id, profile, email, address, phone) permissions from Selected OAuth Scopes attribute.
Leave all other options at their defaults and click Save.
Click Continue when the following message will be displayed.
Click Manage from the created Connected App page to open the Connected App Detail page.
When the Connected App Detail page click Edit Policies button.
Set the Permitted Usersto All users may self-authorize.
Set the IP Relaxation setting to Relax IP restrictions.
Go to App Manager tab, select the created Connected App, and click the View option.
The Client Id and Client Secret could be found on the opened page.
Configure Salesforce user to access Corporate Document using API
The user used to migrate the data must have the API Enabled permission and to enable this permission the following steps are necessary:
From Setup page, enter Permission Sets in the Quick Find box.
Choose the permission set assigned to migration user.
From System section, click the System Permissions.
From this page click Edit button.
Check the API Enabled checkbox and click Save.
In order to import documents, you need to create a migration set with a processing type of “<Source>ToTrackwise(document)” as shown in the screenshot below:
After you have selected the objects to import from the file scans, you need to configure the migration set’s transformation rules.
A migration set with a target type of “Trackwise(document)” has the following system attributes.
You can find a detailed description of the available system rules in the table below:
Rule for setting the Department of the corporate document.
Example: Quality (Q)
Rule for setting the document status. The only allowed values are Draft and Effective.
Name of the corporate document type.
The corporate document workflow name.
The justifications of the corporate document. This field is used to add multiple justifications to the corporate document.
Example: Review complete
If not provided, the corporate document will have no justifications.
Optional rule for importing the content from another location than the one exported by the scanner.Optional
The name of the document.
Example: My Document.docx
The name of the object type from the migration-center’s objects type definitions. This field may contain additional values like: trackwise-control-printing, trackwise-control-download, trackwise-reviewers and trackwise-approvers.
The first value of this field must be the trackwise-corporate-document.
The name of template type. This attribute should be filled if the “document_type” represents a template.
Example: Template (TPT)
The template name if the “document_type” represents a template that has values for the template name.
Example: Test Template
Setting Custom Attributes
Usually you want to set additional custom attributes on the documents. Therefore, you need to define the attributes in trackwise-corporate-document target type first, define the regular transformation rules and associate them with the defined target type attributes after that.
For more details on transformation rules and associations, please see the corresponding chapters in the Client User Guide.
You also need to select the system rule “target_type” in the “Get type name from rule” dropdown box on the | Associations | tab and add all required type definitions in the “Types” list box.
The reviewers are an important part of the corporate document, so the importer allows you to set the document reviewers. To perform this action, it is necessary to define two new regular transformation rules, which will represent the reviewer's name and the review cycle. Those attributes should be multi-value attributes and the first value from the attribute that represent the reviewer’s name is related to the first value from the other attribute that represents the review cycle.
Example: Let’s suppose that the reviewer’s name attribute is reviewer_name and the review cycle attribute is review_cycle.
The review_cycle values are: WF_R2_A1_1, WF_R2_A1_2.
So, this means that the reviewer with username [email protected] is responsible for WF_R2_A1_1 cycle of the review.
If you want to add a user as a reviewer you must use the prefix “user.” and if you want to add a group as a reviewer you must use the prefix “group.”.
The allowed values for Reviewers are the user name of the DMS Users or the group name of the DMS Group.
The next step is to add the "trackwise-reviewers" value to the "target_type" system attribute.
The final step is to associate the regular transformation rule with the defined target type attribute.
The TrackWise Importer is able to add approvers to the corporate documents, and the steps to define the approvers are similar to the ones to set the reviewers.
First, you need to define two regular transformation rules, one for approvers names and one for approve cycles.
Those attributes should be multi-value attributes and the first value from the attribute that represent the approver’s name is related to the first value from the other attribute that represents the approval cycle.
Example: Let’s suppose that the approver’s name attribute is approver_name and the approve cycle attribute is approve_cycle.
The client secret, which you have generated when you configured the Connected App.
The username configured in the Salesforce Named Credentials. Mandatory
The password of the user configured in the Salesforce Named Credentials.
The token endpoint URL configured in the Auth Provider.
The document field used to identify uniquely every document in a batch.
Number of documents that will be imported in a single bulk operation. Mandatory
Number of threads that shall be imported in parallel.
You may increase this value for large imports, depending on the configuration of the machine that runs the job server.
Sets the verbosity of the log file.
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)
History, Reports, Logs
A complete history is available for any Trackwise 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.
Job Report File
Double clicking an entry in the -History-window or clicking the Open button on the toolbar opens the job report file created by that run. The report 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.
Job Log Files
Log files generated by the Trackwise Importer 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\Trackwise Importer\<job run id>
You can find the following files in the <job run id> folder:
The import-job.log contains detailed information about the job run and can be used to investigate import issues.
Note: the amount of information written to the report and log files depends on the setting specified in the ‘loggingLevel’ start parameter for the respective job