Setting Up 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 section discusses:

• Webforms and structured email.

• Webform templates.

• 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 classify it as structured email and be processed by the mail route process accordingly.

The email is displayed in plain text on email workspace for agents to review or process further. On the email body, each piece of data has a corresponding text label that is defined in the webform definition for better readability.

If the email process cannot identify the webform ID, it routes the email to the admin group 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 Define Webform Templates page, where you also select the application message that represents the webform structure. The page has a preview option so that you can see the expected format of all emails that are generated from this webform. 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 (Multipurpose Internet Mail Extensions) part to text/plain to ensure the proper handling of generated structured emails in ERMS.

Webform Templates

Webform templates specify the XML format that is used to generate structured emails after customers enter information on corresponding webforms. A webform template consists of the following elements:

• Inbound service operation.

  The message 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).

• Application service input type.

  This element tells the mail reader process how to pass the email body to the application class method (used in actions). 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.

• Default category.

  The rules engine uses this category to locate the appropriate rule and action for the email if the associated webform is set to always use the default category as the email category. The default category is also used if Verity cannot identify an email category with a threshold value that exceeds the category's confidence level.

• Mapping between webform fields and email workspace fields.

  The rules engine uses this mapping to populate webform data to corresponding fields in the email workspace in a readable manner (in plain text without XML tags).

Inbound Application Message Definitions

The PeopleTools message definition defines the structure of the email. A message definition consists of at least two elements:

• One or more transaction-related records.

  For example, to process a sales order status inquiry, you would include the order header record (RO_HEADER) in the message definition, and you would mark the order ID field (CAPTURE_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 sales order inquiry message that is described in the preceding examples looks like this:

<?xml version="1.0"?> 
<Message> 
<MsgData> 
<Transaction> 
<RO_HEADER class="R"> 
<CAPTURE_ID></CAPTURE_ID> 
<BILL_RECIPIENT_FLG></BILL_RECIPIENT_FLG> 
<BULK_ORDER_FLAG></BULK_ORDER_FLAG> 
<PROD_TERM_CODE></PROD_TERM_CODE> 
<DUE_DATE></DUE_DATE> 
<RESELL_FLAG></RESELL_FLAG> 
<RO_BILL_TO_TYPE></RO_BILL_TO_TYPE> 
<SCHEDULE></SCHEDULE> 
<SUBMIT_DTTM></SUBMIT_DTTM> 
<UID20F_PARTNER></UID20F_PARTNER> 
<UID20F_PARTNERC></UID20F_PARTNERC> 
<FIN_ACCOUNT_ID></FIN_ACCOUNT_ID> 
<RO_MULTILINE></RO_MULTILINE> 
</RO_HEADER> 
<RB_WEBFORM_SBR class="R"> 
<WEBFORM_TEMPL_ID></WEBFORM_TEMPL_ID> 
<FROM_ADDRESS></FROM_ADDRESS> 
</RB_WEBFORM_SBR> 
</Transaction> 
</MsgData> 
</Message> 

Delivered Webform Templates

The following table lists the webform templates that the PeopleSoft system delivers, as well as the AMP rules and actions that process structured emails generated by these templates:

Processing for Structured Emails

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 ERMS system, and the presence of the XML header causes the mail reader process to classify it as a structured email.

4. The mail route process converts the email from XML to plain text using the webform and email workspace field mapping that is set up as part of the webform template definition.

5. The mail route process identifies the default category from the webform definition that is associated with the email, and checks if the option to always use the default category is selected in the webform definition.

   If yes, the system uses the default category as the email category, looks up any AMP rules that are associated with it, and performs rule actions on the email. If the default category is not associated with any rules, the system routes the email to the mailbox's default group worklist.

   If no, Verity is used to identify either the most appropriate group worklist to route the email (if automatic routing is enabled), or the category of the structured email (if automatic routing is disabled). In the case where Verity returns an email category with a threshold value but the threshold value is not high enough to meet the confidence value of any AMP rule associated with the category, the default category is used instead.

6. Processing for the structured email completes and the email is removed from the email queue.

You can access the email on the email workspace. Information about the email appears according to the field mapping of the webform template definition.

See Also

ERMS Processes

Defining Application Services

This section discusses how to:

• Create the application service message definition.

• Create the application class that handles the structured email.

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

Creating the Application Service Message Definition

Access the Messages component of Integration Broker to create the application service message definition that defines the structure for structured email.

Refer to the see also reference for more information on managing message definitions.

See Also

Enterprise PeopleTools 8.50 PeopleBook: Integration Broker

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.BoId⇒
Cust);
      MessageBox(0, " ", 17834, 70333, "Bo Id CONtACT from Email is " | %This.BoId⇒
Contact);
      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 Webform Templates

This section discusses how to:

• Define webform templates.

• Identify email workspace fields for mapping.

• Specify webform and email workspace field mapping.

Perform these tasks to complete the setup of automated mail processing for structured emails.

Pages Used to Define Webform Templates

Defining Webform Templates

To define webform templates, use the Webforms (RB_WEBFORM_DEFN and RB_QA_WEBFORMS) components.

Access the Define Webform Templates page (Set Up CRM, Product Related, Multichannel Definitions, Email, Define Servers and Security, Webforms, Define Webform Templates).

Webform Template	Displays the webform template you entered. The 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.
Default Category	Select the category that the AMP rules engine uses to derive a rule and associated actions to apply to structured emails that are generated from this webform. This category is used if the webform is set to always use the default category to apply rules, or when Verity is unable to identify for an email a category with a threshold value that exceeds the category's confidence level.
Always use Default Category to apply Rules	Select for the system to always use the default category to identify associated AMP rules and performs actions of the rule on structured emails that are generated from this webform.
Application Service Input type	Select the format of the input that the 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 Service Operation	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 email process and the application class.
Preview XML	Click to view the inbound application message definition in XML.
Clone Webform	Click to access the Webform Saveas page to create a new webform using the current webform definition.

Identifying Email Workspace Fields for Mapping

Access the Identify E-mail Workspace Fields for Mapping page (Set Up CRM, Product Related, Multichannel Definitions, Email, System Installation, Identify E-mail Workspace Fields for Mapping).

Use this page to specify fields on the email workspace that would be populated with data of structured emails.

Specifying Webform and Email Workspace Field Mapping

Access the Map Email Fields page (Set Up CRM, Product Related, Multichannel Definitions, Email, Define Servers and Security, Webforms, Map Email Fields).

This page identifies the field data (from XML) to be displayed on the email workspace. Email workspace displays structured email in a readable form rather than showing the actual XML code. User can specify the label for each data item (of XML) on this page.

Email Subject

Email Body

The system populates this list of fields based on the associated webform message definition.