eMail Collab

14
Introduction The Email Collaboration Framework (EMC) allows applications to send, receive and process emails with interactive content. Previously, email notifications were limited to static text. You could write HTML and make your emails a bit more attractive to look at, but if your intent was to have the user take any action, you had to inform them of how to get into the system to take that action (Usually via a hyperlink). Now, you can send the data collection medium (an HTML form) to the user, saving them time by not forcing them to log in to the ERP system to perform their tasks. The following graphic illustrates the chain of events that takes place during a collaborative email session. Pre-Requisites

Transcript of eMail Collab

Page 1: eMail Collab

Introduction

The Email Collaboration Framework (EMC) allows applications to send, receive and process emails with interactive content. Previously, email notifications were limited to static text. You could write HTML and make your emails a bit more attractive to look at, but if your intent was to have the user take any action, you had to inform them of how to get into the system to take that action (Usually via a hyperlink). Now, you can send the data collection medium (an HTML form) to the user, saving them time by not forcing them to log in to the ERP system to perform their tasks. The following graphic illustrates the chain of events that takes place during a collaborative email session.  

 

Pre-Requisites

Before beginning an implementation of the EMC, you should be sure to have a firm grasp on Integration Broker, Process Scheduler, Application Engine, and PeopleSoft Application Classes. The following links contain information pertinant to this end. Integration Broker PeopleBooksUsing Integration Broker Monitor

Page 2: eMail Collab

Understanding Integration Gateway ConfigurationDefining Message Channels and MessagesCreating Message SubscriptionsUnderstanding Peoplesoft Process SchedulerSetting Up Recurrance DefinitionsStarting Programs with the Application Engine Process Request PageUnderstanding Application Classes

Setup

App Server Settings

There are couple things you'll need to make sure of in your app server before the EMC will work. First, you'll need to enable Pub / Sub. Secondly, you'll need to modify the SMTP server. The default app server configuration file has a server that no longer exists in here. You'll want to make sure you have the following: "SMTPServer=psp-smtp-01".

Application Message Definition

The core of an EMC implementation is an Application Message. It's how you define the data that will be sent to the user, and how the user's response is communicated back to you. Throughout the course of this document I will use eProcurement's implementation for Email Approvals as an example. The following graphic shows eProcurement's message definition for Email Approvals:

Take notice of the set of records prefixed by "SAC_EMC." These are records that are required in the positions shown for the EMC to work properly. If these records are not setup properly, you'll know before very long, as subsequent steps in the setup process will let you know.

Integration Broker Node Configuration

In PIA, Navigate to: PeopleTools -> Integration Broker -> Node Definitions. Once there, search and select node PSFT_EMC_GETMAIL. First, you'll need to modify at least one property, so click the "Properties" tab.

Page 3: eMail Collab

The only required property on this page is EMC_REPOSITORY_EMAILADDRESS. This represents the email address of the email repository shown in the diagram at the top of this document. When the user clicks submit, an email with all the data they've inputted will be sent to this address. The other two properties on this page, EMC_CC_LIST and EMC_BCC_LIST, are optional. They are primarily there so customers can log all outgoing emails. Any email addresses in either of these fields will get either CCed or BCCed, respectively, on all outgoing emails. Next you'll need to configure a couple Connector Properties, so click the "Connectors" tab.

Page 4: eMail Collab

The four things you'll need to change in here are: MCF_AttServ - This is the url to your attachment server. Usually you should

just have to change "attachmentservername" to your machine name and "portnumber" to your webserver port number (80 by default).

MCF_Password - This is the password for the email repository account shown in the graphic at the top of this document.

MCF_Server - This is the server on which the email repository resides. MCF_User - This is the user name needed to log into the email repository

account.

Page 5: eMail Collab

The Form Element Definition

Once you have your message setup, the next step is to define a "Form Element Definition." This is meta-data that you'll need to include as system data when it's time to deliver your product. To setup a Form Element Definition, in PIA, navigate to: Set Up Financials / Supply Chain -> Common Definitions -> Setup E-Mail Collaborations -> Form Element Designer. Add a new value for the message you've created for use with the EMC. Upon entering this component, a grid will auto-populate with all of the fields in your message definition (excluding those that are part of the EMC required records and any that are not marked "include" in your message definition). Note: If you change your message definition in the future, you'll need to use the "Rebuild List" button, as the page will not attempt to account for any changes automatically. This will also remove any Form Layout Definitions (more about those next) you've created.

There are only two fields on this page of consequence: Element Type and LabelID. Element Type can be one of 7 values:

Blank – A value may be stored in this field by the application, however it will not be transmitted in the email form, and thus may be used to store sensitive data.

Input – Will be represented as a standard text input field similar to the “Label ID” field shown above

Output – Will be represented as plain text. This will be the application developers method for providing contextual data to the user.

Secret – Similar to an input field, however it provides superficial security, as the contents of the field appear as a set of masked characters (bullets, asterisks, question marks, etc….).

Select – This type of field may be represented in one of two ways: Checkboxes or Multi-select boxes. It gives the user the ability to select multiple values for a single field.

Page 6: eMail Collab

Select1 – Similar to the Select, it may be represented in multiple ways: Radio buttons or dropdown lists. It gives the user the ability to select a single value for a field from a list of available values. NOTE: While radio buttons will be available as a design option, they should be excluded from current EMC designs as Lotus Notes does not enforce mutual exclusion of radio button selections in HTML.

Textarea – This field type gets represented as a long edit box, useful for areas where longer strings of text must be entered or displayed to the user.

LabelID prompts against a field's list of available labels. If you leave this field blank, the field will apear on your form without a label.

Form Layout Definition

Once your Form Element Definition you'll need to setup the layout for your form (This is also system data). Navigate in PIA to: Set Up Financials / Supply Chain -> Common Definitions -> Setup E-Mail Collaborations -> Form Layout Designer.

Page 7: eMail Collab
Page 8: eMail Collab

The layout rules are fairly rigid on this page. Grids will be automatically created for each new level, and fields may not move outside their current grid. Inserting a linebreak at the header level has the expected result of simply wrapping information to a new line. Should the linebreak be inserted inside a grid, however, the effect will be like having a “special grid row.” That is, the fields after the linebreak will not be shown as grid columns, but rather as label:field, as in level 0. Other things you can change on this page are things like grid labels, field sizes, and number of columns (for checkboxes and radiobuttons). These are accesible by clicking the "twisty" icon at the beginning of a row. This icon only appears on rows that have data that can be modified. This page will also allow you to see a preview of your form layout.

Response Processing

You've now got all the meta-data you need to start generating outbound emails, but you still don't have a process running that will retrieve emails from the Email Repository and kick off inbound processing. For this, you'll need to make sure you have a Process Scheduler Server available. Then, in PIA, navigate to Peopletools -> Process Scheduler -> Recurrances. Here you'll need to setup the interval at which you would like your process to run. For my own testing, I was using 1 minute. I would expect that in a live environment this would be more on the order of 5 minutes. Next, you'll need to navigate to PeopleTools -> Application Engine -> Request AE. Add a new value, using Program "SAC_EMC." Make sure you change "Process Frequency to "Always," then click the "Run" button. On the subsequent page, select your process scheduler server and your recurrance, then scroll down, check off the row for SAC_EMC, and click the "OK" button at the bottom. Your program is now running. You can keep an eye on it from Process Monitor (Peopletools -> Process Scheduler -> Process Monitor).

The EMC Runtime - Outbound

Now that you've got all of your setup done, you'll need to start coding (finally... ). The primary Application Class you'll need to interact with in order to send out your collaborative emails is SCM_SAC_EMC:API:emailFormManager, but we'll get to that shortly... First we need to touch on another class: SCM_SAC_EMC:utils. This class has several methods that you should be using during your implementation:

getRowFromPath - Returns a row object. This method will be useful for error processing. When your message expects a date or number field to be returned by the user, but the EMC cannot cast the value it gets back into one of those data types, it will put an error code in the exceptions stack (more about that in the Inbound Processing section). Along side that code in the stack, will be a Row Path. A row path is exactly what it sounds like. It is the path you need to follow to get to a specific row in a rowset. It follows the format (n)SCROLLNAME[(n)...] where n is a row number and SCROLLNAME is the name of the record comprising the rowset you'd like to retrive in that row. When you've got an error of one of these 2 types, you can call this method, passing in your message rowset, the rowpath in the error stack and "false" and you will be returned the exact row where the error occured (the name of the record and field are also in the error stack. You can use those to narrow it down from there).

o &startingRS As Rowset - The rowset from which to start searching for a row.

o &path As string - The rowpath used to find the row in question.

Page 9: eMail Collab

o &createIfNull As boolean - If set to true, getRowFromPath will continue adding rows to &startingRS until it has enough rows to return the row specified by &path. If set to false and the row is not present, and exception will be thrown.

getAppRS - Returns a rowset. Given the rowset object representing your entire message, this rowset will return to you just the part of the overall rowset representing your transaction. In the case of the ePro message defined above, this method would return a rowset starting at PV_EMAIL_REQ_H. It is important to use this rowset rather than parsing through the overall rowset yourself. If, in the future, the requirements of the EMC change, then using this rowset allows us to have a single point of definition from which to make all the changes throughout all the implementations. Said another way: If you extract the rowset yourself, and we change the way we expect the rowset to look, then you have to make changes to your code wherever you did this. If you use this method, however, you don't have to do a thing.

o &msgRS As Rowset - The rowset object representing your entire message.

getPromptsRS - Returns a rowset. This is much like the getAppRS method, except it is used to retrieve the Prompts Rowset. More on prompts in a bit.

o &msgRS As Rowset - The rowset object representing your entire message.

getErrorCodesRS - Returns a rowset. Once again...like the getAppsRS method.

o &msgRS As Rowset - The rowset object representing your entire message.

Ok...back to the emailFormManagerClass. When creating this object, you'll need to pass it 2 paramters: 1) Your full instantiated and populated Application Message. 2) The language code of the user(s) that will receive this email. Note that while translation of things like field labels is handled by the EMC engine, you'll need to translate any values contained within your message yourself. The public properties of interest to implementing applications on the emailFormMangager class are as follows:

inlineText - A string of text that the user will see if the deliveryMethod property is set to inline but their mail client does not support HTML emails. A default is provided. inlineText and attachmentText will never be delivered in the same email.

attachmentText - A string of text that the user will see if the deliverMethod property is set to attachment. This text will generally be used as instructional text telling them to detach the html form and submit it. A default is provided. inlineText and attachmentText will never be delivered in the same email.

subject - The subject of the email to be sent. Default is "PeopleSoft Collaborative Email Routing." Keep language conciderations in mind when using this property

submitMessage - This is the message the user will see when they click Submit. It is used simply to let them know that they successfully sent a response. The default is "Thank you. Your message has been sent."

from - The name of the person/account/etc, sending this email. fromEmail - The email address of the person/account/etc sending this email. replyTo - The address users should reply to if there is a problem. This

defaults to the same email address that form responses are fielded from. propendText - Use this variable to include any text you would like inserted

BEFORE the form being emailed appendText - Use this variable to include any text you would like inserted

AFTER the form being emailed

Page 10: eMail Collab

deliveryMethod - Specifies whether to send the e-mails as in-line html or attachments. Attachments will include a better user interface as the brower used to view the html attachment is likely to support more JavaScript and DHTML than email clients like Lotus Notes. Valid values are "I" for Inline and "A" for attachment.

The public methods of interest to implementing applications are: addRecipient - Users added via this method will be allowed to act on the

email form. o &emailAddress As string - Required o &userID As string - Optional

addCC - email addresses added via this method will be copied on every email sent out.

o &emailAddress As string - Required addBCC - email addresses added via this method will be blind copied on

every email sent out. o &emailAddress As string - Required

addAttachment - Adds an attachment to be sent along with the email. o &filePath as string - A string consisting of the complete path to the

file and the filename itself. o &filePathType as number - A number representing type type of file

path used in paramter 1. Use tools system variables %FilePath_Relative, etc...

o &fileName as string - A string representing the name of the file being attached.

o &fileTitle as string - A string consisting of the title of the file. The titles appear near the attachment icons in place of the fully qualified filename.

sendEmails - Does the actual send of the email once all other information is ready.

o &sentToCheckOnReturn as boolean - If set to true, the EMC will verify that the user to whom the email was sent is the same as the user who sent the response. If this is not true, an error will be inserted into the error stack allowing the implementing application to handle it as they see fit.

So...at this point, you're probably wondering, "I know I can do fields with multiple values to choose from (dropdowns, checkboxes, etc...), but where do the values come from? Ok...maybe you're head's swimming with new information, and that was farthest from your mind, but that's up next. It's pretty simple. First, you'll need to make sure you include a record in your message for every possible combination of selections. This record is placed as a child of SAC_EMC_PROMPTS. In the case of the ePro message, we can see that they're using record PV_APPR_ACTN_PM. This is used to populate a dropdown from which the user chooses "Approve," "Deny," or "Pushback." Ok..this is important: All records that appear as children of SAC_EMC_PROMPTS should ONLY have 3 fields. Those fields are all in sub-record SAC_EMC_PMT_SBR. The first field is VALUE. This lets you assign the value that you're actually trying to track. The second field is DESCR_LONG. This is what the user will see. The third field is SELECTED. Setting SELECTED to "Y" tells the EMC that it is the item you want selected (in the case of a dropdown list or radio buttons). If more than one item is selected for a dropdown list and radio buttons, the EMC just marks them all selected, and allows the email client's HTML parser figure out what to do (usually the first item marked selected is used). In the case of checkboxes, it's perfectly valid to have multiple items selected, so feel free...

Page 11: eMail Collab

The EMC Runtime - Inbound

EMC inbound processing takes all the values retrived from the user's submission and merges them with the values sent out to the user (overriding outbound values with inbound values). It then inserts those values into the same application message you used to define your form, and publishes it. Pretty simple, huh? All you need to do is add a piece of subscription code to catch the published message and process the data.  The thing to keep in mind on the inbound side is error handling. Using the utils class method getErrorCodesRS() described in the EMC Outbound section, you can get a list of error codes inserted by the EMC engine while the inbound message was being processed. The list of codes is as follows:  Error Code

Description

0 No Error

1 Duplicate Response Received - The user submitted the form more than once.

2

Sent-To Check Failed - The user to whom the email was sent is not the user from whom the response was received. Keep in mind when dealing with this error that some users have more than one email alias. For example, both [email protected] and [email protected] are both valid email addresses for me.

3 Invalid date value error

4 Invalid number value error The fields in the error codes rowset are ERROR_CODE, ROW_PATH, RECNAME, FIELDNAME, and RECEIVED_VALUE. These are all fairly self-explanatory. Not all fields are used for all errors, though. ROW_PATH, RECNAME and FIELDNAME for instance are only used when an invalid date or number value is received.

SCM Approvals Engine Integration

Hooks have been placed in the SCM Approvals Engine to allow for easy triggering of email approvals using the EMC. To setup email approvals, in PIA, navigate to Set Up Financials / Supply Chain -> Common Definitions -> Approvals -> Approval Transaction Registry, and find your Approvals transaction (this requires that you already have an approvals implementation configured and working). Once in the Transaction Registry, there are two tabs. The first tab, Approval Transaction Registry, is used by the implementing application to specify the details of their transaction. The second tab, Configuration Options, is there to allow customers to configure how they will use this particular implementation of approvals. The first tab has 3 fields relevant to enabling the EMC:

Page 12: eMail Collab

The first field is simply a checkbox specifying that you are indeed going to use email approvals. In the next two fields, you will specify the path to, and the name of your extension of SCM_SAC_EMC:API:formGeneratorBase, respectively. When the approvals engine determines that it needs to send out an email approval, it will create an instance of the class you specify in these two fields. It will pass to it 2 parameters:

&threads as array of SAC_AW:ENGINE:Thread - This is an array of Approval Engine Threads.

&userID as String - The userid of the individual receiving the email.

You should not have to do anything in the constructor of your extending class. The base class provided takes the parameters passed in and makes them protected properties. Immediately after instantiating your object, the approvals engine will call the only method defined in the base class: returnEFM(). In this method you should take the threads and userid, create an instance of the emailFormManager (discussed in The EMC Runtime - Outbound), and return it. The approvals engine will then call the sendEmails() method on the object you return. Now you're asking, "But what about the sent-to security check flag on the sendEmails() method?" Good question. If you navigate to the second tab in the Transaction Registry you'll see a few more fields relevant to the EMC (these are only visible on this tab, if the "Use Email Approvals" checkbox is turned on in the first tab):  

Page 13: eMail Collab

There is a checkbox here that allows the customer to specify whether or not they want that check to take place. The approvals engine takes this into concideration when calling the sendEmails() method. The other two fields are "Email Approval User List" and "Delivery Method." Email Approval User List is a user list (can be created by navigating to Set Up Financials / Supply Chain -> Common Definitions -> Approvals -> User Lists) that specifies exactly which users should be allowed to do their approvals via email. When the Approvals Engine is sending out notifications for new approvals it will consult this user list. If the user receiving the notification also falls into the Email Approval User List, then they will get an Email Approval rather than a regular email notification. The second field allows a customer to specify whether they would like to receive their Email Approvals inline or as attachments. This is in place primarily for use with email clients that have poor HTML support (like Lotus Notes). This field means that if you're using the EMC in the context of the SCM Approvals Engine, you can ignore deliveryMethod property on the emailFormManager class as it will be set by the Approvals Engine.

Conclusion

Well, that's it. While there's a lot of text on this page, I do believe the implementation is fairly easy, especially when using the hooks in the SCM Approvals Engine. I think the biggest effort in most implementations will be error handling. The ePro folks were able to get this framework up and running in about a week sans any robust error handling.