Managing Messages

This chapter provides an overview of managing messages and discusses how to:

• Create message definitions.

• Manage rowset-based messages.

• Manage nonrowset-based messages.

• Manage message parts.

• Manage container messages.

• Rename and delete message definitions.

• Delete messages during upgrade.

Understanding Managing Messages

This section provides an overview of messages.

Message Definitions

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.

Message Types

Four types of messages are available:

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

Message Record Structure

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 Sending and Receiving Messages.

Underlying Record Definitions

Records that you insert in a message definition are proxies for 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.

Fields Defined as Uppercase

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.

Restrictions for Modifying Messages

Messages may become restricted and become read-only under the following conditions:

• The service to which a message is tied is a restricted service.

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

• A message is referenced in the runtime tables.

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

• If a message is a message part.

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

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

Adding Message Definitions

This section discusses how to add a message definition to the system.

Understanding Adding Message Definitions

When you create a message definition, you first create the message definition, in which you name the message and specify the message version. After doing so, you can then define additional aspects of the message definition.

Page Used to Add Message Definitions

Adding a Message Definition

The following example shows the Message Builder page that you use to name a new message definition and assign a version to it:

The following example shows the Messages - Message Definition page that you use to configure a message after you create the message definition:

Note. For asynchronous integrations, define a single message. For synchronous integrations, define two messages: one request message and one response message, unless the request and response have the same shape.

To add a message definition:

1. Select PeopleTools, Integration Broker, Integration Setup, Messages.

2. Select the Add New Value tab.

3. In the Message Name field, enter a name for the message.

   The message name cannot exceed 30 characters. Do not include any spaces in the message name.

4. In the Message. Version field, enter a version for the message.

   The message version cannot exceed 30 characters. Do not include any spaces in the message version.

   Accepted formats for the message version include:

   • Version_1.

   • V1.

5. Click the Add button.

   The Messages - Message Definition page appears.

6. In the Message Type group box, select the message type. Values are:

   • Rowset-based

   • Nonrowset-based (default)

   • Container

7. (Optional) In the Alias field, enter the name that the external system is expecting, if different from the value in the Message Name field.

   This field appears only when you are defining nonrowset-based or container messages.

8. (Optional) Select the Message Parts check box if the message will be used as a message part in a container message definition.

9. (Optional) In the Description field, enter a description for the definition.

10. (Optional) From the Owner ID dropdown list box, select an owner for the definition.

    The owner ID helps to determine the application team that last made a change to the definition. The values in the dropdown list box are translate table values that you can define in the OBJECTOWNERID field record.

11. (Optional) In the Comment field, enter any pertinent comments about the definition.

12. The next step depends on the type of message definition that you are creating:

    • Rowset-Based Message. You must add a root record to the definition before you can save it.

      See Managing Rowset-Based Messages.

    • Nonrowset-Based Message. The message definition is complete and you can click the Save button to save the changes. You can now add an XML message schema to the definition.

      See Managing Nonrowset-Based Messages.

    • Container Message. You must add at lease one message part to the definition before you can save the changes.

      See Managing Container Messages.

Managing Rowset-Based Messages

This section provides an overview of managing rowset-based message definitions and discusses how to:

• Insert root records.

• Insert child and peer records.

• Specify record aliases.

• Delete records.

• Exclude fields from messages.

• Specify field name aliases.

• Generate XML message schemas for rowset-based messages.

Understanding Managing Rowset-Based Messages

This section provides overview information about managing rowset-based message definitions.

Root Records

When you create a rowset-based message, you must at a minimum insert a root record (level 0) into the definition.

Records and Record Fields

You create and modify records and record fields in PeopleSoft Application Designer.

Note. Avoid using work records in messages. Work records don't behave like regular records when used with PeopleCode rowset methods. A good alternative is to use dynamic views.

Record and Record Field Aliases

Record and field aliases are optional parameters that are used for schema and XML generation.

When record and field aliases are used, the receiver of a message sees the alias names instead of the actual record and field names. The alias names are seen in the message definition, in message schemas, and on generated runtime XML that is sent to the receiver.

Note that the sender still codes to the actual record and field name.

Pages Used to Manage Rowset-Based Messages

Inserting Root Records

You insert a root record into a rowset-based message definition using the Add a New Record page shown in the following example:

Note. There can only be one root record defined for each rowset-based message.

To insert a root record into a definition:

1. On the Messages–Message Definitions page, click the Add Record to Root link.

   The Add New Record page appears.

2. In the New Record Name field, enter the name of the record to add, or click the Lookup button to search for and select one.

3. Click the OK button.

The root record appears in the tree structure. Click the plus button to expand the tree and view fields that are associated with the record.

You can exclude fields from the record and specify field name aliases. Steps for performing these actions are described elsewhere in this chapter.

See Excluding Fields from Messages.

See Specifying Field Name Aliases.

Inserting Child and Peer Records

You insert child and peer records into a rowset-based message definition using the Message Record Properties page shown in the following example:

To insert a child or peer record into a rowset-based message definition:

1. On the Messages–Message Definition page, click the linked record name to which to add a peer or child record.

   The Message Record Properties page appears.

2. In the Action group box, select Add Record.

3. In the New Record Name field, enter the name of the record to add, or click the Lookup button to search for and select a name.

4. Select whether to add the record as a peer record or a child record.

   • Select Peer Record to add the record as a peer.

   • Select Child Record to add the record as a child.

5. Click the OK button.

   The Messages–Message Definitions page appears.

6. Click the Save button.

Specifying Record Aliases

You can specify aliases of the root, peer, and child records that you insert into rowset-based messages.

To specify a record alias:

1. In the Messages–Message Definitions page, click the name of the record for which you want to specify an alias.

   The Message Record Properties page appears.

2. In the Alias Name field, enter an alias name.

3. Click the OK button.

   The Messages–Message Definitions page appears.

4. Click the Save button.

Deleting Records

This section describes how to delete records from a rowset-based message.

Note. Deleting the root record deletes all records and their associated fields that are inserted into the definition.

To delete a record:

1. In the Messages–Message Definitions page, click the name of the record to delete.

   The Message Record Properties page appears.

2. In the Action group box, select Delete Record.

3. Click the OK button.

   The Messages–Message Definitions page appears.

4. Click the Save button.

Excluding Fields from Messages

You can exclude record fields from inclusion in a rowset-based message definition using the Message Field Properties page shown in the following example:

After you exclude fields from records, the tree view of the message definition on the Message Definitions page displays a red icon next to the excluded fields. The following example show two fields, QE_ACNUMBER and QE_OFP, have been excluded from the QE_FLIGHTDATA record.

To exclude fields:

1. From the Messages–Message Definitions page, click the plus button to expand the record tree structure, and locate the field to exclude from the definition.

2. Click the name of the field to exclude.

   The Message Field Properties page appears.

3. Clear the Include check box.

4. Click the OK button.

   The Messages–Message Definitions page appears.

5. Click the Save button.

Specifying Field Name Aliases

To specify a field name alias:

1. From the Messages–Message Definitions page, click the plus button to expand the record tree structure, and locate the field to exclude from the definition.

2. Click the name of the field to exclude.

   The Message Field Properties page appears.

3. In the Alias Name field, enter an alias name.

4. Click the OK button.

   The Messages–Message Definitions page appears.

5. Click the Save button.

Generating XML Message Schemas for Rowset-Based Messages

This section discusses how to:

• Build XML message schemas for rowset-based messages.

• Delete XML message schemas for rowset-based messages.

Building XML Message Schemas for Rowset-Based Messages

After you create a rowset-based message definition and insert a root record into the definition, and optionally, additional peer and child records, you can generate an XML message schema for the definition.

Note. You cannot regenerate message schemas for messages that are defined as part of a restricted service.

To generate an XML message schema for a rowset-based message:

1. Select PeopleTools, Integration Broker, Integration Setup, Messages.

2. Select the rowset-based definition for which to generate an XML schema.

   The Messages–Message Definitions page appears.

3. Click the Schema tab.

4. Click the Build Schema button.

The results appear at the bottom of the page.

Clicking the Build Schema button saves the schema and the message.

Note that when you click the Message Definitions tab to view the definition, the Schema Exists field displays a value of Yes, indicating that a schema has been generated for the definition.

Deleting XML Message Schemas for Rowset-Based Messages

To delete an XML message schema for a rowset-based message:

1. Select PeopleTools, Integration Broker, Integration Setup, Messages.

2. Select the rowset-based definition for which to generate an XML schema.

   The Messages - Message Definitions page appears.

3. Click the Schema tab.

4. Click the Delete Schema button.

The results appear at the bottom of the page.

Note that when you click the Message Definitions tab to view the definition, the Schema Exists field displays a value of No, indicating that a schema has been deleted for the definition.

Managing Nonrowset-Based Messages

This section provides an overview of managing nonrowset-based messages and discusses how to:

• Add XML message schemas to nonrowset-based messages.

• Edit nonrowset-based XML message schemas.

Understanding Managing Nonrowset-Based Messages

After you create a nonrowset-based message definition, you do not need to complete any additional configuration steps for the definition, except to add an XML schema. The XML schema describes the data to be sent, and includes the field names, data types, field lengths and so on.

See Also

Adding Message Definitions

Page Used to Manage Nonrowset-Based Messages

Adding XML Message Schemas to Nonrowset-Based Messages

To add an XML message schema to nonrowset-based messages:

Note. You cannot regenerate message schemas for messages that are defined as part of a restricted service.

1. Select PeopleTools, Integration Broker, Integration Setup, Messages.

2. Select the nonrowset-based definition to which you want to add an XML schema.

   The Messages - Message Definitions page appears.

3. Click the Schema tab.

4. Click the Add Schema button.

   The Schema page appears.

5. Add the XML schema to the message.

   You can add the schema to the message in two ways:

   • Click the Upload Schema From File button to browse for and upload a schema that you have already saved to a file.

   • Enter the XML schema in the Schema text box that is provided.

6. Click the Save button.

If you define the message as a message part, you must supply a schema to save the message. All message parts require a schema at save time.

Editing Nonrowset-Based XML Schemas

After an XML message schema is added to a nonrowset-based message, you can edit the schema using the Schema page.

Note. You cannot regenerate message schemas for messages that are defined as part of a restricted service.

To edit nonrowset-based XML message schemas:

1. Select PeopleTools, Integration Broker, Integration Setup, Messages.

2. Select the nonrowset-based definition that contains the schema that you want to edit.

   The Messages - Message Definitions page appears.

3. Click the Schema tab.

   The Schema page appears and displays the existing XML message schema for the definition.

4. Click the Edit Schema button.

5. In the Schema text box, make your changes and additions to the XML schema.

6. Click the Save button.

Managing Message Parts

This section discusses how to create message parts.

Understanding Message Parts

Message parts are individual message definitions that get used in container messages.

While they can be rowset-based or nonrowset-based, the advantage of using message parts comes when working with rowset-based messages.

Container messages are always nonrowset-based. So, if you use a container message that contains rowset-based part messages, the container messages sends XML that contains none of the standard PeopleSoft message XML structures, such as PSCAMA, FieldTypes, and so on. However, you can use the rowset-based classes and methods to populate and read the structure of each part message.

Creating Part Messages

To create a part message, create a standard rowset-based or nonrowset-based message and click the Part Message box on the Message Definition page.

When the service system status is set to Production, once a message is used in a container message, you cannot alter the message while it is associated with a container message.

You must generate schemas for all part messages before you can save them.

Schemas for rowset-based messages are automatically built when the message is saved. Schemas for nonrowset-based parts must be added in order to save the message.

See Also

Adding Message Definitions

Managing Container Messages

Managing Container Messages

This section provides an overview of managing container messages and discusses how to:

• Add message parts to container messages.

• Generate XML message schemas for container messages.

Understanding Managing Container Messages

Container messages are used for those situations where you want to produce XML that contains none of the standard PeopleSoft messaging XML structures , such as PSCAMA, FieldType, and so on, yet you want to use PeopleSoft rowset-based classes and methods to populate and read the message structure.

Container messages hold one or more message parts.

Container messages are always nonrowset-based messages.

The message parts you add to a container message must all be rowset-based message parts, or all nonrowset-based message parts.

Pages Used to Manage Container Messages

Adding Message Parts to Container Messages

This section discusses how to add message parts to container messages.

Use the Messages–Message Definitions page to perform this task. To access the page, select PeopleTools, Integration Broker, Integration Setup, Messages. The following example shows this page:

When you click the Add Parts link to specify a message, version, and message type to add, the Add Parts page appears as shown in the following example:

For a message definition to be available for you to add to a container message, you must have selected the Message Parts check box when you created the message definition. In addition, container messages can contain only all rowset-based messages or all nonrowset-based messages.

After you add message parts to a container message, the Messages–Message Definitions page displays and the message parts that you have added to the message are listed in the Parts grid. The following examples show of three message parts that are added to a container message:

Click the name of any of the message parts that appear in the grid to open the individual message definition. If the service system status is set to Production, when assigned to a container message, you cannot modify a message definition. To modify the definition, you must delete it from the container message first. The following example shows how the PART_1 message part displays if you click the message name in the Parts grid:

Clicking the Part References link displays all messages to which the message part is assigned.

Note. Before you add nonrowset-based message parts to a container message, you must upload XML message schemas to each message part that you intend to include in the container message. Nonrowset-based part messages cannot be saved without a schema.

To add a message part to a container message:

1. From the Messages–Message Definitions page, click the Add Parts link.

   The Add Parts page appears.

2. Select a message to add.

   You can use one of two methods to select a message to add:

   1. In the Message Name and Message Version fields, enter the message name and version to add.

   2. Select the Show Rowset-Based Parts option or the Show Nonrowset-Based Part option and click the Search button to display all rowset-based or nonrowset-based messages that are designated as part messages in the system.

      Select one or more messages to include in the container message.

3. Click the OK button.

   The Messages–Message Definitions page appears, with the Parts grid populated with the message or messages that you selected.

4. (Optional.) In the Parts grid, enter numeric values in the Sequence column to order message part placement in the container message.

   If you do not enter any values, the system sequences the messages in the order in which you add them to the container message.

5. (Optional.) Specify the minimum or maximum rows that are required to have a valid message.

   1. (Optional.) In the Minimum Occurs field, enter the number of minimum rows in the message part to include in the container message.

   2. (Optional.) To specify a maximum number of rows from the message part to include in the container message, from the Unbound Maximum dropdown list box, select N. The Maximum Occurs field appears in the grid.

      In the Maximum Occurs field, enter the maximum number of rows from the part message to include in the container message.

   The default value for the Unbound Maximum field is Y. This default value means that the number of rows from the part message that the system includes in the container messages is unlimited, or unbound. When you select the default, all rows from a part message are included in the container message. If you change the field value to N, you must enter the maximum number of rows from the part message to include in the container message in the Maximum Occurs field.

Generating XML Message Schemas for Container Messages

XML message schemas for container messages re automatically generated when you save the definition. You can view the generated XML message schema on the Messages–Schema page. The following example shows this page:

The namespace that is used in the XML message schema becomes by default the value that is defined on the Service Configuration page. To change the namespace, enter a the new namespace on the Schema page in the Namespace field, the Message Definition tab, and save the change. The XML message schema is generated again by means of the modified namespace value.

Renaming and Deleting Message Definitions

You can rename and delete messages using the Messages page in the Services Administration component (IB_HOME_PAGE). The Message page contains two sections: a Delete section that enables you to delete message definitions and a Rename section that enables you to rename message definitions.

To access the page, select PeopleTools, Integration Broker, Service Utilities, Service Administration, and click the Messages tab.

When you first access the Messages page, all sections are collapsed. Click the section header arrow buttons to expand and collapse each section.

The following example shows the Messages page with the Delete and Rename sections expanded:

At the top of the page, the Service System Status field displays the current setting. The service system status, set on the Service Configuration page, affects the ability to rename and delete messages.

See Understanding Configuring PeopleSoft Integration Broker for Handling Services, Setting Service Configuration Properties.

Pages Used to Rename and Delete Message Definitions

Renaming Message Definitions

To rename a message definition:

Note. Renaming a message definition renames all versions.

1. Access the Services Administration – Messages page.

2. Click the arrow next to the Rename section header to expand the section.

3. In the Message Name field, enter the message definition to rename, or click the Lookup button to search for and select the message to rename.

4. (Optional.) Click the Message Builder link to view details about the selected message in the Messages–Message Definitions page.

   When you are done viewing the message details, click the Return button to return to the Services Administration –Messages page.

5. In the New Name field, enter the new name for the message definition.

6. Click the Rename button.

Deleting Messages Definitions

To delete a message definition:

1. Access the Services Administration –Messages page.

2. Click the arrow next to the Delete section header to expand the section.

3. In the Message Name field, enter the name of the message to delete, and click the Search button.

   Search results appear in the results grid.

4. In the results grid, select the check box next to the message or messages to delete.

5. Click the Delete button.

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