3.17

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

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:

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

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.

Preparation

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.

Importing Documents

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:

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

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.

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

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

Setting 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 which can be found if you access the Manage ->Object Types option.

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.

For all attributes, you need to define new regular transformation rules, which will be associated with the corresponding attributes from the target object.

Setting 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 which can be found if you access the Manage ->Object Types option.

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.

For all attributes, you need to define new regular transformation rules, which will be associated with the corresponding attributes from the target object.

Configuring the Importer

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.

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

History, Reports, Logs

History

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

Last updated