24.1

Cara Importer

Introduction

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

Known issues & limitations

  • When binding relations by version label, no error is thrown when incorrect or missing version label mapping is provided(#60093)

  • Importing a base document and one update (as result of delta scan) results in unpredictable behavior(#60118)

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

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.

Importer Configuration

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.

Importer Parameters

The common adaptor parameters are described in Common Parameters.

The configuration parameters available for the Alfresco importer are described below:

  • restServiceUrl* The URL of the Cara REST API.

    Example: http://migration.cara.cloud:8090/api

  • username* Cara username. The user must have bulk import rights in Cara.

  • password* The user's password.

  • proxyServer The name or IP of the proxy server.

  • proxyPort The port of the proxy server.

  • proxyUser The username if required by the proxy server.

  • proxyPassword The password if required by the proxy server.

  • uploadContentUsingRest Indicates if the content will be uploaded to the FTP staging folder using the REST API.

  • importAuditAsCustomObjects Indicates if the audit trails will be imported as audit trail objects or as custom objects.

  • language The user's local language. If no value is provided the default value ("en") will be used. This parameter is to create a connection with Cara platform.

    Example: en

  • bulkSize* The number of objects that will be imported in a single bulk operation.

  • fileTransferProtocol

    The protocol name for upload content files to Cara. If the content files were uploaded prior to the importer leave the parameter empty.

    Supported values are: SFTP

  • fileTransferHost The hostname where the files are uploaded. If the fileTransferProtocol is empty, this parameter will be ignored.

  • fileTransferFolder The path of the folder on the file transfer host where the content files are uploaded. This path must exist on the file transfer host and the user must have write access to the folder. If the fileTransferProtocol parameter is empty, this parameter will be ignored.

  • indexDocuments Indicates if imported documents will be be indexed or not.

  • asynchronousIndex Indicates if imported documents will be indexed asynchronous or synchronous.

  • labelsMappingFile The path of the file which contains the mapping between the source version label and the target version label. This file is used just for structures. See Configure Label Mapping File for more details.

  • relationsMappingFile The path of the file which contains the mapping between source relation type names and target relation type names. This file is used for importing relations. See Configure Relations Mapping File for more details.

  • loggingLevel* See Common Parameters.

Parameters marked with an asterisk (*) are mandatory.

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.

  • cara_target_name* The name of the Type being used for the document in the Cara target system. This can differ from the name of the Object Type being used for the Associations in MC. (see target_type) Example: cara_document

  • is_latest Rule used to indicate if the document is the latest version in the version tree.

  • object_id* The ID of the document. This sets the source_id attribute in Cara. Should be unique per object.

  • object_name The name of the document.

  • previous_version_id The id of the document previous version. This should be set when you import multiple versions.

  • root_version_id The id of the root version of the document.

  • target_type* The name of the Object Type associated in MC for the document. This can differ from the actual Type name in the Cara target system. (see cara_target_name)

    Example: cara_document

  • version_label* The document version labels. This is a multi-value rule because a document can have multiple labels.

  • version_no* The number of the document version in the version tree.

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 content.created attribute specifies the content creation.

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.

The rendition.identifier attribute can be set to a custom string.

The rendition.created attribute specified the rendition creation date.

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.

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

Setting Object Reference Attributes

To set Object Reference Attributes, add them in the Object Type like any regular attribute and associate them in the migset.

You have two options on how to set an object reference field:

  1. using the source_id: the id set through migration-center when importing a object.

  2. using the object_id: the Unique ID generated by CARA.

To use the object_id you need to prefix the ID with the tag TARGET_ID: Ex: For object_id = 1234 the value set in MC should be TARGET_ID:1234

Any value without the prefix will be assumed to be a source_id.

If the Object Reference attribute contains the ID of an object that is not currently present in Cara, the imported object will be set to Partially Imported and the Object Reference attribute will not be set. A warning message will be shown in the import log.

If the missing referenced objects are then imported you can reimport the original migset to set the Object Reference Attributes to the now existing objects. This will set the documents to Imported.

If the referenced object has Status = Hidden only the object_id can be used. Using the source_id will result in the imported objects being set to partially imported as if the referenced object does not exist.

The cara type definition must be replicated on migration-center as an object type. The importer is not able to identify the mandatory fields from cara, it will use the object type defined on migration-center.

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 or relation 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 Relations

Relations are supported by Cara Importer. They can currently be generated only by the Documentum Scanner, but technically it is possible to customize any scanner to compute the necessary information if similar data or close to Documentum relations can be extracted from their source systems.

Relations cannot be altered using transformation rules; migration-center will manage them automatically if the appropriate options in the scanner and importer have been selected. A connection between the parent object and its relations must always exist and can be viewed in migration-center by right-clicking on the object in any view of a migration set and selecting <View Relations> from the context menu. A grid with all the relations of the selected object will be displayed together with their associated metadata, such as relation name, child object, etc.

A parent object will be set as "Partially Imported" if its relation fails to import for any reason (missing child object, incorrect relation mapping etc). This means that the document has been imported but its relation has not. If the problem keeping the relation from being imported is fixed, the import can be ran again and, if successful, the document will be set to "Imported" (both the document and its relations have been imported).

Configure Relations Mapping File

The relation type of a relation that was scanned might have a different name from the relation type in Cara. In order to map the Source relation type to a Cara relation type a relations mapping file can be used. This file needs to be created as a text file but can have any custom extension. The path to this file must be set in the relationsMappingFile parameter of the Cara Importer. For example, a scan run from Documentum might have a relation type named mc_relation1 while in the Cara repository we might have a relation type named cara_relation1. The following line will need to be present in the mapping file in order to import the relation under the correct Cara relation type.

mc_relation1=cara_relation1

This mapping can be also done for multiple relation types. The example bellow maps two source relation types to the same Cara relation type and a third source relation type mapped to a different Cara relation type.

mc_relation1=cara_relation1
mc_relation2=cara_relation1
mc_relation3=cara_relation2

Version Label Binding

The child_label attribute of the source relation can be empty or have a value.

If child_label is empty, the binding between parent and child will be done to the version id specified in the attribute child_id.

If child_label is set, the binding between parent and child will be done to the version specified there. The child_id is set with the root version id (ichronicle_id) . The version label present in child_label will be set as it is or it will be mapped based on the Label Mapping File (see Configure Label Mapping File).

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.

  • attribute_list Attributes list with current values, from Documentum.

  • attribute_list_old Attributes list with old values, from Documentum.

  • audited_type* The type name of the audited object. Example: clinical_document

  • event The audit trail event.

  • object_id* The id of the audit trail. The object_id should be unique per object_type.

  • object_name* The name of the audit trail.

  • source_object_id* The source id of audited object.

  • time_stamp* The time when the event has happen.

  • type_name* The type name of the audit trail. Example: cara_audit_trail

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

Custom Properties Change Attributes

Custom Properties Change attributes for audit trails can be added, changed or removed through the transformation rules.

  • properties.added.[attribute_name] Adds a custom attribute with the name [attribute_name]. The value of this rule will be the value of the added attribute.

  • properties.changed.[attribute_name].old Changes the value of a custom attribute with the name [attribute_name]. The value of this rule will be the old value of the changed attribute.

  • properties.changed.[attribute_name].new Changes the value of a custom attribute with the name [attribute_name]. The value of this rule will be the new value of the changed attribute.

  • properties.removed.[attribute_name] Removes a custom attribute with the name [attribute_name].

These attributes need to be added to the object type that will be used for the migration set. You must then associate a transformation rule with the desired attribute for them to take effect.

The properties.[operation].[attribute_name] format needs to be respected when adding the attributes to the object type.

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

Last updated