› Modules and plugins › Export module › CMIS Export plugin

CMIS Export plugin

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.

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 need to configure settings on both Transact and the CMIS repository.

Transact

CMIS Repository

Configure CMIS Export plugin

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

  1. Go to the Batch Class Management.
  2. Select your batch class and click Open.
  3. Go to Modules > Export > CMIS_EXPORT.
  4. Edit the configurable properties for this plugin if required.

    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.

    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 is appended to the export file name, if not already present in the file name.
    These parameters can be used in the 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 such as: 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 user name used to generate tokens is example@abc.com.

    CMIS Version

    • 1.1
    • 1.0

    This property identifies the version of CMIS that the plugin uses for repository connection.

Configure the properties file

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

  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.

    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 Transact_Directory]\SharedFolders\ <batch_class >

    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 is 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.

    If you select "wssecurity", refer to 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 Transact_Directory]\SharedFolders\ <batch_class >

    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 is 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 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 earlier.

DLF-Attribute-mapping.properties

The file is located at [Ephesoft Transact_Directory]\SharedFolders\<batch-class>\cmis-plugin-mapping.

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.

CMIS 1.0 and CMIS 1.1 use the same mapping.

Mapping criteria

Map 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 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 it looks as follows:

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

The file is located at [Ephesoft_Directory]\SharedFolders\<batch-class> \cmis-plugin-mapping.

aspect-mapping.properties

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.

For more information, see the applicable topics:

CMIS 1.0 mapping criteria

Map 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 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" is populated into the aspect property cm:description.

Together it looks as follows:

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

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 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" is populated into the aspect property cm:description.

Map 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" is populated into the aspect property cm:description, and the value of document level field "City" is populated into the aspect property cm: longitude.

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

You can skip this section if you have used the Alfresco Model Manager tool to build out your model. Otherwise, you 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

    With this file, Alfresco knows 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 are mapped with Alfresco repository parameters.

The following is a sample entry in the ephesoftModel.xml 

<typename="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

Max allowed values are 999-999-999

For more information on property type mapping, see 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">

  2. 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>

  3. 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

  4. 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>

If the URL is not loading, the document type may not be correctly deployed in the Alfresco repository. If an error occurs while adding aspects to an uploaded document, fix the errors and restart the batch. The document should upload again. For more information, see 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

The following table includes 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.

Fix the URL in the dcma-cmis.properties file or update the security mode to "basic".

com.ephesoft.dcma.core.DCMAException: Unauthorized

Invalid user name or password.

Enter a valid user name 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

User name 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 database. 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 the 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 Transact 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>