Cara Importer

Introduction

The Cara Importer is one of the target adapters available in migration-center starting with version 3.16. It takes the object processed in migration-center and imports them into Cara platform.

Importer is the term used for an output adapter which is most likely used at the last step of the migration process. An Importer (such as the Cara Importer) takes care of importing the objects processed in migration-center into the target system (such as the Cara platform).

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. Cara Importer can be created, configured, started and monitored through migration-center Client, while the corresponding processes are executed in the background by migration-center Job Server.

Prerequisite

The Cara Importer needs Java 11 to be run. Please make sure you have installed Java 11 and all the environment variables are set correctly.

The user which will do the import must have bulk import rights in Cara.

Cara Importer Properties

To create a new Cara Importer job click on the New Importer button and select "Cara" from the adapter type dropdown list. Once the adapter type has been selected, the parameters list will be populated with the Cara parameters.

The Properties window of an importer can be accessed by double-clicking an importer in the list or selecting the Properties button or entry from the toolbar or context menu.

Common Importer Parameters

Cara Importer Parameters

Additional Importer Configuration

In case your proxy server is configured to require username and password, then a new configuration should be added in the wrapper.conf file. Replace "x" with the next available number:

wrapper.java.additional.x=-Djdk.http.auth.tunneling.disabledSchemes=""

Working with Documents

Cara importer allows importing documents from any supported source system to any supported Cara platform. For that, a migset of type <Source>toCara(document) must be created.

Importing documents with multiple versions is supported by the Cara importer. The structure of the version tree is generated by the scanners of the system that support this feature. The order of versions in Cara is set through the system rules: version_label and version_no.

After you created the desired migration set and you have selected the objects to import from the scan runs, you need to configure the migration set's transformation rules.

Rules for System Attributes

A migration set with a target type of "Cara(document)" has the following system attributes.

To set other standard document attributes you need to define the attributes in the migration object types, create the rules in the migration set and associate those in the Associations tab.

Setting Content Parameters

Three new rules should be added when import documents with content. Those attributes are content.path, content.format and content.type. You can see those attributes on the predefined cara_document object type.

The content.path attribute specifies the file path to the document's content. There are three possible values that this attribute can have, based on the importer configuration:

  • If uploadContentUsingRest is not checked and fileTransferProtocol is empty, the name of the document from the staging folder should be set. The specified document must exist before import. Example: 0906ea5b80043861.pdf

  • If uploadContentUsingRest is not checked and fileTransferProtocol is set to a supported value, the local file path should be set. The transfer will be done by connecting to the specified FTP server and uploading the content on the transfer folder defined using the fileTransferFolder configuration parameter. Example: C:\ExportFolder\3143\0906ea5b80043861.pdf

  • If uploadContentUsingRest is checked, the local file path should be set. The file will be uploaded to the staging folder via REST API. Example: C:\ExportFolder\3143\0906ea5b80043861.pdf

The content.format attribute specifies the file extension of the document's content. Whether the content.path is set then the content.format must be set, it cannot be empty or null because the content.path depends on the content.format.

The content.type attribute specifies the MIME type of the document's content.

The checksum validation feature is also possible in migration-center. To use this feature the parameter content.checksum should be filled with the checksum of the document's content.

Setting Renditions Parameters

Cara Importer allows you to import a document with multiple or no renditions. The attributes used are multi-value attribute and their names are rendition.path, rendition.format, rendition.type.

The rendition.path attribute specifies the file path to the document's rendition. There are three possible values that this attribute can have based on the importer configuration.

  • If uploadContentUsingRest is not checked and fileTransferProtocol is empty, the name of the document rendition from the staging folder should be set. The specified document must exist before import. Example: 0906ea5b80043861.pdf

  • If uploadContentUsingRest is not checked and fileTransferProtocol is set to a supported value, the local file path should be set. The transfer will be done by connecting to the specified FTP server and uploading the file on the transfer folder, the folder defined using the fileTransferFolder configuration parameter. Example: C:\ExportFolder\3143\0906ea5b80043861.pdf

  • If uploadContentUsingRest is checked, the local file path should be set. The file will be uploaded to the staging folder via REST API. Example: C:\ExportFolder\3143\0906ea5b80043861.pdf

The rendition.format attribute represents the file extension of the document rendition. Whether the rendition.path is set then the rendition.format must be set, it cannot be empty or null because rendition.path depends on rendition.format.

The rendition.type attribute specifies the document rendition MIME type.

Cara Importer allows checksum validation for document renditions. To use this feature the parameter rendition.checksum should be filled with document rendition checksum.

Setting Additional Attributes

The Cara Importer can also set additional standard or custom attributes on the documents by defining the attributes in a target object type first and associating transformation rules to them. For example the predefined type cara_document can be used to add one standard attribute and one custom attribute.

The custom attributes must be prefixed with "doc." in the target object type.

A new standard attribute is_published was added to the cara_document object type and a custom one doc.file_name. The custom attribute name in Cara is file_name, but in migration-center the custom attributes are prefixed with "doc.".

After that, new rules are defined in the migration set Rules tab and are associated with the defined target type attributes.

You also need to select the system rule “type_name” in the “Get type name from rule” dropdown box on the | Associations | tab and add all required type definitions in the “Types” list box.

For more details on transformation rules and associations, please see the Client User Guide.

Working with Structures

Cara importer allows importing virtual documents from Documentum source system to any supported Cara platform. The virtual documents are managed in Cara Importer as documents and are automatically transformed into structures based on the virtual document relations. For that, a migset of type DctmToCara(document) must be created.

For more details on how to set the migration set see the Working with Documents section.

If a virtual document has no relations then the imported object in Cara will be a document. The document is transformed on Cara structure only when the object has relations.

Configure Label Mapping File

A Cara structure can have children that are bonded to a specific version label from the version tree. In this case, a properties file was added to help users make the mapping between the source version label and target version label. The file is named labelsMapping.properties and can be found under '…\migration-center Server Components <version>\lib\mc-generiscara-importer'.

For example, in Documentum the version label for the current version from the version tree is CURRENT, but in Cara, the version label is LATEST. To solve this problem in the properties file the following line will be added.

CURRENT=LATEST

When scanning a virtual document, that has a child bound to the default version, the relation will not have any version label. So in the properties file we added a default key, DEFAULT_LABEL, to specify the target version label that will be used in Cara. The example, the properties file contains a line with the following setting, which means that all the children that are bound in Documentum source system to the default label will be bind in Cara to the LATEST version label.

DEFAULT_LABEL=LATEST

Working with audit trails

Cara importer allows importing audit trails from Documentum source system to any supported Cara platform. For that, a migset of type DctmtoCara(audittrail) must be created. After you created the desired migration set and you have selected the objects to import from the scan runs, you need to configure the migration set's transformation rules.

Rules for System Attributes

A migration set of a type DctmToCara(audittrail) has the following system attributes.

A predefined target type (cara_audit_trail) is provided for setting the rest of the audit trail attributes. If you will import the audit objects as audit trail entries in Cara then only the attributes provided in this type can be set by the importer. If you associate the rules with other attributes the importer may not set them.

If you want to import audit trails as any custom object, the Importer parameter importAuditAsCustomObjects must to be checked. In this case you may set any attribute that is supported by custom type. This feature is provided for backward compatibility so it may be removed in future versions.

For more details on transformation rules and associations, please see the Client User Guide

Delta Migration

Cara Importer supports the delta migration feature for documents. The related documents are identified by Cara using the sourceId attribute. When a document is imported using Migration-Center, the document's sourceId is set to the value specified by the object_id system rule.

If you imported a document with a specific sourceId in Cara and you want to update some metadata, then the object which contains the new metadata should have the same sourceId as the imported one. As opposed to most importers, for Cara this document does not need the is_update flag set to 1 for the delta import to work.

Log Files

Log files generated by the Cara 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\Cara 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

Limitations

  • An update object can be imported as a new object in Cara if no other object with the same sourceId exists in Cara platform

  • Validation against nonexistent fields in Cara cannot be made during the validation process

Last updated