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
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:
Checkbox
Currency
Date
Date/Time
Geolocation
Number
Percent
Phone
Picklist
Picklist (Multi-Select)
Text
TextArea
Time
URL
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.
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.
For more details please see https://help.salesforce.com/articleView?id=connected_app_create.htm&type=5
From Setup page, enter App Manager in the Quick Find box.
Click New Connected App.
Fill the connected app’s name with a unique name on your organization.
Enter the API name of the connected app.
Fill the contact email field with a valid email which will be used in case Salesforce wants to contact you.
The other attributes from Basic Information could be filled if those are considered necessary.
Check the Enable OAuth Settings checkbox from API (Enable OAuth Settings) section.
Enter a value for the Callback URL. This value will not be used by migration-center. Example: https://test.salesforce.com/services/oauth2/success
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 Users to All users may self-authorize.
Set the IP Relaxation setting to Relax IP restrictions.
Click Save.
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.
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:
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 values for review_name are: user1@mail.com, user2@ mail.com.
The review_cycle values are: WF_R2_A1_1, WF_R2_A1_2.
So, this means that the reviewer with username user1@mail.com 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 values for approver_name are: user1@mail.com, user2@ mail.com.
The approve_cycle values are: WF_R2_A2_1, WF_R2_A2_2.
So, this means that the approver with username user1@mail.com is responsible for WF_R2_A2_1 cycle of the approval.
If you want to add a user as approver you must use the prefix “user.” and if you want to add a group as approver you must use the prefix “group.”.
The allowed values for Approvers are the user name of the DMS Users or the group name of the DMS Group.
After that, the value "trackwise-approvers" should be added to the "traget_type" system attribute.
The final step is to associate the regular transformation rule with the defined target type attribute.
All the attributes used to control the download of a corporate document can be set using the Trackwise Importer.
To set those attributes you need to use the “trackwise-control-download” object type which can be found if you access the Manage ->Object Types option.
For all attributes, you need to define new regular transformation rules, which will be associated with the corresponding attributes from the target object.
The Trackwise Importer can import all attributes used to control printing of corporate documents.
To set those attributes you need to use the “trackwise-control-printing” object type which can be found if you access the Manage ->Object Types option.
For all attributes, you need to define new regular transformation rules, which will be associated with the corresponding attributes from the target object.
To create a new TrackWise Importer, go to "Importers" and press the "New" button. Then select as
An importer of type TrackWise has the following parameters, which you need to set with the appropriate values.
Additional 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.
Configuration parameters
Values
document_department*
Rule for setting the Department of the corporate document.
Example: Quality (Q)
Mandatory
document_status*
Rule for setting the document status. The only allowed values are Draft and Effective.
Example: Draft
Mandatory
document_type*
Name of the corporate document type.
Example: SOP
Mandatory
document_workflow*
The corporate document workflow name.
Example: WF_Upload
Mandatory
justifications
The justifications of the corporate document. This field is used to add multiple justifications to the corporate document.
Example: Review complete
Optional
If not provided, the corporate document will have no justifications.
mc_content_location
Optional rule for importing the content from another location than the one exported by the scanner.Optional
name*
The name of the document.
Example: My Document.docx
Mandatory
target_type*
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.
Example: trackwise-corporate-document
Mandatory
The first value of this field must be the trackwise-corporate-document.
template_type
The name of template type. This attribute should be filled if the “document_type” represents a template.
Example: Template (TPT)
Optional
template_name
The template name if the “document_type” represents a template that has values for the template name.
Example: Test Template
Optional
Attributes name
Values
DOWNLOAD_Selected_Groups
Represents the groups that can perform the download action. The values are represented by the group name of the Regular Salesforce Groups.
Example: GroupA
DOWNLOAD_Selected_Users
Represents the users that can perform the download action. The values are represented by the user name of the Salesforce Users.
Example: Alex
SPARTADMS_Allow_Download__c
Indicates if the download action is allowed. The only accepted values are TRUE or FALSE.
SPARTADMS_Can_be_downloaded_by__c
The attributes specify if the download action can be performed by “Selected Users” or “No Users”. The only accepted values are Selected Users or No Users. Example: Selected Users
SPARTADMS_Limit__c
This attribute indicates if the download action should be limited. The allowed values are TRUE or FALSE. Example: TRUE
SPARTADMS_Limit_number_of_downloads__c
The number of downloads that a user can do. If the “SPARTADMS_Limit__c” is FALSE then the attribute should have no value.
The value must be greater than 0.
SPARTADMS_Per__c
Specify if the limitation should be applied to “each user” or to “all users”. The attribute should be set if the “SPARTADMS_Limit__c” is TRUE. The allowed values are each user or all users.
SPARTADMS_Frequency__c
Represents the frequency of limitation. The attribute should be set if “SPARTADMS_Limit__c” is TRUE. The supported values are None, Daily, Weekly, Monthly.
Attributes name
Values
PRINT_Selected_Groups
Represents the groups that can perform the print action. The values are represented by the group name of the Regular Salesforce Groups.
Example: GroupA
PRINT_Selected_Users
Represents the users that can perform the print action. The values are represented by the user name of the Salesforce Users.
Example: Alex
SPARTADMS_Enable_Controlled_Printing __c
Indicates if the print action is allowed. The only accepted values are TRUE or FALSE.
SPARTADMS_Can_be_printed_by__c
The attributes that specify if the print action can be performed by “Selected Users” or “No Users”. The only accepted values are Selected Users or No Users.
SPARTADMS_Limit_Print__c
This attribute indicates if the print action should be limited. The allowed values are TRUE or FALSE.
Example: TRUE
SPARTADMS_Limit_number_of_prints__c
The number of prints that a user can do. If the “SPARTADMS_Limit_Print__c” is FALSE then the attribute should have no value. The value must be greater than 0.
SPARTADMS_Per_Print__c
Specify if the limitation should be applied to “each user” or to “all users”. The attribute should be set if the “SPARTADMS_Limit_Print__c” is TRUE. The allowed values are each user or all users.
SPARTADMS_Frequency_Print__c
Represents the frequency of limitation. The attribute should be set if “SPARTADMS_Limit_Print__c” is TRUE. The supported values are None, Daily, Weekly, Monthly.
Configuration parameters
Values
username*
The name of the Trackwise user.
Example: user@qau.com.spring3
Mandatory
password*
The user's password.
Mandatory
serverUrl*
The URL of the Trackwise Platform.
Example: https://dmsdwqau--spring3.my.salesforce.com
Mandatory
clientId*
The client id of the Connected App.
Example: VG9hq7jmfCuKff2B0jhB_Fgm3aWv2oFSXDTxqm_yBBCuxwvDwA0BD Mandatory
clientSecret*
The client secret, which you have generated when you configured the Connected App.
Mandatory
namedCredentialsUsername*
The username configured in the Salesforce Named Credentials. Mandatory
namedCredentialsPassword*
The password of the user configured in the Salesforce Named Credentials.
Mandatory
tokenEndpointUrl*
The token endpoint URL configured in the Auth Provider.
Mandatory
recordUniqueIdentifier*
The document field used to identify uniquely every document in a batch.
Example: Name
Mandatory
batchSize*
Number of documents that will be imported in a single bulk operation. Mandatory
numberOfThreads*
Number of threads that shall be imported in parallel.
Default: 10
Mandatory
You may increase this value for large imports, depending on the configuration of the machine that runs the job server.
loggingLevel*
Sets the verbosity of the log file.
Allowed 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
