Cara Importer
Last updated
Last updated
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.
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.
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.
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) |
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. |
language | The user's local language. If no value is provided the default value ("en") will be used. This parameter is used 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. NOTE: The root folder of the FTP server must point to staging folder on the server so fileTransferFolder must be set with a relative folder to the root folder. |
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. |
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 |
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=""
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.
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. Optional |
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.
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.
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 attribute content.checksum should be set with the MD5 checksum of the document content. If the provided MD5 checksum does not match the checksum calculated by the server during the import an error message is reported to the user.
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.
The rendition.type attribute specifies the document rendition MIME type.
Cara Importer allows checksum validation for document renditions. To use this feature, the attribute rendition.checksum should be set with document rendition checksum.
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.
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.
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.
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.
Cara importer allows importing audit trails that are related to the imported documents. For that, a migset of type toCara(audittrail) must be created. The audit trail entries are imported in a custom data type which name is specified in the system rule "type_name". The reference to audited document is kept by setting an attribute designated for this goal. Ex: audited_obj_id.
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 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
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
