Configuring Pega Web Mashup with the Gateway Configuration Console
The Gateway Configuration Console is a web application (prgateway.war) that you use to support the deployment of a Pega Web Mashup (known as Internet Application Composer (IAC) in Pega 7.1.8 and earlier versions) system. Complete the following steps to get started using the Configuration Console. See the
Readme.txt file in the Pega Web Mashup software distribution for details.
- Configure the prconfig.xml file in systems hosting applications you want to access through Pega Web Mashup by adding the
<env name="Authentication/RedirectGuests" value="false"/>
- Deploy prgateway.war.
- Open the Gateway Configuration Console by opening the servlet, prgateway/index.html, in your browser. Enter
http://hostname:port/prgateway/index.html, substituting the hostname and port number for you deployment, for example,
The console pages guide you through the configuration settings for a Pega Web Mashup deployment:
- Host Configuration
- Gadget Setup
- Gateway Setup
Specify properties and options for the Pega Web Mashup Gateway servlet, including custom error and logoff pages, session timeout values, log details level, cookies option, and URL header options.
The following article describes each of these pages in detail.
To begin using the Configuration Console, you first specify connection settings for the system that hosts the application you want to access. The Configuration Console generates property settings and gadget attributes that are specific to a host.
From the Home page, click Host Configuration.
If you have previously configured hosts, the Manage Hosts section contains a table listing them.
You use the Host Configuration page to:
- Adding a Host
- Test the connection to the host
- Manage Pega Web Mashup hosts: add, edit, and remove.
Complete the form as follows:
|Connection Name||The logical host name (System ID) of the system hosting the application to be displayed. The Connection Name is used by the Pega gadgets that send requests to the Gateway to identify this host.|
|Pega Host URL||The system context URI for this host– for example, http://serverX:8080/prweb.|
|Pega Auth Servlet||
The URL of the servlet providing your authentication service for system access. For example, to use the standard Pega Web Mashup authentication service, IACAuthentication, enter http://localhost:8080/prweb/IAC.
|Use Token SSO||Check to use the security token method of single sign-on.|
|Application ID||If using Token SSO, enter the application ID (Data-Admin-AppID) for the application you wish to display.|
|Department||If using Token SSO, enter the department number.|
|Application Password||If using Token SSO, enter the application password.|
To verify the Host Connection information you have entered, click Test Connection. The Gateway verifies that it can connect to the Host and reports whether it is properly configured for Pega Web Mashup.
Test Connection checks for the following configuration issues:
- The Gateway can connect to the Host URL and application you specified.
- The Pega-IAC RuleSet, pxIAC_04.01.01.zip and required hotfixes have been imported to the Host instance.
- The proconfig.xml file for the Host instance contains the element
<env name="/Authentication/RedirectGuests" value="false" />
Fix any configuration issues reported, before continuing.
When the connection is successful, click Save Connection.
Configured Hosts are added to the Manage Hosts table on the Host Configuration page:
- To configure additional hosts, click Add.
- To modify host settings, select the radio button next to a configured host and click Edit.
- To delete a host from the Gateway configuration, select the radio button next to a configured host and click Remove.
- Click the download icon in the Gadget JS column to download the Gadget Manager, PegaInternetApplicationComposer.js.
- Click the download icon in the Log JS column to download the Gadget client tracing tool, PegaInternetApplicationComposerLog.js.
You copy these files to the web server directory that holds your other site pages and scripts, and include a reference to them on your web page to support Pega Web Mashup gadget functions.
Use the Gadget Setup page to specify the gadget you want to include in your web page. The configuration console creates the Pega Web Mashup gadget code you include in a gadget DIV element on the web page. You create a DIV element for each gadget you want to include on the page.
Gadget Setup first asks for Host Connection information for the system hosting the application this gadget will access.
Complete the Host Connection fields. The Configuration Console uses information about applications on the Host to help you configure the rest of the Gadget Setup.
|Pega Host||Use the drop-down list to select one of the configured hosts.|
|Pega Operator ID
Pega Operator Password
|Enter the username and password of the system operator who has access rights to the application you want to display.|
Complete gadget setup in the following sections:
Required fields are marked with an asterisk.
Complete the Gadget Generation fields:
|Pega Gadget||Enter a name to identify the gadget.
Sets the PegaGadget attribute in the gadget DIV element.
|Application Name||The name of the application—that is, the name of a Rule-Application that specifies a single work pool.
|Pega Resize||From the drop-down list, select Stretch or Fixed height. Specifies the sizing behavior of the gadget: whether it can expand to fill the available space on the page or it must fit into a fixed space on the page. The default is Stretch.
Note:When Pega Resize is set to stretch, the style attribute of the DIV element created by the console is set to "overflow:auto".
|Pega Action||Use the drop-down list to select the default action for the gadget.
The console displays fields appropriate to the action selected. You may see different fields than the ones in this example.
Unless the Pega Defer attribute is set (see the Advanced Settings section) the Gadget Manager automatically executes this action when the web page containing the gadget DIV element is loaded.
Click the plus sign (+) and enter the name and value of the parameter you want to create.
Use this section to define user-defined parameters that are appended to request query.
Click the plus sign (+) again to add more parameters, or the minus sign (–) to remove a parameter.
Complete the Advanced Settings fields.
|Pega Defer||By default, Pega Defer is not checked and this gadget's default action executes automatically when the browser first loads the web page containing the gadget DIV element.
Sets the PegaDefer gadget attribute in the gadget DIV element.
|Encrypt URLs||This setting enables or disables the obfuscation of the URLS which are sent back to the client. By default, Encrypt URLs is not checked and all encryption and obfuscation for this script is disabled.
Check Encrypt URLs to enable encryption. When this property is set to true, the prconfig.xml setting initialization/urlencryption for the node should also be set to true.
|Pega Thread||If you want this gadget process to run in its own thread rather than using the STANDARD Thread on the system, enter a thread name.
|Gadget Target||Specifies whether the gadget should display its contents on the composite page (select _self), or in a pop-up window (select _popup.)
Sets the PegaTarget gadget attribute in the gadget DIV element.
Use this section to define a custom action-specific parameter: PegaA_XXXXX. Enter a name for the "PegaA_" action and its value. These parameters are passed as request query parameters to the system.
Click the plus sign, + , again to add more parameters, or the minus sign, – , to remove a parameter.
When you have completed your gadget setup, click Preview to see the gadget.
In a separate window, the Configuration Console displays the gadget as it will appear in your web page.
Review the gadget to make sure it displays as you expect.
Click HTML to show the files created to support this gadget for you to include in your web page.
- HTML to place in body tag: A div element containing the gadget definition as you specified it in the Gadget Setup sections.
You can copy and paste this text into your web page, or click Download Web Files to generate a Zip file containing the files you need. The Configuration Console creates a Zip file using the name of the gadget (for example, ESupply.zip) and containing:
- PegaInternetComposer.js, the Gadget Manager
- PegaInternetComposerLog.js, the Gadget client logging tool
- An HTML file using the name of the gadget, for example, ESupply.html containing the script and div elements as displayed above.
Use the Gateway Setup section to adjust deployment settings for the Gateway servlet, prgateway.war:
- Add Pega Web Mashup gateway deployment properties
- Add advanced Pega Web Mashup gateway deployment properties
Sets the ErrorPage element in prgateway.xml, for example,
Sets the LogoffPage element in prgateway.xml, for example,
|Session Timeout||Enter the length of time in seconds that an HTTPSessionmay be inactive before it is discarded.
Sets the SessionTimeout element in prgateway.xml, for example,
|Log Details Level||Enter the level of granularity of diagnostic messages written to the console log. Enter one of the following options. The levels are listed in order from least information to most information. For example, SEVERE writes only SEVERE errors to the log and filters all others. WARNING writes SEVERE and WARNING errors, etc..
Sets the LogLevel element in prgateway.xml, for example,
|Secure Cookies||Indicates whether to turn on the 'secure' flag of the session cookie that is sent to the client. This property must be unchecked in implementations that do not use SSL. Check Secure Cookies in implementations using SSL.
Sets the SecureCookie element in prgateway.xml:
|Forward Cookies||Indicates whether user cookies in the browser request are passed on to the server
Sets the ForwardAllCookies element in prgateway.xml:
|Include URL in Header||Indicates whether to instruct the gateway to include a custom header containing the URL for the gateway server in all requests to the system. This header is required if you want the host application to accept connections directly from clients in addition to the connections through the gateway.
Sets the SendBaseURLHeader element in prgateway.xml: <SendBaseURLHeader>true</SendBaseURLHeader>
|Gateway URL||When Include URL in Header is checked, enter the base URL of the gateway servlet.
Sets the BaseURL element in prgateway.xml:
Set this value to the subdomain if the domain needs to be explicitly specified on the cookie. Setting to
The Cookie Domain does not need to be explicitly set. The default behavior is backwards compatible with previous gateway releases and in most cases the default is the preferred configuration.