*

[PlanetJ Corporation

[support@planetJavaInc.com]

[www.PlanetJavaInc.com]

 

 

 

 


WOW Email is a separately licensed, fee based add-on that allows users to create, manage and send email from a WOW Application. Another feature of WOW Email is the ability to have email sent to a specific account when someone inserts or updates a field in a specific table. The newest feature of WOW Email is the ability to use a URL call to send email. This is a very powerful feature as it can be set up via a task scheduler to auto run at a time specified by the user.

 

The uses for WOW Email are almost limitless. You can create a form email and send statements or bills to customers, using replacement variables to fill in their personal information. You can use it to manage and monitor your database by setting up a confirmation email to be sent when someone modifies the database. Anything you can do via webmail or client-based email can be done with WOW Email. Simple, powerful, WOW!


Installation Instructions

Accessing the WOW Mail Application

Email Server Entries

Other Control Settings

SMTP Mail Server Settings

Email Address Settings

Email Batch Settings

Email Entry File

Confirmation Email Settings

Email Entries

Control Settings

Other Email Settings

Email Recipients

Confirmation Email Settings

Configuring Auto Send Email

Configuring Manual Send Email

Configuring Confirmation Send Email

SendEmail API

URL Call

Using SendEmail to Send a Pre-configured Email Entry

Supported URL Parameters (parameter names are case sensitive):

Using SendEmail to Send an Email with the Content Generated from a WOW Operation

Supported URL Parameters (parameter names are case sensitive):

Direct Java Class Call

Sending an Email With the Email Content Generated from a WOW Operation

Constructor Parameters:

Sending Email Using a Pre-configured Email Entry

Constructor Parameters:

Creating Automated Email with WOW SendEmail

Scheduling Tasks with runURL

Using the Results of a Row Collection as a Distribution List


Installation Instructions

 

1. Restore the WOW metadata library (WOWMAIL65):

 

a) i5 or AS400:

1) Ftp the save file provided (wowmail.savf) to your i5. Assuming the save file created has the same name, then

2) RSTLIB SAVLIB(WOWMAIL65) DEV(*SAVF) SAVF(WOWMAIL65) MBROPT(*ALL) ALWOBJDIF(*ALL)

 

b) MySQL:

1) Start up the MySQL Adminstrator for your MySQL DB.

2) Click on the Restore option.

3) Click on the Open Backup File button and select the sql file provided (wowmail65.sql).

4) You should be able to leave the settings to their default values. Restore the catalog wowmail65 by clicking on the "Start Restore" button.

 

2. Add the Email jar to your existing WOW webcontext in Tomcat (if you already have WOW installed). This is needed for adding email functionality to your WOW product:

a) Copy wow-email-X.X.jar and commons-email-X.X.jar(where X.X is the current version) found in this .zip file and paste it into your existing webapp's lib folder:

~\Tomcat 6.0\webapps\wow65\WEB-INF\lib

b) Restart Tomcat to pickup the new jar files and the new web application.


Accessing the WOW Mail Application

To access the WOW Mail application, open a web browser.  Navigate to a URL similar to the following: http:// [ localhost:8080/wow70] /run?id=0&_pj_lib=wowmailXX   You will need to replace the bracketed ([ ]) section of the URL with your WOW URL (something like www.mycompany.com/wow65/) and the XX with the metadata version of WOW Mail you are using.

Email Server Entries

From the WOW Mail application, this menu item (Email Setup > Work with Email Server Entries) lets you define an email server entry to be used for sending email.  You'll need email server and account information (similar to what you would use for email programs such as Microsoft Outlook or Thunderbird):

 

Other Control Settings

 

SMTP Mail Server Settings

 

Email Address Settings

 

Email Batch Settings

 

Email Entry File

 

Confirmation Email Settings


Email Entries

From the WOW Mail application, this menu item (Email Setup > Work with Email Entries) lets you define an email template to be used for sending email:

 

Control Settings

 

Other Email Settings

Note: Replacement variables apply only when a “To ID” operation is specified or this email entry is a confirmation email. There must be a corresponding Row from which replacement variables can locate a substitution value. In the above example, the current value for field “firstname” is used as well as the value from the field "eventid".

 

Email Recipients

 

Confirmation Email Settings

Note: If an operation is defined to send a confirmation email, WOW looks for a matching entry in the email entries defined. A match requires that the file, library and connection name for the operation be the same as the above three values (not these values specifically but the 3 values that reference your own information). If a match is not found, a default email is sent using the default email control entry.


Configuring Auto Send Email

Auto send email is an email that is sent automatically on a set schedule. To configure an auto send email, complete the following steps:

  1. Create an “Email Sender Batch” operation in the Outgoing Email application.
  1. Set the Operation Type to => Auto-Run Batch Process
  2. Replace the Operation Properties with an AutoRun property group similar to the following:

AutoRun {/* The date the batch auto run should start. format = MM/dd/yyyy */startDate:9/01/2005;/* The time the batch auto run should start. format = hh:mm a */startTime:3:00 pm;/* How often the batch auto run should execute (in seconds). 900 seconds = 15 minutes, 86400 = 1day, 604800 = 7 days */frequency:86400;}

  1. Set the operation’s Auto Run status to => Enabled
  1. Create an “Email Sender Control” operation in the Outgoing Email application:
  1. Leave the Operation Type as => SQL
  2. Set the operation code as => SELECT * FROM WOWMAIL64.EMAILCNTRL WHERE ACTIVE='Y'
  3. Set the Row Collection Class as planetj.dataengine.email.EmailSenderRowCollection
  4. Set email drop down for auto-run.
  1. Start the Outgoing Email operation.
  2. Use the “Email Control Entries” operation to create an Email Control entry (defines the SMTP email server settings used for sending the email). Ensure that the “Auto send is active for this entry” field is checked. See the “Email Control Entry Fields” section for more details.
  3. Use the “Email Entries” operation to create an Email entry (defines the email to be sent to each recipient). Ensure that the “Corresponding Control Record in the Control File” field is set to the control entry from the previous step. See the “Email Entry Fields” section above for more details.
  4. Change your WOW application’s web.xml file so that the PJ_AUTO_RUN parameter is set to true.
  5. Restart Tomcat or your application.


Configuring Manual Send Email

 

Manual send email is an “Email Entry” that is sent manually using the send email icon  (to the left of the email entry) from the “Manage Email Entries” screen. To configure a manual send email, complete the following steps:

  1. If an appropriate entry does not already exist, use the “Email Control Entries” operation to create an Email Control entry (defines the SMTP email server settings used for sending the email). See the “Email Control Entry Fields” section for more details.
  2. Use the “Email Entries” operation to create an Email entry (defines the email to be manually sent to each recipient). Ensure that the “Corresponding Control Record in the Control File” field is set to the control entry from the previous step. See the “Email Entry Fields” section for more details.
  3. To send the email, click on the manual email send icon  to the left of this email entry (this sends the email to the To ID or To ID Operation recipients).


Configuring Confirmation Send Email

 

Confirmation send email is an email entry that is sent automatically when an operation is run to perform an update or insert. The email is sent to the email ID included with the confirmation email operation. To configure a confirmation send email, complete the following steps:

 

  1. Create a Confirmation Send Operation. The operation can be created in any application, not just the Outgoing Email application.
  1. Set the Operation Code and Display Attributes (Allow Insert, Allow Updates) to allow for an update or insert into the file that will trigger the confirmation email. The Operation Code must include an email field, which will be the recipient of the confirmation email after the completion of the insert or update. An email field is a character type field with its Usage ID set to -40 (in the field’s Field Descriptor).
  2. In the Advanced section, set the row class to one of the following:

Use the appropriate class file, depending on whether you want a confirmation email sent on an insert, update or both.

  1. If an appropriate entry does not already exist, use the “Email Control Entries” operation to create an Email Control entry (defines the SMTP email server settings used for sending the email). See the “Email Control Entry Fields” section for more details.
  2. Use the “Email Entries” operation to create an Email entry (defines the confirmation email to be sent to each recipient).
  1. Ensure that the “Corresponding Control Record in the Control File” field is set to the control entry from the previous step.
  2. Set the Confirmation Email Settings (File, Library, Connection) to correspond with the Confirmation Send operation in step 1 (the file and library from the operation’s “Operation Code” field and the connection used in the operation’s “Connection Alias” field).
  3. See the “Email Entry Fields” section for more details.
  1. Running the Confirmation Send Email operation should now trigger an email to be sent once the update and/or insert are complete.

 

Note: A Confirmation Send operation can reside in any application, as long as there is a corresponding entry (with the correct table, library and connection) in the EMAILLOG file.


SendEmail API

 

The newest addition to our WOW Email Add-on is the SendEmail api.  This class allows the user to send email using HTML based email or the results of a WOW operation.  The SendEmail api can be invoked by using a URL call or a direct class call. There are 4 different methods to use the SendEmail api.  These will be described in depth below:

 

URL Call

SendEmail can be invoked with a simple URL call.  The two methods are as follows:

Using SendEmail to Send a Pre-configured Email Entry 

SendEmail can be used to send a pre-configured email entry (see section Email Entries) via a URL.  Here is an example of using a URL to invoke SendEmail utilizing an email entry:

        www.mycompany.com/wow65/run?PJMRCLASS=planetj.dataengine.email.SendEmail&emailId=5&logSend=ALL

NOTE in the URL:

Supported URL Parameters (parameter names are case sensitive):

Using SendEmail to Send an Email with the Content Generated from a WOW Operation

SendEmail can be used to send an email, with it's email content populated with the results from a WOW Operation via a URL.  Here is an example of using a URL to invoke SendEmail from an operation:

        www.mycompany.com/wow65/run?PJMRCLASS=planetj.dataengine.email.SendEmail&operation=325&emailConfig=8&emailToId=jcustomer@gmail.com

NOTE in the URL:

Supported URL Parameters (parameter names are case sensitive):

Direct Java Class Call

For the next 2 methods, if you are utilizing a Java subclass, you can invoke the SendEmail API within your custom code.  

Note:  For any optional parameter, use null when non-applicable.

Sending an Email With the Email Content Generated from a WOW Operation

The SendEmail api can be used to send an email, with it's email content populated with the results from a WOW Operation.  SendEmail is invoked as follows:

            int count = 0;

                try {

                    // SendEmail sendEmail = new SendEmail(379, null, null, null, null, null, new Integer(378), new Integer(1), "WOWMAIL65",

                    //    "NONE");  /* Example that uses the default for most of the parameters. */

                        SendEmail sendEmail = new SendEmail(operation, toId, ccId, bccId, bounceId, fromId, new Integer(toIdOperation),

                          new Integer(configId), emailLibrary, logSend);

                        count = sendEmail.send();

                }

                catch (CMException cme) {

                                 System.out.println("Error occurred sending email: " + cme.getMessage());

                }

 

Note: Java 6 will let you specify an int value in place of an Integer value (for Integer parameters) and converts the value for you automatically.

Constructor Parameters:

Sending Email Using a Pre-configured Email Entry

The SendEmail api can be used to send a pre-configured email entry (see section Email Entries).  SendEmail is invoked as follows:

                int count = 0;

                try {

                    // SendEmail sendEmail = new SendEmail(null, null, null, null, null, new Integer(emailId), "WOWMAIL65", null,

                    //     null);  /* Example that uses the default from the Email entry for most of the parameters. */

                        SendEmail sendEmail = new SendEmail(toId, ccId, bccId, bounceId, fromId, new Integer(emailId), emailLibrary, logSend,

                          parameterRow, new Integer(toIdOperation));

                        count = sendEmail.send();

                }

                catch (CMException cme) {

                        System.out.println("Error occurred sending email: " + cme.getMessage());

                }

 

Note: Java 6 will let you specify an int value in place of an Integer value (for Integer parameters) and converts the value for you automatically.

Constructor Parameters:


Creating Automated Email with WOW SendEmail

You can use one of the scheduling tools (such as Windows Task Scheduler) available to invoke the SendEmail class (via a URL call) on a predetermined schedule. The scheduling tool must exist on a system that has access to the WOW server. Below is an example using the Windows Task Scheduler on a Windows based PC

(Note: steps may vary depending on the tool used):

Scheduling Tasks with runURL

WOW includes a utility program named "runURL", which can be used when running a scheduled task.  The runURL program is located in the WEB-INF directory within your WOW installation.  You can either run the program directly from the WEB-INF directory or copy the files runURL.bat and runURL.jar into a more convenient location.  In our example, we copied those 2 files to the folder "C:\Program Files\wow".

 

From the task scheduler, create a new task:

 

 

 


Using the Results of a Row Collection as a Distribution List

By using a PlanetJ created Row Collection Class (planetj.dataengine.email.SendEmailRowCollection), you can use the results of an SQL operation to create a distribution list and email on-the-fly.  In functional terms, this Row Collection Class adds a RowCollection action at the bottom of the screen that will cause the default emailer to pop-up a composition screen pre-filled with all the email addresses that could be extracted from the resulting RowCollection.

To set this up, first start by creating a SQL operation that returns email addresses in the Row Collection.

select * from pjdata.employeeIn this case, pjdata.employee contains a field named EMAIL which has a FD Usage Id of -40, which corresponds to an email field. 

It also has its field class set to Email, as seen in the images below:

You will also want to set the Row Collection Class in the Operation to planetj.dataengine.email.SendEmailRowCollection as seen in the screenshot below:

Now, when you run the operation, a button will appear at the bottom of the Row Collection:

Once clicked, your default email program will open an email composition window.  All the email addresses from the Row Collection will be included in the To: field as seen in the screenshot below:

 

NOTE:  As you can see by the image above, Gmail can even be used to compose the email.  In this case, the browser has Google Toolbar installed so the Gmail window opens.

NOTE:  Since the "mailto" HTML (assigned to the button) must be generated when the RowCollection is rendered, row selection cannot be used to filter the list of email addresses, it must be done by filtering via SQL parameters.