This content has been archived.
Close popover

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.​

  1. Configure the prconfig.xml file in systems hosting applications you want to access through Pega Web Mashup by adding the RedirectGuests element:​
    <env name="Authentication/RedirectGuests" value="false"/>
  2. Deploy prgateway.war.
  3. 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, http://prpc_server:8080//prgateway/index.html.

    Gateway Console Configuration

The console pages guide you through the configuration settings for a Pega Web Mashup deployment:

  • Host Configuration

    Provide connection information for the systems that host the applications you want to display through Pega Web Mashup, and test the connection to be sure the host system is properly configured. You also use this page to download the Gadget Manager JavaScript application that you include on your web page to support the Pega Web Mashup gadgets that present the applications.

  • Gadget Setup

    Specify the gadget name and the application to display. Add gadget actions, user-defined parameters, and advanced settings. You can then preview the application to see how it will look on your web page, and download the Javascript code you need to add to your web page to embed the application.

  • 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.

Host Configuration

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.

Host Configuration

If you have previously configured hosts, the Manage Hosts section contains a table listing them.

You use the Host Configuration page to:

You install these Javascript files on the web server and include them on the web page on which you display the application.

Adding a Host

Click Add:

Click Add on the Host Configuration screen

Complete the form as follows:

Field Description
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.

Test Connection

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 results window.

Test Connection checks for the following configuration issues:

  • The Gateway can connect to the Host URL and application you specified.
  • The Pega-IAC RuleSet, 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.

Managing Hosts

Configured Hosts are added to the Manage Hosts table on the Host Configuration page:

List of configured hosts

  • 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.

From the Manage Hosts table, you can also download the Pega Web Mashup JavaScript applications.

  • 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. 

Gadget Setup

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.

Host Connection

Gadget Setup first asks for Host Connection information for the system hosting the application this gadget will access.

Gadget Setup screen

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.

Field Description
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.

Click Submit.

Complete gadget setup in the following sections:

Required fields are marked with an asterisk.

Generating a gadget

Gadget Generation fields

Complete the Gadget Generation fields:

Field Description
Gadget Generation
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.

Sets the property pega.web.config.appName in the JavaScript configuration object for the page. 

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".


Action Attributes
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. 

User Defined Parameters

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.

Advanced Settings

Complete the Advanced Settings fields.

Field Description
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.

Check Pega Defer to defer the gadget's default action until it is invoked through a doaction called by the page JavaScript or a gadget action in another gadget on the page.

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.

Sets the property pega.web.config.encrypt in the JavaScript configuration object for the page.

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.

Sets the property pega.web.config.thread in the JavaScript configuration object for the page. For more information about Threads, see Contrasting PRThread objects and Java threads.

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. 

Custom Parameters

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.

In IAC release 4.1, the configuration console does not support creation of the gadget action object from the user interface. You must code the action object manually, as in earlier releases. 

When you have completed your gadget setup, click Preview to see the gadget.

Gadget Preview

In a separate window, the Configuration Console displays the gadget as it will appear in your web page.

Preview gadget window, show HTML or download Web files

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.

Show HTML: Displays header and DIV files to include in web page.

  • Javascript to put in header tag: A script element with pega.web.config properties (for example, encrypt, gatewayURL, appName, systemID, and thread properties) that you include in the header of 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, 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.

Gateway Setup

Use the Gateway Setup section to adjust deployment settings for the Gateway servlet, prgateway.war:

Gateway Setup screen

These properties are saved in a properties file, prgateway.xml, that is external to the prgateway.war deployment, not in web.xml as in previous releases. By default, the file is created in the home directory (user.home) of the user running the console. You can specify a different location using the GatewayConfigFile parameter in the prgateway.war application's web.xml file.

Pega Web Mashup Gateway Properties

Field Description
Error Page Enter the path to the page that you want to send to the client when an error occurs in either the gateway or in the system. The default page, Error.jsp, contains important Javascript that must not be altered. If you wish to use a custom error page, the Javascript in the Error.jspfile must be included.

Sets the ErrorPage element in prgateway.xml, for example, <ErrorPage>/webwb/Error.jsp</ErrorPage>

Logoff Page Enter the path to the page that you want to send to the client when the client logs off. The default page, Logoff.jsp contains important javascript that must not be altered. If you wish to use a custom logoff page, the javascript in the Logoff.jsp file must be included.

Sets the LogoffPage element in prgateway.xml, for example, <LogoffPage>/webwb/Logoff.jsp</LogoffPage>

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..
  • OFF
  • INFO
  • ALL

Sets the LogLevel element in prgateway.xml, for example, <LogLevel>WARNING</LogLevel>

Advanced Gateway Properties

Field Description
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: <SecureCookie>false</SecureCookie>

HttpOnly cookies An HttpOnly flag is added to the cookie that is sent back to the client. This flag prevents the JavaScript from accessing these cookies when checked.
Forward Cookies Indicates whether user cookies in the browser request are passed on to the server
  • If checked, all cookies from the user's browser request are passed on to the server
  • If unchecked (the default), all user's cookies in the browser request are blocked at the gateway, and only the system session cookie is passed on to the server.

Sets the ForwardAllCookies element in prgateway.xml: <ForwardAllCookies>false</ForwardAllCookies>

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.
  • Check Include URL in Header if you want the host to accept connections to applications both through the gateway and through direct client connections.

    If Include URL in Header is checked,

    • Gateway URL must contain the URL for the gateway server, and
    • the prconfig.xml file for the Host web node must not contain the initialization/gatewayurl setting
  • Do not check Include URL in Headerif you only want to permit connections to applications on the Host through the gateway.

    If Include URL in Header is not checked, you must set the initialization/gatewayurl setting in the prconfig.xml file on the web node.

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:

Cookie Domain

Set this value to the subdomain if the domain needs to be explicitly specified on the cookie. Setting to default notes the default cookie behavior and the domain property is not set on the cookie. This causes the browsers to send the cookies only to the host that set the cookie. It does not send the cookies to any other host (even in the subdomain).

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.

System Architect User Interface
Suggest Edit

100% found this useful

Have a question? Get answers now.

Visit the Collaboration Center to ask questions, engage in discussions, share ideas, and help others.