Managing Integration Gateways

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

Click to jump to top of pageClick to jump to parent topicUnderstanding Integration Gateway Configuration

This section discusses:

Click to jump to top of pageClick to jump to parent topicLocal 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.4 Integration Broker.

Click to jump to top of pageClick to jump to parent topicTypes of Integration Gateway Configuration

An integration gateway requires several types of configuration:

Security configuration

You implement PeopleSoft Integration Broker security in several ways, including installing digital certificates on the gateway's web server and on the gateway itself to support Secure Sockets Layer (SSL) encryption. To implement encryption, you should complete the certificate installation before continuing with the gateway configuration in this chapter.

Once the gateway's digital certificates are installed, you must enter several configuration parameters in the Integration Gateway Certificates Section of the integrationGateway.properties file. The parameters you must set are the certificate alias name, the certificate alias password, the path to the keystore, and the keystore password.

See Setting Up SSL Encryption.

General configuration

This includes settings for the gateway version, class location, general communication parameters, node connection parameters, message and error logging, and gateway type and location. Most of these settings are entries in the integrationGateway.properties file, but you set a few of them in the Gateways component.

Connector-specific configuration

The number of configuration settings and where they're applied depend on the connector. You configure most of the target connectors delivered with PeopleSoft Integration Broker by using the Gateways component, but some require settings in the integrationGateway.properties file. A few require settings in both environments.

Note. You can override some target connector properties for an individual node.

Click to jump to top of pageClick to jump to parent topicThe Gateways Component

Once the gateway has been installed, you use the Gateways component 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 Administering Integration Gateways.

Click to jump to top of pageClick to jump to parent topicMinimum Integration Gateway Setup Requirements

The minimum setup requirement to run an integration gateway are:

  1. Specify the gateway URL.

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

You can perform these tasks using the Integration Broker Quick Configuration page.

See Also

Using the Integration Broker Quick Configuration Page

Click to jump to top of pageClick to jump to parent topicAdministering Integration Gateways

This section discusses how to:

Click to jump to top of pageClick to jump to parent topicDefining Integration Gateways

Use the Gateway page 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. To access the page, select PeopleTools, Integration Broker, Configuration, Gateways.

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 define and configure a gateway:

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

    The Gateways search page appears. Do one of the following:

  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. You need to enter a port number for a machine only if the machine is listening on a port other than port 80, the HTTP default.

    Note. The URL is case-sensitive.

    The gateway uses the PeopleSoft listening connector to receive messages 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

Click to jump to top of pageClick to jump to parent topicPinging Integration Gateways

You can 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. 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.

Click to jump to top of pageClick to jump to parent topicRegistering Installed 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 registered and the grid is empty. You can register target connectors automatically by introspection or manually by entering information in the grid.

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

Registering 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 register 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.

Click the Load Gateway Connectors button on the Gateways page 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.

Registering Connectors Manually

To register 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 register a new connector:

  1. Add a new row in the Connectors grid of the Gateways page.

  2. Enter the ID for the new connector.

  3. Enter the connector class name.

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

See Also

Using the Delivered Listening Connectors and Target Connectors

Using the Integration Broker Connector SDK

Click to jump to top of pageClick to jump to parent topicRefreshing Integration Gateway Properties

When the gateway server boots, it reads and applies the properties in the integrationGateway.properties configuration file. Changes that you make to the file while the server is running have no immediate effect.

If you make changes to the integrationGateway.properties file while the server is running, you can click the Apply button on the Gateways Properties page. PeopleSoft Integration Broker reapplies the configuration settings—including the changes—without rebooting.

Information about how to access the Gateways Properties page is discussed earlier in this chapter.

See Accessing the integrationGateway.properties File.

Click to jump to top of pageClick to jump to parent topicEditing 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 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 messages 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.

To add a new property instance:

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

    Add a new row on the Connector Properties page.

  2. Select the integration gateway with which to work. The Gateways page displays.

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

  4. Select a Property ID.

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

  5. Select a Property Name.

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

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

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

  8. (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.

  9. Save the properties.

  10. Click OK.

    The Gateways page appears.

Click to jump to top of pageClick to jump to parent topicAccessing Gateway Setup Properties

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

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 userGatewayProfile.xml file located in <PS_HOME>\webserv\<DOMAIN>\applications\peoplesoft\PSIGW\WEB-INF. The password you enter in the userGatewayProfile.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.

Click to jump to top of pageClick to jump to parent topicSetting BEA Jolt Connection Properties

The integration gateway communicates with PeopleSoft application server nodes using BEA jolt connections.

Click to jump to top of pageClick to jump to parent topicUnderstanding BEA Jolt Connection Properties

This section provides an overview of BEA jolt connection properties

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:

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

Click to jump to top of pageClick to jump to parent topicUnderstanding Setting BEA Jolt Connection Properties

You must set properties for each PeopleSoft node with which the integration gateway is to communicate. You can set these properties:

This section discusses setting BEA 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 provides grids for defining BEA 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.

Click to jump to top of pageClick to jump to parent topicSetting BEA Jolt Connection String Properties Using the PeopleSoft Node Configuration Page

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

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 BEA Jolt string connection properties for unknown nodes is optional.

Web Server URL

Enter the machine name and BEA jolt port number of the default application server to use if no valid target node can be determined.

Note. To determine the Jolt port of the application server, check the JOLTListener section in the psappsrv.cfg file. The file is located in <PS_HOME>\appserv\<DOMAIN_NAME>.

Message Node Name

Enter name of the PeopleSoft node with which the integration gateway is to communicate.

User ID

Enter the user ID that you defined when you created the application server domain.

Password

Enter the UserPswd that you defined when you created the application server domain.

PeopleSoft Integration Broker will automatically encrypt this password entry.

Tools Release

Enter PeopleTools version number installed on the application server.

Limit the number you enter to two decimal places. For example, 8.46.

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

Using the integrationGateway.properties File

Configuring Security and General Properties

Click to jump to top of pageClick to jump to parent topicUsing 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

Click to jump to top of pageClick to jump to parent topicAccessing 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 <PS_HOME> directory.

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 <PS_HOME> Directory

The integrationGateway.properties file is located in the following path in the PeopleSoft home directory: <PS_HOME>\webserv\<DOMAIN>\applications\peoplesoft\PSIGW\WEB-INF\integrationGateway.properties

See Also

Encrypting Passwords

Click to jump to top of pageClick to jump to parent topicEncrypting 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.

Click to jump to top of pageClick to jump to parent topicEncrypting 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.

Click to jump to top of pageClick to jump to parent topicEncrypting Passwords Using the PSCipher Java Utility

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

To encrypt a password:

  1. Launch the PSCipher.bat file in the <PS_HOME>\webserv\peoplesoft 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.

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

Click to jump to top of pageClick to jump to parent topicConfiguring Security and General Properties

This section discusses how to:

Click to jump to top of pageClick to jump to parent topicSetting Security Properties

You can implement several types of messaging security with PeopleSoft Integration Broker. One type is SSL 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.

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

Property

Description

ig.certificateAlias

Enter the name that you provided to identify the encryption key pair that you generated for the keystore on which the gateway's public key certificate is based.

ig.certificatePasswd

Enter the password that you provided for the encryption key pair that you generated for the keystore. The certificate password must be encrypted.

See Encrypting Passwords.

secureFileKeystorePath

Enter the full path and file name of the gateway keystore file, which is located in the web server directory structure. The path is <PS_HOME>\webserv\<DOMAIN>\keystore

secureFileKeystorePasswd

Enter the keystore password, which is typically the default, password.

This password should not be encrypted.

See Also

Setting Up Secure Messaging Environments

Click to jump to top of pageClick to jump to parent topicSpecifying the Gateway Version

This required property indicates the version of PeopleTools from which the integration gateway was installed. You can find version in the section of the integrationGateway.properties file 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.46.

Click to jump to top of pageClick to jump to parent topicSpecifying the Gateway Class Location

This required property indicates where the integration gateway classes are installed. You can find it in the section of the integrationGateway.properties file labeled Integration Gateway CLASS INSTALLATION Section. Specify the location as follows: 

ig.installdir=directory_path

where directory_path is the location of the gateway Java classes in the web server directory structure. This is typically <PS_HOME>\webserv\<DOMAIN>\applications\peoplesoft\PSIGW\WEB-INF\classes.

Note. If you deploy the PeopleSoft Pure Internet Architecture installation through an Enterprise Archive (EAR) file on a different machine under a different directory, the ig.installdir value you specify here will be invalid. The program will still be functional because in instances like this, the path is built based on the class file location.

Click to jump to top of pageClick to jump to parent topicSetting General Connection Properties

This section discusses:

The general connection properties include default connector properties and BEA 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

Property

Description

ig.connector.prefix

Identifies the universal resource indicator (URI) prefix added to any target connector name. This property instantiates the connector classes on the system. The default connector prefix is: 

com.peoplesoft.pt.integrationgateway.targetconnector.

Note. Do not change this value.

ig.connector.defaultremoteconnector 

Identifies the connector that the gateway uses to send messages to a remote gateway. The default value of this property is:

HttpTargetConnector

Note. Do not change this value.

ig.connector.ibtargetconnector 

Identifies the connector that the gateway uses by default to send messages to a PeopleSoft Integration Broker application server node. The gateway uses this connector to link to the integration engine running on the node's application server. When the content of a message reaching the gateway doesn't specify a connector (this is often the case with third-party senders), the gateway automatically uses the connector specified by this property. The default value is: 

PeopleSoftTargetConnector

Note. Do not change this value.

Default BEA 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:

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

See Setting General Connection Properties.

BEA Jolt Connect String Properties for Known Nodes

You must set four BEA 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 BEA 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:

Property

Description

ig.isc.$NODENAME.serverURL 

Enter the URL of the application server node, consisting of the machine name and BEA Jolt port; for example:

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

Note. You can determine the Jolt port of the application server by examining the JOLT Listener section in the psappsrv.cfg file located in <PS_HOME>\appserv\<DOMAIN_NAME>.

ig.isc.$NODENAME.userid

Enter the UserID that you defined when you created the application server domain; for example:

ig.isc.MYNODE.userid=TOPDOG

ig.isc.$NODENAME.password

Enter UserPswd that you defined when you created the application server domain. This password must be encrypted; for example:

ig.isc.MYNODE.password=VOBN5KcQZMg

See Encrypting Passwords.

ig.isc.$NODENAME.toolsRel

Enter the version number of PeopleTools installed on the application server node to two decimal places; for example:

ig.isc.MYNODE.toolsrel=8.46

Click to jump to top of pageClick to jump to parent topicSetting Logging Properties

This section discusses:

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

Property

Description

ig.log.level 

Enter a numeric value to specify the desired level of gateway logging and exception handling.

Values are:

  • −100: Suppresses message logging. The property is preset to this value.

  • −1: Logs language exceptions only.

  • 1: Logs language and standard exceptions.

  • 2: Logs all errors and warnings.

  • 3: Logs errors, warnings, and important information. This is the default if you don't specify a value for this property.

  • 4: Log errors, warnings, and important and standard information.

  • 5: Logs errors, warnings, and important, standard, and low-importance information.

Note. Set the log level to 5 to capture the entire contents of incoming HTTP requests, including HTTP headers, in the integration gateway message log file.

ig.log.backgroundImage

Specify the background JPEG image to use when displaying error and message log documents. The default location and image name PSbackground.jpg.

By default it is located in <PS_HOME>\webserv\<DOMAIN>\applications\peoplesoft\PSIGW.

Images in the default location don't require a path, but you can specify a full path to an image file in any other location.

Message Logging Properties

Property

Description

ig.messageLog.filename

Enter the full path and file name of an HTML file to use as a message log. This property is preset to <PS_HOME>\webserv\<DOMAIN>\applications\peoplesoft
\PSIGW\msgLog.html.

ig.messageLog.maxSize

Specify the maximum size of the message log, in kilobytes (KB). This property is preset to 10000, or 10 megabytes (MB). When this limit is reached, the log is archived, and a timestamp is appended to the file name.

ig.messageLog.maxNbBackupFiles

Specify the number of archived files to keep on disk. Use the value 0 to retain all backed up files. This property is preset to 5.

Error Logging Properties

Property

Description

ig.errorLog.filename

Enter the full path and file name of an HTML file to use as an error log. This property is preset to <PS_HOME>\webserv\<DOMAIN>\applications\peoplesoft
\PSIGW\errorLog.html.

ig.errorLog.maxSize

Specify the maximum size of the error log in kilobytes (KB). This property is preset to 1000, or 1 MB. When this limit is reached, the log is archived, and a timestamp is appended to the file name.

ig.errorLog.maxNbBackupFiles

Specify the number of archived error files to keep on disk. Use the value 0 to retain all backed up files. This property is preset to 5.

See Also

Managing Error Handling, Logging, Tracing, and Debugging

Click to jump to top of pageClick to jump to parent topicSetting 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.validateDoc property equal to True, request and response messages are validated against any associated DTD.

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

When the property is set equal to False (default), no validation takes place–even if a DTD reference is supplied.

Click to jump to top of pageClick to jump to parent topicApplying Message Transformations at the Integration Gateway

Typically, you apply filtering, transformation, and data translation to a message at the node level on the application server by using a transaction modifier to invoke an Application Engine transform program. However, on systems with high transaction volumes, Application Engine transformations can constrict message throughput. To improve performance, you can apply XSLT transformation programs at an integration gateway.

Note. While you may apply transformations at the integration gateway level, PeopleSoft strongly recommends that you apply them at the application server level due to a more robust infrastructure to support them.

See http://www.apache.com

See Also

Applying Filtering, Transformation and Translation

Click to jump to top of pageClick to jump to parent topicUnderstanding Applying Message Transformations at the Integration Gateway

Only XSLT transformations can be applied at the gateway. Message filtering, data translation, and PeopleCode transformations must still be applied at the node using an Application Engine transform program, and can be applied in addition to gateway-based transformations.

You can apply XSLT transformations at any gateway that handles the message you want to transform.

When a gateway with transformation enabled processes an IBRequest, it examines the transformation properties in the integrationGateway.properties file to determine if they specify a transformation for the same message with the same source and target nodes as the IBRequest. If these values match, the gateway compiles the specified XSLT transformation program and applies it to the message, then sends the transformed message to the target node.

Note. The IBRequest can specify only a RequestingNode or only a DestinationNode, but it must specify at least one of these values—ig.DefaultServer.LocalNode supplies the other one.

With synchronous transactions, the gateway applies transformations only to the request message, not to the response message. If the original message is compressed and base64 encoded, the gateway decompresses and decodes it before applying the transformation, then compresses and encodes it again before sending.

Note. The integration gateway retains all compiled XSLT transformation programs in a memory cache to improve performance during subsequent transformations. If you edit the code of a transformation program that’s been used before, you must purge the compiled programs from the cache so the new version will be recompiled. To do this, click the Refresh button on the gateway definition.

Click to jump to top of pageClick to jump to parent topicDeveloping and Implementing Gateway-Based Transformation Programs

Developing and implementing gateway-based transform programs requires the following activities:

  1. Determine if the message you want to transform qualifies for gateway-based transformation:

  2. Develop the XSLT transformation program.

    See Applying Transformations.

    You can develop, test and debug the program within Application Engine, but you must save the program code as an external text file. Place the file in any location that can be accessed from the integration gateway machine, for example: 

    C:\XSLProgs\MyTransform.xsl

  3. Configure the appropriate gateway property settings in the integrationGateway.properties file to enable the transformation.

    See Setting Integration Gateway Properties for Gateway-Based Transformations.

  4. Refresh the gateway properties.

Click to jump to top of pageClick to jump to parent topicSetting Integration Gateway Properties for Gateway-Based Transformations

To apply gateway-based transformations, set the following properties in the integrationGateway.properties file.

For each message you want to transform, you must create a set of property entries using the same number, which associate a given transformation program with that message. However, you can specify the same transformation program for multiple messages.

When entering these settings, each transformation must be numbered for identification, using the convention ig.transform1, ig.transform2, ig.transform3, and so on.

Property

Description

ig.isGatewayTransformationEnabled

Specify whether transformation is enabled for this gateway. Valid values are:

  • TRUE. Transformation is enabled.

  • FALSE. Transformation is disabled — the integration gateway will ignore the other transformation properties. This is the default value.

ig.DefaultServer.LocalNode

Enter the name of the node definition that will be used as the source or destination node for a given transformation if either of those values isn’t identified; for example you must specify 

ig.DefaultServer.LocalNode=DEF_NODE

All transformations require that you specify both a source node and a destination node. This property applies if either the ig.transformN.SourceNode property or the ig.transformN.DestinationNode property is empty or invalid, or if the IBRequest doesn’t specify either RequestingNode or DestinationNode.

ig.transforms

Specify the number of transformations configured in the integrationGateway.properties file; for example:

ig.transforms=7

ig.transformN.XSL

Enter the full path and filename of transformation program N.

Your path specification must use either double back slashes or single forward slashes as separators; for example

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

ig.transformN.MessageName

Enter the name of the message to be transformed by transformation program N; for example: 

ig.transform4.MessageName=MY_MSG_A

ig.transformN.SourceNode

Enter the name of the source node from which the original message is being sent, or enter the value ANY; for example: 

ig.transform4.SourceNode=NODE_Aig.transform4.SourceNode=ANY

If this value is ANY, the value of the ig.DefaultServer.LocalNode property will be used instead.

ig.transformN.DestinationNode

Enter the name of the target node to which the transformed message is being sent, or enter the value ANY; for example:

ig.transform4.DestinationNode=NODE_Big.transform4.
DestinationNode=ANY

If this value is ANY, the value of the ig.DefaultServer.LocalNode property will be used instead.

ig.transformN.DestinationMessageName

(Optional.) Enter the name that the target node uses for the transformed version of the message, if it’s different from the original message name; for example: 

ig.transform4.DestinationMessageName=MY_MSG_B

This enables the gateway to rename the message before sending it, so the target node will recognize and accept it.

Click to jump to top of pageClick to jump to parent topicUnderstanding Logged Errors

If an error occurs when you refresh the gateway properties or during a transformation, it’s entered in the gateway’s error log file.

Integration Gateway Refresh Errors

After you specify integration gateway properties and refresh the gateway, errors can be generated for the following reasons:

Runtime Transformation Errors

Errors are generated for the following reasons when the gateway attempts to apply a transformation:

Click to jump to top of pageClick to jump to parent topicBypassing 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

Click to jump to top of pageClick to jump to parent topicUsing 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(Message.QE_FLIGHTPLAN_UNSTRUCT);

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

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

&MSG2 = ConnectorRequest(&MSG);

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

Click to jump to top of pageClick to jump to parent topicUsing 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 = 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 = ConnectorRequestURL("ftp://qedmo:[email protected]:
200/tmp/hello.xml;type=a");