Data exchange through Pega Web Mashup

When you add a Pega Web Mashup to a web page, you can configure the mashup gadget to read data from and send data to the hosting page or another mashup gadget. Passing data in this manner creates a more seamless experience for users.

For example, a bank with a dispute resolution process implemented on the Pega Platform™ has users who may want to dispute a recent transaction they see on the bank's website from a list of transactions (stored in a system of record and accessed by the online banking web page). The transaction details are passed to the Pega application through the mashup. The mashup returns a case ID to the user for future reference.

The Pega Web Mashup supports three options for passing data to or from a Pega application:

• Use the data-pega-event-onpagedata attribute to specify the default value for the gadget.
• Use the Javascript function doAction() to set or read data values from the web page hosting the gadget, such as by clicking a button. Call the doAction() function using the syntax: pega.web.api.doAction([gadgetname],[action],[parameters]).
• Use an action object to perform additional actions on a web mashup gadget or configure the gadget to interact with another gadget. Configure the action object as a script within the gadget DIV tag and specify the attributes and parameters as required to perform the action. For more information on configuring action objects, including the full set of actions available, see the Pega Community article Pega Web Mashup action objects.

The values of mashup attributes and action-specific parameters can be literal values, property references, references to functions in the page JavaScript, or references to input elements in the page JavaScript (DOM elements). Additionally, a parameter object containing name/value pairs for custom parameters is used as input for many actions.

When you specify nonliteral values as attribute or parameter values, use the syntax in the following table.

Use the value of a DOM element

To use the value of an element from the page JavaScript as the value of a gadget attribute or action parameter, use [page/id/elementID], where elementID is the name of the DOM element. For example, you can configure a Pega Web Mashup gadget to use the value of a DOM element named Account by setting the data-pega-parameters attribute: data-pega-parameters="{Customer:'[page\id\Account]'}".

Use the value returned by a function in the page JavaScript

To use the value returned by a function on the page JavaScript as the value of a mashup attribute or action parameter, use the syntax [page/function/token], where token is a string that has meaning to the function. Specify the function used to retrieve the value using the data-pega-event-onpagedata attribute.

For example, to set the class of the harness used by a mashup gadget using a function, set the value of the data-pega-classname attribute using the syntax data-pega-classname =[page/function/AutoClaim]. Then use the data-pega-event-onpagedata to identify the function that returns the appropriate class name based on the token.

Use a property reference in the page JavaScript

Use the getGadgetData and setGadgetData actions to read and set property values in a mashup gadget. The getGadgetData action uses the syntax [gadget/gadgetName/property] to reference the property reference where gadgetName is the name of the mashup, and property is the name of a property used in a Pega application such as .pyID, pyWorkPage.pyID, or.pyWorkParty(operator).pyUserName. gadget is a keyword required by the getGadgetData action.

For example, to display the value of the pyID property on the host page, use the doAction function to call the getGadgetData action with the syntax pega.web.api.doAction("gadgetName", "getGadgetData", "[gadget/gadgetName/.pyID]").

To set the value of a property using setGadgetData action, use the syntax pega.web.api.doAction("gadgetName", "setGadgetData", "propertyReference", strValue). For example, set the value of the property .QuoteType with the setGadgetData action: pega.web.api.doAction("gadgetName", "setGadgetData", ".QuoteType", "Auto").

Use a property reference as the value of a gadget attribute or parameter

To perform an action on a gadget using data from the gadget, create an action object for the gadget. If the property you need to use is in the same gadget as the reference, use the syntax Attribute/parameter = [propertyReference]. For example, when configuring an action object to display a confirmation page that uses operator information as parameter values, set the value of the pageURL attribute using the syntax pageURL: "/statusPage" + "CreateOper=[.pxCreateOpName], where CreateOper is the name of the parameter and pxCreateOpName is the reference to the property in the Pega application.

If the property you need to use is in a different mashup gadget, use the syntax [gadget/gadgetName/propertyReference] to identify the gadget containing the property. This is the same syntax that you use in a property reference from the page JavaScript.

Use object literal notation to preserve attribute and parameter names

Many system properties and parameters have names with mixed cases. When displaying a non-XHTML page, the Firefox browser converts attribute names to all lowercase letters. To prevent this, specify parameter name/value pairs using object literal notation.

The following two examples demonstrate the use of object literal notation:

• To set the value of the data-pega-parameters attribute on the mashup definition using object literal notation: data-pega-parameters="{Customer:'[page/id/Account]', Level:'gold'}"
• To set the parameter object for a gadget action object using object literal notation: params: { Status:"[pyWorkPage.pyStatusWork]"}