0 Introduction

   0.1 Tryout Version
   0.2 Special Thanks

1 Installation

   1.1 Simple Installation
   1.2 Add the EOSP for Sites full version serial number
   1.3 Update your EOSP for Sites version
   1.4 Uninstall EOSP for Sites
   1.5 Installation of the 'Collect Files' EJaP

2 Configuration

   2.1 Basic Configuration (Admin Pages)

      2.1.1 Enable/Disable EOSP, EOSP icons and buttons
      2.1.2 Auto Fill User Information

   2.2 More Configuration Options

      2.2.1 Definition of mandatory fields
      2.2.2 Email body configuration
      2.2.3 The EOSP Tag Library
      2.2.4 Send email order in HTML

   2.3 Multi-Mail (file-based order recipients)
   2.4 How to modify the email order form

3 Finding the ordered files in the Cumulus Catalogs (Collect Files EJaP)

   3.1 Collect Files EJaP - menu and preferences

4 Miscellaneous

   4.1 bcc: the email order
   4.2 Show catalog name in email order form for Multi-Catalog Collections
   4.3 Use Asset Actions to convert files
   4.4 Multi-Language Support
      4.4.1 Add a new language to the product
   4.5 Auto-Fill order form with user information from Cumulus $Users Catalog (Server Console)
   4.6 Disable Save Permissions on a Demo Server
   4.7 Show Thumbnails in Order Form
   4.8 Email Subject configuration
   4.9 Debug Log

5 Feedback & Support

6 Version History

The Email Order System Pro for Cumulus Sites

The Email Order System Pro for Sites is an extension to the Canto Cumulus Sites web portal.

With the help of this extension, the user of the Cumulus Sites web application can order files from his service provider by email. An order form will be displayed which can be configured by the administrator of the website. The order form information will be sent to a given email address (or multiple email addresses) after mandatory fields evaluation. For the person who processes the order, the 'Email Order System Pro' comes with a plugin for the Cumulus Client (for Mac OS and Windows) which helps to find the ordered files in the Cumulus catalogs. The EJaP (Embedded Java Plugin) 'CollectFiles' also allows to use the specified Asset Actions(!) to convert the files. It will also inform about missing files in the catalog.

Two new buttons in the Collection Basket allow to open the Email Order Forms

The 'Email Order System Pro' comes with two different order forms. The first form is used to send a list of the ordered file names (+ additional information) in the order email, the second form enables the user to also specify the number of ordered files, the format, the price or additional information. The second order form can be used for example by print service providers.

Two icons allow to open the Email Order Forms

Two new icons in the Cumulus Sites Collection Basket provide access to the order forms: 'Order Basket' and 'Order Basket with Selection'. It is also possible to access the order forms via the EOSP button pane:

Two buttons allow to open the Email Order Forms

The Cumulus/EOSP Administrator can show or hide the icons and buttons separately. It is possible to use the button pane or the icons, or both. The usage can easily be configured in the EOSP Admin configuration page. It is even possible to configure the access per user by using Cumulus Server permissions. Find more details on how to configure EOSP icons and buttons in the chapter 2.1.1 Enable/Disable EOSP, EOSP icons and buttons.

The Email Order System Pro supports multiple catalogs (Multi-Catalog Collections) and also supports multiple languages. The product supports English, German and Spanish out of the box, more languages can be added in localization files easily! EOSP uses the Cumulus Sites mechanism to set the user's language: it takes the preferred language which is configured in the user's web browser. A fallback language can be configured if the user's browser is set to a language not supported by EOSP.

The first predefined form (configurable) helps to order the files by email

The order emails can be sent in text or html format. The order email contains the configured metadata from the order form and comes with an attached text file that contains the list of ordered files. The attachement is named after the user and the filename also contains date and time of the order.

The HTML email order example

The product comes with an Extension for the Cumulus Client that helps to find the files and copies and converts them, if necessary.

'Collect Files' helps to find the files in the catalog and it also performs the specified Asset Actions

EOSP supports Cumulus' multi-language features that have been introduced by Canto with version Cumulus 8.5: multi-language values are supported for Asset Actions, Catalog Names, and Field Values.

EOSP Multi-Mail: based on the ordered files, EOSP can create multiple order emails with different recipients. For Multi-Mail, the email recipients can be specified in the Cumulus Catalog in a text field named 'EOSP_Recipient' per Cumulus record. This feature allows to have different email order recipients that are responsible to process the order based on the selected assets. So an order for 10 assets in the Collection Basket might result in up to 10 separate order emails (+ one main email that contains all information for the main order recipient). Here is an example:

The EOSP Multi-Mail feature

The assets in the Collection Basket should be processed by the agencies in San Francisco and New York. EOSP will create three different order emails: one is sent to the New York agency (only containing the assets that should be processed by the New York agency), one order email is sent to San Francisco and one order containing all the ordered files are sent to the main order recipient.

Basic user permissions for EOSP can be set in the EOSP Admin for all users of the web application. Since version 8.5 features that have been activated for all users can be disabled for single users by assigning $DisableFeature permissions. These $DisableFeature permissions can be set in the Cumulus Server Console.

Example: $DisableAutoFillUserInformation. If this permission is set for a user, the order form is NOT automatically filled with the user's information from the Cumulus $Users Catalog.

The Email Order System Pro user permissions

In the example above this user will not see the order form icons and will not have access to the Order Form with Selection.

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.

0.1 Tryout Version

The tryout version of the 'Email Order System Pro' is a full version of the product, so you can test all the functionality available.

The tryout version info displayed in the email order form

The limitation: the order form will show a demo info and a link to our website. Also the order email shows the demo information. In the demo version the email order will also be sent to an internal Heymann Consulting email address as a bcc email. There are no other limitations in the tryout version. The demo version is for testing purposes only and you are not allowed to use it in a working environment! To order the full version of the product, please send an email to Heymann Consulting.

The full version comes with a 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 serials in the Remote Admin of the Cumulus Server Console! 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.

0.2 Special Thanks

A special thanks to all who have contributed to the development and improvement of this product. Thank you very much to our sales partners and all our current Email Order System Pro customer who helped us to develop this useful product. We are looking forward to even more feedback from you to make this product even better...

A very special thank you goes to Albert Riera and Ferran Sogas from Microgestió, Barcelona, who provided the Spanish translation files. Also I would like to thank Kuet Ee Foo from Digital Imaging Workflow LLC who helped a lot while improving the product to support Asian character character in the email orders.

The system requirements of the Email Order System Pro product follow the system requirements of your Cumulus Sites installation (see Canto documentation for details).

Before you install the software, please read the license agreement carefully. You can find the license file 'License.rtf' inside the product folder. By installing the software, you accept this license agreement.

1.1 Simple Installation

You will find all the files that are necessary to integrate into your 'Sites' web application inside the 'Installation' folder of the 'EmailOrderSystemProSites' product folder.

IMPORTANT: Please keep in mind that EOSP for Sites is designed to work with Cumulus Sites only. It is not designed to work with any other Canto web technology. There is a seperate product for the Cumulus Web Publisher Pro or Internet Client Pro available.

After the standard installation of Cumulus Sites you will find the Cumulus Sites web application inside the folder 'sites' inside the folder 'webapps' of your Tomcat application folder.

This is what you have to do to install EOSP for Sites:

1. Stop your web application server Tomcat.

2. Copy the folder 'eospSites-9-x-x' that you can find inside the product folder 'Installation' into your Cumulus Sites web application folder into the sub-folder 'customizations'.

After copying the folder the contents of the Sites 'customizations' folder will look like this:

The contents of the Sites 'customizations' folder after the installation

If you already have an older version of 'eospSites-8-x-x installed, please read chapter 1.3 Update your EOSP for Sites version.

3. Restart your web application server Tomcat. When restarting Tomcat, the Cumulus Sites technology will copy all the EOSP product files from 'customizations/eospSites-9-x-x' into the appropriate folders. It copies .jspx files, libraries and other files into the given folder structure. After the first restart of Tomcat the files are just copied into the appropriate folders, but not all files are already visible to Tomcat, so another restart is necessary to use the new functions, so ...

4. Restart Tomcat for a SECOND time to make all the files visible to the Tomcat web application server.

5. Configure the EOSP for Sites attributes by opening the URL

http://myServer(:8080)/Sites/EmailOrderSystemPro/admin

Since EOSP version 8.5 you can also use the new 'shortcut' to access the admin web pages:

http://myServer(:8080)/Sites/eospadmin

Remark: the standard name of the Cumulus Sites web application is 'Sites'. The name of your web application may vary depending on your configuration.

Log into the web application as Cumulus Administrator to change the configuration to meet your needs as described in chapter 2 Configuration. Please make sure that your SMTP Server setup is correct to allow sending emails. The following parameters are necessary to let the system send emails:

- SMTP Server
- SMTP User
- SMTP Password
- Email Sender Address

That's it! Now you can put some files into the Collection Basket and use the email order forms to send the order email.

IMPORTANT: JAVA 7 and JavaMail

If you are using a Java 7 environment: when sending emails with JavaMail, Java 7 is using IPv6 as standard and JavaMail then has problems with connecting to some email servers. You might see an error message like 'No connection' when trying to send the order email. To avoid this problem please make sure that your Tomcat server environment configuration file on Windows

/apache-tomcat-7.0.26/bin/setenv.bat contains the following line

set CATALINA_OPTS=-Djava.net.preferIPv4Stack=true

or on MacOSX or Linux the configuration file

/apache-tomcat-7.0.26/bin/setenv.sh contains the following lines

CATALINA_OPTS="-Djava.net.preferIPv4Stack=true"
export CATALINA_OPTS

This allows to use IPv4 and allows JavaMail to connect to these mail servers correctly.

1.2 Add the EOSP for Sites product full version serial number

The full version serial number is a Cumulus Option serial number that must be added to Cumulus serials in the Remote Admin of the Cumulus Server Console! 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. This is what you have to do:

Option 1: Use the Cumulus Client to activate EOSP:

1. Open the Cumulus Client.

2. Select 'File>Administration>Server Console'.

3. Login as Cumulus Administrator and select 'Remote Admin>License'

4. Use the Server Console menu and click 'Actions>Edit License' and add your EOSP for Sites product serial number.

5. Click 'Activate Cumulus...' to get a new Cumulus Activation Key that also unlocks the EOSP product. The license dialog should indicate an unlimited number of Clients (or 4095) for the EOSP for Sites product.

For more information on how to add a serial number to the Cumulus Option serials, please consult the Canto Cumulus manual.

You can also use the Cumulus Remote Admin through a web page to activate EOSP:

OR Option 2: Use the Cumulus Remote Admin to activate EOSP:

1. Open the following URL in a web browser on the Cumulus Server: http://localhost:8954/login.html (or replace localhost by the name of your server or its IP-address)

2. Login as Cumulus Administrator.

4. Click 'Edit License' and add your EOSP for Sites product serial number to the list of serial numbers.

5. Click 'Register with Canto via WWW' to get a new Cumulus Activation Key that also unlocks the EOSP product. The license dialog should indicate an unlimited number of Clients (or 4095) for the EOSP for Sites product after adding the new Activation Key.

For more information on how to add a serial number to the Cumulus Option serials using the Remote Admin web pages, please consult the Canto Cumulus manual (chapter Remote Admin via Web Browser).

Important: from Cumulus 9.2 or higher you will get the serial number for the product from Modula4. You will get a textblock to unlock the software from Modula4, which has to be entered in the Cumulus server console module 'Modula4 General Settings' shipped by Modula4. You will find more information about how to unlock the product in the Modula4 documentation.

1.3 Update your EOSP for Sites version

To update your 'Email Order System Pro for Sites' installation, you just have to remove the older EOSP product folder and replace it with the new version in the 'customizations' folder of your Sites web application. Here is an example how to update EOSP 8.1.1 with version 8.5.1:

1. Remove the folder .../Cumulus Sites/apache-tomcat-6.0.x/webapps/Sites/customizations/eospSites-8-1-1 (keep it as a backup!)

2. Copy the new product folder 'eospSites-8-5-1' to .../Cumulus Sites/apache-tomcat-6.0.x/webapps/Sites/customizations/eospSites-8-5-1

3. Please also delete the corresponding subfolder that belongs to your web application folder (folder with the same name in /work/Catalina/localhost) inside the 'work' directory of your Tomcat installation to make sure, that all pages of your web application are refreshed.

4. Restart Tomcat 2(!) times.

After the second restart of Tomcat your Sites web application will show the new functionality.

1.4 Uninstall EOSP for Sites

To uninstall the 'Email Order System Pro' from your Cumulus Sites installation, you just have to remove the 2 EOSP product folders from your Sites folder:

.../Cumulus Sites/apache-tomcat-6.0.x/webapps/Sites/customizations/eospSites-8-x-x
.../Cumulus Sites/apache-tomcat-6.0.x/webapps/Sites/EmailOrderSystemPro

After a restart of Tomcat your Sites web application will show its orginal behaviour.

1.5 Installation of the 'Collect Files' EJaP

The 'Email Order System Pro' comes with an application called 'Collect Files' to find the ordered files in the Cumulus catalog. This application is a Cumulus EJaP (Embedded Java Plugin) based on Canto's EJaP technology.

In the product folder you will find a folder '/Installation/CollectFiles'. Copy the sub-folder ('CollectFiles' and its contents) into the 'ejp' folder in the installation folder of your Cumulus Client application. Under Windows it is e.g. 'C:\Program Files\Canto\Cumulus Client\ejp', under Mac OS X it is 'Macintosh HD/Applications/Cumulus Client'. The 'ejp' folder of the Cumulus application can be found in the Cumulus package. You can reach this folder by clicking the mouse-button while holding down the CTRL-key on the Cumulus application. Click on 'Show Package Contents' in the context-menu. This will open a Finder window with a subfolder 'Contents'. In that folder you will find a 'MacOS' folder and there you will find the 'ejp' folder in which to copy the 'CollectFiles' folder.

Restart the Cumulus application to use the 'Collect Files' application, it will show a new menu item in your Cumulus application called 'Email Order System Pro'.

Important: if you already have an older version of the EJaP installed (filename 'CollectFiles.ejp'), please delete the old version before you restart your Cumulus Client! Only use this version if you have a Cumulus version 7.5 or higher installed!

The Email Order System Pro can be easily configured by using the Admin Pages that are installed inside your web application. When saving the settings through the Admin Pages for the first time, a configuration file (filename: 'eosp85Sites.properties') is created in the /temp/ directory of Tomcat.

After creating that file you can use the Admin Pages to change the settings or edit the configuration file '/temp/eosp85Sites.properties' with a text editor directly.

2.1 Basic Configuration (Admin Pages)

The Email Order System Pro comes with Admin Pages that help the Administrator to configure the settings of the EOSP functions. You can access the Admin Pages by opening this URL:

http://myServer(:8080)/mySites/EmailOrderSystemPro/admin

or by using the shortcut

http://myServer(:8080)/mySites/eospadmin

You will be redirected to the Login Page which requires the Cumulus Administrator Login to access the configuration pages. You can select the language of the configuration pages: English, Spanish or German. You can add more languages, if you like.

The Email Order System Pro's Admin Login Page

The Basic Configuration Page displays information about your current web application settings (like product serialisation and Mail Server Settings).

The Email Order System Pro's basic settings

The mail server settings are read from the EOSP configuration attributes. In the screenshot above these parameters are not set, make sure that they are set properly to allow sending emails.

Click on 'Configure...' to specify your Email Order System Pro attributes:

EOSP Mail Server Attributes

When opening this configuration for the first time, a basic initial set of parameters is displayed in the page. The parameters depend on the language selected (!), so if you have selected German as the language for the Admin Pages, you will find initial German settings. When saving the settings through the Admin Pages for the first time, a configuration file (filename: 'eosp85Sites.properties') is created in the /temp/ directory of your Tomcat web application server.

After creating that file you can use the Admin Pages to change the settings or edit the configuration file 'eosp85Sites.properties' with a text editor directly.

1) SMTP mail host: specify the SMTP mail host to connect to for sending any emails (configuration file attribute SMTPHost).

2) SMTP Port: you can leave the parameter empty, if you do not use SSL technology, EOSP will use the standard SMTP port in this case.

3) SMTP Security: if your mail server is using SSL technology, select 'Secure SMTP (SSL)'. Please specify the port that you have to use. E.g. if you use 'googlemail', the port is 465.

4) SMTP user name: the user name for the SMTP server authentication (configuration file attribute SMTPUsername).

5) SMTP password: the password for the SMTP server authentication (configuration file attribute SMTPPassword).

6) Sender Email: specify the e-mail sender address of any e-mail sent out by the Email Order System Pro (configuration file attribute SenderEMail).

Email Order System Pro Configuration: Attributes

7) EOSP function access: Enable the EOSP icons or buttons that you want to display (more details in chapter 2.1.1 Enable/Disable EOSP, EOSP icons and buttons).

8) Language: specify the basic language that should be used for sending emails (configuration file attribute EmailOrderSystemProLanguage). (en_US = English, de_DE = German, es_ES = Spanish). Other languages can easily be added by creating the appropriate localization files.

9) Order Limit: you can limit the number of files that all users of the web application are allowed to order in one step. For example: if you set the order limit to 5, the user will get an error message when he tries to send the order while the Collection Basket is containing more than 5 records. Important: you can disable the order limit for single users by assigning the Cumulus Server Permission $DisableOrderLimit in the User Manager of the Cumulus Server-Console.

10) Email Template Files: specify the email template files that are used to generate the email (configuration file attribute EmailTemplateFile.OrderForm and EmailTemplateFile.OrderFormWithSelection). You can find different template files in the folder '/EmailOrderSystemPro/config/templates'. If you would like to create your own email template file, put your version into this folder and specify the name of your file in this attribute (with suffix 'txt' or 'htm'.). The content type (text or html) that is used to generate the email is automatically set based on the suffix of the template file. Valid attributes are 'text/plain; charset=UTF-8' (default) and 'text/html; charset=UTF-8'. E.g. if the template file name ends on '.htm' the content type is set to 'text/html; charset=UTF-8' and so the Email Client software will interpret the email as HMTL.

11) Email Order Receipient: specify the email recipient address (the person who processes the orders) (configuration file attribute EmailOrderRecipient). You can specify one email address or a list of email addresses seperated by comma.

12) Use User Information: if you would like to use the additional information stored in the Cumulus User Manager (address information, etc.), set the attribute UseUserInformation to 'true'. This will automatically fill the fields in the order form with the information stored for the authenticated user in the Cumulus User Management (Cumulus $Users Catalog). Set the attribute to 'false', if the initial values of the order form fields should be empty. (more details in chapter 2.1.2 Auto Fill User Information).

Click on 'Save Configuration' to create or update the configuration file. The properties file, that you can find in the /temp/ directory of your Tomcat web application server, holds the parameters of your configuration.

All these attributes are valid for all the web applications using EOSP for Sites on your Tomcat web application server.

Important: please note that the name of a attribute must not contain a space charater alone, as this character would seperate words from each other. It is important that you put a \ in front of every space in the attribute name to glue the parts of the word together.

2.1.1 Enable/Disable EOSP, EOSP icons and buttons

You can show or hide EOSP and EOSP functions for all users of the web application and for single users seperately. To show or hide EOSP and its functions, just use the following (as we think) self-explaining settings:

The Email Order System Pro Product Configuration

After activating the EOSP feature for all users of the web application, you can disable the feature for single users separately. To disable EOSP functions, you can use Cumulus Server permissions that can be assigned to the user in the User Manager of the Cumulus Server Console:

The Email Order System Pro user permissions

The following Server Permissions are defined to disable EOSP functions:

Please note that you have to use the name of the permission exactly as shown in the list above (permission names are case sensitive!).

2.1.2 Auto Fill User Information

If you would like to use the additional user information stored in the Cumulus User Manager (address information, etc.), set the attribute UseUserInformation to 'true'. This will automatically fill the fields in the order form with the information stored for the authenticated user in the Cumulus User Management (Cumulus $Users Catalog). Set the attribute to 'false', if the initial values of the order form fields should be empty.

Auto Fill User Information in the order form

If the feature is set to true for all user, you can disable this feature for single user by setting the following Cumulus Server Permission for this user:

Please note that you have to use the name of the permission exactly as shown in the list above (permission names are case sensitive!).

2.2 More Configuration Options

After the installation of the 'Email Order System Pro' there is a new folder 'EmailOrderSystemPro' inside your web application folder and some modifications are made to original Cumulus Sites files in the main folder. Here is a list of the important files and folders:

When Tomcat is restarted, the copy mechanism of Cumulus Sites will copy the folder 'EmailOrderSystemPro' into the Sites' main folder and will also perform some modifications of original files based on XSLT. For example, one xslt stylesheet will add the EOSP buttons to the Collection Basket page, another one will add a load function for the EOSP application to the Sites.jspx file.

The order forms can be accessed in the Collection Basket page by clicking one of the new email order buttons or icons:

The first email order form

If you want to change the order form, open the file '...myTomcat/webapps/mySites/eospconfiguration.jspx' with a text or HTML editor.

REMARK: after changing the file in a running Tomcat environment (which is good for immediate testing) it is necessary to copy the modified file (when final) over to the folder /customizations/sitesEOSP-x-x-x to make sure that it is copied at next startup of Tomcat. If you do not copy the file, your file version will be overwritten by the original file at Tomcat startup.

Please note that one parameter of the order form sets the subject of the email. The hidden parameter 'Subject' sets the subject of the email in the file 'eospconfiguration.jspx' in line 155:

You can specify the subject of the email

The extended email order form comes with fields to specify the number of ordered files and their format. It also contains a price field and a remark field to show the functionality of the TAGs 'getPrice' and 'getFieldValue'. The 'Email Order System Pro' reads the information from the Cumulus catalog record fields 'Price' and 'Remarks'. If these fields are not available in your catalog, the fields in the File Selection section of the order form are left empty.

The second email order form

2.2.1 Definition of mandatory fields

You can define mandatory fields in the email form very easily. The technical name in the form of mandatory fields start with a '_' character, so just insert this character at the beginning of the field name to require a value. The 'Email Order System Pro' will check all mandatory fields before the email is generated.

In order to display the name with a "*" sign on your page in order to indicate to the user that this is a mandatory field simply add the "*" after the placeholder for the field name.

For example:

<td><label for="FirstName">${eospFirstName}:*</label></td>

The following error message is displayed if the user does not fill the mandatory fields:

The mandatory fields error message

Please note that the leading '_' is not diplayed in the field name in this error message.

Remark: if you change a field name in the order form ('eospconfiguration.jspx' or 'eospselectionconfiguration.jspx'), you also have to change the name of the field in the email template 'EmailTemplate.txt'.

2.2.2 Email body configuration

The body of the order email can be configured by using an Email Template file. The software comes with an example Email Template file called 'EmailTemplate_en_US.txt' (or 'EmailTemplate_de_DE.txt' for a German email or 'EmailTemplate_es_ES.txt' for a Spanish email). This is the contents of the example file:

The contents of the English Email Template File

The 'Email Order System Pro' reads the Template file and replaces the field names in brackets ([...]) against their values. Example: [_Name] inside the Template file is replaced against the value of the mandatory field 'Name'. An empty string is inserted if the specified field does not exist inside the order form.

The 'Email Order System Pro' also implements a placeholder to insert the date and time into the email. The placeholder for the default server date format is [$DATETIME$]. 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_en_US$ will return the date in a US English format. So it is 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.

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

The Selection Area at the end of the Email Template file is used for the second email order form (eospselectionconfiguration.jspx). A lot of parameters are transmitted in this order form. The number of parameters depend on the number of files in the Collection Basket. The Email Template file uses the *-notation to specify these form parameters. E.g. the placeholder [a*] stands for all the Asset Names in the email order form ('a0' to 'an').

The default selection in the English Email Template File

If you specify the file selection as in the example above ('[Selection]' without additional parameters), the default selection values are used, which are: number, asset name, catalog name and format.

You can also specify the exact values that you want to show in the email by specifying additional parameters following the word 'Selection' in round brackets (new since version 8.6.0.3):

A modified selection in the English Email Template File

In the brackets you can provide the placeholders you want to use separated by ':'.

In addition to the values that come from the order form as request parameters that you can specify by using the placeholders (n*, a*, c*, s*), you can also use Cumulus field UIDs to show the field value's display string provided by the Cumulus Java Classes. You have to specify the field UIDs incl. the curly brackets '{...}'. In the example above the record name field is specified by its UID.

Here is another example:

A selection using placeholders and field UIDs in the English Email Template File

The Email Template file seen in the example above creates an email like this:

The contents of the email order - use 'Collect Files' to find and convert the files

Important: all template files have been converted to UTF-8, if you make any modifications in the file please make sure to store its contents in UTF-8 format.

2.2.3 The EOSP Tag Library

The 'Email Order System Pro' consists of a lot of web pages (in HTML and JSPX format) and a TAG library that enhances the functionality of Cumulus Sites. The Tag library consists of the following TAGs:

2.2.4 Send Email Order in HTML format

EOSP can also send the order email in HTML format, if the template file is a HTML file (with suffix '.htm'). In this case the Content Type of the email will be set to 'text/html; charset=UTF-8' (default is 'text/plain; charset=UTF-8') and the email will be sent in HTML format. This will allow to use formatting the text in the email order by using HTML tags.

The HTML Email Order example

The product comes with six example Email HTML Templates (in English, German and Spanish) that you can use as a start to develop your own HTML templates. You can find the files at 'mySites/EmailOrderSystemPro/config/templates':

- EmailTemplate_en_US.htm (English HTML template for simple order form)
- EmailTemplateWithSelection_en_US.htm (English HTML template for order form with selection)
- EmailTemplate_de_DE.htm (German HTML template for simple order form)
- EmailTemplateWithSelection_de_DE.htm (German HTML template for order form with selection)
- EmailTemplate_es_ES.htm (Spanish HTML template for simple order form)
- EmailTemplateWithSelection_es_ES.htm (Spanish HTML template for order form with selection)

To use these files to send an HTML Email Order (for example in English), the following settings are necessary:

The Email Order HTML settings

The suffix of the template file (.htm) indicates that the email shall be sent in HTML format.

Important: all template files have been converted to UTF-8, if you make any modifications in the file please make sure to store its contents in UTF-8 format.

2.3 Multi-Mail (file-based order recipients)

The Multi-Mail function allows to send the order email to email addresses contained in a metadata field. In the case that different assets need to be handled/processed by different people this function is very helpful.

The order email containing the list of all selected files in the basket is sent to the main email order recipient (configured in the basic settings of EOSP). Additionally email orders are sent out to all the email adresses specified in the metadata field.

The software looks for a metadata field named 'EOSP_Recipient' in the Cumulus Catalog, which has to be a text field (of type 'String').

The 'EOSP_Recipient' field definition in Cumulus

If the field is available, it gets the field value and verifies if the value is a valid email address or contains a list of valid email adresses separated by comma. If so, additional email orders are generated and sent out to these email recipients. In this case order list in the email only contains the names of the files they 'own'.

In the example below, Paul has the ownership for this file and he will get the order email containing a request for the file 'P1030998.JPG'. If he has the ownership for more files in the Cumulus Catalog and some of these files have also been collected by the web user, he will get a list of these order files to process.

The 'EOSP_Recipient' field value in the information window

Here is an example. The web user orders these 5 files:

EOSP will generate 4 order emails:

1) A full order is sent to the main EOSP contact (configured in the EOSP settings) containing the requested files file1.tif, file2.tif, file3.tif, file4.tif, file5.tif.

2) Multi-Mail generates the following separate orders based on the defined ownership:

Email no. 2 goes to paul@ad-agency.com: file1.tif, file4.tif, file5.tif
Email no. 3 goes to peter@service-buero.de: file2.tif
Email no. 4 goes to linda@ad-agency.com: file4.tif

If there is no ownership defined (for example file3.tif) the file will appear in the main order email but no additional multi-mail order email is necessary.

If the field 'EOSP_Recipient' is missing in the Cumulus catalog, no multi-mail email orders are sent out.

Remark: please note that the web user might have access to different catalogs at the same time and some catalogs might have the multi-mail metadata field and others might not. EOSP will send out multi-mails for the records from the catalog with 'EOSP_Recipient' field, although there might be files in the Collection Basket without this ownership defined.

2.4 How to modify the email order form

Here is an example of how to modify the email order form. This example adds two new fields to the order form, a text field and a checkbox.

1) Add the following field definitions to the email order form file '/mySites/customizations/eospSites-x-x-x/eospconfiguration.jspx' in the <form> section:

<tr>
<td><label for="Email">Add. Order Info:</label></td>
<td>
<input type="text" id="AddOrderInfo" name="AddOrderInfo" class="inputCreatePINCollection" value=""/>
</td>
</tr>

<tr>
<td><label for="Brochure">Brochure:</label></td>
<td align="left">
<input type="checkbox" id="Brochure" name="Brochure" class="inputCreatePINCollection" checked="checked"/>
</td>
</tr>

2) To forward the form field values to the order email you have to modify the email order template file 'Template /mySites/customizations/eospSites-x-x-x/EmailOrderSystemPro/config/templates/EmailTemplate_en_US.txt':

Add. Order Info: [AddOrderInfo]
Brochure: [Brochure]

To make the modifications available, you have to restart your Tomcat web application server which will copy the modified files into the mail web application folder. That's all you have to do to add the these two fields to your order process!

3) If you want to make sure that the user specifies the 'Addional Order Information', you have to make the field mandatory just by adding the '_' to the field name, as every field name starting with '_' will be treated as a mandatory field.

Modification in file '/mySites/customizations/eospSites-x-x-x/eospconfiguration.jspx':

<tr>
<td><label for="Email">Add. Order Info:</label></td>
<td>
<input type="text" id="AddOrderInfo" name="_AddOrderInfo" class="inputCreatePINCollection" value=""/>
</td>
</tr>

Modification in 'Template /mySites/customizations/eospSites-x-x-x/EmailOrderSystemPro/config/templates/EmailTemplate_en_US.txt':

Add. Order Info: [_AddOrderInfo]

4) If you would like to support multiple languages in the order form, you can use the localisation files technology coming the Sites (and also used by EOSP):

Modification in file '/mySites/customizations/eospSites-x-x-x/eospconfiguration.jspx':

<tr>
<td><label for="Email">${AddOrderInfo}:</label></td>
<td>
<input type="text" id="AddOrderInfo" name="AddOrderInfo" class="inputCreatePINCollection" value=""/>
</td>
</tr>

<tr>
<td><label for="Brochure">${Brochure}:</label></td>
<td align="left">
<input type="checkbox" id="Brochure" name="Brochure" class="inputCreatePINCollection" checked="checked"/>
</td>
</tr>

The label name is not a static string anymore but defined by the variable ${AddOrderInfo} and ${Brochure}.

Modification in file '/mySites/customizations/eospSites-x-x-x/eospconfiguration.jspx':

<fmt:message var="AddOrderInfo" key="EOSP.EmailOrderForm.AddOrderInfo" />
<fmt:message var="Brochure" key="EOSP.EmailOrderForm.Brochure" />

Add these <fmt:message> statements to the list of statements at the beginning of the page.

To specify the label text in the different languages, add the appropriate string to the localisation files in the folder '/mySites/customizations/eospSites-x-x-x/WEB-INF/classes/resources/bundles':

eosp.properties
eosp_de.properties
eosp_en.properties
eosp_es.properties

Add the following text to the eosp.properties file to specify the English localisation:

# new field localisations added to the order form

EOSP.EmailOrderForm.AddOrderInfo=Additional Order Information
EOSP.EmailOrderForm.Brochure=Brochure

Then modify all the other localisation file accordingly.

Important: a Tomcat restart is necessary after every modification of the localisation files as the /resources/ folder is read by Tomcat only at startup.

The Email Order System Pro comes with an application called 'Collect Files' for Mac OS X and Windows which helps to find the ordered files in the Cumulus catalogs. This application is based on the Canto EJaP (Embedded Java Plugins) technology. After installing the EJaP in the Cumulus Client (see chapter 1.2 Installation of the 'Collect Files' EJaP for details), a new menu item 'Email Order System Pro' is available to the user.

'Collect Files' helps to find the files in the catalog and it also performs the specified Asset Actions

With the application 'Collect Files' the user can verify, if all the ordered files are available in the Cumulus catalog. The 'Email Order System Pro' generates an email that holds a list of files with the Cumulus catalog name, the asset name, the unique RecordID, and the asset action (conversion) from the WPP/ICP collection basket. The values are seperated by semicolon.

This is what you have to do to process the order using the 'Collect Files' functionality:

1. Open the Cumulus Client and open the Cumulus catalogs necessary to process the order (you will find the names of the catalogs in the order email).

2. Open the application 'Collect Files' by clicking on the menu item 'Email Order System Pro>Collect Files...'.

3. Open your email application and the order email of your customer.

The list of ordered files in the email

4. Copy the list of ordered files from the Email into the 'Collect Files' textfield. The list contains the catalog names, asset names, the unique RecordIDs, and the asset actions, delimited by semicolon. If you have saved the list of order files to a text file, you can load this file by clicking the button 'Load File List'.

5. Start the search in the frontmost Collection by clicking the start button 'Start Search'. A search will be performed for the files in the frontmost Collection. You will get an error message if the frontmost collection does not contain all necessary catalogs.

6. All the found records will be displayed in the frontmost Collection and a search statistic will be displayed. A list of error messages will be displayed if some of the files could not be found in the Catalog. The frontmost Collection now contains all the found files. You can select all records in the Collection and assign appropriate metadata or copy the assets to a folder to prepare the files for shipment (by using Cumulus functionality).

7. Click the button 'Copy + Convert Files...' to use the asset actions provided in the email order. The files will be converted based on the asset action and copied to the selected folder.

The Collect Files configuration dialog

8. If you deselect the checkbox 'Use action while copying asset' the asset action is not used and just the original files are copied to the selected folder. The button title changes to 'Copy Files...'.

Remark: the language of the application 'Collect Files' depends on the current language of the Cumulus Client (English or German).

3.1 Collect Files EJaP - menu and preferences

The Collect Files EJaP creates its own menu 'Email Order System Pro' in the Cumulus menu.

The Menu Options

The menu comes with the following options:

Collect Files...

Opens the main dialog and asks to select the text file containing the list.

Preferences...

Opens the Canto Cumulus Preferences dialog. You will find the Collect Files preferences under 'User Settings>General>Collect Files EJaP'.

Online Documentation...

Brings you to the product's web page which contains detailed product information and the current product documentation.

Info...

Version number information and a button that leads you to the website.

The Collect Files preferences allow to specify the encoding of the text file that contains the list of information that you want to search for.

The Collect Files User Settings

The Collect Files EJaP use the standard encoding of the operating system when opening the text file. If your text file uses a different encoding (e.g. UTF-8), please specify the encoding here before selecting the file.

For a user that has never opened and saved the CollectFiles preferences before, the initial value of the encoding is set based upon a configuration file, that you can find in the folder myCumulusClient/ejp/CollectFiles/conf/CollectFiles.properties.

4.1 bcc: the email order

You can also send the email order as a blind carbon copy to a list of users. You can specify the bcc address in the form parameter 'bcc' in the email forms 'eospconfiguration.jspx' and 'eospselectionconfiguration.jspx'.

Specify a bcc address if needed

4.2 Show catalog name in email order form for Multi-Catalog Collections

The name of the catalog is displayed with every asset in the collection basket. This is necessary if you are working with a mult-catalog collection. The name of the catalog is not displayed if you are only using one catalog in the current collection.

The catalog names are displayed with every asset

4.3 Use Asset Actions to convert files

The email order also contains the asset action per file that has been specified by the user in the Collection Basket of WPP/ICP.

The email order also contains asset action information

The 'Collect Files' EJaP supports these 'Asset Actions'. In the example above, some of the files will just be copied into the specified folder, others will be converted to JPG before they are put into the specified folder.

Select 'Use action' to convert the files before collecting the files in a folder

In the 'Collect Files' EJaP you can specify if you want to convert the files by using the specified Asset Actions, or not.

Important: please not that Canto does not support using the asset actions in EJaPs on Mac OS X in Cumulus Version 6. This function is only available to all Windows users (Cumulus 6 or 7) and to Macintosh users with Cumulus version 7.0 and higher.

4.4 Multi-Language Support

The Email Order System Pro supports English and German out of the box. The Cumulus Admin can add more languages, if necessary. All the text can be localised in localization files and the language used in the order forms and emails can be specified in the configuration file.

The product comes with three localization files:

- eosp_en.properties (English)
- eosp_de.properties (German)
- eosp_es.properties (Spanish)

and a fallback file 'eosp.properties'.

4.4.1 Add a new language to the product

To add another language (French in this example) to the product, please follow these steps:

1) Duplicate the English localization file '.../Cumulus Sites/apache-tomcat-6.0.x/webapps/Sites/customizations/eospSites-8-x-x/WEB-INF/classes/resources/bundles/eosp_en.properties' and rename it 'eosp_fr.properties' in that folder. The naming convention for the file uses the country code after the '_' character.

2) Translate the contents of the file. After a restart of Tomcat the new translations will be available to EOSP. If you are using French in your Web Browser settings, you will get the order forms in French now.

3) If you want to translate the order email into French either, duplicate the template file '.../Cumulus Sites/apache-tomcat-6.0.x/webapps/Sites/customizations/eospSites-8-x-x/EmailOrderSystemPro/config/templates/EmailTemplate_en_US.txt' and rename it 'EmailTemplate_fr_FR.txt' in that folder. Translate the Strings in the file into French, but not the variables in the brackets '[]'.

4) Log into the EOSP Admin and set the Email Template File setting to 'EmailTemplate_fr_FR.txt'. You can also set the standard language setting of the product to 'fr_FR', if you like. After saving the settings and a restart of Tomcat, which will copy the files from the customizations folder into the main directory, the next order email will be sent in French.

5) If you want to send the email orders in HTML format, apply steps 3) and 4) to '.../Cumulus Sites/apache-tomcat-6.0.x/webapps/Sites/customizations/eospSites-8-x-x/EmailOrderSystemPro/config/template/EmailTemplateHTML_en_US.txt'.

6) To use the new language in the admin area, you just have to login into the admin pages with the appropriate web browser settings. If you want to set the language for the admin pages explicitely, use the following URL to log into the admin area:

http://myServer(:8080)/Sites/EmailOrderSystemPro/admin/login.jsp?lang=fr

If you have created the localization files, we would be happy to add these to our product. Please just send the files to us by clicking here and we will make sure that your translation is part of the next product.

4.5 Auto-Fill order form with user information from Cumulus $Users Catalog (Server Console)

The Canto Cumulus User Management that is implemented in the Cumulus $Users catalog can hold a lot of information about the user. You can specify the additional user information in the Server Console User Manager in the 'Additional Fields' Tab. These user properties can be used by the Email Order System Pro in the email order form:

Specify the additional user info in the Cumulus Server Console to use it on the order form

If the configuration attribute 'UseUserInformation' is set to true (default), the information is automatically read into the Email Order form, so the user does not have to specify all the details with every order again and again. Of course the user is allowed to overwrite the information in the order form, if necessary.

Please keep in mind that you can open the $Users catalog in the Cumulus Client to fill the additional fields in a quite comfortable way!

4.6 Disable save permissions on a Demo Server

The Cumulus / Email Order System Pro Administrator can enable or disable all functions that modifies the settings by setting an attribute inside the web application. This option is useful for sales partners to set up Email Order System Pro on a demo server.

You can disable all saving functionality in the page '/Standard/EmailOrderSystemPro/admin/switch.jsp' in line 14:

session.setAttribute("com.hc.eosp.writeEnabled", "true");

Set the value of the attribute to "false" to disable the saving of permissions.

4.7 Show Thumbnails in the Order Form

The TAG 'getThumbnail' allows to show the thumbnails from the Cumulus catalog in the order form. You can specify the size of the Thumbnail in the TAG attribute 'size'. In the example below, the size attribute is set to 64 pixels.

You can show the Thumbnails in the Order Form

4.8 Email Subject configuration

The email subject can be configured in the localization files of EOSP.

All the text can be localized in localization files and the language used in the order forms and emails can be specified in the configuration file.

The product comes with three localization files:

- eosp_en.properties (English)
- eosp_de.properties (German)
- eosp_es.properties (Spanish)

and a fallback file 'eosp.properties'.

To modify the email subject just find the entry named 'EOSP.EmailOrderForm.Subject'.

4.9 Debug Log

If sending the order emails by EOSP fails, you can activate a DEBUG Log to find out more on what is going wrong. Open the EOSP configuration file /apache-tomcat-x.x.xx/temp/eospXSites.properties with a text editor and add a new line with the folling settings:

debug=true

After saving this new line to the configuration file and sending another EOSP order you will find the log file at /apache-tomcat-x.x.xx/temp/EOSPEmailLog.txt. The file will inform about your current settings and the error message, if available.

Your feedback is very much welcome!

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

Remark: we do not offer a telephone hotline for this product. Please send in all your requests by email.

Version 9.0.0.2 - December 2014

This update implements modifications to support Cumulus 9.2. It implements a new serial number mechanism which is independent from the Canto module serial numbers.

Version 9.0.0.1 - Januar 2014

Bugfix release that fixes a bug when sending multi-mails with a modified selection of field values.

Version 9.0.0 - October 2013

Implements a necessary modification for Cumulus Sites 9.

Version 8.6.0.3 - August 2013

Implements two major modifications:

- the contents of the file selection part of the order email can be specified by using placeholders and (new) Cumulus field UIDs.
- new parameters for the <getNumber> TAG to allow to specify value, size and maxlength of the number box in the order form with selection

Version 8.6.0.2 - January 2013

Implements a necessary modification for Cumulus Sites 8.6.1. EOSP Admin was running into a null pointer exception when showing the current settings.

Version 8.6.0.1 - November 2012

A runnung CIP Canto Integration Platform inside the Tomcat webapps folder overwriting all mail settings prevented sending EOSP order emails (a IOError was displayed). The new version creates new settings independant from the Canto CIP module.
New DEBUG functionality to get a more explicit error message when sending the email order fails. A more explicit debug log information is written into /temp/EOSPEmailLog.txt file and the Tomcat log files.
New version of the Collect Files EJaP to also support different encodings (like UTF-8) when loading the order text files, new EJaP preferences (initialEncoding settting) and an optimized menu.

Version 8.6.0 - July 2012

This new version implements the EOSP technology for Cumulus 8.6 (requires Cumulus Java Classes technology 8.6).

Version 8.5.0 v2 - April 2012

The new version shows the order forms for the Admin user, independent from the permissions.
A version number is displayed in the order forms.
The technology can now be used in the Tomcat ROOT directory also.

Version 8.5.0 v1 - January 2012

The email template files are now read in UTF-8 format to also support the Korean system. All template files have been converted to UTF-8, if you make any modifications in the file please make sure to store its contents in UTF-8 format.

Version 8.5.0 - December 2011

This new version implements the EOSP technology for Cumulus 8.5 (requires Cumulus Java Classes technology 8.5).

- Support of the Cumulus' Multi-Language features of Cumulus 8.5
   - Asset Actions
   - Catalog Name
   - Field Values

- Multi-Mail feature: based on the ordered files, EOSP can create multiple order emails with different recipients. The email recipients can be specified in the Cumulus Catalog in a text field named 'EOSP_Recipient'.

- New CollectionBasket button pane to open the order forms.

- CollectionBasket Buttons and Icons configurable for the web application and (!) per User, new settings and permissions

- Fully integrated into the Multi-Languages of Cumulus Sites 8.5

- List of files additionally sent as email attachement, attachement filename based on username, date and time of order

- Easy access to EOSP Admin web application through /eospadmin forwarding into the appropriate directory

- Auto fill use information can be disabled per user (permission $DisableAutoFillUserInformation)

- new optimized 'CollectFiles' EJaP to find the files in the Cumulus Client 8.5 or higher (optimized for CJC 8.5 technology)

- minor modifications:
   - removed Selection List from EOSP email order when using the simple order form
   - separated the template files for simple order and order with selection
   - removed configuration parameter 'EmailContentType', which is now read automatically from the template filename suffix
   - renamed HTML email template files
   - order form field 'AssetActions' can now be configured mandatory ('_AssetActions')

Version 8.1.1 v1- June 2011

The email order contentType has been set to 'text/plain; charset=UTF-8' to support special characters in all the email applications.

Version 8.1.1 - June 2011

This release comes with an implementation for Cumulus Sites 8.0.x, 8.1.x (installation folder eospSites-8-1-0) and another one for Cumulus Sites 8.5 (installation folder eospSites-8-5-0). The implementation for Cumulus Sites 8.5 also supports the new Sites' 'themes' technology.

This new version also supports Spanish in the order forms, the EOSP Admin section and the email templates. A new function to allow Java Date and Time patterns was added to support Spanish date and time format in the email orders.

It also fixes a localisation bug and a problem with the selected Asset Action on Mac OS X servers.

Version 8.1.0 v4 - May 2011

This update allows the Administrator to configure the Email Subject.

Version 8.1.0 v3 - January 2011

This update contains some minor modification that have to do with empty records in Cumulus Catalogs. Since version 8 of Cumulus it is possible create empty records, that obviously do not have a thumbnail or an Asset Name in the beginning. EOSP for Sites now supports these empty records.

A problem with Asset Names containing the character " (quotation mark) has been fixed.

Version 8.1.0 v2 - January 2011

This update contains a minor modification that fixes a bug that slowed down the display of the order form. The old version tried to get the catalog names of the records by analyzing all records in the current collection (which might be in worst case all records in all catalogs). In this new release the catalog names are read from the records in the collection basket, which is much faster (of course).

Version 8.1.0 v1 - December 2010

This update contains a minor modification that was necessary to use SSL when sending emails through EOSP for Sites.

Version 8.1.0 - November 2010

This version of the Email Order System Pro is the first version for the Cumulus Sites product. The product is based on the Email Order System Pro product that has been out on the market since 2003 in different versions for various Cumulus web applications.

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.