Enabling HTML Email Approvals for HCM

A few months ago Oracle release HTML Email Approvals for Approval Framework. With this OOTB feature you can now easily enable Approvals that can be managed from your mail, without having to log into PeopleSoft first.
Although the technology for HTML Email Approvals have be part of AWE for years now and is also highly used in FSCM, this is the first email templates that are delivered in HCM. The following email templates are delivered:

• Job Opening
• Job Offer
• Absence Request
• Extended Absence Request
• Promote
• Transfer
• Reporting Change
• Performance Document

Download feature

The HTML Email Approvals are delivered with the following patches for HCM 9.1:
Patch 17467921: HCM 9.1 HTML EMAIL APPROVAL BACKPORT
Patch 17050637: HTML EMAIL APPROVAL 91

As always these patches have prerequisite patches, so you need to be at least on
Patch 15879456: HRMS 9.1 BUNDLE #13

Once you have downloaded all the required patches for your environment, you might be hitting a missing prerequisite patch 883338, I know I did. When looking for this patch, you will eventually discover that this patch is superseded by Bug Number 17631599 (Update ID 902126). Because the superseded patch number does not match the prerequisite patch number of Bundle #13, I was not able to select all the required patches in CA. Instead, I installed patch 902126 individually and afterwards inserted manually a new row in PS_MAINTANCE_LOG with patch number 883338, which is a copy of patch 902126. Now you can start CA and start applying all the required patches. When CA was applying the last patch, I was prompted to update my PeopleTools version to at least 8.52.18 or 8.53.06. This was kind of a surprise, because you are usually prompted in front if a patch requires a certain PeopleTools patch level. Nevertheless I patched my environment to the required PeopleTools level.
Now when you start testing AWE, you will hit a PeopleCode Error that AWE is missing methods in classes. AWE off course is part of Enterprise Objects and HTML Approvals is part HCM. So I went and patched my environment with the latest available EO patches (Patch 13741307: EO91 COMMON OBJECTS BUNDLE #10 2013).

Are you still with me? If so, your HCM 9.1 environment is now ready to enable HTML Email Approvals.

For HCM 9.2 this feature is incorporated into PeopleSoft Image 9.2.004 (released 12th December 2013).

How does it work?

When Approval Framework is configured for a transaction, email and/or worklist items are generated for approval. Whenever HTML Email Approval is generated an email is generated with an Approve and Deny link in the mail. Now when an approver clicks in the approve or deny link an email reply is send to an inbox, also called the Response Repository. At a configured interval an application engine EOAWEMC runs to check the inbox for new replies. The application engine retrieves the replies and publishes them as services operations.

Configure mails to be send and fetched by PeopleSoft  

SMTP server

First of all your environment must be able to send emails when transactions are initiated. Here is a blog on how to configure GMail as your SMTP server.

Response Repository

The inbox to where to HTML Email replies will be send, will have to be configured in node PSFT_EMC_GETMAIL.

The configuration can be found by clicking on the Properties link.

I have created a (test) Gmail account which I will be using for the inbox and enabled POP on the Gmail account.

Now we need to configure the connection setting to the Response Repository. This will be configured in the Connector tab of the PSFT_EMC_GETMAIL node.

I have changed the properties that are marked:

• MCF_Server, this is the POP mail server address of Gmail
• MCF_User, this is the mail address of the Gmail account, our Response Respository
• MCF_Password, this is the password of the Gmail account, encrypted
• MCF_Protocol, this is the protocol to use, IMAP can also be used
• MCF_Port, this is the POP port for Gmail 
• MCF_UseSSL, this enables SSL which is required by Gmail

Because we need to communicate through SSL with Gmail, we need to import the Gmail certificate in the Integration Gateway. For this export the root certificate of Gmail and store it on the webserver. See this blog on how to do so. 

After you exported the root certificate, go to [PS_CFG_HOME]\webserv\peoplesoft\piabin and issue the command:

pskeymanager -import

You will be prompted for the password of the keystore, default is password upon install.

Next provide a alias for the certificate and provide the location of the exported certificate.

Finally say yes to trust the certificate. After this bounce the webserver.
This certificate alias needs to be mentioned in the Response Repository Connector properties. Like in the screenshot above you notice that there are two more properties that I did not mention:

• MCF_ClientCertAlias, this is the alias for the Gmail certificate we just created in the keystore
• MCF_ClientCertPass, this is the password of the keystore

Update Approval Transaction Registry to Send Email Approvals

Let's take Request Reporting Change as an example.

Select  Use Email Approvals checkbox to enable HTML Emaill Approvals. Provide the above values for Form Generate Package Root and Class Path. This Package and Class apply to all HTML Approvals. 

Set Internal URL Base settings like shown above. These settings apply to all HTML Approvals. The Internal URL Base is the url to your HCM environment that will be used in the mail as a link to the transaction if the user would like to navigate to the transaction from the mail. This URL needs to reflect your environment.

I have used the ip address of my sandbox environment running on my local WiFi, you should off course use the FQDM of your webserver.

Configure Transactions for Email Approvals

Select Send Email Approvals to All and select Delivery Method: Inline - HTML Links. If you like you could add a security policy that Peoplesoft will check if the sender of the Approval if actually the one that received the approval mail by selecting Perform Send-To Security Check. In the Allowed Actions section select the actions you want to be enabled in the HTML emails.

With the Edit Template button you are redirected the the actual HTML email content template. This button did not do anything for me after applying the patches. I had to manually add the the Edit Template page to a permission list. 

You could use the pre-delivered templates or customize the the templates using the RTE.

Schedule EOAWEMC

It is up to you how you schedule the interval of this process, but I believe it is a wise to schedule this process with a small interval. I have scheduled it every 5 minutes.

Runtime

You are now done with all the configuration and ready to start using the HTML Email Approvals. Let's go through the entire process.

Request Reporting Change

Logged in with user PS and request a reporting change for an employee.

Selected new Supervisor and submit request

Approve from mail

When Approve is selected from the mail, a reply is send to the Respone Repository.

Process Approval

Process EOAWEMC fetches replies from the Response Repository and processes the transaction.