Defining Message Channels and Messages

This chapter discusses how to:

Define a message channel.
Configure a message channel.
Apply channel partitioning.
Define a message.
Define message versions.
Use records in a message definition.
Configure message properties.

Understanding Messages

Message definitions are the heart of PeopleSoft Integration Broker. They are templates for the data that the application sends or receives. You create message definitions in PeopleSoft Application Designer. There are two types of messages:

Rowset-based messages.

For hierarchical data based on PeopleSoft records, you create a message definition by assembling records, organizing them into a hierarchy, and selecting fields from those records to include in the message. The result is a rowset that doesn’t need to match an existing rowset structure in the application. Use the PeopleCode Rowset and Message classes to generate, send, receive, and process these messages.
Non-rowset-based messages.

These messages can have virtually any structure and content. You create a message definition, but you do not insert any records. The message definition serves as a placeholder for the actual message. Use the PeopleCode XmlDoc and Message classes to generate, send, receive and process these messages. If you’re handling Simple Object Access Protocol (SOAP) compliant data, you can also use the SoapDoc class to generate and process these messages.

For asynchronous integrations, define a single message. For synchronous integrations, define two messages: one for the request and one for the response.

See Also

Sending and Receiving Messages

Understanding Message Channels

Channels are logical groupings of messages. Each message must belong to exactly one message channel. Channels are used to:

Establish message processing sequence.
Increase throughput by using unordered processing.
Maintain messaging security.
Maintain messages with common configuration properties.
Define processing attributes for timeout parameters, error thresholds, and delivery type.

You create channel definitions in PeopleSoft Application Designer. You must define a channel before you define the messages that are assigned to it.

Defining Message Channels

In PeopleSoft Application Designer, select File, New, Message Channel.

A new channel definition appears. It consists of two views, showing assigned messages on the left and partitioning fields on the right. In a new channel definition, both views are blank. You must define messages in PeopleSoft Application Designer before you can assign them to the channel or partition the channel.

The following graphic shows a message channel that contains one message.

You must save the message channel before you can assign messages to it.

Applying Channel Partitioning

Granting Security Access to Message Channels

Configuring Message Channels

To configure a message channel, you use the Use tab in the Message Channel Properties dialog box. To access the Message Channel Properties dialog box, from an open message channel definition, select File, Definition Properties.

Message Channel Status

The options are:

Run: Messages assigned to this channel are received and processed normally.

Pause: Messages are received but not processed until the status is reset to Run.

Note. Message channels can also be paused and restarted with Integration Broker Monitor.

See Monitoring Channel Status.

Archive Messages?

Select to archive instances of messages that assigned to the channel. If you clear this check box, the messaging archive process purges the queue entries that have been processed.

This check box also controls whether the Archive or Delete action is available in the Message Details component of the Integration Broker Monitor.

See Monitoring Asynchronous Message Details.

Unordered?

By default, inbound messages assigned to this channel are processed one at a time in the order that they are sent. Consequently, the sending node can engage in a series of transactions that modify a specific record, and the changes are applied by the receiving node in the correct order. This can be inefficient when sequence doesn’t matter.

Select this check box to force the channel to handle all of its messages in parallel (unordered), which does not guarantee a particular processing sequence. This disables the channel’s partitioning fields.

Clear this check box if you want all of the channel’s messages processed sequentially or if you want to use the partitioning fields.

See Applying Channel Partitioning.

Sending Messages in Order

You can’t specify a particular message order as part of the channel definition, even when you clear the Unordered check box and apply partitioning. The channel always processes messages in the order sent. Therefore, be sure to send messages in the proper order.

For example, you can’t specify in the channel definition that a message named PO_CREATE is processed before a message named PO_UPDATE. If you send PO_UPDATE before PO_CREATE, the recipient processes PO_UPDATE first.

Applying Channel Partitioning

This section provides an overview of channel partitioning and discusses how to select partitioning fields.

Understanding Channel Partitioning

By default, all inbound messages assigned to a given message channel are processed one at a time, in the order they are sent. Consequently, the sending node can engage in a series of transactions that modify a specific record, and the changes are applied by the receiving node in the correct order. This can be inefficient if the sequence does not matter or if the sequence is relevant only within groups of messages with the same key values. One solution to this inefficiency is partitioning.

Note. Partitioning applies only to asynchronous messaging.

To maximize messaging efficiency and throughput, you want the system to simultaneously process as many messages as possible. Because message channels enforce message sequence, ideally you have a separate message channel for each group of messages that must be processed in order. You can achieve this goal by designating specific fields that are common to the messages assigned to a channel. These fields partition (divide) the channel into subchannels. PeopleSoft Integration Broker creates these subchannels at runtime.

Each subchannel processes only the messages for which the designated common fields have an identical combination of values. The messages within each subchannel are processed in the order that they are sent, so they remain in sequence. Each subchannel works in parallel with the other subchannels—all subchannels simultaneously process their own associated messages.

You implement partitioning by designating the partitioning fields in the message channel definition; no other steps are required.

Note. The more partitioning fields you designate, the more subchannels are generated. If you designate a combination of fields that are unique for each message, all messages are processed simultaneously—in their own subchannels—without regard to sending order. This is the equivalent of selecting the Unordered check box in the message channel properties.

Selecting Partitioning Fields

You can partition a message channel using any combination of:

Database record fields.
Message header fields.
Message XML fields.

Note. Fields of types image and long character aren’t available for partitioning. In addition, when partitioning nonrowset-based or inbound messages, tags cannot be mixed case.

Database Record Fields

Database record fields are the data fields in a PeopleSoft rowset-compatible message. Typically, the more messages you assign to the channel, the fewer fields they have in common.

The database record fields common to all messages in the channel appear in the channel’s partitioning field list. If only one message is assigned to the channel, all of its fields appear on the partitioning list.

To designate a field as a partitioning key, select the check box next to its name.

Message Header Fields

The message header fields are system-maintained fields common to all messages, regardless of format. If a message channel includes any non-rowset-compatible messages, the message header fields are the only ones that PeopleSoft Integration Broker recognizes as common to every message. You can view them as part of the message XML in Integration Broker Monitor. Some of them are also accessible using equivalent PeopleCode Message class properties, as indicated later in this chapter. The message header fields are:

MSGNAME: This field contains the name of the message definition in PeopleSoft Application Designer.

You can access this field with the Message class Name property, which is read-only.
MSGNAMEDETAIL: This field has no automatically defined value—you can assign any value that serves your purposes.

You can access this field with the Message class MessageDetail property, which is read-write.
PUBLISHER:This field contains the user ID in effect when the message is published—that is, the ID of the user who is signed on to the publishing database.
PUBPROC: This field refers to the PeopleSoft process that publishes the message.

It's generated when the message is published, and it can be the name of a component, an Application Engine program, or an iScript program.

These header fields are always available in the channel’s partitioning field list. To designate a field as a partitioning key, select the check box next to its name.

Message XML Fields

The message XML fields comprise all the fields that exist anywhere in a message, including PeopleSoft common application message attributes (PSCAMA) record fields. Such fields may not be visible in the channel’s partitioning field list, but they are valid for partitioning.

To designate a message XML field as a partitioning key:

Open the message channel definition that you want to partition.
Right-click anywhere on the partitioning field list, and select Add Partition Field.
Enter the tag name of the XML field and click OK.

The field should exist in all of the channel’s assigned messages exactly as named.

Note. When using PublishXmlDoc, defined field tags in messages cannot be mixed case.

At runtime, the integration engine searches each message for the first instance of that field tag and uses the value associated with it for partitioning. Therefore, if you have common fields in the PSCAMA record that are specific to a batch publish set, you can use those fields.

Granting Security Access to Message Channels

Users can view messages only in channels to which they have read access. All edit actions require write access.

In addition, in Integration Broker Monitor, users can view only those transactions that contain messages in channels to which they have access.

To grant security access to message channels, use permission lists in the Security component by navigating to PeopleTools, Security, Permissions & Roles, Permission Lists.

See Setting Up Permission Lists.

Deleting Message Channels During Upgrade

To delete a channel definition in an application upgrade project, first ensure that there are no live instances of messages assigned to that channel. Archive or delete any such messages in both the source and the target database. Otherwise, an error message appears during the copy process indicating that the message is in use.

Defining Message Definitions

In PeopleSoft Application Designer, select File, New, Message.

A new message definition consists of the Message Structure view on the left side of the page and the Field List View on the left side of the page.

The following graphic shows a defined message definition.

When you click on a record in the Message Structure View, data displays in the Field List View.

To define a new message:

Assign the message to a message channel.

Open the message properties dialog box for the new message definition, select the Use tab, specify the message channel that you want to assign it to in the Message Channel field, and click OK.

Note. You can’t save the message definition until you assign it to an existing message channel.
Save the message definition.

You are prompted for a message name.

Using the Message Structure View

The message structure view includes the following sections:

Message Structure section.

This section displays different versions of the message and the hierarchy of record definitions within each version. To use the message definition, you must define at least one version; new message definitions supply an initial entry called VERSION_1 by default. To use the message definition to send or receive PeopleSoft rowset-compatible data, you must populate the version with record definitions.
Message Subscriptions section.

This section contains the PeopleCode programs used to receive and process inbound asynchronous messages.

Note. To receive and process inbound synchronous messages, PeopleCode must be associated with the message OnRequest PeopleCode event.

Using the Field List View

The field list view displays the fields comprising the selected record definition in the message structure. The field list includes the following columns:

The Field Name column lists all fields in the selected record definition.
The Alias column enables you to specify, for each field, an XML field tag value that differs from the original field name.

PeopleSoft Integration Broker sends the field with this name instead of the original field name on the sending system. If the sender doesn’t specify an alias value, the field is sent with the original field name. The Alias field is useful for cross release and third-party integration.
The Include column enables you to specify which fields to include in the generated XML.

Select the check box to send the field or to receive it in an inbound message.

See Also

PeopleSoft Rowset-Based Message Format

Defining Message Definition Versions

This section discusses how to:

Create a new message version.
Rename a message version.
Set the default version.

Creating New Message Versions

Open an existing message definition.

With the message definition open, select Insert, Version.

You can also right-click anywhere in the message definition and select Insert Version from the pop-up menu. A new version entry appears on the message structure tree. Note that a corresponding subscription is not added to the Message Subscriptions section. The Subscription or OnRequest PeopleCode must explicitly select the message version that you want to process.

See Also

Understanding Integration PeopleCode

Renaming Message Versions

Each message version has the default name VERSION_N. This naming scheme starts with VERSION_1 and increases in increments of one for each version that you insert.

To rename a message version, click the message name twice (do not double-click it) and type over the existing name. You can also right-click on the message version name and select Rename from the pop-up menu.

Setting Default Message Versions

The message version marked with the lightning bolt is the default version. To change the default, right-click the version that you want as the default, and select Set As Default from the pop-up menu.

You can also set the default version in the Message Properties dialog box. Select the Use tab, then select the default version from the list of available versions.

Using Record Message Definitions

This section provides an overview of message record structure and discusses how to:

Insert a record into a message definition.
Reorganize the record structure.
Create record aliases.

Understanding Message Record Structure

If a message handles PeopleSoft record data, you must insert records in the message definition in an appropriate hierarchical structure. However, if the message data doesn’t map to a record hierarchy, do not insert any records. You supply or receive the data—and its structure—from an external source, using the PeopleCode XmlDoc or SoapDoc classes.

See Sending and Receiving Messages.

You can insert a new record in the message when a version name or a record name is selected in the Message Structure view. If a version name is selected, you can only insert a record immediately below it in the hierarchy—a child record. If a record name is selected, you can also insert a sibling record—one at the same level as the selected record.

Note. Virtually no difference exists between a child record and a sibling record. You can move any record to any location in the version hierarchy after it has been inserted.

Underlying Record Definitions

Records that you insert in a message definition are proxies for the original record definitions. Any change you make to an underlying record definition is automatically reflected by a change in the corresponding record in the message definition.

Fields Defined as Uppercase

If a message definition includes character fields defined as uppercase, then character data in those fields is automatically converted to uppercase when the message is received. This happens when the receiving PeopleCode inserts the message data in a rowset, and it overrides any previous changes in the data, including transformation and data translation.

Inserting Records into Message Definitions

You must insert the first record into a message version as a child record.

To insert a record into a message version:

Select a message version or record.

For a child record, select the message version or existing record below which you want to insert the new record. For a sibling record, select an existing record at the same level where you want to insert the new record.
Select Insert, Child Record.

For a sibling record, select Insert, Record.

You can also right-click the selected message version or record name and select Insert Child Record (or Insert Record) from the pop-up menu.
Use the Insert Record dialog box to search for, select, and insert the record.

Note. The Insert Record dialog box remains active until you click Close. This enables you to quickly insert multiple records at the same level.

Reorganizing Record Structure

Use the directional buttons on the message definition toolbar to reposition a record within the hierarchy of a message version.

The up and down arrows do not change the level of the selected item—they change only its order among other items at that level. The left and right arrows move the selected item lower and higher in the message structure hierarchy.

Note. When you reposition a record in the message version structure, its child records are also repositioned, as well as their child records, and so on.

Creating Record Aliases

In addition to field aliases, you can also provide an alias for each record in a rowset-based message definition. The alias is an XML record tag value which differs from the original record name. PeopleSoft Integration Broker sends the record with this name instead of the original record name on the sending system. If the sender doesn’t specify an alias value, the record is sent with the original record name. Record aliases are useful for cross release and third-party integration.

In the message structure view, right-click the record name and select Message Record Properties. In the Message Record Properties dialog box that appears, enter an alias for the record name.

See Also

PeopleSoft Rowset-Based Message Format

Configuring Message Definition Properties

With a message definition open, click the Properties button and select the Use tab.

Active

Select to indicate that PeopleSoft Integration Broker can send this message.

Note. If you clear this check box to deactivate the message, any transactions and relationships that use it are also deactivated. Activating the message does not automatically reactivate the transactions and relationships; they must be individually reactivated.

NR (nonrepudiation)

Select to indicate that this message must be sent and received in nonrepudiated form.

Validate

Select to indicate that when the message is received, each field’s data type and length should be validated against the field’s format in the local database. If a field fails this validation, the transaction fails with an error.

If you clear this check box, validation is still performed, but the transaction doesn't fail. Instead, the data in mismatched fields is truncated to fit the field length in the local definition.

Note. It's recommended that you enable validation to ensure that field formats are identical at the sending and receiving systems. You can nevertheless use different field, record, and message definitions on each system by applying a transform program to the message before sending it or after receiving it.

See Applying Filtering, Transformation and Translation.

Message Channel

Select the message channel to which you want to assign the message. To save the message definition, you must first specify a message channel.

Default Version

Select the version of this message that is sent or received by default when the sending or receiving PeopleCode does not specify a version.

Message Viewing/Correction

Specify the message viewing and correction method to use for the message at runtime. The options are:

Use Message Monitor Dialog: Use Integration Broker Monitor to view and correct the message. This is the default value.

Use Page: Use a page that you design to view and correct the message.

Implementing Nonrepudiation

You must supply the node-based digital certificates containing the private and public keys needed for each transaction. These elements are required at every node that participates in the transaction; PeopleSoft Integration Broker handles the mechanics of applying the keys.

You must configure the nodes that send and receive this message so that they support nonrepudiation.

If a participating node doesn’t use PeopleSoft Integration Broker, that node is nevertheless responsible for managing the appropriate public and private keys, inserting properly formatted signatures in the nonrepudiation messages that it sends, and properly handling signatures in messages that it receives.

Assigning Message Definitions to Message Channels

Before you can assign a message to the message channel, you must define the message. You make the assignment in the message definition’s properties.

See Defining Message Definitions.

Note. Once a message is assigned to the channel and appears in the Messages view, you can open its definition by double-clicking the message name.

To assign a message definition to a message channel.

In PeopleSoft Application Designer, open a message definition.
Click the Properties button and select the Use tab.
From the Message Channel dropdown list, select the message channel to which you want to assign the message.
Save the changes.

Deleting Message Definitions During Upgrade

To delete a message definition in an application upgrade project, you must first make sure that no live instances of the message exist. Archive or delete any such messages in both the source and the target database. Otherwise, you receive an error message during the copy process indicating that the object is in use.

Active	Select to indicate that PeopleSoft Integration Broker can send this message. Note. If you clear this check box to deactivate the message, any transactions and relationships that use it are also deactivated. Activating the message does not automatically reactivate the transactions and relationships; they must be individually reactivated.
NR (nonrepudiation)	Select to indicate that this message must be sent and received in nonrepudiated form.
Validate	Select to indicate that when the message is received, each field’s data type and length should be validated against the field’s format in the local database. If a field fails this validation, the transaction fails with an error. If you clear this check box, validation is still performed, but the transaction doesn't fail. Instead, the data in mismatched fields is truncated to fit the field length in the local definition. Note. It's recommended that you enable validation to ensure that field formats are identical at the sending and receiving systems. You can nevertheless use different field, record, and message definitions on each system by applying a transform program to the message before sending it or after receiving it. See Applying Filtering, Transformation and Translation.
Message Channel	Select the message channel to which you want to assign the message. To save the message definition, you must first specify a message channel.
Default Version	Select the version of this message that is sent or received by default when the sending or receiving PeopleCode does not specify a version.
Message Viewing/Correction	Specify the message viewing and correction method to use for the message at runtime. The options are: Use Message Monitor Dialog: Use Integration Broker Monitor to view and correct the message. This is the default value. Use Page: Use a page that you design to view and correct the message.