Managing Integration Gateways

This chapter provides an overview of integration gateway configuration and discusses how to:

• Administer integration gateways.

• Access gateway setup properties.

• Set Oracle Jolt connection properties.

• Use the integrationGateway.properties file.

• Encrypt passwords.

• Configure security and general properties.

• Mask gateway log elements.

• Refresh integration gateway properties.

• Bypass integration engines to send messages.

Understanding Integration Gateway Configuration

This section discusses:

• Integration gateway versions and application server versions.

• Local gateway compatibility.

• Types of integration gateway configuration.

Integration Gateway Versions and Application Server Versions

Local and remote integration gateways must be at the same or higher version as the application servers with which they communicate.

Out of the box, PeopleTools 8.51 is delivered with a PeopleTools 8.51 integration gateway and a PeopleTools 8.51 application server, thus meeting this requirement

However, situations may arise where your integration environment is comprised of PeopleSoft systems running different versions of PeopleTools, or your integration partners are running different versions of PeopleTools. When this is the case, you must ensure that the integration gateway is at the same or higher version as the application server with which it communicates or integrations will fail.

The following list describes several compatible integration gateway/application server version combinations:

• You are using a PeopleTools 8.51 integration gateway to communicate to a PeopleTools 8.51 application server.

• You are using a PeopleTools 8.51 integration gateway to communicate to a PeopleTools 8.49 or earlier application server.

• You are using a PeopleTools 8.51 remote integration gateway to communicate with a PeopleTools 8.51 or earlier application server.

The following list describes several incompatible integration gateway/application server version combinations. Integrations will fail with these combinations:

• You are using a PeopleTools 8.49 or earlier integration gateway to communicate with a PeopleTools 8.51 application server.

• You are using a PeopleTools 8.49 remote integration gateway to communicate with a PeopleTools 8.51 application server.

Local Gateway Compatibility

Because database administrator passwords and gateway keystore passwords are encrypted in the current PeopleTools release, the local gateway specified by a node in the current release of PeopleSoft Integration Broker must be from PeopleTools 8.41 or later to support encryption. If you upgrade PeopleTools and the integration engine from a release earlier than PeopleTools 8.41, you must also upgrade the local gateway.

Note. The current release of the integration gateway works with nodes that use PeopleTools 8.4x PeopleSoft Integration Broker.

Types of Integration Gateway Configuration

An integration gateway requires several types of configuration:

The Gateways Component

Once the gateway has been installed, you use the Gateways component (IB_GATEWAY) to make it accessible to any node that uses it for messaging. You can also use it to override the gateway's default connector properties for individual nodes without having to directly edit the integrationGateway.properties file on the gateway machine.

See Managing Integration Gateways.

Minimum Integration Gateway Setup Requirements

The minimum setup requirement to run an integration gateway are:

1. Specify the gateway URL.

2. Specify the Oracle Jolt connection string properties to enable communication with each PeopleSoft Integration Broker node that will be involved in an integration that uses a gateway.

3. Set and encrypt the keystore password.

See Also

Using the Integration Broker Quick Configuration Page

Setting SSL/TLS Encryption Security Properties

Administering Integration Gateways

This section discusses how to:

• Define integration gateways.

• Ping integration gateways.

• Register installed target connectors.

• Refresh the gateway properties.

• Edit available connector properties.

Defining Integration Gateways

Use the Gateways page (IB_GATEWAY) in the Gateways component (IB_GATEWAY) to specify the location of the gateway, update configuration settings, and register target connectors to be used with the gateway.

Note. A default local gateway definition is automatically created upon installation. If you plan to use only the local gateway, you do not need to create a new definition; however, you still must configure the gateway.

To access the Gateways page, select PeopleTools, Integration Broker, Configuration, Gateways. The following example shows the Gateways page:

To define and configure a gateway:

1. Access the Gateways page (select PeopleTools, Integration Broker, Configuration, Gateways).

   • Click Search, and select an existing gateway definition.

     The Gateways page appears, displaying the gateway definition.

     Note. The default ID for the delivered local gateway is LOCAL.

   • Add a new value, enter an integration gateway ID, and click Add.

     The Gateways page appears.

2. (Optional.) Select Local Gateway to designate the gateway as local.

   Each PeopleSoft Integration Broker node requires exactly one local gateway, which is the application’s first point of contact with other PeopleSoft applications, third-party systems, Integration Broker hubs, and remote gateways.

   Note. You must open the definition of the designated local gateway and clear the Local Gateway check box before you can select that check box in another definition.

3. Enter the gateway URL for the selected gateway’s PeopleSoft listening connector.

   Specify the URL with the format:

   http://machinename:port/PSIGW/PeopleSoftListeningConnector

   In this case, machinename:port is the machine name and port, host name, or IP address of the web server hosting the gateway.

   By default the port number is 80 for HTTP and 443 for HTTPS. If using the default port number, you do not need to specify it in the URL.

   For HTTPS, the URL should start with https.

   The integration gateway URL is case sensitive.

   The gateway uses the PeopleSoft listening connector to receive service operations from an integration engine node or a remote gateway.

4. (Optional.) To load the delivered target connectors, click the Load Gateway Connectors button.

   You can load the delivered target connectors at this point, or at a later time.

5. Save the gateway definition.

6. Click the Gateway Setup Properties link to configure additional gateway settings and connector properties.

See Also

Configuring Integration Gateways for Load Balancing When Using Third-Party Software

Pinging Integration Gateways

Use the Gateways page to ping an integration gateway to verify that it is running. Before you ping an integration gateway, you must define the gateway URL.

To ping an integration gateway:

1. Access the Gateways page (select PeopleTools, Integration Broker, Configuration, Gateways).

2. Select the integration gateway to ping.

   The Gateways page appears.

3. Click the Ping Gateway button.

If the ping is successful a PeopleSoft Listening Gateway page appears that displays the PeopleTools release and a status of Active.

Loading Target Connectors

The Connectors grid on the Gateways page lists the target connectors registered with the current gateway. Initially, none of the delivered connectors are loaded and the grid is empty. You can load target connectors automatically by introspection or manually by entering information in the grid.

Note. You typically load and configure the gateway target connectors only when you configure a new gateway or install a new connector.

Loading Connectors by Introspection

If the connector was delivered with the PeopleSoft application or developed using the PeopleSoft Integration Broker Connector Software Development Kit (SDK), you can easily load it with the PeopleSoft Integration Broker connector introspection feature. Before you can register a new connector, you must install it.

See Using the Integration Broker Connector SDK.

To load connectors by introspection:

1. Access the Gateways page (select PeopleTools, Integration Broker, Configuration, Gateways).

2. Click the Load Gateway Connectors button to trigger introspection for the current gateway.

PeopleSoft Integration Broker examines the properties of all installed target connectors and loads those properties into the gateway definition. All the connectors appear in the Connectors grid, and the properties of each connector are updated to reflect its current state.

Note. The introspection never overrides existing information. It adds only missing information, so manually edited values are not affected. If you modified a connector, new and modified properties are loaded and do not interfere with existing properties.

Loading Connectors Manually

To load and configure a connector manually, you enter the connector ID, connector class name, and property information that’s hard-coded in the connector. This information is provided by PeopleSoft for all delivered connectors; information about connectors from any other source must be provided by that source.

To load a new connector manually:

1. Access the Gateways page (select PeopleTools, Integration Broker, Configuration, Gateways).

2. Add a new row in the Connectors grid.

3. Enter the ID for the new connector.

4. Enter the connector class name.

5. Click Properties to edit the connector’s properties.

See Also

Using the Delivered Listening Connectors and Target Connectors

Using the Integration Broker Connector SDK

Editing Connector Properties

Node-level target connector properties represent parameters that can be used by the connector. These properties are hard-coded in the connector class. The Connector Properties page (IB_CONNPROP) lists all of a connector’s available properties and their values. When you specify a connector in a node definition, only the properties that you are required to set and specify display.

Note. Available connector properties are automatically entered on the Connector Properties page when you register the connector.

Each property entry is defined by a combination of property ID and property name, both of which must already exist in the connector class. A single connector can handle service operations that adhere to different header formats, communication protocols, or other requirements. You can represent these variations on the Connector Properties page by entering multiple instances of the properties used, each with a different value.

Warning! Do not add new properties to any of the delivered connectors, as doing so requires changes to the delivered Java connector programs. Add connector properties only for custom connectors you have created.

The following example shows the Connector Properties page:

To add a new property instance:

1. Access the Connector Properties page (select PeopleTools, Integration Broker, Configuration, Gateways to display the Gateways page).

2. In the Connectors section locate the row that lists the target connector with which you want to work, and click the Properties link at the end of the row. The Connector Properties page displays.

3. Select a Property ID.

   Available property IDs are specific to the connector that you’re configuring.

4. Select a Property Name.

   The available property names are specific to the property ID that you selected.

5. If the property is required for the connector to work properly, select the Required check box.

   All instances of a property (that is, all identical property ID and property name combinations) should have the same Required status.

6. Enter an appropriate value for the property instance.

   Appropriate values might come from PeopleSoft, from the connector’s developer, or from your own experience and requirements.

7. (Optional.) Select the Default check box.

   When you specify the connector in a node definition, only properties marked as both required and default appear automatically on the Connectors page of the Node Definitions component.

   Note. In most cases, only one instance (value) of a required property should be used by a given node; however, you might designate multiple values as default so that they all appear. Keep in mind which properties can be used with multiple values and which ones require a single value.

8. Save the properties.

9. Click OK.

   The Gateways page appears.

Accessing Gateway Setup Properties

This section discusses how to access the integration gateway set up properties.

You can access the gateway setup properties from the Quick Configuration page or from the Gateways page.

• To access gateway setup properties from the Quick Configuration page, select PeopleTools, Integration Broker, Configuration, Quick Configuration. The Quick Configuration page appears. Click the Advanced Gateway Setup link.

• To access gateway setup properties from the Gateways page, select PeopleTools, Integration Broker, Configuration, Gateways. The Gateways page appears. Click the Gateway Setup Properties link.

The Gateway Properties signon page (IBGWSIGNON) appears as shown in the following example:

The default user ID is administrator and the default password is password. Check the Change Password box to change the default password.

Note. You should change the default password as soon as possible.

You can reset the password in the gatewayUserProfile.xml file located in <PIA_HOME>\webserv\<DOMAIN>\applications\peoplesoft\PSIGW.war\WEB-INF. The password you enter in the gatewayUserProfile.xml file must be encrypted. You can use the PSCipher utility to encrypt the password.

After you successfully enter the user ID and password, the PeopleSoft Node Configuration page displays where you specify information about how to connect to nodes and access the integrationGateway.properties file to establish additional gateway settings.

Setting Oracle Jolt Connection Properties

The integration gateway communicates with PeopleSoft application server nodes using Oracle Jolt connections.

Understanding Oracle Jolt Connection Properties

This section discusses setting Oracle Jolt connection string properties using the PeopleSoft Node Configuration page. Setting these properties in the integrationGateway.properties file is discussed later in this section.

The PeopleSoft Node Configuration page (PSGTWPROPS_SEC) provides grids for defining Oracle Jolt connection properties for unknown (default) and known nodes. When you save the properties you set on this page, they are written to the integrationGateway.properties file. To edit or define these properties in the future, you can use the PeopleSoft Node Configuration page or the integrationGateway.properties file.

Connection Settings When Target Nodes are not Known

Within any inbound message, the integration gateway requires only the names of the message and the requesting node. If the message is sent by a PeopleSoft Integration Broker system, it also includes the name of the target node. The gateway searches the integrationGateway.properties file for the Jolt connect string properties for the specified target node, so it can properly direct the message.

However, the integration gateway cannot determine the target node in the following cases:

• The Jolt connect string settings for the specified target node are missing from the integrationGateway.properties file.

• The message format does not include a To node specification.

To handle these cases, you can specify a default application server to handle the message if no valid target node can be determined.

Connection Settings for Known Target Nodes

You must set four Oracle Jolt connect string properties for each PeopleSoft Integration Broker application server node with which the integration gateway communicates. The gateway uses this information to access each node's database through a Oracle Jolt connection with its PeopleSoft target connector.

Note. These properties apply only to communications that don't cross a firewall and for which the gateway uses the PeopleSoft target connector.

Setting Oracle Jolt Connection String Properties

The PeopleSoft Node Configuration page provides a grid for setting Oracle Jolt connection string properties for unknown (default) target nodes and known target nodes.

To access the PeopleSoft Nodes Configuration page, select PeopleTools, Integration Broker, Configuration, Gateways. The Gateways page appears. Click the Gateway Setup Properties link. Enter the gateway user ID and password and click the OK button. The PeopleSoft Node Configuration page appears.

To define properties for unknown nodes use the Gateway Default Application Server grid on the PeopleSoft Node Configuration page. To define properties for known nodes use the PeopleSoft Node grid on the PeopleSoft Node Configuration page.

Note. Setting Oracle Jolt string connection properties for unknown nodes is optional.

The properties and values you set in the PeopleSoft Node Configuration page are located in the DELIVERED CONNECTOR CONFIGURATION Section of the integrationGateway.properties file.

The properties you set for unknown nodes are in the subsection ## JOLT connect string setting for optional Default Application Server. The properties you set for known nodes are in the subsection ## JOLT connect string settings for Application Server(s) with known NODENAMEs.

See Also

Accessing Gateway Setup Properties

Using the integrationGateway.properties File

Configuring Security and General Properties

Using the integrationGateway.properties File

To establish settings for the integration gateway and its delivered connectors, you use the integrationGateway.properties file.

The integrationGateway.properties file is a text file.

The property settings in the file are stored as name-value pairs in labeled sections, and the lines are commented out using the pound sign (#). Here's an example of a commented-out property setting:

#ig.isc.userid=MYUSERID

Accessing the integrationGateway.properties File

You can access and edit the integrationGateway.properties file using the Gateways component in the Pure Internet Architecture or using the text file located in the <PIA_HOME>\webserv directory.

Understanding Accessing the integrationGateway.properties File

Most integration systems are configured such that the application server, integration gateway, and PeopleSoft Pure Internet Architecture are running the same PeopleTools versions.

However, there may be some instances where the integration system is configured such that there is a shared integration gateway working with application servers on different versions of PeopleTools. If this is the case, you must access and edit the integrationGateway.properties in one of the following ways:

• Manually edit the text file located in the <PIA_HOME> directory. Use the PSCipher Java utility to generate encrypted passwords.

  Using the PSCipher Java utility is described elsewhere in this chapter.

  See Encrypting Passwords Using the PSCipher Java Utility.

• Access and edit the properties file via the PeopleSoft Pure Internet Architecture in the Gateways component. You must log into the PeopleSoft Pure Internet Architecture that is installed on the application server that is running the same PeopleTools release as the integration gateway. If you use this method, you must ensure that copies of the same psvault key file are installed on all application servers and gateway/web server in the configuration.

  The psvault key file is discussed elsewhere in PeopleBooks.

  See Encrypting Text With PSCipher.

Accessing the integrationGateway.properties File in the Pure Internet Architecture

Access to the integrationGateway.properties file using the PeopleSoft Pure Internet Architecture is password-protected. You can access the file using the Integration Broker Quick Configuration page or the Gateways component.

To access the integrationGateway.properties file using the Integration Broker Quick Configuration page:

1. Select PeopleTools, Integration Broker, Configuration, Quick Configuration.

   The Integration Broker Quick Configuration page displays.

2. Click the Advanced Gateway Setup link.

   The Gateway page displays.

3. Click the Gateway Setup Properties link.

   The Sign on to access the integrationGateway.properties file box displays.

4. Enter the user ID and password and click the OK button.

5. Click the Advanced Properties Page link.

To access the integrationGateway.properties file using the Gateways component:

1. Select PeopleTools, Integration Broker, Configuration, Gateway.

2. Select a gateway with which to work.

3. Click the Gateway Setup Properties link.

   The Sign on to access the integrationGateway.properties file box displays.

4. Enter the user ID and password and click the OK button.

5. Click the Advanced Properties Page link.

The Gateway Properties page also provides access to the Password Encryption Utility and you can encrypt passwords required in the integrationGateway.properties file directly from that page.

Accessing the integrationGateway.properties File in the <PIA_HOME> Directory

The integrationGateway.properties file is located in the following path in the PeopleSoft home directory:

<PIA_HOME>\webserv\<DOMAIN>\applications\peoplesoft\PSIGW.war\WEB-INF\integrationGateway.properties.

When you access the integrationGateway.properties file in directly in the <PIA_HOME> directory, you must restart the PeopleSoft Pure Internet Architecture for the changes to take effect.

See Also

Loading Target Connectors

Encrypting Passwords

Entering Values in the integrationGateway.properties File

When entering values in the integrationGateway.properties file that contain paths, you must use either double-backslashes (“\\”) or forward slashes (“/”) as path separators.

Note. Do not use backslashes (“\”) as path separators for directory names in the integrationGateway.properties file. Backslashes are misinterpreted as escape characters by the Java processes that access the file.

To correctly specify a path in the integrationGateway.properties file, you must use either double backslashes (“\\”) or single forward slashes (“/”) as separators; for example:

ig.transform1.XSL=C:\\XSLProgs\\MyTransform.xsl
ig.transform1.XSL=C:/XSLProgs/MyTransform.xsl
ig.transform1.XSL=/usr/xsls/MyTransform.xsl

Note. The one exception to this is when entering path separators for EIP test automation properties. When working with those properties you must enter path separators as backslashes.

Encrypting Passwords

The integration gateway properties file and target connectors feature required and optional passwords. All passwords must be encrypted.

PeopleSoft provides an encryption utility, PSCipher, that you can use to encrypt passwords. You can access the utility from the PeopleSoft Pure Internet Architecture or from a Java utility.

Encrypting Passwords in the PeopleSoft Pure Internet Architecture

The Password Encryption Utility dialog box displays in areas where required or optional passwords are specified.

To encrypt a password using the Password Encryption Utility:

1. On the page where you are working, click the Password Encryption Utility arrow to display the dialog box.

2. In the Password field, enter a password.

3. In the Confirm Password field, enter the password again.

4. Click the Encrypt button. The encrypted password displays in the Encrypted Password field.

5. From the Encrypted Password field, cut the encrypted password and paste it into the appropriate location.

Encrypting Passwords Using the PSCipher Java Utility

You launch the PSCipher utility from the <PIA_HOME> directory.

To encrypt a password:

1. Launch the PSCipher.bat file in the <PIA_HOME>\webserv\<DOMAIN>\bin directory.

2. If using UNIX, change the script file’s permissions so that you can execute it.

3. Execute the script file with your password as an argument.

   The utility returns the encrypted password as a string.

   • On a Windows machine, enter:

     pscipher MYPASSWORD

   • On a UNIX machine, enter:

     PSCipher.sh MYPASSWORD

4. Copy the encrypted string and paste it into the appropriate location.

Configuring Security and General Properties

This section discusses how to:

• Set SSL encryption security properties.

• Specify the gateway version.

• Specify the gateway class location.

• Set general connection properties.

• Set logging properties.

• Set DTD validation properties.

• Set Oracle Jolt session pooling parameters.

• Set the namespace for generic SOAP faults.

Setting SSL/TLS Encryption Security Properties

You can implement several types of messaging security with PeopleSoft Integration Broker. One type is SSL/TLS encryption, which applies digital certificates from two keystores to encrypt inbound and outbound messages, respectively. The integration gateway manages the certificates in the keystore that supports outbound messaging.

You must first install the certificates in the keystore. Then you set the security properties, which you can find in the integrationGateway.properties file section labeled Integration Gateway CERTIFICATE Section.

Warning! Integrations will fail if you do not set the path to the keystore using the secureFileKeystorePath property and enter an encrypted keystore password for the secureFileKeystorePasswd property.

You must set the following properties in integrationGateway.properties so that the gateway can access the SSL/TLS encryption certificates.

See Also

Setting Up Secure Integration Environments

Specifying the Gateway Version

The gateway version property, ig.version, indicates the version of PeopleTools from which the integration gateway is installed.

The integration gateway version must be the same or higher version than the version of the application server with which you want to communicate. For example, you can use a PeopleTools 8.51 integration gateway to communicate with a PeopleTools 8.51 application server or to communicate with a PeopleTools 8.47 application server.

Integration gateways cannot communicate with application servers on higher versions. For example a PeopleTools 8.47 integration gateway cannot directly communicate with a PeopleTools 8.51 application server. If this kind of communication is required, then the communication should be setup where the 8.47 gateway is set up as a remote gateway.

The version property is located in the integrationGateway.properties file in the section labeled Integration Gateway VERSION Section. Specify the version as follows:

ig.version=version_number

where version_number is the version of PeopleTools with two decimal places; for example, 8.51.

Setting General Connection Properties

This section discusses:

• Default connector properties.

• Node-specific Oracle Jolt connect string properties.

• Default Oracle Jolt connect string properties.

The general connection properties include default connector properties and Oracle Jolt connect strings for nodes that designate this gateway as their local gateway. You can find these properties in the section of the integrationGateway.properties file labeled DELIVERED CONNECTOR CONFIGURATION Section.

Default Connector Properties

com.peoplesoft.pt.integrationgateway.
targetconnector.

HttpTargetConnector

PeopleSoftTargetConnector

Default Oracle Jolt Connect String Properties

Within any inbound message, the integration gateway requires only the names of the message and the requesting node. If the message was sent by a PeopleSoft Integration Broker system, it also includes the name of the target node. The gateway searches the integrationGateway.properties file for the Jolt connect string properties for the specified target node, so it can properly direct the message.

However, the integration gateway cannot determine the target node in the following cases:

• The Jolt connect string settings for the specified target node are missing from the integrationGateway.properties file.

• The message format does not include a To node specification.

  This can include general HTTP calls to listening connectors other than the PeopleSoft listening connector.

• When using Send Master for testing purposes.

To handle these cases, you can specify a default target node for the gateway if no valid target node can be determined.

Use the default Jolt connect string properties:

#ig.isc.serverURL=//<machine name>:<jolt port>
#ig.isc.userid=<database user id>
#ig.isc.password=<database password>
#ig.isc.toolsRel=<peopletools release version>

Uncomment these four lines and enter values to designate a PeopleSoft Integration Broker node as the gateway's default (backup) target node. It typically is one of the nodes for which you already created node-specific Jolt connect string properties.

There's only one set of these default properties. They specify the same parameters as the node-specific properties, except that you don't include a node name; for example:

ig.isc.serverURL=//MYMACHINE:9000
ig.isc.userid=TOPDOG
ig.isc.password=VOBN5KcQZMg
ig.isc.toolsRel=8.51

See Oracle Jolt Connect String Properties for Known Nodes.

Oracle Jolt Connect String Properties for Known Nodes

You must set four Oracle Jolt connect string properties for each PeopleSoft Integration Broker application server node with which the integration gateway communicates. The gateway uses this information to access each node's database through a Oracle Jolt connection with its PeopleSoft target connector.

Note. These properties apply only to communications that don't cross a firewall and for which the gateway uses the PeopleSoft target connector.

The integrationGateway.properties file contains a template for these properties:

ig.isc.$NODENAME.serverURL=//<machine name>:<jolt port>
ig.isc.$NODENAME.userid=<database user id>
ig.isc.$NODENAME.password=<database password>
ig.isc.$NODENAME.toolsRel=<peopletools release version>

For each node, make a copy of this template and replace $NODENAME with the name of the node definition. Enter appropriate values for each property as described in the following table:

ig.isc.MYNODE.serverURL=//MYMACHINE:9000

ig.isc.MYNODE.userid=TOPDOG

ig.isc.MYNODE.password=VOBN5KcQZMg

ig.isc.MYNODE.toolsrel=8.51

Setting Logging Properties

This section discusses:

• General logging properties.

• Message logging properties.

• Error logging properties.

• Overriding the IP address used for gateway logging.

The logging properties specify parameters for logging messaging activity and errors. You can find these properties in the section of the integrationGateway.properties file labeled LOGGING Section.

General Logging Properties

Message Logging Properties

Error Logging Properties

See Also

Understanding Error Handling, Logging, Tracing and Debugging

Overriding the IP Address Used for Gateway Logging

The gateway captures its own IP address and returns this information in responses sent to the application server. The application server uses the address to locate the physical machine where the gateway runs; this is where the various gateway logs are stored.

In certain instances, the value of the IP address captured may be incorrect, due to issues with the underlying web server. For example, the address may show up as 127.0.0.1, which from the gateway's perspective is correct (since that's the IP loopback address ) but this value is not useful to the application server as it needs the actual IP of the gateway.

PeopleSoft provides the following property that enables you to override the IP address that the gateway captures and hardcode the IP address used for gateway logging:

ig.GatewayIPAddressOverride

This property is located in the Gateway IP Address Override section in the integrationGateway.properties file.

To use the property, set it equal to the IP address of the machine running the integration gateway.

Note that the actual machine that writes the logs does not change. If set the value to one that is not the IP address of the machine that the gateway is actually on, when the application server creates links to display log info, those links will not point to the actual log files.

Setting DTD Validation Properties

You can validate XML request messages and response messages against associated document type definitions (DTD) by enabling DTD validation on the integration gateway.

When you set the ig.dtdLookup property equal to True (default), request and response messages are validated against any associated DTD.

References to DTDs may be inline pointers to files or references to URLs.

When you set the ig.dtdLookup property equal to False, no validation takes place—even if a DTD reference is supplied.

If the ig.dtdLookup property is removed or otherwise missing from the integrationGateway.properties file, the system responds as if the property is set to True, and request and response messages are validated against any associated DTD.

Setting Oracle Jolt Session Pooling Parameters

The integration gateway maintains a pool of jolt sessions to handle requests between itself and the integration engine. The integration gateway issues a jolt session from the pool, uses it for the connection, and then returns the session to the pool once it receives the response from the integration engine.

The number of sessions to maintain in the session pool is defined in the integrationGateway.properties file using the following property:

ig.connection

Set this property equal to the maximum number of sessions to maintain in the pool. The default value is 10.

Setting the Namespace for Generic SOAP Faults

The system generates generic SOAP faults for framework-level errors, such as when it cannot find a routing for an integration.

To specify the namespace to use for generic SOAP faults, set the following property in the integrationGateway.properties file equal to the namespace to use:

ig.GenericFaultNamespace

Masking Gateway Log File Elements

This section provides and overview of masking gateway log file elements and discusses how to:

• Access the logfilter.properties file.

• Mask elements not contained in namespaces.

• Mask elements contained in namespaces.

• Mask attributes of elements.

• Mask child element names.

• Change the global mask message.

• Create custom mask messages.

• Disable gateway log masks.

Understanding Masking Gateway Log File Elements

You can mask, or hide, elements that appear in the integration gateway log files, thereby prohibiting sensitive information from displaying in the generated logs.

Note. The system applies gateway log masks and messages to both the integration gateway message log file (MsgLog.html) and the integration gateway error log file (ErrorLog.html).

Global and Custom Mask Messages

By default, all masked elements have a global mask message applied to them, whereby every element you mask is replaced with a standardized message. You can also create custom mask messages for specific elements. You can use a combination of global and custom mask messages.

The default global mask message is *** deleted for security purposes ***. You can change the global mask as you wish to a message that best suits your business needs.

Default Masks

Several gateway log masks are implemented by default. They include, but are not limited to, the following elements:

• WSSE password.

• NodePassword.

• ExternalUserPassword.

• XML format request with password.

• PSFT AuthToken.

• SAML-TokenData.

You can disable any of these masks in the logfilter.properties file.

logfilter.properties File

To mask and unmask gateway log file elements use the logfilter.properties file.

To use the file to specify the element names, attribute names, and element namespaces to mask. You can also use the file to change the global mask message and set up custom mask messages.

Note. After you make any changes to the logfilter.properties file, you must reboot the webserver for the changes to take effect.

Property Types

The following table lists the property types with which you can work in the logfilter.properties file:

Note. The examples provided in this section show property names appended with a number. These numbers are property indexes and are discussed elsewhere in this section.

Property Indexes

All properties in the logfilter.properties file are appended with an index number. Indexes group related properties and their values. The following example shows an excerpt from the logfilter.properties file and the ElementName.<index_number> naming scheme.

#IBInfo NodePassword
​ElementName.2=NodePassword

#IBInfo ExternalUserPassword
​ElementName.3=ExternalUserPassword

#XML format request with Password
​ElementName.4=Password

You can use any number as an index number. Index numbers do not have to be used in sequence. Using the previous example, if you were to add a new element name to the file, you would not have to name it ElementName.5. You could use any number not already in use, such as ElementName.72.

Properties can appear in any order in the logfilter.properties file and do not have to appear in sequential index order. As an example, ElementName.72 could appear first in the file, followed by ElementName.3, followed by ElementName.1, followed by ElementName.12, and so on.

Mask Variables

PeopleSoft Integration Broker provides the following mask variables:

***deleted for security purposes***

Accessing the logfilter.properties File

The logfilter.properties file is located in the following path in the PeopleSoft home directory:

<PIA_HOME>\webserv\<DOMAIN>\applications\peoplesoft\PSIGW.war\WEB-INF⇒
\logfilter.properties

Masking Element Names Not Contained in Namespaces

Use the ElementName property to mask an element name that is not contained in a namespace.

To mask an element name that is not contained in a namespace, enter the element name to mask in logfilter.properties file in the following format:

ElementName.<index_number>=<Element_to_mask>

Be sure to specify a unique index number.

An example of a mask for an element name is shown in the following example.

ElementName.1=NodePassword

If you are using the default global mask, the element appears as follows in the gateway log files:

<NodePassword>*** deleted for security purposes ***</NodePassword>

Masking Element Names Contained Within Namespaces

Use the ElementName property and the Namespace property to mask elements contained within namespaces.

To mask an element name contain within a namespace, enter the element name to mask and namespace in which it is contained in the logfilter.properties file in the following format:

ElementName.<index_number>=<Element_to_mask>
Namespace.<index_number>=<Namespace_that_contains_element>

The ElementName and Namespace properties must use the same unique index number.

The following example shows how to enter a mask for the Username element contained in a namespace:

ElementName.9=Username
Namespace.9=http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-⇒
secext-1.0.xsd

If you are using the default global mask, the element appears as follows in the gateway log files:

<Username>*** deleted for security purposes ***</Username>

Masking Attributes of Element Names

Use the ElementName property and the AttributeName property to mask an attribute of an element.

To mask an attribute of an element, enter the element name and attribute name in the logfilter.properties file in the following format:

ElementName.<index_number>=<Element_name>
AttributeName.<index_number>=<Attribute_of_element_to_mask>

The ElementName and AttributeName properties must share the same unique index number.

The following example show the default mask for the password from the requesting node of a PeopleSoft 8.1x system:

#8.1x from node password
ElementName.6=from
AttributeName.6=password

An example request before masking is:

<?xml version="1.0"?>
<request version="1.0">
    <from node="PSFT_HR" password="my_password"/>
    <to node="QE_LOCAL"/>

When the mask is applied, the request looks as follows:

<?xml version="1.0"?>
<request version="1.0">
    <from node="PSFT_HR" password="*** Deleted for security purposes ***"/>
    <to node="QE_LOCAL"/>

Masking Child Element Names

Use and set the IsLeaf property equal to false to mask an element and all child elements. By default, child tags are not masked.

To mask an element and all child elements, enter the element name and set the IsLeaf property in the logfilter.properties file in the following format:

ElementName.<index_number>=<Element_name_(and_child_elements)_to_mask>
IsLeaf.<index_number>=false

The ElementName and IsLeaf properties must use the same unique index number.

As an example an address element could contain street number, street name, city, state, and zip code tags, as shown in the following example:

<address>
  <streetnumber>4433</streetnumber>
  <street>Oracle Lane</street>
  <city>Pleasanton</city>
  <state>California></state>
  <zipcode>94588</zipcode>
</address>

The following example shows how to mask the address element and all children of the element:

ElementName.11=address
IsLeaf.11=false

If you are using the default global mask, the element appears as follows in the gateway log files:

<address>***deleted for security purposes***</address>

However, if you wanted to mask just one of the child elements such as zip code, you would do so as shown in the following example:

ElementName.11=zipcode

The following example shows how the zip code tag would appear in the gateway logs if using the default global mask:

<address>
  <streetnumber>4433</streetnumber>
  <street>Oracle Lane</street>
  <city>Pleasanton</city>
  <state>California></state>
  <zipcode>***deleted for security purposes***</zipcode>
</address>

Changing the Global Mask Message

The value of the GlobalReplaceWith variable located in the logfilter.properties file determines the default global mask message. The default value is:

GlobalReplaceWith=***deleted for security purposes***

You can change this value as necessary to suit your business needs by setting the GlobalReplaceWith variable equal to another value. For example:

GlobalReplaceWith=####  PeopleSoft Confidential Information  ####

Creating Custom Mask Messages

You can override the global mask message on an element-by-element basis by setting the RepalceWith variable equal to a custom mask message.

The format is:

ElementName.<index.number>=<Element_to_mask>
ReplaceWith.<index_number>=<Custom_mask_message>

The index number you set must be the same unique index number used for the element, namespace, and/or attribute entry.

The following code snippet shows an example of overriding the default global mask message with a custom message:

#PSFT AuthToken
ElementName.7=AuthToken
ReplaceWith.7=-->Proprietary Information<--

When the gateway logs are generated the mask for this element will look as follows:

<AuthToken>-->Proprietary Information<--</AuthToken>

The following code example was shown earlier in this section. It has been modified to show how to override the default global mask message with a custom message:

ElementName.9=Username
Namespace.9=http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-⇒
secext-1.0.xsd
ReplaceWith.9=**  Data removed per company security policy **

When the gateway logs are generated the mask for this element will appear as follows:

<Username>**  Data removed per company security policy **</Username>

Disabling Gateway Log Masks

You can disable a mask for any element by commenting out the mask data in the logfilter.properties file.

For example, the following sample mask entry could appear in the logfilter.properties file:

#Sample Mask Entry
ElementName.44=NodeName
Namespace.44=http://my_namespace.xsd
ReplaceWith.44=--->Confidential/Proprietary Information<---

To disable the entry comment out all lines as shown in the following example:

#Sample Mask Entry
#ElementName.44=NodeName
#Namespace.44=http://my_namespace.xsd
#ReplaceWith.44=--->Confidential/Proprietary Information<---

Refreshing Integration Gateway Properties

If you modify integration gateway properties by accessing and directly modifying the integrationGateway.properties file located in the <PIA_HOME> directory, you must restart the web server for the changes to take effect.

If you modify integration gateway properties in the PeopleSoft Pure Internet Architecture, any changes you make take effect when you save the changes or click the OK button. This includes changes you make to the integrationGateway.properties file, but only if you access the file through the PeopleSoft Pure Internet Architecture using the Gateways Properties page.

Bypassing Integration Engines to Send Messages

You can use the PeopleCode built-in functions ConnectorRequest and ConnectorRequestURL to send synchronous requests directly to the integration gateway, without any message processing taking place on the integration broker engine, thereby eliminating the need for transactions.

Note. ConnectorRequest and ConnectorRequestURL are for use with synchronous requests only.

To use any of these methods, the integration gateway must be configured and running.

When you use either of these functions, errors and messages are written to the integration gateway logs.

See Also

Generating and Sending Messages

Using the ConnectorRequest Built-In Function

The ConnectorRequest function enables you to build a message object and perform a POST or GET using any target connector. With this function, you use the Message object to populate connector values.

Response messages are returned unstructured in the IB_GENERIC message. The IB_GENERIC message is delivered out-of-the-box.

The following example shows using the ConnectorRequest function to perform a GET to obtain a stock quote.

Local XmlDoc &Output;

Local Message &MSG1, &MSG2;

&MSG = CreateMessage(OPERATION.QE_FLIGHTPLAN);

&MSG.IBInfo.IBConnectorInfo.ConnectorName = "HTTPTARGET";
&MSG.IBInfo.IBConnectorInfo.ConnectorClassName = "HttpTargetConnector";

&nReturn = &MSG.IBinfo.IBConnectorInfo.AddConnectorProperties
    ("Method", "GET", %HttpProperty);
&nReturn = &MSG.IBinfo.IBConnectorInfo.AddConnectorProperties
    ("URL", "http://finance.yahoo.com/d/quotes.txt/?symbols
   =PSFT&format=l1c1d1t1", %HttpProperty);

&MSG2 = %IntBroker.ConnectorRequest(&MSG);

&Output = &MSG2.GetXmlDoc();  // Get the data out of the message

Using the ConnectorRequestURL Built-In Function

The ConnectorRequestURL function enables you to use HTTP or FTP to perform a GET using a query string.

Based on the format of the string you provide, the integration gateway uses the HTTP target connector or FTP target connector to perform the GET.

Response messages are returned in a string.

Using ConnectorRequestURL with HTTP

The following example shows using the ConnectorRequestURL function to perform a GET to obtain a stock quote using HTTP.

&Output = %IntBroker.ConnectorRequestURL("http://finance.yahoo.com/d/quotes.txt/
?symbols=PSFT&format=l1c1d1t1");

Using ConnectorRequestURL with FTP

The syntax of the FTP URL is:

ftp://<user>:<password>@<host>:<port>/<url-path>;type=<typecode>

The following example shows using the ConnectorRequestURL function to perform a GET to obtain a stock quote using FTP.

&Output = %IntBroker.ConnectorRequestURL("ftp://qedmo:qedmo@ftp.globalsoft.com:
200/tmp/hello.xml;type=a");