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.

Structured emails are checked for context-based, customer-based, and thread-based routing before automated mail processing (AMP). While the application of AMP is fairly similar to both structured and unstructured emails, for NLP to perform content analysis on structured emails, the AMP rules engine first needs to convert the email format from XML to plain text and extract the email subject and body based on the mapping in the webform definition. If NLP is unavailable, the rules engine obtains the default category from the webform definition of the email, finds the associated rule from the mailbox definition, and triggers actions of the highest priority. Threshold values do not apply. You can set up the system to always use the default category. In this case, NLP is not used.

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.

Note. If NLP is available yet field mapping is unavailable for fields such as Template Type, Product Group, Product, Mood, and Priority, the rules engine populates these values with suggestions returning from NLP.

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 application message.

  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 if NLP is unavailable. You can set up the rules engine to always use the default category even if NLP is available, which means that the default value overrides the category suggested by NLP. Use this option if the emails generated from a webform template have a very specific and clear goal, such as status inquiry.

• 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 email is sent to the NLP system for content analysis.

   A recommended category and threshold value return. The rules engine locates from the email's mailbox definition an AMP rule with a matching category. If the returned threshold value is the same or higher than the required value specified in the rule, the rules engine then tries to trigger the actions of the highest priority by comparing the returned and required threshold values. If the returned value is higher, actions are performed automatically; if not, the rules engine attempts the next action. If no rule can apply or none of the actions can be performed, the email is routed to the default group worklist.

   If NLP is unavailable, the rules engine obtains the default category from the webform template definition. In this scenario, the threshold value is not used.

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 PeopleSoft Application Designer to create the application service message definition that defines the structure for structured email.

1. Create a new message definition.

   Create a new message definition.

2. Add transaction-specific records to the message.

   The system uses these records 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 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>. 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 pages 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 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.

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 whose associated rule is used to apply to structured emails that are generated from this webform. This category is used if NLP is not available, or if NLP is unable to return a suggested category.
Always use Default Category to apply Rules	Select this option if you want the system to always use the default category regardless of the presence of NLP. The rules engine does not make any call to NLP when this option is selected. For example, you can use this option for structured emails that are intended for one expected category, such as inquiry for cases, service orders, or orders.
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 Application 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 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.

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.

This page identifies the data (from XML) that can be used for NLP analysis. 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.