Implementing B2C mashup interfaces

The same rules can be used to uniquely identify a contact whether using the Create a case mashup action or the Display a page mashup action. The only question is whether to apply mashup-associated contact identification code to the concrete FSG-Data-Contact class or define a new abstract -SelfService class in a new ruleset, that class pattern-inheriting FSG-Data-Contact.

Developing a common way, at the enterprise layer, for contacts to approve cases created in a higher-layer application is challenging but not impossible. Note how the D_pxCaseDetail data page can change class from Work- to the class name supplied to its CaseClass parameter. But how then to display a section that is sourced to D_pxCaseDetail? And, how are the values supplied to D_pxCaseDetail's CaseClass and CaseID parameter obtained specific to the uniquely identified contact?

There are two ways to display a section dynamically:

1. Stub out a section at the Work- enterprise level, then have the higher-layer application override that section by name within a case type class.
2. As demonstrated in the non-templated Work- pyApproval section, use .pyApprovalSectionName to name the embedded section dynamically.

Option 1: New class and ruleset or existing class and ruleset

The -SelfService class name extension makes sense because it can be abstract. A TrueFalse Authenticated property makes sense to be added to that abstract  -SelfService class, not FSG-Data-Contact since the value of the Authenticated property can only be true when on-line. In the Advanced tab of a property rule, it is possible to select the Do not save property data check box, meaning it is possible to apply the Authenticated property to the FSG-Data-Contact and not have it be persisted. Still, for maintenance reasons, properties should be applied to a class synonymous with their purpose for existing. Creating the FSG-Data-Contact-SelfService class in a separate ruleset has advantages as well. If you want to locate the rules used for contact self-service, look in the ContactSelfService ruleset.

Having a concrete base class be extended by an abstract class can be challenging. The FSG-Data-Contact-SelfService class can persist data to FSG-Data-Contact just by executing the FSG-Data-Contact SavePlan activity. Properties defined in FSG-Data-Contact-SelfService are unknown to FSG-Data-Contact, so those properties are never persisted.

What about the reverse? The FSG-Data-Contact-SelfService class is supplied the pyGUID for a Contact. The SelfService class can certainly use the D_Contact data page sourced to a database lookup, but how can the SelfService class absorb the properties of the contact instance without having to set each property one by one? The SelfService class wants to leave its pxObjClass property value as is.

A solution is to leverage the Page-Merge-Into method in an activity. In the first step, the pxObjClass of the Primary page is set to param.ObjClassNew. The second step is Page-Merge-Into. The third step, Page-Change-Class, is used to restore the pxObjClass value of the Primary page.

Option 2: Dynamic case section display

Templated sections do not support properties such as pyApprovalSectionName to dynamically render an embedded section by name. The only option is to use a generic stubbed-out section name such as ContactSelfServiceApproval.

Having to use a stubbed-out section with a specific name does limit the self-service mashup design to allowing only one type of approval for each case type, but is that truly a limitation? It is unrealistic to have a customer make approval or rejection of decisions in multiple case type stages. FSG’s current need is to provide self-service up to and including the Quotation stage of the BookEvent case. Beyond the Quotation stage, other FSG personas come into play, such as Executives and Event Managers. The customer does not need to be involved in those stages.

Option 3: Source for CaseClass and CaseID information and how limited to the Contact

Suppose a case associated with an external contact wants that contact to review it. The case needs a way to persist this review intent in a manner that allows the contact to discover that intent. The enterprise layer has no way of knowing what those case types are. A unique solution can be coded for each case-specific mashup interface, but that is not the correct way to develop software.

The best way for a case to advertise itself to a contact that review is requested is to define a data class at the enterprise level. In the FSG application, an FSG-Data-ContactIssuedApproval class is added to the ContactSelfService ruleset. The properties in this class are ApprovalType, Approved, CaseClass, CaseRef, ContactRef, LinkText, and WaitingForContactInput. A case populates and persists an instance of this class, then waits at a work queue assignment for the contact to review the case. The contact can change Approved to true, or submit leaving the value as false, false implying Rejected. On submit of the contact's Approve or Reject decision, the WaitingForContactInput property, which had initially been set to true, is set to false. 

Within a Display a page mashup interface, an identified contact can view a list of FSG-Data-ContactIssuedApproval instances where the ContactRef property is equal to the contact’s GUID and WaitingForContactInput is equal to true. A D_CaseDetail data page uses the CaseClass and CaseRef values to set the proper context to display the BookEvent case’s ContactSelfServiceApproval section override of the stubbed-out, enterprise layer defined Work- ContactSelfServiceApproval section. LinkText is a short description of what the approval is about. A link control does not need to be used. The table layout that displays ContactIssuedApproval instances can instead be configured for Master/Detail operation. When a row is clicked, a modal dialog is launched.

FSGSample directory

The FSGSample.zip file is downloaded from a Rule-File-Binary rule as shown below.

The FSGSample.zip file can be extracted to a ../tomcat/webapps directory then accessed using<span> the  the  </span><cite>http://<host>:<port>/FSGSample/</cite>. A Pega Platform™ Personal Edition, with the prweb web app removed, will launch very quickly. A bookmark can be created named "FSG Sample" to capture the webapp url.

There is no need to do this, however. The HTML files in the unzipped PASample directory can be opened directly. The index.html file is opened first when accessed by a web server such as Tomcat. You can, however, click case1.html and case2.html directly.

The mashup interface configuration view in Dev Studio or App Studio generated the mashup code in the case1.html and case2.html files. The URL for the BookingEventCustomer anonymous Authentication Service is copied into the URL field before clicking the Generate Mashup code button. You can and should change the <host>:<port> information between https:// and /prweb/PRAuth/BookingEventSelfService to point to the server to where your Booking application is installed.

The background image file, bg.png, is located in the FSGSample/images directory

How contact-issued approval works

Log in to the FSG application. Note the Approvals section of FSG-Data-Contact-SelfService, which is displayed as a tab in the RegisterContact section.

The Approvals section embeds the non-templated PendingApprovals section. The PendingApprovals section contains a table layout that displays a list of FSG-Data-ContactIssuedApproval instances. The D_PendingApprovalList list data page passes its ContactGUID parameter through the PendingApprovals report definition, which filters FSG-Data-ContactIssuedApproval rows by ContactRef = param.ContactGUID and WaitingForContactInput = true.

The table layout of the PendingApprovals section is configured for a Master/Detail operator. Clicking a row that displays the value of the LinkText property displays a ShowWaitingApproval flow action in a dialog box. At the top of the ShowWaitingApproval section is an embedded section named ContactSelfServiceApproval. The embedded section is sourced to D_CaseDetail[pyID:.CaseRef,CaseClass:.CaseClass].

At the bottom of the ShowWaitingApproval section is an embedded section named ApprovalButtons. The Approve button executes the EnterDecision data transform, passing Approve as the value for the decision parameter. The Reject button passes Reject to the same transform.

The EnterDecision data transform sets the value of the Approved property appropriately according to the value of the decision parameter, followed by setting WaitingForContactInput to false.

Lastly, the EnterDecision data transform executes the SavePlan activity that is defined in the FSG-Data-ContactIssuedApproval class, followed by a commit.

Booking application Quote self-service mashup interface

The self-service quote capability is implemented entirely at the Booking application-level except for the customer registration and unique identification process.

On the surface, it appears that only the Quotation multistep process moved from the Question stage to the Create stage within the pyCreatedByChannel = Mashup the circumstance of the BookEvent case type rule.

The PostCaptureCustomer data transform is circumstanced using the pyIsMashup circumstance template. The difference is minor. The base rule obtains .CustomerGUID from D_ContactEditable.pyGUID. The circumstanced rule obtains .CustomerGUID from D_ContactSelfServiceEditable.pyGUID.

The PostCaptureCustomer and EditEventDetails sections are also edited using the pyIsMashup circumstance template. If these sections are saved to PostCaptureCustomerBase and EditEventDetailsBase, respectively, the two original sections can be modified to embed two sections where a view privilege controls the visibility of those sections.

Booking application Self Service Approvals Mashup interface

Very little is needed to define the self-service approvals mashup interface at the Booking application level because virtually all of the work is implemented at the enterprise level. The only thing needed is an application stack that reaches the level where an override of the ContactSelfServiceApproval section shows real data.

The Display a page mashup interface opens the enterprise-defined RegisterContact harness applied to the FSG-Data-Contact-SelfService class. The FSG-Booking-Work-BookEvent override of the ContactSelfServiceApproval section embeds a section named CustomerQuoteReview. As the name implies, this read-only section does not display costs or profit. It does display the DiscountPercentage field, which a Sales Executive can manipulate, but the customer cannot manipulate. A Sales Executive may decide to offer a self-service customer a discount before requesting approval from that customer.

Sales portal

Although not directly related to the two mashup interfaces, it is important to mention how the Sales Executive persona’s custom portal facilitates customer self-service.

A BookEventActiveQuotes harness is embedded within the Sales harness which in turn, is displayed by the BookingSales portal. All three rules are applied to FSG-Booking-UIPages.

The BookEventActiveQuotesContent section embeds a non-templated section named BookEventActiveQuotesList that has a table layout sourced to D_BookEventQuotationStageList, which does not have any parameters. 

That list data page is sourced to a report definition named QuotationStageBookEvent. The report definition queries every BookEvent case that is in the Quotation stage. The report joins to FSG-Data-ContactIssuedApproval by ContactIssuedApproval CaseRef = BookEvent pyID. The join is needed to display whether or not the Customer has approved the quote. 

If Approved = true, the Sales member is free to continue the BookEvent case. If not, the Sales member can contact the customer or wait for the work queue assignment to time out after 14 days.