CMIS Export Plugin

Overview

This plug-in is used for uploading PDF/TIFF file being generated as final output of batch execution to a CMIS compliant repository as ‘Document’ object. Currently Ephesoft supports Alfresco, Nuxeo, SharePoint, IBM CM, Documentum and all other CMIS compliant repositories.

Configuration

To upload documents and associated properties on the repository, user needs to configure configuration settings on following two ends:

Ephesoft
Repository

Ephesoft Configurable Properties

For CMIS configuration and mappings, user needs to make changes at following location:

CMIS_Export Plugin: This plugin is present in Export Module. It contains properties that deals with the repository configuration settings where the documents needs to be uploaded. These settings are done at Batch class level.

“Test CMIS” button tests the CMIS connection with the repository. A message will be displayed whether the connection can be established or not.

“Get Token” button is used to get token while using CMIS Auth.

Configurable property	Type of value	Value options	Description
CMIS Root folder Name	String	N-A	Name of the folder at CMIS repository where files will be exported.
CMIS Upload File Extension	List of values	pdf tiff	The extension of the files being uploaded.
CMIS Server URL	String	For example : http://{Server_ip}:{port_number}/alfresco/service/cmis for Alfresco 3.x with CMIS 1.0 http://{Server_ip}:{port_number}/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	The URL of the CMIS repository server. This URL varies for different repository like “Alfresco”, “Share point”, “Nuxeo” etc.
CMIS Server User Name	String	For example: “admin”	The username for CMIS repository server login.
CMIS Server User Password	String	For example: “admin”	The password for CMIS repository server login.
CMIS Server Repository Id	String	For example: “83b9c8bb-415e-46fd-9feb-c9fb8e4e2122” “-default-” for Alfresco 4.2d to Alfresco 5.x with CMIS 1.0 or CMIS 1.1.	Id of the CMIS repository used for uploading files.
CMIS Server Switch ON/OFF	List of values	ON OFF	This property governs whether CMIS Export Plugin will execute or not
Aspect Switch	List of values	ON OFF	This property governs whether Aspect has to be applied on the uploaded document or not. This property is specific to Alfresco repository.
CMIS Export File Name	String	For example: “$BATCH_IDENTIFIER” There are some patterns according to which user can add cmis Export file name. Following parameters can be added: BATCH_IDENTIFIER BATCH_CLASS BATCH_FIELD_VALUE DOCUMENT_TYPE DLF SERVER_NAME DATE TIME BATCH_IDENTIFIER: batch instance identifier BATCH_CLASS: batch class identifier BATCH_FIELD_VALUE: batch field value DOCUMENT_TYPE: document type DLF : denoting document level fields SERVER_NAME : server name DATE: date TIME: time	The name of the file to be uploaded. In case parameter is being used, then it must begin with ‘$’ symbol. Different fields must be separated by ‘&’ which will be replaced by empty string in the file name. Underscore can be added in the file name by using &_&. Similarly space, colon, hyphen, etc. can be added. By default, Document ID will be appended to the export file name, if not already present in the file name to ensure uniqueness. These parameters can be used in “CMIS Root folder Name” property as well.
CMIS Export Client Key	String	For example: I7xxada2542414e44b87a71c076c6ad5b513	Client key for getting Alfresco Oauth authentication from CMIS repository server.
CMIS Export Secret Key	String	For example: 3fafbfc4d43b49cfa3d6fb234ceea564	Secret key for getting Alfresco Oauth authentication from CMIS repository server.
CMIS Export Refresh Token	String	Empty string/value generated by Get Token button click.	Token generated by Alfresco OAuth authentication from CMIS repository server after login on click of Get Token button.
CMIS Export Redirect URL	String	For example: http://127.0.0.1:8090/Callback	The URL to generate login page for generation of refresh token for Alfresco OAuth authentication.
CMIS Export Network	String	For example: *abc.com* where username used in token generation is xyz.def@abc.com	The mail account server which is used in username when refresh token is created while using Alfresco OAuth authentication.
CMIS Version	List of values	1.1 1.0	This property identifies the version of CMIS used by the plugin for repository connection.

2. dcma-cmis.properties: This property file is present Ephesoft_Installation_Directory\Application\WEB-INF\classes\META-INF\dcma-cmis folder.

These settings are Application level settings.

Configurable property	Type of value	Value options	Description
cmis.document_versioning_state	List of values	NONE: The document will be created as a non-versionable document. CHECKEDOUT: The document MUST be created in the checked-out state. 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. Default or in case of invalid option: CHECKEDOUT
cmis.security.mode	List of values	“*basic” for HTTP Basic Authentication (default) “wssecurity*” for WS-Security Username Token based security.	Specify the security mode employed by the CMIS endpoint.
cmis.repo.create_batch_subfolders	List of values	true false	This is to specify whether or not a subfolder should be created for the batch within the configured target repository folder.
cmis.aspect_mapping_file_name	String	For example: aspects-mapping.properties This is the name of the aspect properties file present in Ephesoft_Installation_Directory\SharedFolders\{BatchClass}\cmis-plugin-mapping folder ”.	Property file where aspect mapping is defined for the documents to be uploaded to CMIS repository.
cmis.plugin_mapping_file_name	String	For example: DLF-Attribute-mapping.properties This is the name of the DLF properties file present in Ephesoft_Installation_Directory\SharedFolders\{BatchClass}\cmis-plugin-mapping folder ”.	Property file where document’s properties mapping is defined for the documents to be uploaded to CMIS repository.
cmis.date_format	String	For example: MM/dd/yyyy	This property specifies the format of the value of DLF having DATE datatype being used for mapping.

Specify the WSDL URL’s for each of the CMIS services if “wssecurity” is specified for the value of the “cmis.security.mode” property. The text {serverURL} may be inserted into the path if you wish to have the batch class configured server URL to be used for part of the URL.

Example:

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

cmis.url.acl_service={serverURL}/ACLService?wsdl, where {serverURL} is the CMIS server URL configured within the batch class.

Similarly following properties are set for wssecurity:

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

Mapping Files: Each Batch class contains following 2 mapping files inside Ephesoft_Installation_Directory\SharedFolders\{Batch Class}\cmis-plugin-mapping folder, file names can be configured using properties described above:
DLF-Attribute-mapping.properties: For document mapping.
aspects-mapping.properties: For aspect mapping.

DLF-Attribute-mapping.properties:
This property file is used to map Ephesoft Document Types to Alfresco Document types and Ephesoft Document Level Fields to Alfresco document properties.
For document type mapping, D: is used.
The mapping is same for CMIS v1.0 and CMIS v1.1.

Mapping criteria:

User can map Ephesoft document types to Alfresco documents by adding the name of the Ephesoft document type as key and Alfresco documents as the value.

e.g.: Application-Checklist= D:ephesoft:ephesoft

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

User can map Ephesoft document level fields to Alfresco document properties. This can be done by using the key as “{DocumentType}.{DocumentLevelFieldName}” and the value as the corresponding document property.

e.g.: Application-Checklist.InvoiceDate=ephesoft:invoiceDate

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

Example:

Application-Checklist=D:ephesoft:ephesoft

Application-Checklist.InvoiceDate=ephesoft:invoiceDate

Application-Checklist.PartNumber=ephesoft:partNumber

where,

Application-Checklist: Ephesoft Document Type

InvoiceDate, PartNumber: Ephesoft Field Type/Index Field

ephesoft: Alfresco Document Type

invoiceDate, partNumber: Alfresco Document Properties

aspects-mapping.properties:
This property file is used to map Ephesoft Document Types to Alfresco Aspect types and Ephesoft Document Level Fields to Alfresco aspect properties.
For aspect type mapping, P: is used.
The mapping is different for CMIS v1.0 and CMIS v1.1.

Mapping criteria for CMIS v1.0:

User can map Ephesoft document types to multiple aspects (separated via semicolon). This is done by adding the name of the Ephesoft document type as key and Alfresco aspects as the value.

e.g.: Application-Checklist=P:cm:titled;P:cm:taggable

In this example user is adding two aspects: “P:cm:titled” and “P:cm:taggable” to all documents with document type “Application-Checklist”.

User can map document level fields to aspect properties. This can be done by using the key as “{DocumentType}.{DocumentLevelFieldName}” and the value as the corresponding aspect property.

NOTE: The P: property identifies the aspect, and the item that follows the pipe sign identifies a property underneath that aspect. cm:description is a property of the cm:titled aspect in Alfresco, not cm:taggable. In the above example, defining both the aspects is necessary.

e.g.: Application-Checklist.State=cm:description

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

Example:

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

Application-Checklist.State=cm:description

where,

Application-Checklist: Ephesoft Document Type

State: Ephesoft Field Type/Index Field

titled, taggable: Alfresco Aspect Type

description: Alfresco Aspect Properties

(semicolon is used as separator between multiple aspect mapping)

Mapping criteria for CMIS v1.1:

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

e.g.: Application-Checklist= P:cm:taggable|State::cm:description

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

e.g.:

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

In this example user is adding aspect “P:cm:taggable” & “P:cm:geographic” to all documents with document type “Application-Checklist”. Also, the value of document level field “State” will be populated into the aspect property “cm:description” of aspect “P:cm:taggable” and the value of document level field “City” will be populated into the aspect property “cm: longitude” of aspect “P:cm:geographic”

“|” is separator between aspect name and corresponding mapped aspect properties.
Semicolon is used as separator between multiple aspect mapping

Note: In case there is space in the name of the Document or in Document Level Fields, then escape it with “\ “character. Eg: Application-Check\ list.State=ephesoft:city

Alfresco Configurable Properties

There are three configuration files which should be placed at the Alfresco installation directory’s following path :< 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 configurations file for stating the parameters (Document level index fields) that will be mapped with alfresco repository parameters.

Sample entries in 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

Reference Links: http://wiki.alfresco.com/wiki/Data_Dictionary_Guide#Data_Types, http://wiki.alfresco.com/wiki/CMIS_Model_Mapping#Property_Type_Mapping

Ephesoft Data Type	Alfresco data type	Alfresco Property Type mapping (Internally Converted to)	Comments (If any)
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: 999-999-999

Checklist

Mapping of document types in DLF-Attribute-mapping.properties file should be equivalent to type defined in model file in Alfresco repository.

DLF-Attribute-mapping.properties	ephesoftModel.xml
Application-Checklist=D:ephesoft:ephesoft	<type name=”ephesoft:ephesoft”>

Data Type of document level fields defined in DLF-Attribute-mapping.properties file should be equivalent to the types of document attributes defined in ephesoftModel.xml file in Alfresco repository.

DLF-Attribute-mapping.properties

ephesoftModel.xml

Application-Checklist.InvoiceDate

The datatype from Ephesoft Application should be of type “String”.

While browsing the Alfresco repository, user should be able to view the available document types via the following URL: http://127.0.0.1:8181/alfresco/cmisbrowse?url=http://127.0.0.1:8181/alfresco/service/cmis/types/descendants

(Update the server IP address and port number accordingly in the above URL.)

While browsing the Alfresco repository, user should be able to view the available Document attributes for a given document type via the following URL: http://127.0.0.1:8181/alfresco/cmisbrowse?url=http://127.0.0.1:8181/alfresco/service/cmis/type/D:ephesoft:ephesoft

(Update the server IP address and port number accordingly in the above URL. Please replace the {D:ephesoft:ephesoft} text with the given document type.)

In case the URL is not loaded, then one can infer the document type is not correctly deployed at Alfresco repository. In case an error is encountered while adding aspects to an uploaded document, the user will have to restart the batch after correcting the errors due to which the error was encountered, and the document will be uploaded again.

For more information on aspects, please refer to the link: http://wiki.alfresco.com/wiki/Aspect

Using Alfresco version before 4.2d:

To use Alfresco before 4.2d Repositories for Ephesoft v4.0.x.y (prior to v4.0.3.0), user needs to apply a HOT-FIX available at https://ephesoft.com/docs/cmis-1-1foralfresco42dorhigher . Steps to apply hot-fix is as follows:

Stop the Ephesoft server.
Remove following listed JARs from [EphesoftInstallationDirectory]\Application\WEB-INF\lib\*:
1. chemistry-opencmis-client-api-0.10.0.jar
2. chemistry-opencmis-client-bindings-0.10.0.jar
3. chemistry-opencmis-client-impl-0.10.0.jar
4. chemistry-opencmis-commons-api-0.10.0.jar
5. chemistry-opencmis-commons-impl-0.10.0.jar
6. alfresco-opencmis-extension-1.0.jar
Paste following jar files from the HOT-FIX at [EphesoftInstallationDirectory]\Application\WEB-INF\lib\*:
1. chemistry-opencmis-client-api-0.6.0.jar
2. chemistry-opencmis-client-bindings-0.6.0.jar
3. chemistry-opencmis-client-impl-0.6.0.jar
4. chemistry-opencmis-commons-api-0.6.0.jar
5. chemistry-opencmis-commons-impl-0.6.0.jar
6. alfresco-opencmis-extension-0.2.jar
7. dcma-cmis*.jar
Restart Server.

Note: After this change JAR files, user can use only alfresco versions below Alfresco 4.2d onwards with CMIS 1.1. They cannot use newer versions of Alfresco or CMIS 1.1.

Dependency

The plugin runs after Create Multi Page Files Plugin in Export Module. The plugin assumes that the multipage tiff/pdf has been successfully generated for the batch and uploads the multipage tiff/pdf to the CMIS repository.

Troubleshooting

Following are few common error messages observed due to mal-functioning:

S no.	Error message	Possible root cause
1	com.ephesoft.dcma.core.DCMAException: Not Found	Alfresco server URL is invalid.
2	com.ephesoft.dcma.core.DCMAException: Repository not found!	Repository ID is invalid.
3	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. Solution: Either updates it to basic or corrects the URL in {dcma-cmis.property} file.
4	com.ephesoft.dcma.core.DCMAException: Unauthorized	Invalid user name or password.
5	Server URL is null/empty from the data base. Invalid initializing of properties.	Server URL is empty or not mapped to database.
6	Server User Name is null/empty from the data base. Invalid initializing of properties	User name is Empty or not mapped to database.
7	Server User Password is null/empty from the data base. Invalid initializing of properties.	Password is empty or not mapped to database.
8	UploadFileTypeExt is null/empty from the data base. Invalid initializing of properties	Upload file type extension is empty or not mapped to database.
9	RootFolder is null/empty from the data base. Invalid initializing of properties.	Root Folder is empty or not mapped to database.
10	org.apache.chemistry.opencmis.commons.exceptions.CmisConstraintException: Conflict	Files already exist in the specified folder hierarchy. Please try deleting old files.
11	java.lang.IllegalArgumentException: Object Id must be set!	Unable to create folder in the specified hierarchy.
12	CMISExporter – Bad Request issue	Mapping defined in DLF-Attribute-mapping.properties file is not the same as mapping defined in content model at Alfresco repository.
13	CMISExporter – Property ‘ephesoft:partNumber’ is a String property” from Alfresco repository.	Mismatch in the type of Document Level fields defined in Ephesoft application and those defined in the Alfresco content model. NOTE: Detailed description of error #13 is below.

Description of error #13

User may have following mappings defined in Alfresco content model:-

</property>

(“partNumber” mapped as “text” type.)

Let assume that this property is mapped to type INT in Ephesoft application. So, there will be a mismatch resulting in the following error:

“CMISExporter – Property ‘ephesoft:partNumber’ is a String property”

Correction: Update the content model in Alfresco repository with appropriate data types. (For further reference of data type mappings, please refer following link. http://wiki.alfresco.com/wiki/Data_Dictionary_Guide#Data_Types)

</property>