Defining Structured Email Handling

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

• Define application services.

• Define Webform templates.

Understanding Structured Email

This overview discusses:

• Webforms and structured email.

• Application services.

• Structured email processing.

Webforms and Structured Email

Structured email is generated from a Web page where customers enter and submit information. The Web page takes the information that customers enter, applies XML markup, inserts a Webform ID, and sends the XML as an email to a mailbox that the PeopleSoft CRM email response management system monitors. When the Mail Reader process (RB_MAIL_READ) analyzes the email, the presence of an XML header causes the system to place the email in the structured email queue for further processing by the Structured Email process (RB_STR_EMAIL).

The Structured Email process parses the XML to find the Webform ID, and then it uses that ID to invoke an application service—a set of processing rules that you set up to handle specific email content. If the Structured Email process cannot identify the Webform ID, it routes the email to the exception worklist for the mailbox.

The Web page where customers submit email exists outside the PeopleSoft system. To ensure proper handling of structured email, the email generated by the external Webform must include a WEBFORM_TEMPL_ID tag with a Webform ID that you set up within the PeopleSoft system. You define the ID on the Webform Template page, where you also select the application service that handles email with that ID. The Webform Template page has a preview option so that you can see the expected format of all emails with the ID. Validate the actual email that the external Web page generates against the expected format that appears in the preview.

Because the Webform where the structured email originates is external to the PeopleSoft system, its design is completely up to you. For example, you could use a Webform exclusively for inquiries about the status of a service order, or you could use the same Webform for several types of inquiries. Regardless of how you design the Webform, it is your responsibility to ensure that the email it generates always contains a unique Webform ID and a structure that matches the structure of the Webform template within the PeopleSoft system.

Important! When you design Webforms, always set the MIME part to text/plain to ensure the proper handling of generated structured emails in ERMS.

Application Services

Multiple Webforms can use the same application service. Application services accept input from the Structured Email process, evaluate the input, and return parameters to the Structured Email process, which then sends a reply to the email.

Application Service Definition

Application services consist of the following elements:

• A PeopleTools message definition.

  The message definition sets the expected format of the XML in the email body. Fields that you include in the message definition must appear in the XML, and the names of the XML tags must match the field name or its alias (if you defined an alias).

• An application class.

  This is the PeopleCode that processes the email. It accepts input parameters from the Structured Email process and performs transaction-specific processing. It passes the results back to the Structured Email process, which creates an email reply based on the output from the application class.

• An input type.

  This tells the Mail Reader process how to pass the email body to the application class. If the input type is XMLDOC or Rowset, the system converts the email body text to the specified format. If the input type is Custom, the application class must perform any necessary conversion.

  The easiest input format to work with is normally a rowset; the message definition determines the rowset structure. All of the application services that PeopleSoft delivers use rowset as the input type.

Message Definitions

The PeopleTools message definition that an application service references defines the structure of the email that the application service can process. A message definition consists of at least two elements:

• One or more transaction-related records.

  For example, to process a service order status inquiry, you would include the service order header record (RF_SO_HDR) in the message definition, and you would mark the service order ID field (SO_ID) for inclusion.

• The standard Webform subrecord (RB_WEBFORM_SBR).

  This includes two fields—the Webform ID (WEBFORM_TEMPL_ID) and the customer's email address (FROM_ADDRESS). Both of these fields are required; ensure that the Webform provides this data.

The message definition for the service order inquiry message that is described in the preceding examples looks like this:

<?xml version="1.0"?> 
<Message> 
<MsgData> 
<Transaction> 
<RF_SO_HDR class="R"> 
<SO_ID></SO_ID> 
</RF_SO_HDR> 
<RB_WEBFORM_SBR class="R"> 
<WEBFORM_TEMPL_ID></WEBFORM_TEMPL_ID> 
<FROM_ADDRESS></FROM_ADDRESS> 
</RB_WEBFORM_SBR> 
</Transaction> 
</MsgData> 
</Message> 

Delivered Application Services

The following table lists the application services that PeopleSoft delivers. These are all simple inquiry responses. For example, the CASE_INQUIRY application service accepts a case ID and sends a reply with the case status.

PeopleSoft also delivers the application classes and message definitions that are referenced in the application service definitions.

See The Mail Reader Process (RB_MAIL_READ).

Structured Email Processing

Structured email processing follows this sequence:

1. A customer submits data using a Webform.

2. The Webform creates an XML-formatted email message containing transaction information, a Webform ID, and the customer's email address.

3. The email arrives in an mailbox that is monitored by your email response management system (ERMS), and the presence of the XML header causes the Mail Reader process to place the email in the structured email queue.

4. The Structured Email process parses the email to find the Webform ID and then looks at the Webform definition to identify the associated application service.

   If there is not a valid Webform ID, the email is routed to the structured email exception worklist for the mailbox, and an administrator can troubleshoot the Webform where the email originated. Normally, this occurs only in the test environment; the notifications help you identify issues with the submit processing on your Webforms (which are external to the PeopleSoft system).

5. The Structured Email process converts the email body to the input format (rowset, XML, or a custom input type) that you selected for the application service that is associated with the Webform definition, then passes the data to the application class that you selected for the application service.

6. The application class processes the information that the Structured Email process passes to it and returns the appropriate parameters.

   The application class returns an outcome (Success, Failure, or Error) and an optional correspondence template package to use when replying. It also returns the key values for the transaction that was processed; the Structured Email process then passes these keys to correspondence management to be used when resolving transaction-related token.

7. The Structured Email process replies to the email using either the correspondence template package that the application service returned or a default correspondence template package that you specified for the Webform.

   Each Webform definition has three default correspondence template packages, one for each possible outcome (Success, Failure, or Error).

8. The Structured Email process removes the original email from the structured email queue.

The following diagram illustrates the process flow from the time the Structured Email process reads the email until it finishes processing it:

Structured email process flow

See Also

ERMS Processes

Defining Application Services

To define application services, use the Application Services (RB_APPSRV_DEFN) component.

This section discusses how to:

• Create the application service message definition.

• Create the application class that handles the structured email.

• Define application services.

• Clone an existing application service definition.

• Review a list of Webforms that use an application service.

Pages Used to Define Application Services

Creating the Application Service Message Definition

Access PeopleSoft Application Designer and create the message definition that defines the structure for structured email.

To create the application service message definition:

1. Create a new message definition.

2. Add transaction-specific records to the message.

   These are the records that the system uses to process the structured email. For example, the message used to process service order status inquiries includes the RF_SO_HDR record (the service order header record).

3. Select the Include check box for the fields that are to be included in the structured email.

   The email that your Webform generates must include XML tags for every included field. Content is not required for every included field, but the tags themselves are.

4. (Optional) Enter an alias for the included fields.

   If you do not enter an alias, the field name is used in the XML tag name. If you do enter an alias, the alias is used.

   For example, if the field SO_ID is included but does not have an alias, then the email that the Webform generates must have <SO_ID> and </SO_ID>. But if you give this field the alias ServiceOrderID, the tags are <ServiceOrderID> and </ServiceOrderID>.

5. Add the RB_WEBFORM_SBR record to the message.

The following screen shots illustrate a message definition for service order status inquiries.

Creating the Application Class That Handles the Structured Email

Access PeopleSoft Application Designer and create the application class by extending the delivered ApplicationServices base class.

The application class that an application service references performs the core processing to respond to the email. It accepts inputs from the Structured Email process and returns parameters that the Structured Email process uses to create an automatic reply.

The delivered ApplicationServices base class is in the RB_MCF_SETUP package under RB_APPS_API subpackage. This class has properties that are used to send input to your application class and to set the output of the application class.

Base Class Properties

The following table lists the relevant properties of the base class:

Constructor Method

The Constructor method is different for each application service; its name is the same as the name of the application class. For example, CaseStatus is the constructor method for the CaseStatus application class.

The Constructor method has the following parameters, which are used to invoke the base class Constructor method that populates the corresponding properties of the application class:

• InputType

• InputMessage

• EmailId

ConvertEmailBody Method

The ConvertEmailBody method converts the email body text from a string to either XMLDOC or ROWSET format, depending on the input type that you select on the Application Services Setup page. If you select Custom as the input type, you must override this method with code that performs the custom conversion.

ExecuteApi Method

Override the existing ExecuteApi method with your own application-specific code that sets some or all of the following properties:

Sample Code for the ExecuteApi Method

The following sample code does three things:

• If the case ID entered in the Webform is not in the system, then it returns an outcome of F (failure).

• If the case ID entered in the Webform is a valid issue in PeopleSoft CRM for Financial Services, the code returns a outcome of S (success).

• If the case ID entered in the Webform is in the system, but is not a PeopleSoft CRM for Financial Services issue, then the code returns an outcome of E (error).

import RB_MCF_SETUP:RB_APPS_API:*;
import RB_MCF_SETUP:RB_APPS_API:RB_ERMS_MESSAGE:*;

class IssueStatus extends ApplicationServices
   method IssueStatus(&Input_Type As string, &Msgname As string, &Email_Id As number);
   method ExecuteApi();
end-class;

method IssueStatus
   /+ &Input_Type as String, +/
   /+ &Msgname as String, +/
   /+ &Email_Id as Number +/
   Rem******************************************************************************;
   Rem -- Invoke Base Class Constructor before invoking other methods   ------------;
   Rem******************************************************************************;
   %Super = create ApplicationServices(&Input_Type, &Msgname, &Email_Id);
end-method;

method ExecuteApi
   Local Rowset &Case_Rs;
   Local number &Case_Id;
   Local string &Status, &Xml_String;
   Local string &Business_Unit, &Market;
   Local number &Bo_Cust, &Bo_Contact, &Role_Type_Cust, &Role_Type_Contact;
   Local Record &Rec1, &Rec2;
   
   Rem*****************************************************************************;
   Rem -- Get Case Id from the Rowset Passed in to this Class           -----------;
   Rem*****************************************************************************;
   
   &Rec1 = CreateRecord(Record.RC_CASE);
   &Case_Id = %This.InputRowset.GetRow(1).RC_CASE.CASE_ID.Value;
   
   %This.TransactionRecord = &Rec1;
   &Rec2 = CreateRecord(Record.RBC_SUBINT_WRK);
   %This.SubInteractionRecord = &Rec2;
   
   
   SQLExec("SELECT BUSINESS_UNIT,RC_STATUS,BO_ID_CUST,BO_ID_CONTACT,
   ROLE_TYPE_ID_CUST,ROLE_TYPE_ID_CNTCT,MARKET FROM PS_RC_CASE WHERE CASE_ID=:1", &Case_Id, &Business_Unit, &Status, &Bo_Cust,
&Bo_Contact, &Role_Type_Cust, &Role_Type_Contact, &Market);
   
   %This.Outcome = "F";
   If All(&Business_Unit) Then
      
      Rem***************************************************************************;
      Rem --------- This indicates the Case_Id is valid  ---------------------------;
      Rem***************************************************************************;
      
      MessageBox(0, " ", 17834, 70333, "Bo Id Cust from Email is " | %This.BoIdCust);
      MessageBox(0, " ", 17834, 70333, "Bo Id CONtACT from Email is " | %This.BoIdContact);
      MessageBox(0, " ", 17834, 70333, "Bo Id Cust From Case is " | &Bo_Cust);
      MessageBox(0, " ", 17834, 70333, "Bo Id CONtACT from Case is " | &Bo_Contact);
      
      If (&Market = "FIN") Then
         Rem************************************************************************;
         Rem ---- Valid Finacial Case, hence set the outcome to Success   ----------;
         Rem************************************************************************;
         
         %This.Outcome = "S";
      Else
         
         Rem************************************************************************;
         Rem ---- InValid Finacial Case, hence set the outcome to Error   ----------;
         Rem************************************************************************;
         
         %This.Outcome = "E";
      End-If;
      
      If (%This.Outcome = "S") Then
         &Rec1.CASE_ID.Value = &Case_Id;
         &Rec1.BUSINESS_UNIT.Value = &Business_Unit;
         
         &Rec1.SelectByKey();
         %This.TransactionRecord = &Rec1;
         
         Rem **********************************************************************;
         Rem --- Populate the Receipient Details for Correspondence Management ----;
         Rem **********************************************************************;
         %This.RecepientBoId = &Rec1.BO_ID_CONTACT.Value;
         %This.RecepientRoleType = &Rec1.ROLE_TYPE_ID_CNTCT.Value;
         
         
         /* Prepare RBC_SUBINT_WRK for Sub Interactions */
         &Rec2 = CreateRecord(Record.RBC_SUBINT_WRK);
         &Rec2.PNLGRPNAME.Value = "RB_WEBFORM_DEFN";
         &Rec2.MARKET.Value = "GBL";
         &Rec2.CREATE_SUBINT_IND.Value = "Y";
         &Rec2.SUBINT_OBJ_TYPE.Value = "CASE";
         &Rec2.BUSINESS_UNIT_RI.Value = &Business_Unit;
         &Rec2.SETID_RI.Value = "";
         &Rec2.OBJECT_ID.Value = String(&Case_Id);
         &Rec2.BO_ID_CUST.Value = &Bo_Cust;
         &Rec2.ROLE_TYPE_ID_CUST.Value = &Role_Type_Cust;
         &Rec2.ROLE_TYPE_ID_CNTCT.Value = &Role_Type_Contact;
         %This.SubInteractionRecord = &Rec2;
      End-If;
      
   End-If;
end-method;

Defining Application Services

Access the Application Services Setup page.

Clone Application Service	Click to access the Application Services Saveas page and clone the current application service definition.
Application Class ID, Package Tree Viewer, and Application Class Path	Enter the ID and path for the application class that processes the email. Click the Package Tree Viewer link to access the Application Packages Lookup page, where you can browse for application classes and select one to use.
Input Type	Select the format of the input that the Structured Email process passes to the application class. Rowset is normally the easiest format for application classes to work with. Other options are Custom and XMLDoc.
Inbound Message	Select the message definition that controls the expected format of the XML in the email body and that is used when passing rowset data between the Structured Email process and the application class.

Cloning an Existing Application Service Definition

Access the Application Services Saveas page.

Application Services and Description

Enter names and descriptions for the application services you want to create. When you click the OK button, the system creates these new application service definitions as clones of the application service from which you accessed this page.

Reviewing a List of Webforms That Use an Application Service

Access the Application Service Reference page.

This page lists the Webform templates that reference this application service.

Defining Webform Templates

This section discusses how to:

• Define Webform templates.

• Clone Webform templates.

Pages Used to Define Webform Templates

Defining Webform Templates

To define webform templates, use the Webforms (RB_WEBFORM_DEFN) component.

Access the Define Webform Templates page.

Webform Template	Displays the webform template you entered. The Structured Email process uses this ID to match an inbound email to the parameters that you enter on this page. When you set up your external Webform, be sure the email it generates includes this ID in the WEBFORM_TEMPL_ID tags.
Language Code	Select the language of the default reply templates. This language code limits the selections in the Correspondence Management Package Details for Responses group box.
Clone Webform	Click to clone the current Webform definition.

Application Service Details

Correspondence Management Package Details for Responses

See Setting Up Correspondence Templates.

Cloning Webform Templates

Access the Webform Saveas page.

Webform Template and Description

Enter names and descriptions for the Webform definitions you want to create. When you click the OK button, the system creates these new Webform definitions as clones of the Webform definition from which you accessed this page.