0 Introduction

1 Installation

   1.1 Tryout Version

2 Usage

3 CumulusConnector Actions

   3.1 Check Field Values
   3.2 Catalog Asset
   3.3 Set Field Value

      3.3.1 Using Placeholders and Variables
      3.3.2 Usage example 1: Create and assign a Category
      3.3.3 Usage example 2: Log file usage in Cumulus field

4 Additional Information

   4.1 Cumulus Client Licenses
   4.2 Java Date and Time patterns

5 Version History & Product Support

The CumulusConnector for Enfocus PowerSwitch enables the administrator to use Canto Cumulus Catalogs and the Assets stored in these Catalogs in Enfocus PowerSwitch workflows.

The CumulusConnector for Enfocus PowerSwitch

The current version of the product implements the following features as so called CumulusConnector Actions:

- React on the Assets field values
- Catalog the Asset while passing the flow
- Set Cumulus Field Values (ie creating Categories and storing text in Cumulus Text Fields)

These CumulusConnector Actions are fully configurable and come with a lot of properties to adjust the functionality to the needs of your workflow.

Do you need additional functionality in the application? We develop additional functionality based on your needs. You can send an email with your feature requests by clicking here.

1.) Please download the Cumulus Java Runtime Installer from the Canto Website and install it on the server that is running your version of Enfocus PowerSwitch.

The Cumulus Java Runtime Installer copies a folder to your harddisk that holds all the technology necessary to connect to a Cumulus Server. It is part of the Canto Cumulus product family and it comes for free without any additional costs.

2.) In the 'Installation' folder of the CumulusConnector product you will find the following CumulusConnector files:

- CumulusConnector.jar: Java Classes that implement the connection to the Canto Cumulus Server
- CumulusConnector.properties: a file that hold the default settings to connect to the Cumulus Server
- CumulusConnector.sscript: a Enfocus PowerSwitch script file that allows to configure the CumulusConnector Action used to communicate with Cumulus
- CumulusConnector.sh: a shellscript file that is necessary on Mac OS X to start the CumulusConnector. The file is not used on Windows.

Please copy these files into the main folder of the 'Cumulus Java Runtime' folder that you have just installed.

3.) On Mac OS X only:

After copying the 'CumulusConnector.sh' shellscript, it is necessary to allow the execution of that file. Open the Terminal application and navigate into your Cumulus Java Runtime directory that contains the 'CumulusConnector.sh' file.

Use 'chmod' to allow the shellscript to be executed

When you try to start the script, you will get a 'Permission denied' error. Use the 'change mode' command to make the file executable:

chmod 775 CumulusConnector.sh

After that you can start the shellscript and it can be used by PowerSwitch.

4.) For easy use of the CumulusConnector it is helpful to specify the Cumulus Server Login parameters in the file 'CumulusConnector.properties'. You can edit the file with every text editor and specify the Login parameters for the Cumulus Server.

The CumulusConnector.properties file

In the example above the Cumulus Server is installed on the same maschine as the Cumulus Java Runtime and uses the username 'cumulus' with password 'cumulus' to connect to the server.

5.) The CumulusConnector software comes in demo mode. If you have a full version serial number for the product, go to the Cumulus Server-Console to add the serial number to your Cumulus Server licensing.

1.1 Tryout Version

The tryout version of the 'CumulusConnector for Enfocus PowerSwitch' is a full version of the product, so you can test all the functionality available.

This tryout version already expired

The software comes in demo mode and is fully functional for a limited time of 2 weeks after first usage. After that period of time the CumulusConnector will not work at all, so you want to make sure that you have done all your testing in the first two weeks after the first use of the software. To order the full version of the product, please just send an email to Heymann Consulting.

The full version comes with a serial number (Canto Cumulus Option serial number) that unlocks your demo installation, so you do not have reinstall anything.

Remark: the full version serial number is a Cumulus Option serial number that must be added to the current serials in the Remote Admin of the Cumulus Server Console (File>Administration>Server Console>Remote Admin>License)! Add the serial number to the list of serials in the license dialog of the Remote Admin and get a new Activation Key from the Canto website for your Cumulus environment to unlock Cumulus and all its Options.

To make use of the CumulusConnector in a Enfocus PowerSwitch Flow, this is what to do:

1.) Add a new Script Element from the Tools Section of the Elements pane to your flow.

2.) Specify the CumulusConnector.sscript in the script package property of the Script Element. You have to select the file inside the installation folder in the file dialog.

A PowerSwitch Flow containing the CumulusConnector

3) Connect the Script with an in and out connection.

4) Set the properties of the CumulusConnector Script as described in Chapter 3 CumulusConnector Actions of this documentation.

Do you need additional functionality in the product? We develop additional functionality based on your needs. Send an email with your feature requests by clicking here.

The CumulusConnector allows the System Administrator to use Cumulus Catalogs and its Assets and metadata information in Enfocus PowerSwitch Workflows.

The current version of the CumulusConnector implements the following Connector Actions:

1. Check field values (see 3.1 Check Field Values for details)

The workflow can react on a specified field value of an asset. For example, the workflow can be stopped if the status of the file in the Cumulus Catalog is not appropriate.

2. Catalog Asset (see 3.2 Catalog Asset for details)

The file can be cataloged into Cumulus while the file passes the workflow.

3. Set field value (see 3.3 Log file usage in Cumulus field for details)

A field value is saved in a specified Cumulus Field inside the Asset's record. This Action can be used for example for creating Categories and assigning them to the record of the Asset or to log the file usage in a Cumulus text field.

The Switch Properties Pane

CumulusConnector properties:

- Path to CumulusConnector.jar

Specifies the path to the CumulusConnector application that implements the communication with Canto Cumulus. The path must be valid and the CumulusConnector.jar file must have access to the Cumulus Java Classes in the same folder. We recommend to install the CumulusConnector in a Cumulus Java Runtime folder as described in Chapter 1 Installation of this documentation. To use the CumulusConnector in a Switch workflow, please specify the properties.

- Cumulus Server Connection

To communicate with the Cumulus Server and to open a Cumulus Catalog it is necessary to specify a Cumulus Server (by IP address or name) and a user account that is used to connect to Cumulus. There are two different options to specify the login parameters:

1) Use default settings (from CumulusConnector.properties file)

The CumulusConnector.properties file holds the login parameters for the Cumulus Server. This is a convenient method if you are using just one Cumulus Server and always the same user account for the connection.

2) Specify Server Login

The Cumulus Server Login parameters

You can provide the login parameters that are used to communicate with Cumulus as separate properties. You have to specify the Server, Username and Password.

- Cumulus Catalog Name

You have to specify the name of the Cumulus Catalog that you want to work with.

- Connector Action

Specify the CumulusConnector Action that you want to use in your workflow. Depending on this CumulusConnector Action, there are different properties that you have to specify to use the action. For more details on the actions' properties, go to:

3.1 Check Field Values
3.2 Catalog Asset
3.3 Set field value

- Create Log File (Yes / No)

You can create a log file that contains information about the process like Cumulus Login information, Catalog access, messages and errors.

The Log File Settings

If you have activated the log file by setting 'Create Logfile to yes' you have to specify the following parameters:

- CumulusConnector Log File Path

A log file named 'CumulusConnectorLog.txt' will be created at the specified location.

- Log File Mode

Set the log file mode to Append, if you want to have all log information in one file. Overwrite will create a new log file for each CumulusConnector Action. Default: Overwrite.

- Activate Debug Mode (Yes / No)

A log file in Debug Mode will have even more information about the usage of the CumulusConnector in the flow (and some 'may be' confusing technical info as well).

- Maximum Memory (kb)

Default: 128 kb

The CumulusConnector is running in a separate Java Virtual Machine. When starting the VM, this memory parameter is used to allow the script to have enough memory. If you ever face a memory problem with the CumulusConnector that is caused by low memory assignment, you can choose a higher value to provide more RAM to the script.

IMPORTANT: CumulusConnector Actions that modify the Cumulus Catalog connect to the Cumulus Server with write-access permissions. One spare Client license is needed to access the Cumulus Catalog. CumulusConnector Actions that do not modify the Catalog's metadata do not need write-access permissions and the script will just connect with read-only permissions, so this connection will not eat up a license with Cumulus Enterprise. The Cumulus Enterprise Server allows an unlimited number of Clients with read-access permissions, so you will never run into a out-of-license issue when connecting with just read-only permissions and Cumulus Enterprise. The log file will tell if the CumulusConnector tries to connect with read-only or write-access permissions. With Cumulus Workgroup, a free Cumulus Client license is necessary with read-only and write-access permissions.

Find more information about necessary Client licenses in Chapter 4.1 Cumulus Client licenses.

3.1 Check Field Values

Depending on the value of a Cumulus Catalog field, the workflow can be stopped. For example if the Status field value inside the Cumulus Catalog for an Asset is set to 'to be approved', you might want to stop the workflow until the file status is set to 'Approved'.

Check file status and allow only if 'Approved'

In the example above, the field value of the field with the name 'Status' is evaluated.

The CumulusConnector connects to the specified Cumulus Catalog and searches for the Asset's record and gets the field value (as a String value). Then it compares the field value with the String value specified in the flow element properties ('Cumulus Field Value'). If the value in the database equals the specified value it allows or denies to process the file depending on the 'Process file' property. So in this example: if the Status field value for the file is not set to 'Approved', the flow will stop.

Remark: this function can be used for each field type in your Cumulus Catalogs! So this not just for text fields, but for every field, that can be turned into a String value for comparison. The String value might differ depening on the Cumulus version and the language settings that you are using. If you are not sure, what the field value will be like, you can just run the flow and look into the log file that will show you the field value that is returned by Cumulus.

The 'Check field value' Action properties:

- Cumulus Field Name

A valid name of a Cumulus field inside the specified Catalog.

- Cumulus Field Value

A String value that shall be compared to the value returned by the Cumulus field.

- Process file (Allow / Deny)

Set this property to 'Allow' if you want to resume the flow if the returned value of the Cumulus field is equal to the specified value. Set this property to 'Deny' if you want to stop the flow if both values are the same.

Remark: this CumulusConnector Action does NOT need one spare Client license when connecting to a Cumulus Enterprise Edition to access the Cumulus Catalog. Find more information about licensing in Chapter 4.1 Cumulus Client licenses.

3.2 Catalog Asset

This CumulusConnector Action allows to catalog a file into a Cumulus Catalog that is passing the flow element. So the file is passed to Cumulus for cataloging, make sure that the Cumulus settings are appropriate to meet your needs.

Catalog Asset with the appropriate settings

The 'Catalog Asset' Action properties:

- Cumulus Asset-Handling-Set

Specify a Cumulus Asset-Handling-Set to be used to catalog the file. Please keep in mind that depening on the settings of the Asset-Handling-Set the file might not be cataloged into your Cumulus Catalog due to switched off file filters or Update Record settings! Please make sure that you are using an Asset-Handling-Set that allows to catalog a file of that type and the necessary modules are activated.

- Metadata Template

You can specify a Metadata Template that allows to add metadata to the record that is created while cataloging the file.

Remark: this CumulusConnector Action needs one spare Client license to access the Cumulus Catalog (because it modifies the Catalog's metadata). Find more information about licensing in Chapter 4.1 Cumulus Client licenses.

3.3 Set field value

This CumulusConnector Action creates a text entry in a specified Cumulus field. In the following example we create a new category in the Categories field of the Cumulus Catalog:

Create a new Category 'Used in PowerSwitch Flow' at top level

The Action performs a search for the file in the specified Cumulus Catalog and stores the text information in the specified Cumulus field.

The 'Set field value' Action properties:

- Cumulus Field Name

A valid name of a Cumulus field inside the specified Catalog. In the current version the field has to be of type 'TEXT' or you can use the Categories field.

- Cumulus Field Value

The specified text will be written into the specified Cumulus Catalog field. This text can either be plain text or text containing placeholders or variables. Placeholders or variables have to be enclosed by square brackets [].

- Text Mode

If the text shall be stored in a text field, the function will append or insert the specified text to the current field value. If you set the Text Mode to Overwrite, the new value will replace the current one. Remark: this setting is only valid for text fields and it is not valid if you create Categories with this function. Creating a new Category and assigning it to a record will (of course) NOT remove all the other Category assignments from the record.

Remark: this CumulusConnector Action needs one spare Client license to access the Cumulus Catalog (because it modifies the Catalog's metadata). Find more information about licensing in Chapter 4.1 Cumulus Client licenses.

3.3.1 Using Placeholders and Variables

While defining the text that should be saved into Cumulus by the CumulusConnector, you can use plain text as well as placeholders and variables. This will help to store additional information like date, time or the name of the user which is evaluated at runtime.

In the current version, the following placeholders are supported:

$DATETIME$ (Date and Time)
$DATE$ (Date)
$TIME$ (Time)
$USER$ (the user's login name)

You can add a locale to the parameters to get the value in the desired local format. For example $DATETIME_DE$ will return the current date and time in a German format or $DATE_US$ will return the date in a US English format.

The product supports the following locales out of the box:

EN = International English
US = US English
DE = German
FR = French
ES = Spanish

It is also possible to specify the format that should be used by providing Java Date and Time Patterns. You can just add a valid Java Date and Time Pattern after the '_' character. Here is an example:

$DATETIME_yyyy-MM-dd HH:mm$

Find more information on Java Date and Time Patterns here on the Java Website. If the pattern is not valid the default date and time formats are used.

Here are some examples:

3.3.2 Usage example 1: Create and assign a Category

With the Set field value Action you can create a new Category and assign it to the found record. The Cumulus Field Value attribute will define the name of the created Category. In the following example we create a new category in the Categories field of the Cumulus Catalog:

Create a new Category 'Used in PowerSwitch Flow' at top level

After running the flow using this CumulusConnector setting, a new Category has been created at top level of the Category hierarchy:

A new Category 'Used in PowerSwitch Flow' at top level

You can create Category hierarchies by using the Category level delimiter ":". Remark: if you need a ":" character inside a Category name, please use "::" to tell the function not to use the ":" character as a level delimiter.

Create a new Category 'Used in PowerSwitch Flow' under $Categories

After running the flow using this CumulusConnector setting, a new Category has been created under $Categories Category hierarchy:

A new Category 'Used in PowerSwitch Flow' under $Categories

As described in in Chapter 3.3.1 Using Placeholders and Variables, you can use the placeholders to be replaced at runtime by current values. In the next example, the [$DATE$] placeholder has been used to create a Category tree based on the date a file passes the workflow. Here is the example that creates a date hierarchy:

A date hierarchy setting

Here, we use the [$DATE$] placeholder and Java Date and Time Patterns (see Java Website for details).

A date hierarchy is created in the Category list

We use 'MMMMMMMM' in the pattern to get the name of the month as text (April instead of 04), you can just use 'MM' to get the month as a number as shown in the next example:

A date hierarchy is created under $Categories

This example uses 'MM' to get the month as a number:

A date hierarchy is created under $Categories using the month's number

Remark: the 'Text Mode' attribute is not use when creating new Categories.

3.3.3 Usage example 2: Log file usage in Cumulus field

With the Set field value Action you can save text into the specified field of the found record. The specified Cumulus Field Value attribute will be saved in the selected field, 'Notes' in this example:

Log information into a Cumulus text field

In the example we also make use of the placeholders as described in Chapter 3.3.1 Using Placeholders and Variables, after using this setting the Notes field will contain:

2011-04-24 05:07:36 File passing Switch Flow (User:'cumulus')

- Text Mode (Append / Insert / Overwrite)

You can add the text to the current field value at the end of the field (Append) or at the beginning of the field (Insert). You can also overwrite the current field value with the specified text.

4.1 Cumulus Client licenses

When connecting to the Cumulus Server, the CumulusConnector needs a free Cumulus Client license, if it connects with write-access permission. So if the CumulusConnector Action modifies the Cumulus Catalog's metadata in any way, it needs to connect with write-access permissions and therefor needs a spare Client license.

Some of the CumulusConnector Actions might just read information from the Catalog (ie Check field value) and do not modify the Catalog's data at all. In this case the Action will only use a read-only connection to Cumulus which does not need a free Client license when connecting to the Cumulus Enterprise Server, but it needs a free license with the Cumulus Workgroup Server!

Check field values => read-only (no Client license required with Cumulus Enterprise Edition)
Catalog Asset => needs write permissions (free Client license required)
Set field value => needs write permissions (free Client license required)

If no free Client license is available, the CumulusConnector will stop and you will find information about the missing license in the log file.

4.2. Java Date and Time patterns

Using date and time in the text definition is fairly simple by using placeholders. This feature can be even more powerful by adding a date and time pattern. The definition of Date and Time patterns follow the Java guidelines.

Go to the Java Website to find more details on the correct pattern definition.

Version 8.0.0.1 - May 2011

A shellscript for Mac OS X ('CumulusConnector.sh') has been added to start the CumulusConnector functionality on OS X.

Version 8.0 - April 2011

This is the first version of the CumulusConnector for Enfocus PowerSwitch.

Please send all your questions about the product to the email address support@heymann-consulting.de. We try hard to answer your questions quickly and improve our products by implementing functionality based on your feedback.