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.
Known issues & limitations
Indexing is not set when importing documents with both "indexDocuments" and "asynchronousIndex" parameters checked (#59574)
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)
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
Configuration parametrs | Values |
Name | Enter a unique name for this importer Mandatory |
Adapter type | Select the "Cara" adapter from the list of available adapters Mandatory |
Location | Select the Job Server location where this job should be run. Job Servers are defined in the Jobserver window. If no Job Server was selected, migration-center will prompt the user to define a Job Server Location when saving the importer. Mandatory |
Description | Enter a description for this importer (optional) |
Cara Importer Parameters
Configuration paramters | Values |
restServiceUrl* | The URL of the Cara REST API. Example: http://migration.cara.cloud:8090/api Mandatory |
username* | Cara username. The user must have bulk import rights in Cara. Mandatory |
password* | The user's password. Mandatory |
proxyServer | The name or IP of the proxy server if there is any. |
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. Mandatory |
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:
|
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* | Sets the verbosity of the log file. 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 |
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.
System Rule | Description |
is_latest | Rule used to indicate if the document is the latest version in the version tree. Optional |
object_id* | The id of the document. The object_id should be unique per object type. Mandatory |
object_name* | The name of the document. Mandatory |
previous_version_id | The id of the document previous version. This should be set when you import multiple versions. Optional |
root_version_id* | The id of the root version of the document. Mandatory |
type_name* | The type name of the document. Example: cara_document Mandatory |
version_label | The document version labels. This is a multi-value rule because a document can have multiple labels. Mandatory |
version_no* | The number of the document version in the version tree. Mandatory |
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.
The rendition.identifier attribute can be set to a custom string.
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 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.
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.
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.
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.
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.
System Rule | Description |
attribute_list | Attributes list with current values, from Documentum. Optional |
attribute_list_old | Attributes list with old values, from Documentum. Optional |
audited_type* | The type name of the audited object. Example: clinical_document Mandatory |
event | The audit trail event. Mandatory |
object_id* | The id of the audit trail. The object_id should be unique per object_type. Mandatory |
object_name* | The name of the audit trail. Mandatory |
source_object_id* | The source id of audited object. Mandatory |
time_stamp* | The time when the event has happen. Mandatory |
type_name* | The type name of the audit trail. Example: cara_audit_trail Mandatory |
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
