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 a ‘document’ object. Currently the application is supporting Alfresco, Nuxeo, Documentum, IBM FileNet P8, SharePoint and IBM CM repository.

Configuration

Ephesoft Configurable Properties

  • Edit the configurations in CMIS Export Plugin as follows:

 

400px-3.1_CMIS_Export_Plugin_10001

 

400px-3.1_CMIS_Export_Plugin_10002

 

  • Following is the list of configurable properties for the plugin:

 

Configurable property Type of value Value options Description
Cmis Root folder
Name
String NA Name of the folder at Cmis repository.
Cmis Upload
File Extension
List of
values
pdf
tiff
Extension format for uploading file.
Cmis Server URL String For example : http://{Server_ip}:{port_number}/alfresco/service/cmis The url of the Cmis repository server. This URL varies for different repositories like Alfresco,Share point, documentum, 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 Id of the Cmis repository used for uploading files.
Cmis Server
Switch ON/OFF
List of
values
ON
OFF
This property tells whether CMIS Export Plugin has to work or not.
Aspect Switch List of
values
ON
OFF
This property tells whether
Aspect is added and applied on the uploaded document or not on Cmis repository via Ephesoft. This property is specific to Alfresco repository.
Cmis Export File Name String For example:
"EphesoftBatchID && _ && $EphesoftDOCID"
The name of the file to be uploaded.

Must contain one or more parameters out of – EphesoftBatchID/ EphesoftDOCID /a document level field name. A parameter name must begin with '$' symbol. Different fields must be separated by '&&'.
If none specified, name of the local folder to be exported is used to get filename to be exported.
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.

 

Documentum Repository Configurable Properties

  • CMIS Server URL: [ http://]<host address>:<port_of_emc-cmis>/emc cmis/resources/repositories/Repository_id

 

  • Repository id is the repository name and can be extracted from a xml file which can be downloaded by hitting URL:  [ http://]<host address>:<port_of_emc-cmis>/?repositoryId=RepositoryName
  • To create/edit configuration types in Documentum, use Eclipse plugin for WebTop Development Kit  (Please refer following link:

http://marketplace.eclipse.org/content/documentum-webtop-development-kit). Create a type corresponding to Ephesoft’s Document Type to be used in CMIS as a child of dm_document type and add attributes which corresponds to DLFs in Ephesoft’s Document type.

  • Following are the steps for viewing Documentum Repository configurations:
    • Users use Documentum Administrator to explore uploaded files and to create types in Documentum Repository.
    • URL to access Documentum Administrator is http[[://<host address>:< port_of_da>/da]]
    • It will ask for login credentials to repository.
    • After successful login, user can select a type under Repository/Administration/Types to view its properties and attributes :

 

400px-3.1_CMIS_Export_Plugin_10003

 

Figure: Showing access to properties of a type in Repository

  • DLF-Attribute-mapping.properties(located at [EphesoftInstallationDirectory]\SharedFolders\[Batch-class-Folder]\cmis-plugin-mapping):

DocumentTypeName=DocumentumTypeName DocumentTypeName.FieldTypeName1=Documentum’sType’sAttributeName1 DocumentTypeName.FieldTypeName2=Documentum’sType’sAttributeName2 DocumentTypeName.FieldTypeName3=Documentum’sType’sAttributeName3

A sample file content is:

INV=invoice

INV.inv_num=inv_num

INV.inv_amount=inv_amount

INV.inv_date=inv_date

  • Uploaded documents can be viewed at Repository/Administrator/Cabinets/*location in Documentum Administrator:

 

400px-3.1_CMIS_Export_Plugin_10004

 

Figure: Showing an uploaded document via Ephesoft

 

  • The properties of uploaded batch can be viewed by following by right click on uploaded file and selecting Properties.

 

400px-3.1_CMIS_Export_Plugin_10005

 

Figure:Showing access to properties of an uploaded document

 

400px-3.1_CMIS_Export_Plugin_10006

 

Figure: Properties of an uploaded document.

 

  • Properties in dcma-cmis.properties file located at  [EphesoftInstallationDirectory]\Application\WEB-INF\classes\META-INF\dcma-cmis\* are similar to for Alfresco Repository (Refer ‘dcma-cmis.properties’  for Alfresco specified below).

 

 (NOTE: If wssecurity is used, URL that returns a page that containing a list of web services is: [ http://]<host address>:<port_of_emc-cmis>/emc-cmis/services/RepositoryService).

Alfresco Configurable Properties

There are configuration files which should be placed at the Alfresco installation directory’s following path :< Alfresco installation path>\tomcat\shared\classes\alfresco\extension

  • There are three configuration files used in Ephesoft to map parameters:
    • web-client-config-custom.xml: Alfresco automatically looks for this file on the class path in the alfresco.extension package for configuration.
    • ephesoft-model-context.xml: To tell the location of the custom configuration file (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>

  • A default xml file is available with the Ephesoft release.

 

  • DLF-Attribute-mapping.properties:

 

  • The properties file used to get the mapping of parameters onto alfresco custom parameters i.e. mapping of Ephesoft specific Document Types to Alfresco Document Types and Ephesoft specific Document Level Fields to Alfresco specific Document Level Fields.
  • Sample entries in properties file:

Application-Checklist=D:ephesoft:ephesoft

Application-Checklist.InvoiceDate=ephesoft:invoiceDate

Application-Checklist.PartNumber=ephesoft:partNumber

Application-Checklist.InvoiceTotal=ephesoft:invoiceTotal

Application-Checklist.State=ephesoft:state

Application-Checklist.State=ephesoft:city

Application-Check\ list.State=ephesoft:city

  • Note: In case there is space in the name of the Document or in Document Level Fields, then escape it with “\ “character.
  • A default properties file is available with the Ephesoft release starting from 2.5 latest versions.
  • Properties for dcma-cmis.properties:

 

A property is given as property_name=value

 

Configurable property Type of value Value options Description
cmis.document_versioning_state List of
values
NONE: The document will be created as a non-version able 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.plugin_mapping_filename String NA Name of the file containing mapping of cmis repository properties to ephesofts dlfs.
cmis.date_format String NA Date Format to be used for date values added as properties uploaded documents.
cmis.security.mode List of
values
'basic' for HTTP Basic Authentication (default)

'wssecurity' for WS-Security Username Token based security.

'oath' for oauth using Alfresco repository.
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. If invalid or missing it is true.
cmis.aspect_mapping_file_name String For example:

aspects-mapping.properties

This is the name of the aspect properties file present in '\META-INF\dcma-cmis\dcma-cmis.properties'.
This is to add aspects to documents being uploaded on Cmis repository via Ephesoft for alfresco repository.

 

WSSecurity

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.

  • Use cmis.url.acl_service=http://<host>:<port>/alfresco/cmisws/RepositoryService?wsdl for Alfresco 4.0x
  • Use cmis.url.acl_service=http://<host>:<port>/alfresco/cmis/RepositoryService?wsdl for Alfresco 3.0x

For 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:

 

OAUTH Authentication security

 

To use this security user must have an Alfreco Cloud Account, accessible from https://my.alfresco.com

 

UI configuration for this security is:

 

400px-3.1_CMIS_Export_Plugin_10007

 

User need to specify client key, server key, redirect URL and Export Network. Get Token button is used for generating refresh token for authentication. On click of Get Token button with valid values for client key, secret key and redirect URL, a window like shown below pops up:

 

400px-3.1_CMIS_Export_Plugin_10008

 

Enter valid username and password for user’s Alfresco Cloud Account and click on Allow button to generate a fresh refresh token automatically populated in the refresh token UI property.

 

If time taken is much longer than the 10 mins for login in above pop up than following error will generate:

 

400px-3.1_CMIS_Export_Plugin_10009

 

After successful login, refresh token will generated on the Plug in Detail Screen as following:

 

400px-3.1_CMIS_Export_Plugin_100010

 

Uploaded document can be found at https://my.alfresco.com and CMIS Export Network name is

 

400px-3.1_CMIS_Export_Plugin_100011

 

Mappings

 

  • Mappings of Data types defined in Ephesoft and at Alfresco Server

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 ephesoftModel.xml 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.

 

Screen Shot 2014-09-07 at 12.12.40 PM

 

  • Screenshot from Ephesoft application for Data Types.

 

400px-3.1_CMIS_Export_Plugin_100012

 

 

Aspect switch configuration

Below is the requirement to add aspect:

  • To add aspects to the file being uploaded:

Aspects will be added to the document file being uploaded. This will be done according to its document type defined in its batch.xml file. To know which aspect is to be added to documents of which document type (when uploading), there has to be a mapping of document type v/s aspects.

  • Add values to properties defined by an aspect:

These values will be the values of document level fields that have been mapped to that property.

Mapping Properties

Path of mapping properties file

There has to be a mapping defined for the above two requirements. This will be done in Ephesoft with the help of a property file.

The absolute path of the file is specified by the following steps:

  • The folder name in which this property file resides inside the batch class folder of ephesoft-data is specified through the “batch.cmis_plugin_mapping_folder_name” property in the file: “\META-INF\dcma-batch\dcma-batch.properties”.

e.g.: batch.cmis_plugin_mapping_folder_name=cmis-plugin-mapping property

P.S: This is the same property that defines the folder path of the property file for Cmis content type mapping.

  • The name of this property file is specified by a new property “cmis.aspect_mapping_file_name” in the property file: ”\META-INF\dcma-cmis\dcma-cmis.properties”.

e.g.: cmis.aspect_mapping_file_name=aspects-mapping.properties

The above defined property file contains the entire mapping associated with aspects.

Content of mapping properties file

It is needed to add mapping for:

  • Mapping document types to aspects:

User can map document types to multiple aspects (i.e. the aspects user intend to add to documents of a certain document type).

This will be done through adding the name of the document type as key and aspects as the value (each aspect separated with a semi-colon “;”)

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

  • Mapping document level fields to aspect properties:

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 property to be mapped to.

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

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

In case of an error encountered while adding aspects to a uploaded document, the user will have to restart the batch after correcting the errors due to which the error was being encountered, and the document will be uploaded again.

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

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 received due to mal-functioning of the plugin:

 

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

NOTE: Detailed description of error #12 is below.
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 #12

  • User may define in properties file a mapping as follows:-
  • Application-Checklist=D:ephesoft:document
  • Application-Checklist.InvoiceDate=ephesoft:invoiceDate
  • Application-Checklist.PartNumber=ephesoft:partNumber
  • Application-Checklist.InvoiceTotal=ephesoft:invoiceTotal

 

  • At Alfresco repository, however, it may be defined as follows:-

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

 

  • This mismatch would give “Bad Request” error from CMIS plugin while it tries to upload the document.

 

Description of error #13

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

<property name=”ephesoft:partNumber”>

<type>d:text</type>

</property>

<property name=”ephesoft:invoiceTotal”>

<type>d:int</type>

</property>

 

  • partNumber” may be mapped as “text” type.(Let us say, this is of type LONG in Ephesoft application)
  • invoiceTotal” may be mapped as “int” type.( Let us say, this is of type DOUBLE in Ephesoft application)

Above mismatch gives the “CMISExporter – Property ‘ephesoft:partNumber’ is a String property” from Alfresco repository.

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>

<property name=”ephesoft:invoiceTotal”>

<type>d:double</type>

</property>

 

 

 

 

 

Was this article helpful to you?

wikiadmin