Managing Integration Gateways

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

• Administer integration gateways.

• Use the integrationGateway.properties file.

• Encrypt passwords.

• Configure security and general properties.

• Configure integration gateways for load balancing.

• Apply message transformations at the integration gateway.

• Bypass integration engines to send messages.

Understanding Integration Gateway Configuration

This section discusses:

• Local gateway compatibility.

• Types of integration gateway configuration.

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

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.

Pages Used to Administer Integration Gateways

Defining Integration Gateways

Use the Gateway page in the Gateways component 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:

   • 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

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

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.

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.

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

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

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

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.

Accessing Gateway Setup Properties

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

Page Used to Access Integration Gateway Properties

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

Setting BEA Jolt Connection Properties

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

Understanding BEA Jolt Connection 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.

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

Page Used to Set BEA Jolt Connection Properties

Setting BEA Jolt Connection String Properties

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.

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

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

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

   • On a Windows NT or Windows 2000 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 security properties.

• Specify the gateway version.

• Specify the gateway class location.

• Set general connection properties.

• Set logging properties.

• Set DTD validation properties.

• Set BEA Jolt session pooling parameters.

Understanding Integration Gateway Properties and OAS Clustering

If using OAS web server and implementing clustering, you must specify the path to the cluster component for the following integration gateway properties:

• ig.messageLog.filename

• ig.errorLog.filename

• secureFileKeystorePath

For example:

ig.messageLog.filename=<OAS_HOME>/j2ee/<component_name>/applications/<app_name>
/PSIGW/msgLog.html

A red paper posted on Customer Connection titled Clustering and High Availability for Enterprise PeopleTools 8.4x provides additional information. See chapter 3, “Configuring an Oracle Application Server Cluster with PeopleTools 8.47”

See http://www.peoplesoft.com/media/cupa/pdf/red_paper/clustering__8_4.pdf

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

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.49 integration gateway to communicate with a PeopleTools 8.49 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.49 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.49.

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

Setting General Connection Properties

This section discusses:

• Default connector properties.

• Node-specific BEA Jolt connect string properties.

• Default BEA Jolt connect string properties.

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

com.peoplesoft.pt.integrationgateway.
targetconnector.

HttpTargetConnector

PeopleSoftTargetConnector

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:

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

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:

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

ig.isc.MYNODE.userid=TOPDOG

ig.isc.MYNODE.password=VOBN5KcQZMg

ig.isc.MYNODE.toolsrel=8.49

Setting Logging Properties

This section discusses:

• General logging properties.

• Message logging properties.

• Error logging properties.

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

Managing Error Handling, Logging, Tracing, and Debugging

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

Applying 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

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

Developing 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:

   • The message content must be XML-DOM compliant.

   • The message must not have nonrepudiation activated.

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.

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

ig.DefaultServer.LocalNode=DEF_NODE

ig.transforms=7

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

ig.transform4.MessageName=MY_MSG_A

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

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

ig.transform4.DestinationMessageName=MY_MSG_B

Understanding 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:

• No value is specified for ig.transformN.XSL.

• No value is specified for ig.transformN.MessageName.

• No value is specified for both ig.DefaultServer.LocalNode and ig.transformN.SourceNode.

• No value is specified for both ig.DefaultServer.LocalNode and ig.transformN.DestinationNode.

• The gateway is in the process of loading, compiling or caching a transformation program.

Runtime Transformation Errors

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

• Nonrepudiation is enabled for the message.

• The integration gateway is unable to transform the message.

• The integration gateway is unable to decompress and decode the message.

• The integration gateway is unable to compress and encode the message.

• The IBRequest does not specify a RequestingNode and no value is specified for ig.DefaultServer.LocalNode.

• The IBRequest does not specify a DestinationNode and no value is specified for ig.DefaultServer.LocalNode.

• The IBRequest specifies neither a RequestingNode nor a DestinationNode.

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:[email protected]:
200/tmp/hello.xml;type=a");