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 |
|
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 |
|
This property governs whether CMIS Export Plugin will execute or not |
Aspect Switch | List of values |
|
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 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.
|
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: | 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 |
|
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 |
|
This is the document versioning state for uploading.
Default or in case of invalid option: CHECKEDOUT |
cmis.security.mode | List of values |
|
Specify the security mode employed by the CMIS endpoint. |
cmis.repo.create_batch_subfolders | List of values |
|
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
Or
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”. |
<type>d:text</type> |
- 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\*:
- chemistry-opencmis-client-api-0.10.0.jar
- chemistry-opencmis-client-bindings-0.10.0.jar
- chemistry-opencmis-client-impl-0.10.0.jar
- chemistry-opencmis-commons-api-0.10.0.jar
- chemistry-opencmis-commons-impl-0.10.0.jar
- alfresco-opencmis-extension-1.0.jar
- Paste following jar files from the HOT-FIX at [EphesoftInstallationDirectory]\Application\WEB-INF\lib\*:
- chemistry-opencmis-client-api-0.6.0.jar
- chemistry-opencmis-client-bindings-0.6.0.jar
- chemistry-opencmis-client-impl-0.6.0.jar
- chemistry-opencmis-commons-api-0.6.0.jar
- chemistry-opencmis-commons-impl-0.6.0.jar
- alfresco-opencmis-extension-0.2.jar
- 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 name=”ephesoft:partNumber”>
<type>d:text</type>
</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 name=”ephesoft:partNumber”>
<type>d:int</type>
</property>