Creating an Application Engine Program for Responses

This section provides an overview of 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:

Field or Control

Definition
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.

To activate the Send Notification component:

  1. 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.

  2. 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.

  3. Enter the names or email addresses of the recipients in the To, CC, or BCC fields.

  4. Enter the message text in the Message Text field.

  5. 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.

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:

  1. Select PeopleTools, Workflow, Notifications, BlackBerry Response Program.

  2. Add a new run control ID.

  3. Set the node field name to MCF_GETMAIL.

  4. 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.