Configuring Nodes and Transactions

This chapter discusses how to:

• Configure nodes.

• Configure transactions.

Understanding Configuring Nodes and Transactions

When an integration engine receives a message, it searches the transaction definitions associated with that message definition to determine the valid target nodes for the message, then passes the message to the synchronous or asynchronous request processes. The handler directs the message to each valid node, using the gateway and target connector specified by the node definition. It could also direct the message to local Subscription or OnRequest PeopleCode. A transaction might also be modified by a defined relationship, which could involve a transformation.

Prerequisites

To configure a node and its associated transactions, at least one gateway with one connector must be defined.

Routing Types

When you configure a node or override transaction properties, you must also specify the routing type.

The routing type specifies how the integration engine should determine whether to send a message to the selected node.

This property is ignored for inbound transactions.

Explicit Routing

When you select explicit routing, the current node won’t be included as a target node unless you specify it directly in your sending PeopleCode. You can either:

• Specify the target node as a parameter of the message class Publish or SyncRequest methods.

• Specify the target node as a parameter of the PublishXMLDoc or SyncRequestXMLDoc built-in functions.

If you selected a node type of External, the routing type is Explicit by default.

Implicit Routing

When you select implicit routing, all nodes with this routing type are included as target nodes unless the sending PeopleCode references specific nodes. In that case, only the referenced nodes are targets. If you selected a node type of PIA, the routing type is Implicit by default.

Note. You can also include the selected node — or filter the list of included nodes to produce a single target node — using the OnRouteSend PeopleCode event associated with the message definition.

See Routing Events.

Configuring Nodes

This section discusses how to:

• Define node.

• Specify contact information.

• Define node properties.

• Specify node gateways and connectors.

• Rename or delete node definitions.

Understanding Configuring Nodes

To configure nodes you use the Node Definitions page in the Integration Setup component (PTIB_ADMIN). To access the Node Definitions page, select PeopleTools, Integration Broker, Integration Setup, Node Definitions.

Understanding Local and Remote Nodes

Each PeopleSoft Integration Broker database involved in an integration must contain a default local node definition for itself, and a remote node definition for each of the other nodes involved.

Local and remote nodes are concepts relative to the database in which the nodes are defined. If you’re signed on to database A which has node A defined, then node A is local. If you’re signed on to database B, node A is defined as remote.

For example, if the following definitions exist in the node A database:

• NODE_A (default local)

• NODE_B (remote)

The following definitions must exist in the node B database for it to integrate with node A:

• NODE_A (remote)

• NODE_B (default local)

Note. In practice, only portals use nodes designated simply as Local. The only local node definition used by Integration Broker is the one designated Default Local, which represents the database you're signed on to.

Creating Node Definitions

This section describes how add new nodes to the system or select existing nodes, and define node parameters.

Adding New Nodes

To define a new node, select PeopleTools, Integration Broker, Integration Setup, Node Definitions.

Note. The name you specify for a remote node must be the same as the name it specifies for itself.

To add a node:

1. Select PeopleTools, Integration Broker, Integration Setup, Node Definitions.

2. Click the Add a New Value tab.

3. In the Node Name field, enter a name for the node, keeping in mind that node names must begin with a character.

4. Click the Add button to define the node.

   The Node Definitions tab displays.

Selecting Existing Nodes

Select PeopleTools, Integration Broker, Integration Setup, Node Definitions. Click the Search button to select from a list of defined nodes. Click the node with which to work. The Node Definitions tab displays.

Defining Node Parameters

To define node parameters, use the Node Definitions tab in the Node Definitions component.

Description	Enter a descriptive name for the node.
Default Local Node	Indicates whether the current node represents the database to which you are assigned. PeopleSoft Integration Broker is delivered with one node predefined as the default local node. You can't change which node is the default local node, but you can use the Rename Node button to rename the default local node to more appropriately reflect your application or system. Note. After you rename the default local node, you must reboot the web server. See Renaming or Deleting Node Definitions.
Local Node	Indicates that the current node is either a portal node or the default local node. Note. You can't change this setting for the default local node.
Active Node	Select to make the current node definition active, so it can be used by PeopleSoft Integration Broker. Note. If you clear this check box to deactivate the node, transactions and relationships that use it are also deactivated. Activating the node won’t automatically reactivate the transactions and relationships; they must be individually reactivated. You can't deactivate the default local node. See Editing Transaction Details, Administering Relationships.
Non-Repudiation	Select to activate nonrepudiation for the current node. Note. You must also activate nonrepudiation in the definition of each message for which you want this feature. See Administering Messaging Servers for Asynchronous Messaging.
Segment Aware	Check the box to configure the node to handle message segments. See Working With Message Segments.
Node Type	Select from: PIA: Designates the node as a PeopleSoft database that uses PeopleSoft Integration Broker. This is the default for a new node. External: Designates the node as an entity that doesn’t use PeopleSoft Integration Broker. ICType: A portal-specific setting that PeopleSoft Integration Broker doesn’t use.
Routing Type	Specify how the integration engine should determine whether to send a message to the current node. After you create a node, the routing type for the node and the routing type for outbound transactions function independently. For example, if you create a node and choose a routing type of Explicit, and then create several outbound synchronous and outbound asynchronous transactions and save your work, the routing type for the transactions you created defaults to Explicit. However, if you later change the node routing type, the routing type does not automatically get changed for any of the existing outbound transactions. You must manually change the transaction routing type, if desired, on the Transactions Detail tab for the transaction. See Routing Types.
Authentication Option	Select from: Certificate: The current node uses a digital certificate to sign the messages it sends, and expects messages it receives to be signed by a complementary digital certificate. When a PeopleSoft Pure Internet Architecture node receives a message, PeopleSoft Integration Broker extracts the distinguished name from the certificate and validates it against the sending node's distinguished name retrieved from the default local node’s keystore. Messages sent by the default local node have the digital certificate automatically inserted by Integration Broker. An external node is expected to respond to certificates outwardly the same way as a PeopleSoft Pure Internet Architecture node. None: No authentication is required. This is the default value. Important! Single signon isn't compatible with this option. If you select None for the default local node, and implement single signon on the same system, all transactions will fail. You must select either Password or Certificate when implementing single signon. Password: Two new fields appear: Password and Confirm Password. Enter your password in the first edit box, and confirm it in the second edit box. With a PeopleSoft Pure Internet Architecture node, PeopleSoft Integration Broker expects messages both outbound to and inbound from the current node to include a password, which it validates against the password entered here. An external node is expected to respond to passwords outwardly the same way as a PeopleSoft Pure Internet Architecture node.
Password	Displays when the Authentication Option is Password. Enter the node password.
Confirm Password	Reenter the node password you entered in the Password field.
Hub Node	Select the name of a node that will serve as a “gatekeeper” for the current node. All transactions outbound from the default local node to the current node will be redirected to the selected hub node instead. You can select any existing PeopleSoft Pure Internet Architecture node for this purpose. You must define appropriate transactions and relationships at that node to route the message properly. Use this field to add hub capability for existing transactions that specify the current node as a target, without having to modify those transactions. Note. Not all node types are appropriate as hub nodes. Nodes of type ICType are portal-specific, and aren’t used by PeopleSoft Integration Broker. A node of type External typically isn’t an Integration Broker system, so it might not be usable as a hub node unless you’ve explicitly configured it to be compatible with Integration Broker. See Administering Relationships.
Master Node	This field is for information only. If the current node is used as a hub, you can indicate the target node with which it’s associated. If the current node represents a subordinate database, you can indicate the primary database.
Company ID	Enter the name of the company or organization associated with the current node.
Image Name	Select an image from the system database. Any application that uses images can use the selected image to represent the current node.
Code Set Group Name	Select the codeset group to which you want the current node to belong. Transform programs invoked by the default local node use this association to search for message data requiring translation. See Performing Data Translation.
Copy Node	The Copy Node button displays after you have saved the initial node definition. Click to define a new node with the same properties as the current node. The Default Local check box is cleared for all new nodes. All transactions associated with this node definition are copied as well, so the messaging interactions you've developed with one node can be duplicated for another node in a single step. Note. If you copy a local node, the new node will be local as well. You must clear the Local Node check box to use it with PeopleSoft Integration Broker.
Rename Node	The Rename Node button displays after you have saved the initial node definition. You can rename only the default local node. See Renaming or Deleting Node Definitions.

Specifying Contact Information

Select the Contacts tab to access the Node Definitions − Contacts page.

Each node represents a database or other software entity managed by one or more people. Use this page to record information about the people associated with the current node.

Defining Node Properties

Select the Properties tab to access the Node Definitions − Properties page.

This page provides a convenient place to store additional information about the current node that can be referenced by any other node. Properties created for all nodes are stored in a single table, PSNODEPROP.

Examples include a DUNS number or Tax Identification Number. These properties can be used to update messages with additional information. They can also serve to add additional categorization for custom processing; for example, add a Region property so nodes can be referenced by region for special processing.

Specifying Gateways and Connectors

Select the Connectors tab to access the Node Definitions − Connectors page.

Use this page to specify how the default local node should send messages to the current node.

At least one gateway with at least one target connector must be defined and configured. If the current node is remote, it can use the default local node’s gateway or any other installed gateway as its local gateway. If the current node has its own gateway installed, the default local node’s database must contain a definition for it, configured as a remote gateway.

Specifying a Gateway and Target Connector for the Current Node

To specify a gateway and connector for the current node:

1. Select the gateway ID for the gateway you want the current node to use.

   When the default local node sends a message to any other node, the message first goes to the default local node’s local gateway through its PeopleSoft listening connector, regardless of the gateway ID you select here.

   • If you specify a remote gateway ID, the local gateway uses its default remote gateway connector (specified in the integrationGateway.properties file) to route messages to the remote gateway through the remote gateway’s PeopleSoft listening connector. The remote gateway sends the messages directly to the current node, using the connector you specify in the next step.

     Note. The default remote gateway connector setting initially specifies the HTTP target connector, which is unlikely to change unless you develop a custom target connector.

   • If you specify the local gateway ID, the local gateway sends messages directly to the current node, using the connector you specify in the next step.

2. Select a connector ID from the list of connectors registered with the selected gateway.

   Specify the target connector appropriate to the communication method preferred by the current node. If the node is a PeopleSoft application with Integration Broker installed, select PSFTTARGET. If the node is a PeopleSoft 8.1x application, select PSFT81TARGET.

   The rows on the Properties and Data Type/Description tabs are automatically populated with the connector’s properties that are designated Required in the gateway definition. The fields on these tabs are the same as those on the Connector Properties page. If the connector has multiple instances of a required property defined, only the instance designated as Default appears.

   See Editing Connector Properties.

3. Click the Save button.

Note. You can override the gateway and connector selection for individual outbound transactions.

Working With Connector Properties

Properties that appear on this page are copies of the specified connector’s required properties.

Changes you make on this page have no effect on the originals. You can:

• Add an instance of a non-required property.

• Add a new instance of a required property.

• Modify the value or description of a property instance.

• Remove a property instance.

Information about appropriate modifications might come from PeopleSoft, from the connector’s developer, or from your own experience and requirements.

Important! Don’t remove a required property unless you replace it with another instance of the same property. Without all of its required properties, the connector is unlikely to work correctly.

You must encrypt any password connector property values. The Connector tab features access to the Password Encryption Utility that enables you to encrypt a password value and paste it into the appropriate field on the page. To access the utility, click the Password Encryption Utility arrow.

Accessing the Integration Gateway Properties File

The Connectors tab features a Gateway Setup Properties link you can use to access the integrationGateway.properties file directly from this tab.

Testing Connector Configurations

The Connectors tab features a Ping Node button you can use to test your configuration.

If the ping is successful, a window displays with a message indicating that the gateway is active and the PeopleTools version that you are running. If the ping is not successful, a window displays with a message indicating the gateway could not be found.

See Also

Editing Transaction Details

Encrypting Passwords

Editing Connector Properties

Renaming or Deleting Node Definitions

There are several situations in which you might need to rename or delete a node definition. When you do so, PeopleSoft Integration Broker automatically handles most of the dependencies involved — such as a relationship that refers to that node — by changing the reference to use the new name, or by deactivating the relationship if the node is deleted.

However, the live message data in Integration Broker Monitor remains unchanged. If that data still contains references to the node you want to modify, Integration Broker will prevent you from making the modification. You must remove all data from the live message tables before you can rename or delete the node definition.

You cannot delete a note that hosts a portal. As a result, the Delete Node button is hidden on a node definition if the node hosts a portal.

Note. If you upgraded your PeopleSoft application from a PeopleTools 8.1x release, the newly created default local node definition must be renamed, so you must first remove any remaining live message data if you didn’t do so before the upgrade.

Renaming or deleting a node requires the following actions:

1. Deactivate all the domains in your messaging system.

   1. In the PeopleSoft Pure Internet Architecture, select PeopleTools, Integration Broker, Monitor Integrations, Monitor Message, Domain Status.

   2. On the Domain Status page, select All Domains Inactive.

   3. Click Update to change the status of all domains to Inactive and all dispatchers to Cleanup.

   4. Click Force Reset to change the status of all dispatchers to Inactive.

2. Remove the data from the live message tables.

   You have several choices when removing data from the live message tables:

   • You can archive messages one at a time from the Message Details or Synchronous Details component.

   • You can archive messages with a batch process using the Archive Messages component.

   • You can purge message data using one of several Data Mover scripts delivered with PeopleSoft Integration Broker. You'll find them in PS_HOME\scripts:

     AppMsgPurgeLive.dms	Deletes the queue data from every live message table in the database.
     AppMsgPurgeAll.dms	Deletes the message data from every live message table and every archive message table in the database. This is the recommended procedure when upgrading from earlier versions of PeopleTools, because the archived data is largely incompatible with the new release.

3. Rename or delete the desired node definition.

4. Reboot the web server.

5. Reactivate the messaging domains.

   1. In the PeopleSoft Pure Internet Architecture, select PeopleTools, Integration Broker, Monitor Integrations, Monitor Message, Domain Status.

   2. On the Domain Status page, select All Domains Active.

   3. Click Update to change the status of all domains and dispatchers to Active.

See Also

Renaming or Deleting Node Definitions

Monitoring Asynchronous Message Details

Viewing Synchronous Message Details

Monitoring Messaging System Information

Purging Messaging Tables

Understanding Data Mover Scripts

Configuring Transactions

This section discusses how to:

• View available transactions.

• Define a transaction.

• Edit transaction details.

• Edit transaction message details.

• Edit transaction connector properties.

Understanding Transactions

A transaction is the basic unit of work in an integration. Each transaction is associated with a specific node. You use a transaction to designate:

• A message that the current node can send or receive.

• Whether the message is inbound or outbound.

• Whether the message is synchronously or asynchronously transmitted.

Thus there are four distinct transaction types:

• Outbound asynchronous (OutAsync).

• Outbound synchronous (OutSync).

• Inbound asynchronous (InAsync).

• Inbound synchronous (InSync).

Note. When you define a node or transaction, current refers to the definition you have open — for example, the current node. Selected refers to an item you’ve indicated other than the definition you have open — for example, the selected transaction.

See Transaction Types.

Transaction Definitions for Cross-Node Messaging

Each PeopleSoft Integration Broker node involved in an integration point must define a transaction for each node with which it communicates. For example, for an integration in which node A transmits message X to both node B and node C:

• In the node A database, the NODE_B definition must contain an outbound transaction that specifies request message MSG_X.

• In the node A database, the NODE_C definition must contain an outbound transaction that specifies request message MSG_X.

• In the node B database, the NODE_A definition must contain an inbound transaction that specifies request message MSG_X.

• In the node C database, the NODE_A definition must contain an inbound transaction that specifies request message MSG_X.

For this integration, transactions don’t need to be defined for the default local node in any database.

Note. For a basic integration, all transactions involved must be of the same transmission type — all synchronous or all asynchronous. However, you can mix transmission types by defining transaction modifiers.

Transaction Definitions for Local Messaging

Because a local integration involves only the default local node, it requires only a single transaction. For example, for an integration in which node A transmits message X to itself (a local transaction), the NODE_A default local node definition in the node A database must contain an outbound transaction that specifies request message MSG_X.

No other transaction is necessary. Because NODE_A is the default local node, the inbound transaction is implicit, and the integration engine automatically routes it appropriately.

See Also

Administering Relationships

Common Elements Used in This Section

Viewing Transactions

Select PeopleTools, Integration Broker, Setup Integrations, Node Definitions and select the Transactions tab to access the Node Definitions — Transactions page.

Edit	Click to access the Transaction Detail page and modify the properties of the transaction.
Add Transaction	Click to access the Node Transactions page and define a new transaction.
Copy All Transactions	Click to copy all of the current node's transactions to another node definition. The properties of each copied transaction are identical to the originals except for the node name, which changes to reflect the node definition to which you copied the transactions.

This page lists all the transactions associated with the current node, including the transaction type, the request message and version, and the effective date for each transaction.

Note. If you delete a transaction row, any transaction modifiers that use that transaction are also deleted.

Note. The transactions listed on this page always define interactions between the current node and the default local node (the database you’re signed on to). If the current node is the default local node, the transactions are local. The transaction direction is always with respect to the default local node — outbound is from the default local node, and inbound is to the default local node.

See Also

Defining Transactions

Editing Transaction Details

Managing Transaction Modifiers

Defining Transactions

Click Add Transaction on the Node Definitions — Transactions page.

Node Name	Select the name of a node defined in the current database. The name of the current node is already entered, but you can select a different node with which to associate this transaction. Note. If you select a different node, the selected node’s definition opens when you save the transaction.
Effective Date	Enter the date which the message is to become effective.
Transaction Type	Select from: Outbound Asynchronous (OutAsync): The default local node sends a request message to the selected node. Outbound Synchronous (OutSync): The default local node sends a request message to the selected node, requiring a response. Inbound Synchronous (InSync): The default local node receives a request message from the selected node, requiring a response. Note. Inbound transactions aren’t supported for the default local node definition.
Request Message	Select the message to be sent or received with this transaction. Note. The PeopleCode associated with the message must support the selected transaction type.
Request Message Version	Select the version of the request message to be sent or received with this transaction.
Add	Click to confirm the parameters you entered for the new transaction. The Transaction Detail page appears.

Note. To edit an existing transaction definition, select the Find an Existing Value tab and search for a transaction based on any of its key parameters. If you select a transaction associated with a different node than the current one, the selected node’s definition opens when you save your changes.

No Multiple Synchronous Targets

In practice, only one target node at a time can receive a message sent with a synchronous transaction. Even though you can define the same outbound synchronous transaction for multiple nodes, you must make sure the transaction resolves to a single target node in one of the following ways:

• Specify the target node in your sending PeopleCode as a parameter of the Message class SyncRequest method. This forces Integration Broker to consider only the transactions defined for that node.

• Specify the target node in your sending PeopleCode as a parameter of the SyncRequestXMLDoc built-in function. This forces Integration Broker to consider only the transactions defined for that node.

• Filter the available target nodes in your OnRouteSend PeopleCode.

If you specify a target node in your sending PeopleCode, no other nodes are considered valid targets, including those with a routing type of Implicit.

See Also

Receiving and Processing Messages

Message Class

XmlDoc Class

Editing Transaction Details

To access the Transaction Detail page, click Edit on the Node Definitions − Transactions page or click Add on the Node Transactions − Add a New Value page.

Note. The transaction’s basic parameters can be altered only by defining a new transaction with different values.

Activating Transactions

When a transaction is active, PeopleSoft Integration Broker can immediately use it to route messages to or from its associated node. However, messaging also depends on the status of the messages and the node — their definitions in the local database must all be set to active status. The following table outlines how this dependency is enforced.

See Also

Routing Types

Editing Transaction Connector Properties

Editing Transaction Message Details

Select the Messages tab on the Transaction Detail page to access the Messages page.

Note. The Synchronous Logging drop-down list and the Response Message group box appear only if you defined the transaction as synchronous.

See Also

Using Integration Broker Monitor

Editing Transaction Connector Properties

Select the Connectors tab on the Transaction Detail page to access the Connectors page.

Note. This page appears only if you specified a connector override on the Transaction Detail page and saved your changes.

Because the selected gateway and target connector override those specified for the selected node, you can also override the connector’s properties. These fields are identical to the Node Definitions — Connectors page.

If any of the new connector properties require a password, click the Password Encryption Utility arrow to display the dialog box and encrypt the password.

See Also

Encrypting Passwords