PeopleTools 8.52: Workflow Technology

Designing BlackBerry Email Responses

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

Set properties for BlackBerry email responses.
Create an Application Engine program for responses.

Understanding RIM BlackBerry Email Responses

The RIM BlackBerry Email Responses feature enables customers to extend PeopleSoft transactions to a mobile device. By replying to predefined emails, Research In Motion (RIM) BlackBerry wireless handheld users can perform transactions in the PeopleSoft system. For example, they can approve sales quotes, accept field service tickets, and so on.

Before you can use the BlackBerry email response feature in an application, you must:

Define a notification template to send email messages from a specific component.
Develop an Application Engine program to handle the responses.

Setting Properties for BlackBerry Email Responses

This section provides an overview of application server Simple Mail Transfer Protocol (SMTP) settings for sending email messages and discusses how to configure the email channel.

Understanding Application Server SMTP Settings for Sending Email Messages

At runtime, the Send Notification feature depends on application server configuration settings for SMTP. These settings can be changed using PSADMIN.

The following settings are used for BlackBerry email response notifications:

SMTPGuaranteed

0: (Default) Indicates that the SMTP call is done synchronously (while the user waits).

1: Indicates that the SMTP call is done in a service operation handler (service operation = EMAIL_MSG).

Enter 1 if you want TriggerBusinessEvent email PeopleCode to be delivered through the messaging system.

SMTPBlackBerryReplyTo

Use when the sender on the template is set to System (which is always the case for BlackBerry) and BlackBerry email responses are defined for the template (on the Define Template page).

Enter the internet address that you want to be the reply-to address for Blackberry email responses. This must be a valid address, such as user1@example.com.

The default is null.

Note. The node MCF_GETMAIL is delivered with the PeopleSoft system. Users must configure the user, password, and server for their environments.

The following table describes MCF_GETMAIL routings:

Service Operation Name	Description
MCFEM_MSGCOUNT	Retrieves the number of email messages that are available on a mail server.
MCFEM_READALL	Reads all messages from a mail server.
MCFEM_REQ_DELMSG	Deletes a specific message from a mail server.
MCFEM_REQ_DELATT	Deletes an attachment.
MCFEM_REQ_MKFOLDER	Creates an IMAP folder.
MCFEM_REQ_READHDRATT	Reads headers and attachment information from a mail server.
MCFEM_REQ_READMSGATT	Reads a specific message with attachments from a mail server.

Configuring the Email Channel

Because the email channel uses a PeopleSoft Integration Broker gateway, the email channel requires additional configuration.

See Configuring PeopleSoft Integration Broker for the Email Channel.

Creating an Application Engine Program for Responses

This section provides an overview of application engine programs for responses and discusses how to:

Activate the Send Notification component.
Run a BlackBerry response Application Engine process.

Understanding Application Engine Programs for Responses

After you determine the valid responses for a transaction, code a separate Application Engine program section to handle each response. The program sections require that:

The Application Engine program that contains the called sections are tagged as a library.

Each section must have public access.
The program includes the WL_RIMRESP_AET and WL_RIMRESP2_AET state records.
The called section accesses all of the fields from the WL_RIMRESP2_AET state record:
The called section need not perform database commits.

The calling program does this.

The following fields can be included in Blackberry response state records:

EMAIL_FROM	The email address of the person replying to the BlackBerry email message.
WL_SUBJECT	The email subject.
WL_RESPONSE	The response from the BlackBerry pager, as it was extracted from the email body.
EMAIL_TEXTLONG	The complete email body.
WL_PROCESS_FLAG	This field marks a BlackBerry transaction as having been worked. If the application requires that multiple BlackBerry responses be processed, the called Application Engine user section must set this field to N before ending. The main Application Engine program then updates the appropriate table.
COMPONENT_ID	The component of the template that was used in the originating email message (if any).
MARKET	The market of the template that was used in the originating email message (if any).
WL_TEMPLATE_ID	The template ID.
LANGUAGE_CD	The language of the original email message.
NOTIFY_TO	A listing of the user IDs that were used when the original email message was sent.
EMAIL_SENDER2	The value of SMTPBlackBerryReplyTo that was used in the application server configuration file when the initial email message was sent to the pager.

Activating the Send Notification Component

To activate the Send Notification component:

Select the component for which you created the template.

You must have previously created a component template and associated it with a component. Navigate to that component page on your browser. You should see a Notify button in the lower part of the screen.
Click the Notify button.

This action saves the transaction and opens the Send Notification component. The text from the template appears on this page and shows that all of the variables have been resolved.

Note. BlackBerry responses do not appear in the template text section.
Enter the names or email addresses of the recipients in the To, CC, or BCC fields.
Enter the message text in the Message Text field.
Click the Send button.

Additional Notes about Send Notification

Activating the Send Notification component validates recipient names (not email addresses) and then determines whether any BlackBerry email responses must be appended to the message text.

If the template includes BlackBerry email responses, a globally unique identifier (GUID) is generated and linked to the NOTIFY_ID. The GUID is appended to the subject text so that it is available in the reply email message. The system sorts the users by preferred language and sends the notifications by language to the recipients.

The send method in the notification application class determines whether the send is Worklist, Email, or Both (based on the values that the recipient sets in the workflow routing preferences user profile).

All notifications are saved to the database and keyed by NOTIFY_ID and LANG_CD.

Running a BlackBerry Response Application Engine Process

The BlackBerry Response program processes email messages that have been returned from BlackBerry devices. Typically, users set up the BlackBerry Response program to run automatically every few minutes within the process scheduler. The run frequency depends on the individual installation and on the amount of expected traffic of BlackBerry pager email responses.

To perform a BlackBerry response from a run control page:

Select PeopleTools, Workflow, Notifications, BlackBerry Response Program.
Add a new run control ID.
Set the node field name to MCF_GETMAIL.
Click the Run button.

Possible Errors Encountered

The BlackBerry Response program processes only email messages that contain the GUID in the subject line. All other emails are ignored and will be left in the POP3 server. The presence of the GUID indicates that the email message is a BlackBerry pager response.

If the program encounters unexpected conditions while running, it logs error information for each email message and the error count increments:

Find the error count in the Message Catalog for each run of the program.
Find the error details in the BlackBerry error log, accessible from the BlackBerry Error Log component.

This component enables users to identify unprocessed BlackBerry pager response email messages. Search for errors by the run process ID of the BlackBerry Pager Response program. The page shows the error condition that was encountered.

Some errors (error numbers 200−299) cause the program to terminate abnormally. If this happens, restart the program to process email messages that were left unfinished. This table describes the errors:

Error	Description
101	No row was found in table PS_PT_WF_NOTFYGUID. This table should always contain a row for the GUID being processed.
102	The email ID of the response email message was not found as a user ID in table PS_PT_WF_NOTFY_TBL.
103	No email ID was found for the current OPRID.
104	The response returning in the email message was not found in the template.
105	No row was found in PS_PT_WF_NOTFY_TBL for the current GUID.
202	The node name was left blank or was invalid in the run control of the program.
203	The call to Synchrequest failed. Unable to connect to the POP3 connector or the POP3 server.
204	An email message with a valid GUID did not return from the POP3 connector with a unique identification listing (UIDL). Normally, the POP3 server always returns a UIDL for each email message. If the POP3 server does not offer a UIDL, BlackBerry Pager Response processing cannot function. This is a requirement.
205	Failed to delete the email message from the POP3 server.