Realtime processing of Webforms using ERMS

The use of Web forms with SAP ERMS is a powerful combination.
By providing the content of a web form to an incoming mail it is possible to add this data to the ERMS Fact base.
These additional fields can then be used in the ERMS rule modeler and can help you to further improve your automated email responses.
Standard SAP provides a so-called fact gathering service that will take care of this process. In this blog we will describe the use of the standard SAP fact gathering service for processing web form content in ERMS. This service expects the web form content to be delivered as an XML-file attached to an incoming mail.
As not all platforms are able to add an XML file as an attachment (as well as the fact that adding XML as attachments to emails might give you trouble with exchange server policies and virus checkers), this blog will also describe an alternative way to achieve the same goal using a custom built fact gathering service that will extract the web form fields directly from the HTML content of the email body using some custom field tagging.

Processing Web forms using a standard SAP service 

The fact gathering service for handling web forms Standard SAP is providing is called ‘FG_WEBFORM’. Its definition can be found in customizing:

SPRO-> Customer Relationship Management-> E-Mail Response Management System-> Service Manager->Define Services 

The underlying class CL_CRM_ERMS_FG_WF has one method called EXECUTE which is responsible for adding the web form fields to the ERMS fact base. After analysis of this method the following requirements are identified for a successful implementation of this standard service.

In Customizing add the service ‘FG_WEBFORM’ as a ‘Directly Called Service’ in your service manager profile. ( SPRO-> Customer Relationship Management-> E-Mail Response Management System-> Service Manager->Define Service Manager Profiles)

As a prerequisite fact gathering service ‘FG_EMAIL’ must have been executed successfully as it adds the incoming email attributes to the fact base which are used in the service FG_WEBFORM. This is a prerequisite but the FG_WEBFORM service will automatically take care of this by calling the following ABAP code which will execute service FG_EMAIL if it hasn’t been executed yet:

The web form fields should be added to the incoming mail as an XML attachment. The attachment must contain the following pattern anywhere in its name: ‘WEBFORM.XML’ (not necessarily in upper case). The service can handle multiple attachments of a single email as long as the naming convention is correct.

The attached XML file must have a specific lay-out so SAP will be able to translate (parse) it correctly. To parse the XML attachment standard SAP class CL_CRM_ERMS_WF_READER is being used. From method PARSE_XML of this class we learn that the parser is looking for the following tags/paths:

After the base element the following fields are expected: ‘VERSION’, ‘WEBFORM_ID’, ‘SENDER’ and ‘WEBFORM_ACCOUNT’ of which ‘WEBFORM_ID’ and ‘SENDER’ are mandatory. Under the SOURCE tag the parser is looking for nodes (name is not important but in the example below it is O2PARAVALU) that contain name / value pairs with the tags ‘NAME’ and ‘VALUE’. These are the actual webform fields that will be added to the fact base. As this is all rather technical the example below, of a file that will be processed correctly, is probably more illustrative.

When all requirements mentioned above are in place the last thing that remains is defining the Web form fields as parameters in the ERMS repository. But before you can do this you have to understand how the web form fields are stored in the Fact base. After parsing the web form fields from the attachment(s), service FG_WEBFORM will construct an XML fragment based on these fields. This XML fragment will then be incorporated in the already existing fact base XML. The XML fragment (in the ABAP code referred as XML-chunk) based on the example above will look like this:

The XML fragment is added to the fact base with method ADD_SNIPPET of class CL_CRM_ERMS_FACT_BASE of which an instance is present in the SERVICE_MANAGER object. See the code below.

Now we know how the web form fields are stored in the fact base it is time to define them as parameters in the ERMS repository so that they will be available in the ERMS Rule modeler

SPRO-> Customer Relationship Management-> E-Mail Response Management System->Define Repository

If we for example do this for the web form field ‘first name’ it will look like this:

Explanation of the fields:

• Context – ‘ERMS’ because that is what we are working with 
• Attribute – Your own identifier, in this case ZWF_MYFIRSTNAME 
• Description – Your own description 
• Show attribute – If this flag is set the attribute will be visible in the rule Modeller 
• FG service – Fact gathering service responsible for adding the attribute 
• Attr. Ext. Class – Determines which operators are valid for attributes in the rule Modeler 

This has to be repeated for all other web form fields as well.

With the attribute(s) in place the values are available for you in several different ways. You can easily access the attributes via ABAP code in subsequent services within your service manager profile using the following code:

This will retrieve the corresponding value of attribute ZWF_MYFIRSTNAME from the fact base.

Another option is, as mentioned before, that the web form field is now available in the ERMS Rule modeler. To demonstrate this a new rule policy ‘MY_ERMS_RULE’ has been created

In the rule details we can now add a condition and choose our ‘First name’- attribute from the drop down list as shown below.

The operators available in the operator dropdown are determined by the Attribute Extension Class parameter defined in the repository.

The end result will be like this:

Processing Web forms using custom built services.

The scenario described above makes use of the standard SAP service and your web form handling should be conform the restrictions SAP places on you. But you are of course free to define your own fact gathering services with an alternative way to handle your web form content. In the example described below the incoming email doesn’t contain an XML-attachment but the web form fields are in the HTML body of the email.

Email:

HTML Body (fragment):

The first thing to do is create our own fact gathering service which can be done in customizing: and define our fact gathering service class in the customer namespace.

SPRO-> Customer Relationship Management-> E-Mail Response Management System-> Service Manager->Define Services 

Make sure you pick ‘Fact Gathering’ as the service type and make sure your Z-class implements the interface IF_CRM_ERMS_SERVICE which contains the EXECUTE method.

In this case we used the standard SAP service FG_WEBFORM as a base as there is a lot of coding which can be reused. The biggest difference is how the web form fields are retrieved from the HTML body of the incoming mail. This done using the following logic:

First the email context is retrieved from the service manager using the following statement:

The variable LV_EMAIL_CONTEXT contains now the HTML body as one long string.

The email context is then parsed to an internal table using the static method PARSE_HTML_STRING of class CL_CRM_HTML_PARSER

Internal table LT_PARTS now contains the HTML data neatly organized and ready to be read.

All web form fields and their values can now be easily retrieved by selecting all rows from the internal table where the field TAG equals ‘td’ and the field ‘IS_END_TAG’ is initial. The internal table attributes should contain an entry with the name ‘data-form-field-id’ and the value of the field name.

The actual value of the web form field can be found in the next table row in the field PART. Based on these data we can collect the name value pairs of the web form fields.

With the name value pairs in hand we can now construct the XML-fragment again and add it to the fact base XML in an similar way as described in the standard SAP service FG_WEBFORM.

Conclusion 

We have seen that fact gathering services in ERMS can be used to collect the fields and values from web forms and store them in the fact base. These fields are then available for other ERMS services and can also be used as parameters in the ERMS Rule modeller. But it doesn’t have to stop there! You can use the fact gathering services to collect data from any accessible source you can imagine and then add it to the ERMS fact base XML by the methods described below:

• Create an XML fragment which contains your data 
• Add it to the fact base XML using the ADD_SNIPPET method 
• Define your parameters in the ERMS repository with the correct XPATH 

This allows you to add more flexibility and intelligence to your automated email responses.

Definitions 

ERMS: E-mail Response Management System.
Web form: A Web form, also called an HTML form, is an online page that allows for user input. It is an interactive page that mimics a paper document or form, where users fill out particular fields.
Fact Base: The fact base is an E-Mail Response Management System (ERMS) component that serves as a data container for any information that is related to an inbound e-mail and can be relevant during rule evaluation.
Fact gathering Service: A service for gathering data relevant to the inbound e-mail and add the data to the fact base.