Email Message Catalog

Email message catalog (EMC) is wrapper application package for the PeopleSoft MCF Mail classes that allows you create email messages using the message catalog as a template for the subject and body of the email.

To get an understanding of what it does, here's the basic application code you would use to create and send an email message from a message catalog entry:

import PW_EMC:Email:*;
Local PW_EMC:Email &oEmail;
 
/* Specify the email addresses to work with */
&oEmail = create PW_EMC:Email("from@test.com", "to@test.com", "cc@test.com", "bcc@test.com", "replyto@test.com");
 
/* Compose the email using a message catalog "template" and pass it some bind variables */
&oEmail.Compose(32767,1, "<strong>An example bind parameter</strong>", %CurrentDateTimeIn, %OperatorID);
 
/* Send the email. Note the results are stored in the table PW_EMC_RESULT */
&oEmail.Send();

The PW_EMC:Email application class is a wrapper that takes care of the details of creating and sending the email message.

It also adds some useful functionality like:

  • Distinguishing between your production and non-production environments to prevent emails from being sent to real users from non-production environments.
  • Allowing you to pass three bind parameters to the message catalog entry. These parameters can even be HTML stored in a HTML definition.
  • Using settings configured and stored in the table PW_EMC_SETTINGS to determine how to send the email.
  • The details of each email sent are stored in an audit table - PW_EMC_RESULT.

Interested in using it?

Follow these instructions to download, install, configure, and test it. Remember to try it out in a play or test environment first. There is also a section at the end of this article that explains the customisation impacts of the PW_EMC project on your PeopleSoft environment.

Download

Download the PW_EMC application designer project:

Version Description
PW_EMC Project Zip (2010-06-06) Minor Bug Fix (Current Release)
PW_EMC Project Zip (2010-05-08) Initial Public Release

Note, so far I have only tested email message catalog on PeopleTools 8.48/8.49/8.50 with SQL Server and Oracle databases. So if you are on a different platform, you may encounter some issues. If you do, please post them to the email message catalog forum.

Installation

Unzip the downloaded file.

Import the project into your play/test environment using Application Designer.
Tools > Copy Project > From File. Press select to kick off the import process:

pw-emc-import-project.png

Note if you are copying over an older version, make sure that you choose the default of copying the project definition from file so you get the latest version.

Make sure all definition types are selected, and press Copy:

pw-emc-copy-from-file.png

You can perform a Tools > Validate Project at this stage. The project should validate without any errors.

Once the copy is complete, select Build > Project. Select Create Tables and choose either Build the script file and run it on your database or execute and build script to build it through application designer. There are two tables to be built: PW_EMC_RESULT and PW_EMC_SETTINGS.

pw-emc-build-settings.png

Hopefully they build successfully without any errors. If you do have errors, check the build logs. If you can't resolve the problem, please post a question on the email message catalog forum.

Navigation

The email message catalog project introduces a new folder navigation in your application under:

  • PeopleTools > Utilities > PeopleSoft Wiki

The email message catalog settings are available through the following navigation:

  • PeopleTools > Utilities > PeopleSoft Wiki > Email Message Catalog

To access these folders you will need the PeopleSoft Wiki role which was imported by the email message catalog project. Give yourself the PeopleSoft Wiki role through user security. Note the PeopleSoft Wiki role contains one permission list — PW_SECURITY.

Hopefully you can reach the navigation to the Email Message Catalog. If not, you may need to purge your portal registry cache. Also make sure you gave yourself security!

Settings

Navigate to PeopleTools > Utilities > PeopleSoft Wiki > Email Message Catalog. You will need to update the SMTP and environment settings here.

To do this you will need to specify:

  • Your organisation's SMTP server
  • Your organisation's SMTP server's port
  • The time to wait for delivery (leave at 3000ms or 3s)
  • The name of your production database
  • The alternate from email address to use when not in production (for testing purpose). Make this something like moc.etisruoy|ylperon#moc.etisruoy|ylperon.
  • The alternate to email address to use when not in production (for testing purposes). Make this your email address so you can check if emails are working.

Note the default settings are not saved to the database. So you will need to change them and save them before you can use the tester.

pw-emc-settings.png

Tester

Message Catalog Setup

The tester allows you to make sure your email message catalog settings work. Before you can use the tester, the first step is to configure a new message catalog entry under:

PeopleTools > Utilities > Administration > Message Catalog

  • Add a new value with a message set number of 32767
  • Specify the description: PeopleSoft Wiki
  • Specify the short description: PSWIKI
  • Specify the message set number: 1
  • Specify the message severity: Message (default)
  • Specify the Message text: Email Message Catalog Tester
  • Specify the following Description/Explanation text:

Congratulations <strong>%1</strong>, the email message catalog is working successfully. Note that this is just a <em>test</em> email message sent from PeopleSoft using the PeopleSoft Wiki Email Message Catalog utility.

pw-emc-tester-message-catalog.png

This is a template email message catalog for the tester application to use. Note that the description/explanation text includes HTML and a bind parameter (%1) which will be converted to the user ID of the person that sent the email message through the tester.

The reason this is a manual step is so you can see how you would set up your own message catalog entries to use with email message catalog in your own code.

Save the message catalog entry and go back to the email message catalog:
PeopleTools > Utilities > PeopleSoft Wiki > Email Message Catalog

Test your settings

Once you are confident in your settings, switch to the tester tab. Then, test out your settings by clicking the Send Test Email button. Note that can take a long time if your settings are wrong (SMTP server & port). Eventually you will get output that looks something like this:

Retrieving Settings

... SMTP Server: smtp.example.com
... SMTP Port: 25
... Time to wait for delivery: 3000
... Production DB: PROD
... Current DB: TEST
... From Email Address: noreply@peoplesoftwiki.com
... To Email Address: peoplesoftwiki@gmail.com

Composing Email

... Using message set nbr: 32767
... Using message cat nbr: 1
... Message parameter 1: PSWIKI
... Message parameter 2: 
... Message parameter 3: 
... Email subject: Email Message Catalog Tester
... Email text: Congratulations <strong>PSWIKI  (... showing first 30 chars only)

Sending Email

... Email Result Code: 1
... Email Result Text: Delivered successfully
... Email Result Saved to Database? True

A few things to note here. If the email subject/text looks like this:

... Email subject: GetMessageText: No default message. (32767,1)
... Email text: GetMessageText: No default mes  (... showing first 30 chars only)

It means you didn't set up the message catalog entry (or save it). Go back and do that. you will still get an email if settings are correct, it just won't show the right things.

The following lines tell you the send result:

... Email Result Code: 1
... Email Result Text: Delivered successfully
... Email Result Saved to Database? True

Hopefully you get a code of 1 / Delivered Successfully. You can also run a query on the database table PW_EMC_RESULT to confirm the email message was saved to the database. If you don't get a successful result it is more than likely due to your SMTP server configuration (server name and port).

Finally check that you actually received an email!

Customisation Impact

The PW_EMC is a bolt-on project, and largely introduces its own objects, all with a prefix of PW_ (PeopleSoft Wiki) and an update user of PSWIKI. The main customisation impact is to the portal registry and security. In particular, the project includes the Folder:

  • PT_UTILITIES (EMPLOYEE portal)

In terms of security it introduces:

  • A new menu: PW_MENU
  • A new role: PeopleSoft Wiki
  • A new permission list: PW_SECURITY

In the PIA, this translates two new entries in the navigation:

  • PeopleTools > Utilities > PeopleSoft Wiki
  • PeopleTools > Utilities > PeopleSoft Wiki > Email Message Catalog

To check which version of the Email Message Catalog project is in your database, look at the project properties at the end of the comments section. E.g. it will say Version: 2010-05-08.

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License