Understanding Managing Messages

This section provides an overview of messages.

Message definitions provide the physical description of the data that is being sent, including fields, field types, and field lengths. You create message definitions in the PeopleSoft Internet Architecture.

Note: Messages are shapes that describe the contents of a service operation transaction. Unlike prior PeopleTools releases, messages do not contain any processing logic. All processing logic is defined in service operations, using service operation handlers.

Five types of messages are available:

Field or Control

Definition
Rowset-based messages

For hierarchical data that is 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 operation classes to generate, send, receive, and process these messages.
Nonrowset-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 operation 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.

Container messages

A container message is a nonrowset-based message that holds one or more part messages.

A container message must contain all rowset-based messages or all nonrowset-based message parts.

Message parts

Message parts are rowset-based messages or nonrowset-based messages that you designate as a part message, to be used in a container message.
Document messages

A document messages are messages based on the PeopleSoft XML document technology. You create and manage these messages in the PeopleSoft Document Builder, either by creating the XML documents from the ground up, importing them from schema definitions, or from PeopleSoft records.

The following table describes when to use a given message type:

Message Type

When to Use

Rowset-based message.

All PeopleSoft-to-PeopleSoft integrations.

Nonrowset-based message.

Integrations with third-party systems.

Container message with rowset-based message parts.

Exposing PeopleSoft services to third-party systems.

Container message with nonrowset-based message parts.

Exposing PeopleSoft services to third-party systems and need to provide nested parts.

Document message.

Integrations with third-party systems.

When naming the following message metadata, names cannot start with “xml,” digits or special characters:

  • Message names.

  • Message aliases.

  • Record aliases.

  • Field aliases.

If a message handles PeopleSoft record data, that is, a rowset-based message, 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 Understanding Sending and Receiving Messages.

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

If a message definition includes character fields that are 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.

Message aliases are read-only once you save the message definition. As a result, once you create a message alias for a message definition, any subsequent versions of the message that you create use the original alias.

This section lists the conditions under which a message may become restricted and read-only. This list applies to all message types, including rowset-based messages, nonrowset-based messages, container messages, part messages, and subpart messages.

You cannot modify a message if one or more of the following conditions exists:

  • The service to which a message is contained in a restricted service.

  • The message is used internally by the system. For example, the delivered IB_GENERIC message is read-only and is used internally by the system.

  • The message is referenced in the runtime tables.

    To work around this, you must remove any entries in the runtime tables that reference the message.

  • The message is used in a service operation where WSDL documents have been generated.

  • The message is used in a service operation that has validation enabled.