Approval Framework

Using Email Collaboration

This chapter provides an overview of email collaboration and discusses how to:

Set up the PSFT_EMC_GETMAIL node.
Define Integration Broker message and service operation.
Define and map EMC forms.
Trigger email collaboration.

Understanding Email Collaboration

The Email Collaboration Framework (EMC) allows applications to send, receive, and process emails with interactive content. You can send an HTML form to a user, and they do not need to log into their system to perform tasks.

This diagram shows the email collaboration flow:

Email Collaboration flow

A system event triggers PeopleSoft PeopleCode, which creates a collaborative email and sends it to a user.
The user who receives the email takes appropriate action and clicks Submit..
The user's submission is sent to an email account that is designated for holding responses.
An application engine program runs on a configured interval, polling the repository for new emails.

It processes the emails and publishes them as service operations.
The service operation runs, allowing the implementing application to process the data in a known and supported format.

Setting Up Email Collaboration

To set up email collaboration, you need to:

Set up the PSFT_EMC_GETMAIL node.
Create Integration Broker message.
Create Integration Broker service operation.
Define EMC forms, EMC Layout and fields mapping.
Update an Approval Process notification option.
Schedule the application engine program EOAWEMC.

Setting Up the PSFT_EMC_GETMAIL Node

Email collaboration uses the Integration Broker framework to retrieve new emails from the response repository. The node PSFT_EMC_GETMAIL is used to retrieve these emails. Integration Broker must be configured and pub/sub must be enabled.

See Enterprise PeopleTools 8.50 PeopleBook:PeopleSoft Integration Broker Administration, Administering Messaging Servers for Asynchronous Messaging

Pages used to Set Up the PSFT_EMC_GETMAIL Node

Page Name	Definition Name	Navigation	Usage
Node Definitions	IB_NODE	PeopleTools, Integration Broker, Integration Setup, Nodes	Set up the PSFT_EMC_GETMAIL node.
Node Properties	IB_NODEPROP	PeopleTools, Integration Broker, Integration Setup, Nodes Click the Properties link.	Use this page to modify the node properties required for email collaboration to function.

Page Name

Definition Name

Navigation

Usage

Node Definitions

IB_NODE

PeopleTools, Integration Broker, Integration Setup, Nodes

Set up the PSFT_EMC_GETMAIL node.

Node Properties

IB_NODEPROP

PeopleTools, Integration Broker, Integration Setup, Nodes

Click the Properties link.

Use this page to modify the node properties required for email collaboration to function.

Setting Up the PSFT_EMC_GETMAIL Node

To set up the PSFT_EMC_GETMAIL node:

Access the Node Definitions page (PeopleTools, Integration Broker, Integration Setup, Nodes), activate the PSFT_EMC_GETMAIL node.
Click the Properties link to access the Node Properties page.
Enter the email address of the email repository in the EMC_REPOSITORY_EMAILADDRESS property.
(Optional) On the Node Properties page, enter appropriate values for EMC_BCC_LIST and EMC_CC_LIST properties to automatically send a copy of all collaborative emails to the address specified.
Access the Connector page.

This node uses the GETMAILTARGET target connector. You will need to configure the GETMAILTARGET properties.

See Enterprise PeopleTools 8.50 PeopleBook: MultiChannel Framework, Configuring the Email Channel, Configuring PeopleSoft Integration Broker for the Email Channel
Save the node.

Defining Message and Service Operation

This section provides discusses how to:

Define Integration Broker message.
Define Service Operation.

Pages Used to Define Message and Service Operation

Page Name	Definition Name	Navigation	Usage
Message Definition	IB_MESSAGE_BUILDER	PeopleTools, Integration Broker, Integration Setup, Messages.	Define a message.
Services	IB_SERVICEDEFN	PeopleTools, Integration Broker, Integration Setup, Services	Define or update a service.
Service Operation Definition-General	B_SERVICE	PeopleTools, Integration Broker, Integration Setup, Service Operations	Define or update a service operation.
Service Operation Definition-Handler	IB_SERVICEHDLR	PeopleTools, Integration Broker, Integration Setup, Service Operations Select the Routing tab.	Specify handler name, the handler type, and the implementation method for the handler.
Handler Details	IB_SERVICEHDLR_SEC	Click the Details link on the Handler page.	Specify the handler details

Defining Integration Broker Message

The Integration Broker message created for EMC needs to be a rowset-based message that includes the EMC records listed in this table:

Record	Level	Description
EOAWEMC_HDR	0	Header record for EMC.
EOAWEMC_TXNDATA	1	Transactional data record for EMC.
EOAWEMC_PROMPTS	1	Prompting record for EMC. Application will add records for the specific prompt action.
EOAWEMC_ERRORS	1	Error record for EMC.

The application transaction record structure is added at level 2 under EOAWEMC_TXNDATA.

This example shows the Record Only view for a message created to approve expense reports. In this example, the application records that contain transactional data start with EX_EMC.

Define Service

All service operations must be associated with one or more services. You can create a new service operation for an existing service or create a new service with which to associate your service operation.

See Enterprise PeopleTools 8.50 PeopleBook: Integration Broker, Managing Services, Adding and Configuring New Service Operations for Services

Defining Service Operation

You will need to create an asynchronous one-way service that uses the EMC message structure.

Note. The service operation must have the same name as the message.

See Enterprise PeopleTools 8.50 PeopleBook : Integration Broker, Managing Service Operations, Adding Service Operation Definitions

You will also need to create an application class that will to process the EMC form, to be used as the handler .

The application class created to process inbound subscriptions needs to extend the EOAW_EMC:API:emailFormManager and EOAW_EMC:utils classes.

When creating this object, you will need to pass it 2 parameters:

Your full instantiated and populated service operation.
The language code of the user(s) that will receive this email.

Note. EMC engine will handle transaction of things like field labels , however you will need to translate any values contained within your message yourself.

See Using EMC Classes.

EMC Runtime-Inbound

EMC inbound processing takes all the values retrieved 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 service operation used to define your form, and publishes it. You will need add a piece of subscription code to catch the published message and process the data.

Using the utils class method getErrorCodesRS() , 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.
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. 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.

Defining and Mapping EMC forms

This section provides an overview of EMC forms and discusses how to:

Define EMC form.

Define EMC form layout.

Define field mapping.

EMC Forms

EMC allows applications to send, receive and process emails with interactive content. The EMC forms are created based on service operations. The service operation defines the messages structure and the handler necessary to process the EMC forms.

Pages Used to Define and Map EMC Forms

Page Name	Definition Name	Navigation	Usage

Form Element Designer	EOAWEMC_ELEMENTS	Enterprise Components, Approvals, Email Collaboration, EMC Form	Define metadata used as system data when you deliver an email collaboration.
Form Layout Designer	EOAWEMC_LAYOUT	Enterprise Components, Approvals, Email Collaboration, EMC Layout	Defines the layout of the email.
Field Mapping	EOAWXLAT_SYMBOL	Enterprise Components, Approvals, Email Collaboration, Field Mapping	Map field values to the form.

Defining EMC forms

Select Enterprise Components, Approvals, Email Collaboration, EMC Form

To create a new form:

Select the Add a New Value tab.
Enter the Message name.

Note. The message name must be the same as the service operation name.

Upon entering this component, a grid will auto-populate with all of the fields in your message definition , except those that are part of the EMC required records and any that are not marked include in your message definition.

Rebuild List	If you change your message definition, use this button to regenerate the field list. Changes are not automatically updated. This will also remove any Form Layout Definitions associated with this message.
Element Type	Select the element type.
LabelID	LabelID prompts against a field's list of available labels. If you leave this field blank, the field will appear on your form without a label.

Element Types

This table lists the valid element types:

Element Type	Description
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 .
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, such as bullets, asterisks, question marks, and so on.
Select	This type of field may be represented in one of two ways: check boxes or multi-select boxes. It gives the user the ability to select multiple values for a single field.
Select1	Similar to the Select, it may be represented in multiple ways: radio buttons or drop down 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 are available as a design option, some email servers do 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.

Defining EMC Layouts

Select Enterprise Components, Approvals, Email Collaboration, EMC Layout

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 line break at the header level has the expected result of simply wrapping information to a new line. Should the line break be inserted inside a grid, however, the effect will be like having a “special grid row.” That is, the fields after the line break will not be shown as grid columns, but rather as label:field, as in level 0.

On this page, you can change grid labels, field sizes, and number of columns for check boxes and radio buttons. You can also add line breaks and move fields up or down.

Use the Preview button to see a preview of your form layout.

Defining Field Mapping

Select Enterprise Components, Approvals, Email Collaboration, Field Mapping

Use the field mapping page to define values for fields that are used with drop down lists in your form.

Triggering Email Collaboration

This section describes how to:

Update Approval Transaction Registry to send email approvals.
Configure transaction for email approval.
Schedule the application engine program EOAWEMC.
Add or modify email addresses for users.

Pages Used to Trigger Email Collaboration

Page Name	Definition Name	Navigation	Usage
Register Transaction	EOAW_TXN	Enterprise Components, Approvals, Approvals, Transaction Registry	Use to create and update the transaction registry.
Configure Transactions	EOAW_TXN_NOTIFY	Enterprise Components, Approvals, Approvals, Transaction Configuration	Configure how a specific approval process uses email notification options. See Configuring Approval Transactions.
Recurrence Definition	PRCSRECURDEFN	PeopleTools, Process Scheduler, Recurrences	Defines how often you want the process scheduler to run processes.
Application Engine Request	AE_REQUEST	PeopleTools, Application Engine, Request AE	Set up the Request AE for EOAWEMC.
Email Addresses	USER_EMAIL	PeopleTools, Security, User Profiles, User Profiles Select the Email Addresses link.	Modify email addresses.

Updating Approval Transaction Registry to Send Email Approvals

Select Enterprise Components, Approvals, Approvals, Transaction Registry

Use Email Approvals	Select this check box to use Email Approvals.
Form Generator Package Root	Enter the package name that contains the class that contains the form generator application class for this transaction, or use the Lookup button to search for and select one.
Form Generator Class Path	Enter the application class path that contains the form generator application class for this transaction, or use the Lookup button to search for and select one.

Application Class for Form Generator

The application class for the form generator must be an extension of EOAW_EMC:API:formGeneratorBase. When the approvals engine determines that it needs to send out an email approval, it will create an instance of the class you specify on this page. It will pass to it 2 parameters:

&threads as array of EOAW_CORE:ENGINE:Thread - This is an array of Approval Engine Threads.
&userID as String - The userid of the individual receiving the email.

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, and return it. The approvals engine will then call the sendEmails() method on the object you return.

Configuring Transactions for Email Approval

Select Enterprise Components, Approvals, Approvals, Configure Transactions

The Notification Options section is only available if the Use Email Approvals check box is selected for this transaction on the Transaction Registry page.

See Notification Options.

Scheduling the Application Engine Program EOAWEMC

To schedule the application engine program EOAWEMC:

(Optional) Access the Recurrence Definition page (PeopleTools, Process Scheduler, Recurrences), and specify an interval for the process scheduler recurrence.
Select PeopleTools, Process Scheduler, Processes for the application engine program EOAWEMC and up the process definition
Access the Process Definition Option tab and specify the process schedule server and the recurrence.

See Enterprise PeopleTools 8.50 PeopleBook: PeopleSoft Process Scheduler, Defining PeopleSoft Process Scheduler Support Information, Defining Process Definitions

Adding or Modifying Email Addresses for Users

Select PeopleTools, Security, User Profiles, User Profiles

Click the Edit Email Addresses link.

To update your own email address, select System Profile.