24.2

TrackWise Importer

Introduction

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

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:

    • Checkbox

    • Currency

    • Date

    • Date/Time

    • Email

    • 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.

Prerequisites

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

Create a Connected App

  • 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.

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.

Importer Configuration

To create a new TrackWise Importer, go to "Importers" and press the "New" button. Then select Adapter type as Trackwise.

Importer parameters

The common adaptor parameters are described in Common Parameters.

The configuration parameters available for the TrackWise Importer are described below:

  • username* The name of the Trackwise user. Example: user@qau.com.spring3

  • password* The user's password.

  • serverUrl* The URL of the Trackwise Platform. Example: https://dmsdwqau--spring3.my.salesforce.com

  • clientId* The client id of the Connected App. Example: VG9hq7jmfCuKff2B0jhB_Fgm3aWv2oFSXDTxqm_yBBCuxwvDwA0BD

  • clientSecret* The client secret, which you have generated when you configured the Connected App.

  • namedCredentialsUsername* The username configured in the Salesforce Named Credentials.

  • namedCredentialsPassword* The password of the user configured in the Salesforce Named Credentials.

  • tokenEndpointUrl* The token endpoint URL configured in the Auth Provider.

  • recordUniqueIdentifier* The document field used to identify uniquely every document in a batch. Example: Name

  • batchSize* Number of documents that will be imported in a single bulk operation.

  • numberOfThreads* Number of threads that shall be imported in parallel. Default: 10

  • loggingLevel* See: Common Parameters.

Parameters marked with an asterisk (*) are mandatory.

Migset System Rules

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.

Documents

In order to import documents, you need to create a migration set with a processing type of “<Source>ToTrackwise(document)”.

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:

  • document_department* Rule for setting the Department of the corporate document. Example: Quality (Q)

  • document_status* Rule for setting the document status. The only allowed values are Draft and Effective. Example: Draft

  • document_type* Name of the corporate document type. Example: SOP

  • document_workflow* The corporate document workflow name. Example: WF_Upload

  • justifications The justifications of the corporate document. This field is used to add multiple justifications to the corporate document. Example: Review complete

  • mc_content_location Optional rule for importing the content from another location than the one exported by the scanner.

  • name* The name of the document. Example: My Document.docx

  • 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 Note: 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)

  • template_name The template name if the “document_type” represents a template that has values for the template name. Example: Test Template

Trackwise Features

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.

Reviewers

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.

Approvers

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.

Controlled download attributes

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.

  • 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.

Controlled printing attributes

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.

  • 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.

Additional logs

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.