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:

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

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>

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

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

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 http://wiki.ephesoft.com/cmis-1-1foralfresco42dorhigher . Steps to apply hot-fix is as follows:

  1. Stop the Ephesoft server.
  2. 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
  3. 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
  4. 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>

Was this article helpful to you?

Engineering

Comments are closed.