Transact

⌘K
  1. Home
  2. Transact
  3. Features and Functions
  4. Administrator Role and Fe...
  5. Modules and Plugins
  6. Export Module
  7. CMIS Export Plugin

CMIS Export Plugin

Available: on-premises, cloud

The CMIS Export plugin is used to upload the final output of batch execution (PDF or TIFF files) to a CMIS-compliant repository as a “Document” object.

Ephesoft Transact supports most CMIS-compliant repositories, including the following:

  • Alfresco
  • Nuxeo
  • SharePoint
  • IBM CM
  • Documentum

To upload documents and associated properties on the repository, you will need to configure settings on both Ephesoft Transact and the CMIS repository.

Ephesoft Transact

CMIS Repository

Configure CMIS Export Plugin

This section provides information on how to configure the CMIS_EXPORT plugin. This plugin only needs to be configured once per batch class.

Perform the following steps to navigate to the plugin:

  1. Go to the Batch Class Management page.
  2. Select your batch class and click Open.
  3. Go to Modules > Export > CMIS_EXPORT.

Figure 1. CMIS Export Plugin

The following are the configurable properties for this plugin.

Configurable property Value options Description
CMIS Root Folder Name N/A Name of the folder in the CMIS repository where files will be exported, relative to the root folder of the repository.
CMIS Upload File Extension
  • PDF
  • TIFF
The extension of the files being uploaded.
CMIS Server URL N/A

The URL of the CMIS repository server, which varies for different repositories.

Examples:

  • http://<Server_IP>:<port>/alfresco/service/cmis for Alfresco 3.x with CMIS 1.0
  • http://<Server_IP>:<port>/alfresco/cmisatom for Alfresco 4.x with CMIS 1.0
  • http://<hostname>:<port>/alfresco/api/-default-/public/cmis/versions/1.1/atom for Alfresco 4.2d to Alfresco 5.x used with CMIS 1.1
  • http://<hostname>:<port>/alfresco/api/-default-/public/cmis/versions/1.0/atom for Alfresco 4.2d to Alfresco 5.x used with CMIS 1.0
CMIS Server User Name N/A

The username for CMIS repository server login.

For example, “admin”.

CMIS Server User Password N/A The password for CMIS repository server login.
CMIS Server Repository Id N/A

The ID of the CMIS repository used for uploading files.

Examples:

  • “83b9c8bb-415e-46fd-9feb-c9fb8e4e2122”
  • “-default-” for Alfresco 4.2d and above using CMIS 1.0 or CMIS 1.1.
CMIS Server Switch ON/OFF
  • ON
  • OFF
The switch to turn the CMIS Export plugin on or off.
Aspect Switch
  • ON
  • OFF

This property determines whether the aspect should be applied to the uploaded document or not.

Note: This property is specific to Alfresco repositories.

CMIS Export File Name N/A

The name of the file to be uploaded.

  • If the file name is the same as a parameter, then it must begin with the dollar ($) symbol.
  • Different fields must be separated by an ampersand (&), which will be replaced by an empty string in the file name.
  • Underscore can be added in the file name by surrounding the underscore with ampersands ( & _ & ). The same logic applies for spaces, colons, and hyphens.
  • By default, the document ID will be appended to the export file name, if not already present in the file name.

Note: These parameters can be used in “CMIS Root Folder Name” property as well.

Examples:

  • $BATCH_IDENTIFIER
  • $BATCH_CLASS
  • $BATCH_FIELD_VALUE
  • $DOCUMENT_TYPE
  • $DLF
  • $SERVER_NAME
  • $DATE
  • $TIME

For example,

$DLF:USDOTNumber & _ & $DLF:DBAName & _ & $DOCUMENT_TYPE & _ &

$BATCH_IDENTIFIER & _ & $DOCUMENT_ID

Where,

  • “$DLF:USDOTNumber” is 11223344
  • “$DLF:DBAName” is ACME Trucking
  • “$DOCUMENT_TYPE” is MCS-150B
  • “$BATCH_IDENTIFIER” is BI123
  • “$DOCUMENT_ID” is DOC1

Would result in a file name like:

11223344_ACME Trucking_MCS-150B_BI123_DOC1.pdf

CMIS Export Client Key N/A Client key for getting Alfresco OAuth authentication from the CMIS repository server.
CMIS Export Secret Key N/A Secret key for getting Alfresco OAuth authentication from CMIS repository server.
CMIS Export Refresh Token Click Get Token to get this value. Token generated by Alfresco OAuth authentication from CMIS repository server after login.
CMIS Export Redirect URL N/A

The URL to generate a login page for refresh tokens. This applies to Alfresco OAuth authentication.

For example, http://127.0.0.1:8090/Callback

CMIS Export Network N/A

The domain portion of the email account used to create the refresh token. This applies to Alfresco OAuth authentication.

For example, abc.com when the username used to generate tokens was example@abc.com.

CMIS Version
  • 1.1
  • 1.0
This property identifies the version of CMIS the plugin will use for repository connection.

Configure Properties File

This section provides information on how to configure the dcma-cmis.properties file.

  1. Open the dcma-cmis.properties file, located at [Ephesoft_Directory]\Application\WEB-INF\classes\META-INF\dcma-cmis.
  2. Configure the properties file according to your workflow needs. The following table provides more information on each property and their available options.

Note: The settings in this file make changes at the Application level.

Configurable property Value options Description
cmis.plugin_mapping_file_name The name of the DLF properties file present in the cmis-plugin-mapping folder, located at [Ephesoft_Directory]\SharedFolders\<batch_class>\cmis-plugin-mapping.

Property file where the document properties mapping is defined for the documents to be uploaded to the CMIS repository.

For example, DLF-Attribute-mapping.properties.

cmis.date_format N/A

This property specifies the format of the DLF value using the DATE data type for mapping.

For example,

MM/dd/yyyy

cmis.document_versioning_state
  • NONE: The document will be created as a non-versionable document
  • CHECKEDOUT: The document must be created in the “checked-out” state (default)
  • MAJOR: The document must be created as a major version
  • MINOR: The document must be created as a minor version
This is the document versioning state for uploading.
cmis.security.mode
  • basic: for HTTP Basic Authentication (default)
  • wssecurity: for WS-Security username token-based security
  • oauth: for OAuth2.0 using Alfresco

Specify the security mode employed by the CMIS endpoint.

Important: If you select “wssecurity”, refer to the section WS-Security Mode for more required configurations.

cmis.repo.create_batch_subfolders
  • true
  • false
This specifies whether or not a subfolder should be created for the batch within the configured target repository folder.
cmis.aspect_mapping_file_name This is the name of the aspect properties file present in the cmis-plugin-mapping folder, located at [Ephesoft_Directory]\SharedFolders\<batch_class>\cmis-plugin-mapping.

Property file where aspect mapping is defined for the documents to be uploaded to CMIS repository.

For example,

aspects-mapping.properties

cmis.export_retry N/A The number of times the export will be attempted.
cmis.export_retry_interval N/A The amount of time in milliseconds between retry attempts.

WS-Security Mode

If you set the cmis.security.mode property to “wssecurity”, you will also need to specify the Web Service Definition Language (WSDL) URL for each CMIS service.

If you want the batch class configured server URL to be used for part of the URL, insert “{serverURL}” in the path. For example,
cmis.url.acl_service={serverURL}/ACLService?wsdl
Or the following, where “{serverURL}” is the CMIS server URL configured within the batch class.

cmis.url.acl_service=http://hostname:8080/alfresco/soap/ACLService?wsdl

Similarly, the following properties are set for WS-Security:

cmis.url.discovery_service=http://localhost:8181/alfresco/cmisws/DiscoveryService?wsdl

cmis.url.multifiling_service=http://localhost:8181/alfresco/cmisws/MultiFilingService?wsdl

cmis.url.navigation_service=http://localhost:8181/alfresco/cmisws/NavigationService?wsdl

cmis.url.object_service=http://localhost:8181/alfresco/cmisws/ObjectService?wsdl

cmis.url.policy_service=http://localhost:8181/alfresco/cmisws/PolicyService?wsdl

cmis.url.relationship_service=http://localhost:8181/alfresco/cmisws/RelationshipService?wsdl

cmis.url.repository_service=http://localhost:8181/alfresco/cmisws/RepositoryService?wsdl

cmis.url.versioning_service=http://localhost:8181/alfresco/cmisws/VersioningService?wsdl

Configure Mapping Files

Each batch class contains the following two mapping files in the cmis-plugin-mapping folder:

File names can be configured using the properties described above.

DLF-Attribute-mapping.properties

Located at [Ephesoft_Directory]\SharedFolders\<batch-class>\cmis-plugin-mapping.


Figure 2. DLF-Attribute-mapping.properties File

This property file is used to map Transact document types to Alfresco document types, and Transact document level fields to Alfresco document properties.

Note: CMIS 1.0 and CMIS 1.1 use the same mapping.

Mapping Criteria

Map Ephesoft Transact document types to Alfresco documents

  • Set the key to the name of the Transact document type.
  • Set the value to the name of the Alfresco document.
  • Use the “D:” property to identify the Alfresco document.

For example,

Application-Checklist=D:ephesoft:ephesoft

In this example you are mapping all documents with the document type “Application-Checklist” to the Alfresco document “D:ephesoft:ephesoft”.

Map Ephesoft Transact document level fields to Alfresco document properties

  • Set the key as “{DocumentType}.{DocumentLevelFieldName}”.
  • Set the value as the corresponding Alfresco document property.

For example,

Application-Checklist.InvoiceDate=ephesoft:invoiceDate

In this example you are specifying that for all documents with the document type “Application-Checklist”, the value of the document level field “InvoiceDate” will be populated in the Alfresco document property: “ephesoft:invoiceDate”.

Together this might look like the following:

Application-Checklist=D:ephesoft:ephesoft

Application-Checklist.InvoiceDate=ephesoft:invoiceDate

Application-Checklist.PartNumber=ephesoft:partNumber

Here is the preceding example broken down into its respective parts:

  • Transact Document Type: “Application-Checklist”
  • Transact Index Fields: “InvoiceDate” and “PartNumber”
  • Alfresco Document Type: “ephesoft”
  • Alfresco Document Properties: “invoiceDate, partNumber”

aspects-mapping.properties

Located at [Ephesoft_Directory]\SharedFolders\<batch-class>\cmis-plugin-mapping.


Figure 3. aspect-mapping.properties File

This property file is used to map Transact document types to Alfresco aspect types, and Transact document level fields to Alfresco aspect properties.

CMIS 1.0 and CMIS 1.1 use different mappings. Refer to the section applicable to you for more information:

CMIS 1.0 Mapping Criteria

Map Ephesoft Transact document types to Alfresco aspects

  • Set the key as the name of the Transact document type.
  • Set the value as the Alfresco aspects.
  • Use the “P:” property to identify the aspect.
  • Separate each aspect with a semicolon (;).

Application-Checklist=P:cm:titled;P:cm:taggable

In this example, you are adding two aspects—“P:cm:titled” and “P:cm:taggable”—to all documents with the document type “Application-Checklist”.

Map Ephesoft Transact document level fields to Alfresco aspect properties

  • Set the key as “{DocumentType}.{DocumentLevelFieldName}” and the value as the Alfresco aspect property.
  • Use the “P:” property to identify the aspect.

Application-Checklist.State=cm:description

In this example, you are specifying that for all documents with document type “Application-Checklist”, the value of the document level field “State” will be populated into the aspect property “cm:description”.

Together this might look like the following:

Application-Checklist=P:cm:titled;P:cm:taggable

Application-Checklist.State=cm:description

Here is this example broken down into its respective parts:

  • Transact Document Type: “Application-Checklist”
  • Transact Index Field: “State”
  • Alfresco Aspect Type: “titled” and “taggable”
  • Alfresco Aspect Property: “description”

Notice that a semicolon (;) is used to separate multiple aspect mappings.

CMIS 1.1 Mapping Criteria

This configuration can be used for Alfresco 4.2d onwards and all other CMIS compliant repositories.

Map Ephesoft Transact document types to Alfresco aspects

  • Set the key as the name of the Transact document type.
  • Set the value as the Alfresco aspects.
  • Use the “P:” property to identify the aspect.
  • Separate aspect names and corresponding mapped aspect properties with a pipe (|).

Application-Checklist=P:cm:taggable|State::cm:description

In this example you are adding the aspect “P:cm:taggable” to all documents with document type “Application-Checklist”. Also, the value of the document level field “State” will be populated into the aspect property “cm:description”.

Map Ephesoft Transact document level fields to Alfresco aspect properties

  • Separate aspect names and the corresponding mapped aspect properties with a pipe (|).
  • Separate each mapped aspect and aspect property pair with a semicolon (;).

Application-Checklist=P:cm:taggable|State::cm:description;P:cm:geographic|City::cm:longitude

In this example you are adding two aspects—“P:cm:taggable” and “P:cm:geographic”—to all documents with document type “Application-Checklist”. The value of document level field “State” will be populated into the aspect property “cm:description”, and the value of document level field “City” will be populated into the aspect property “cm: longitude”.

Note: If your document type name or document level field contains spaces, escape the space with a backslash (\) character. For example,

Application-Check\ list.State=ephesoft:city

Alfresco Configurable Properties

Note: You can skip this section if you have used the Alfresco Model Manager tool to build out your model. Otherwise, you may need to build the following property files manually.

There are three configuration files which should be placed in the Alfresco extension folder, located at [Alfresco_Installation_Path]/tomcat/shared/classes/alfresco/extension.

  • web-client-config-custom.xml: Alfresco automatically looks for this file on the class path in the alfresco.extension package for configuration. This file is not mandatory.
  • ephesoft-model-context.xml: To let Alfresco know which model files need to be loaded. Any file ending with “-context.xml” is used to tell the location of the custom configuration file.
  • ephesoftModel.xml: The custom configuration file for stating the parameters (index fields) that will be mapped with Alfresco repository parameters.

The following is a sample entry in the ephesoftModel.xml file:

<type name="ephesoft:ephesoft">

<title>Ephesoft Document Procedure</title>

<parent>cm:content</parent>

<properties>

<property name="ephesoft:invoiceDate">

<type>d:text</type>

</property>

<property name="ephesoft:partNumber">

<type>d:text</type>

</property>

<property name="ephesoft:invoiceTotal">

<type>d:text</type>

</property>

<property name="ephesoft:state">

<type>d:text</type>

</property>

<property name="ephesoft:city">

<type>d:text</type>

</property>

</properties>

</type>

Mappings of Data Types

The following table provides a brief overview of data type mappings and conversions.

Transact Data Type Alfresco Data Type Alfresco Property Type Mapping (Internally Converted to)
STRING d:text String
INTEGER d:int Integer
FLOAT d:float Decimal
DOUBLE d:double Decimal
DATE d: datetime DateTime
BOOLEAN d: boolean Boolean
LONG d: long

Integer

Note: Max allowed values are 999-999-999

For more information on property type mapping, refer to the following Alfresco documentation: CMIS Model Mapping.

Checklist

Refer to the following checklist to ensure your property files are correctly mapped.

  1. Transact document types in the DLF-Attribute-mapping.properties file are mapped to their Alfresco equivalents. Alfresco equivalents are defined in the ephesoftModel.xml file in the Alfresco repository.
DLF-Attribute-mapping.properties ephesoftModel.xml
Application-Checklist=D:ephesoft:ephesoft <type name=”ephesoft:ephesoft”>
  1. Transact document level fields defined in the DLF-Attribute-mapping.properties file are mapped to the equivalent Alfresco attributes. Alfresco attributes are defined in the ephesoftModel.xml file in Alfresco repository.
DLF-Attribute-mapping.properties ephesoftModel.xml

Application-Checklist.InvoiceDate

The Transact data type should be “String”.

<type>d:text</type>
  1. You are able to view the available document types while browsing the Alfresco repository from the following URL: http://<IP_Address>:<Port_Number>/alfresco/cmisbrowse?url=http://<IP_Address>:<Port_Number>/alfresco/service/cmis/types/descendants
  2. While browsing the Alfresco repository, you are also able to view the available document attributes for a given document type from the following URL: http://<IP_Address>:<Port_Number>/alfresco/cmisbrowse?url=http://<IP_Address>:<Port_Number>/alfresco/service/cmis/type/<Document_Type>

Note: If the URL doesn’t load, the document type may not be correctly deployed in the Alfresco repository. If an error occurs while adding aspects to an uploaded document, correct the errors and restart the batch. The document should upload again. For more information, refer to About aspects from Alfresco.

Dependency

The plugin runs after the CREATEMULTIPAGE_FILES plugin in the Export module. The plugin assumes that the multipage TIFF or PDF has been successfully generated for the batch, and uploads the multipage file to the CMIS repository.

Troubleshooting

Following are some common error messages and their possible root causes.

Error Message Possible Root Cause Possible Solution
com.ephesoft.dcma.core.DCMAException: Not Found Alfresco server URL is invalid. Update with the correct server URL.
com.ephesoft.dcma.core.DCMAException: Repository not found! Repository ID is invalid. Update with the correct repository ID.

Cannot initialize Web Services service object [org.apache.chemistry.opencmis.binding.webservices.RepositoryService]: Failed to access the WSDL at: http://localhost:8181/alfresco/cmisws/RepositoryService?wsdl. It failed with:

Connection refused: connect.

Invalid URL for wssecurity. Correct the URL in the dcma-cmis.properties file, or update the security mode to “basic”.
com.ephesoft.dcma.core.DCMAException: Unauthorized Invalid username or password. Enter a valid username and password.
Server URL is null/empty from the data base. Invalid initializing of properties. Server URL is empty or not mapped to the database.
Server User Name is null/empty from the data base. Invalid initializing of properties Username is empty or not mapped to the database.
Server User Password is null/empty from the data base. Invalid initializing of properties. Password is empty or not mapped to the database.
UploadFileTypeExt is null/empty from the data base. Invalid initializing of properties Upload file type extension is empty or not mapped to the database.
RootFolder is null/empty from the data base. Invalid initializing of properties. Root Folder is empty or not mapped to the database.
org.apache.chemistry.opencmis.commons.exceptions.CmisConstraintException: Conflict Files already exist in the specified folder hierarchy. Delete or rename the older files.
java.lang.IllegalArgumentException: Object Id must be set! Unable to create a folder in the specified hierarchy.
CMISExporter – Bad Request issue Mapping defined in DLF-Attribute-mapping.properties file is not the same as mapping defined in the content model at Alfresco repository.
CMISExporter – Property ‘ephesoft:partNumber’ is a String property” from Alfresco repository. Mismatch in the type of document level fields defined in Transact and those defined in the Alfresco content model.

You may have “partNumber” mapped as “text” type in the Alfresco content model:

<property name=”ephesoft:partNumber”>

<type>d:text</type>

</property>

If this property is mapped to type INT in the Ephesoft application, there will be a mismatch.

Update the content model in Alfresco repository with appropriate data types.

<property name=”ephesoft:partNumber”>

<type>d:int</type>

</property>

Articles