This plugin requieres the formcycle version 8.2.0 or above.

This plugin enables you to connect to a Document Management System, through its CMIS interface. The plugin contains a menu to configure the connection aswell as a workflow action node that allows the creation of a new object on the CMS.

Contents

CMIS connection configuration

Through this menu entry you will be able to configure the connection to an existing CMIS interface.

CMIS Interface

• Name
  The name of the configured connection.
• Binding Type
  The Binding Type specifies the protocol which should be used for communicating with the CMIS interface. There are 3 supportet Types.
  - AtomPub
  - Browser (Access through HTTP-Methods GET and POST in the JSON format)
• Server URL
  The URL of the server that hosts the CMIS interface.
• Repository ID
  The identificator of the repository to be used. This is only relevant if there is more than one repository on the specified URL. If the field is left empty, the first repository found is used when the connection is established.All selectable repositories of the configured connection are searched using the "Search repositories" button. As soon as repositories are found, all IDs are visible in a selection and can be selected. Information on the selected repository is displayed via the information icon at the top right. 2.3.1+
• Connection parameters
  Additional parameters that are relevant for establishing a connection with the CMIS interface. You can find more under OpenCMIS connection parameters.

Authentication

• Authentication Type
  Specifies the type of authentication that should be used.
  The available types are the following:
  - None
  - Basic Auth
• Username and Password
  The username and password for Basic Auth.

Proxy settings

• Use Proxy
  Idicates wheter a proxy server should be used or not.
• Proxy Host
  The URL of the proxy server.
• Proxy Port
  The port of the proxy server.
• Username and Password
  If the proxy need a Basic Auth authentication the credential can be entered here.

Existing folders and documents of the CMIS connection

The Load CMIS Objects button displays the folder and file structure of the CMIS connection in this area. Only the CMIS objects are visible to users who have the appropriate permissions according to the configured authentication. The displayed structure allows you to check whether the workflow action has created folders and documents correctly. Click on the copy symbol to copy its path to the clipboard.

Example structure for a CMIS connection

It is also possible to test to configured connection. For doing so all fields that are required to establish a connection need to be filled out. The fields necessary are the Server URL and the configuration of the Authentication. If there is a proxy that should be used, the relevant fields also have to be filled out.

CMIS queries

The editor can be used to enter CMIS queries that are executed on the configured CMIS connection. The results are displayed in a table. The maximum number of results can be specified to limit the query and shorten the query time.

Workflow action - Provide a CMIS document  2.8.0+

This action allows a CMIS document to be made available and reused in the workflow for a configured CMIS connection. To do this, a connection must first be created in the CMIS connection management. In addition, the object ID for the CMIS document object to be made available must be defined. The object ID can also be specified using a placeholder.

Details for providing a CMIS document

• Connection

Selection of the previously configured CMIS connection that is used to provide the CMIS document.

• Object ID

Here, you enter the object ID for the CMIS document object that is to be provided by the action. The folder tree button opens a help dialog that allows you to select an existing document. The respective object ID is then copied into the input field. It is also possible to specify an object ID using placeholders, for example, the success placeholders of the workflow actions “Execute CMIS query” or “Create CMIS object.”

Storage of generated files

• Name of the output file

Specifies a file name that has a provided file in the workflow. If this field is left blank, the object name of the CMIS document is used as the file name.

• Attach to the process

When enabled, the provided CMIS document is attached to the process, allowing the file to be accessed in the inbox, for example.

Success values

• [%$<Aktionsname>.RESULT.name%]
  Name of the CMIS object
• [%$<Aktionsname>.RESULT.fileSize%]
  File size in bytes for the provided CMIS document
• [%$<Aktionsname>.RESULT.objectId%]
  Unique ID of the object
• [%$<Aktionsname>.RESULT.objectTypeId%]
  Type of object 
• [%$<Aktionsname>.RESULT.createdBy%]
  Creator of the object
• [%$<Aktionsname>.RESULT.creationDate%]
  Creation date of the object 
• [%$<Aktionsname>.RESULT.lastModificationDate%]
  Date of last edit 
• [%$<Aktionsname>.RESULT.lastModifiedBy%]
  User who last edited the object
• [%$<Aktionsname>.RESULT.objectProperties['key']%]
  A key-value pair collection of the object properties of the provided CMIS document. A key can be set to select a specific property. Individual values of a multiple property can be accessed via [%$<action name>.RESULT.objectProperties[‘key’][i]%].

Mögliche Fehler

• CMIS_CONNECTION_NOT_FOUND
  Error code if the CMIS connection could not be found. This can happen if the connection has been deleted in the meantime.
• DOCUMENT_NOT_FOUND
  Error code if the CMIS document for the specified object ID could not be found.
• DOCUMENT_PROVIDE_ERROR
  Error code if an error occurred during the provision of the CMIS document.
• UNABLE_TO_CONNECT
  Error code if the connection to the CMIS connection could not be established, for example if the URL or login information is invalid.

Workflow action - Execute CMIS query  2.5.0+

This action enables a CMIS query to be executed. To do this, a connection must first be created in the CMIS connection management. Placeholders can be used within the query, for example to insert form data into the query.

Details of the CMIS query

• Connection
  Selection of the previously configured CMIS connection, which is used to execute the CMIS query.
• Max. Results
  Maximum number of results that will be returned. This can be used to reduce the duration of the CMIS query. The default value is 100.
• Return all document versions
  This option controls whether all versions of a document should be included in the results of a CMIS query. If this option is activated, all versions of each document that fulfils the query conditions are returned in the results.
• CMIS query
  Enter the CMIS query to be executed. Placeholders can be used, for example, to use form data in the CMIS query.

Values on success

• [%$<action name>.RESULT.result[i]['key']%]
  A JSON array with the results of the CMIS query. Each entry in the JSON array is a JSON object, where the key corresponds to the name of the CMIS property.
• [%$<action name>.RESULT.resultCount%]
  Number of results found from the executed CMIS query. This value is limited by the configured maximum number of hits.

Possible errors

• CMIS_CONNECTION_NOT_FOUND
  Error code if the CMIS connection was not found. This can happen if the connection has been deleted in the meantime.
• QUERY_EXECUTION_FAILED
  Error code if the CMIS query cannot be executed against the CMIS connection.
• UNABLE_TO_CONNECT
  Error code if the connection to the CMIS connection could not be established, for example if the URL or the login information is invalid.

Workflow Action - Create CMIS object

The configured CMIS connections can now be used in the Workflow Action Create CMIS Object. This action allows you to create a new folder, document or item in an CMS that has a configured CMIS interface.

Connection settings

• Connection
  One of the existing CMIS connections must be selected here in order to configure the workflow action.
• URL
  The configured server URL of the selected CMIS connection.
• Test connection 2.2.0+
  This button checks the CMIS connection configuration and checks whether a connection can be established.

Object Settings

• Object type
  Defines the base type of the object. 
• Object type ID
  Defines the Identificator of the Object Type. If no ID is specified that default ID of the base type is used. The supported types are Folder, Document and Item. If no specific identifier is specified, the base identifier of the object type is used (documents: "cmis:document", folders: "cmis:folder", items: "cmis:item"). If available, possible IDs of the CMIS connection are displayed via the selection or input. These are IDs of the basic identifiers "cmis:document", "cmis:folder" or "cmis:item".
• Object name
  The name to be given to the object to be created. If it is a document and no object name has been entered, the file name is used as the object name. If several files have been selected to be created, the respective file name of the file is also used as the object name if this field is left empty.  The default value for folder and object is ‘output’.
• Return existing folder 2.3.0+

  This option returns a folder if a folder with the object name specified in the "Object name" text field already exists in the specified target folder path. In this case, no new CMIS object is created, but the existing CMIS object is returned. This option can only be activated if the "Folder" object type has been selected. In addition, the option "Add automatic version number" is not available if this option is activated.

• Update object properties  2.5.0+
  This option allows you to update the properties of a found folder object. If a folder object with the specified name is found, you can use this option to update the properties of the folder object. 

• Automatically add version number 2.2.0+

  By ticking this option, the system checks whether the desired name of the object already exists at the configured storage location when a CMIS object is created. If yes, the object is given a version number in the name instead. An example of this would be: the configured object name "Object" is adapted to "Object (1)" or, for files with the extension, "File.pdf" is renamed to "File (1).pdf".

• Remove file extension  2.5.0+

  This setting can be selected for the creation of CMIS documents. If it is enabled, the file extension is removed.

• Activate document versioning 2.4.0+
  Activate this option to create a major version in the CMIS repository for each newly created document. Please note that this function depends on the capabilities of the CMIS repository used and only works if the repository supports versioning. If versioning is deactivated, no versioning takes place.
• Save in dynamic directory 2.4.0+
  Activate this option to create the document without assigning it to a folder. It is saved in a virtual, invisible directory. A prerequisite for this function is that the CMIS repository supports 'Unfiling'. If this option is activated, it is not necessary to enter a target folder path.
• Configure destination folder with object ID2.6.0+

  This function allows you to configure the path to the destination folder with a specific object ID. The object ID of the destination folder must be entered in the text field. The object ID can be found in the CMIS connection overview. This option is particularly relevant if the CMIS interface used does not support folder paths.

• Folder Path/ Folder ID
  The path or ID of the CMIS folder in which the CMIS object to be created is to be stored must be entered in this field. The folder structure of the connection can be displayed using the button with the folder icon. All relevant information about the selected CMIS object is displayed here. This includes a general overview of the metadata of a CMIS object, the object properties of the object, and a specification of the object type IDs that can be created in the selected folder. The copy icon can be used to automatically copy the path or object ID to the selected folder into the text field for the target folder.
  If the destination folder is only created when the workflow is executed, the respective success placeholder can be used to configure the destination folder. If the “Configure destination folder with object ID” option is deactivated, the placeholder [%$<action name>.RESULT.objectPath%] must be used. Otherwise, the placeholder for the object ID, i.e., [%$<action name>.RESULT.objectId%], must be used.

Configuring object properties for CMIS objects

Here you can configure the object properties for the CMIS object to be created. CMIS objects have basic, standardized properties (beginning with “cmis:”) as well as additional properties defined by the respective DMS. Each property has a defined data type that is specified by the CMIS interface or the DMS. The default data type is string. For properties of type date, a date format must be specified. All date properties used should have the same date format.

Adding and configuring object properties

After selecting an object type ID, clicking the Add button (top right) opens a dialog box displaying all properties available for the type as well as those already configured 2.2.0+. The ID, name, and data type are displayed for each property. You can filter by attributes in the table header. The desired properties are added to the existing properties by selecting them and clicking on “Update.”

The properties can then be filled with fixed values or placeholders. The value must always correspond to the data type of the property.

Multi-value properties 2.7.0+

The CMIS standard allows certain properties to be multi-valued, i.e., they can accept multiple values. All values must correspond to the data type specified for the property.

Multiple properties are automatically recognized as such in the selection dialog and added accordingly. Alternatively, a property can be manually defined as multi-valued: The column for activating multi-valued properties can be displayed via the visibility configuration of the property table. A property may only be configured as multi-valued if this has been defined by the DMS for the property, otherwise an error message will appear.

Using placeholders in multiple properties

Placeholders can be used for both simple and multi-valued properties. They must always correspond to the data type of the property. Especially in the case of form element placeholders that refer to repeated form elements, the placeholder is resolved in such a way that each value of the repeated element is entered as a separate value in the multiple property.

Values on success

• [%$<Action name>.RESULT.objectPath%]
  The folder path of a folder object. For documents an empty string is returned.
• [%$<Action name>.RESULT.createdCount%]2.3.0+

  Number of CMIS objects created. This value is useful, for example, if the "Return existing folder" option is activated and a check is to be made as to whether a CMIS object has been created or an existing object has been found.

• [%$<action name>.RESULT.name%]2.5.0+
  Name of the CMIS object
• [%$<action name>.RESULT.objectId%] 2.5.0+
  Unique ID of the object 
• [%$<action name>.RESULT.objectTypeId%] 2.5.0+
  Type of the object 
• [%$<action name>.RESULT.baseTypeId%] 2.5.0+
  Base type of the object 
• [%$<action name>.RESULT.createdBy%] 2.5.0+
  Creator of the object
• [%$<action name>.RESULT.creationDate%] 2.5.0+
  Creation date of the object 
• [%$<action name>.RESULT.lastModificationDate%] 2.5.0+
  Date of the last modification 
• [%$<action name>.RESULT.lastModifiedBy%] 2.5.0+
  User who last edited the object 
• [%$<action name>.RESULT.changeToken%] 2.5.0+
  Token that identifies changes to the object 
• [%$<action name>.RESULT.objectProperties['key']%] 2.5.0+
  A key-value pair collection of the object properties of the created CMIS object. A key can be set to select a specific property.
• [%$<action name>.RESULT.documentsProperties[i]['key']%] 2.5.0+
  A JSON array with all object properties of the created CMIS documents. Each entry in the JSON array is a JSON object, where the key corresponds to the name of the CMIS property of a CMIS document.

Possible Errors

• CONNECTION_FAILED
  The attempt to connect to the server failed.
• FILE_SYSTEM_ERROR
  Accesssing the file failed.
• INVALID_PATH
  The path to the folder was invalid. This error contains the path segment that caused this error.
• AUTHENTICATION_FAILED
  The authentication was not possible.
• NOT_AUTHORIZED
  The user lacks authorization for his action.
• REPOSITORY_NOT_FOUND
  If there was a Repository ID specified and the specified repository was found or no repository was found under the specified URL
• TYPE_NOT_SUPPORTED
  The type that was defined through the field Object Type ID is not supported by the interface.
• OBJECT_PROPERTY_CREATION_FAILED

  The creation of an object property failed. This happens for example if a wrong format was taken for a date or the input could not be converted into the respective data type.

• OBJECT_CREATION_FAILED

  The creation of the object on the CMIS interface failed.

• OBJECT_ALREADY_EXISTS

  If the object already exists at the configured folder path with this name.

Troubleshooting

NullPointerException during the "Create CMIS Object" action

Error description

In this specific case, an attempt was made to create a folder. The target folder path has been precisely defined. The action is named "Create CMIS Object - Folder".

The folder created will be used in the next step to store a document in the DMS. This action is called "Create CMIS Object - File".

Solution

In the ‘Create CMIS Object - Folder’ action, the target folder ID is used instead of the target folder path to create the folder. To enable this, the "Configure destination folder with object ID" checkbox must first be activated. This also makes it necessary to enter the target folder ID, which can then be selected via the folder structure.

In the ‘Create CMIS Object - File’ action, in which the document is stored, the "Configure destination folder with object ID" checkbox should be activated again. The target folder ID can then be assigned via the placeholder selection, as the result of the previous action is applied here. In this context, the menu item Workflow (Action) should be opened.

The placeholder in this example is: [%$ Create CMIS Object - Folder.RESULT.objectId%]

Changing the ObjectId has now successfully enabled the file to be stored.