Managing Messages

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

• Search for message definitions.

• Add message definitions.

• Manage rowset-based messages.

• Manage nonrowset-based messages.

• Manage message parts.

• Reuse message parts.

• Manage container messages.

• Manage document messages.

• View service operations that reference a message.

• Resolve inconsistencies in exported WSDL and WADL documents.

• 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

Five types of messages are available:

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

Naming Conventions for Message Metadata

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

• Message names.

• Message aliases.

• Record aliases.

• Field aliases.

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

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.

Message Aliases and Message Versions

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.

Restrictions for Modifying Messages

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.

Searching for Message Definitions

To search for an existing message definition in the system use the Messages - Search page (IB_MSGSEARCH). To access the page select PeopleTools, Integration Broker, Integration Setup, Messages. The following example shows the page:

To search for a message definition:

1. Access the Messages - Search page (PeopleTools, Integration Broker, Integration Setup, Messages).

2. Search for a message definition.

   You can search for message definition in one of two ways:

   • Enter search criteria in one or more of the following fields, and then click the Search button:

     Type	From the dropdown list, select the type of message for which you are searching. The options are: Container. Document. Nonrowset. Part nonrowset. Part rowset. Rowset.
     Message Name	Enter the name of the message.
     Version	Enter the version of the message.

   • Click the Search button to display all message definitions in the system.

   The results appear in the Search Results grid.

3. Click the name of the message to view.

Adding Message Definitions

This section discusses how to:

• Add rowset, nonrowset and part message definitions.

• Add document message definitions.

Understanding Adding Message Definitions

When you add a message definition to the system you first give the message a name and specify a message version. After doing so, you can then define additional aspects of the message definition.

Adding Rowset, Nonrowset or Part Message Definitions

The following example shows the Add New Message page (IB_MSGSEARCH_ADD) that you use to name a new message definition and assign a version to it:

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

Different options appear on the Message–Message Definition page, depending on the type of message that you are defining.

By default the message type is set to Nonrowset-based as shown in the previous example.

If you select a Rowset-based or Container message type, additional options appear on the page with which you can work.

The following example shows the Message–Message Definition page when you select Rowset-based as the message type:

In the previous example, notice the additional options that display on the upper right portion of the page.

When you define a container message, it, too, has its own unique options that you define, as shown in the following example:

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 rowset, nonrowset, or part message definition:

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

   The Messages – Search page appears.

2. Click the Add a New Valuelink.

3. From the Type drop-down list, select a message type to create. The options are:

   • Container. Select this value to add a container message to the system.

   • Document. Select this value to add a document message to the system.

     Adding a document message type to the system is described elsewhere in this section.

     See Adding Document Message Definitions.

   • Nonrowset. Select this value to add a nonrowset-based message to the system.

   • Part Nonrowset. Select this value to add a nonrowset-based message part to the system.

   • Part Rowset. Select this value to add a rowset-based message part to the system.

   • Rowset. Select this value to add a rowset-based message to the system.

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

5. In the 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.

6. Click the Add button.

   The Messages - Message Definition page appears.

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 drop-down 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 drop-down 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. In the Root Element field, enter a value to appear in the root element in generated WADL documents when the message is used in a REST service operation.

    Note. You must provide a value in this field if you are using the message in a REST-based service operation. This field value is required for proper WADL document generation.

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

13. The next steps to adding a message definition depend on the type of message definition that you are creating:

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

      See Managing Rowset-Based Messages.

    • Nonrowset-Based Message or Message Part. 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 least one message part to the definition before you can save the changes.

      See Managing Container Messages.

Adding Document Message Definitions

This section discusses adding document message definitions.

Understanding Adding Document Message Definitions

When you create a document message definition in the system, you create a message definition that references a document. .

Prerequisites for Adding Document Message Definitions

Before you add a document message definition to the system, the document definition that the message will reference must exist in the system

Adding a Document Message Definition

When you add a document message definition, the following page appears:

After you provide a message name, version, and optional alias, you specify the document package, document name, and version to which to link the message.

After you click the Add button, the document that you specified in the message definition appears in the Document Builder – Document page, as shown in the following example:

The Metadata References section in the definition shows that there is an Integration Broker message called TEST_DOC_MSG.v1 that references the document.

Note that the message definition is not saved until you click the Save button in the Document Builder.

To add a document message definition:

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

2. Select the Add New Value tab.

3. From the Type drop-down list, select Document.

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

5. In the 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.

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

7. In the Package field, enter the document package or click the Lookup button to search for one.

8. In the Document field, enter the document name or click the Lookup button to search for one.

9. In the Version field, enter the document version or click the Lookup button to search for one.

10. Click the Add button.

    The Document Builder–Document page appears, displaying the document definition for the document you specified. The Metadata References grid displays the name of the message definition you added.

11. Click the Save button.

Managing Rowset-Based Messages

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

• View rowset-based message structures.

• Insert root records.

• Insert child and peer records.

• Specify record aliases.

• Delete records.

• Exclude fields from messages.

• Specify field name aliases.

• Managing XML message schemas for rowset-based messages.

• Enforce message record and field aliases in generated WSDL.

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

XML Schema for Rowset-Based Messages

When you create or make changes to a rowset-based message definition, the system automatically generates message schema.

Viewing Rowset-Based Message Structures

This section discusses the three ways to view the structure of rowset-based message definitions. This section discusses how to:

• View the entire structure of rowset-based message definitions.

• View only the records in rowset-based message definitions.

• View only included records fields in rowset-based message definitions.

Viewing the Entire Structure of Rowset-Based Message Definitions

By default, when you open a rowset-based message definition PeopleSoft Integration Broker displays the complete message definition structure. The following graphic shows the complete message definition structure for the message QE_FLIGHTPLAN.

The system displays the definition in a tree structure. Use the plus (+) and minus (-) buttons to expand and collapse the tree to view all records, subrecords and fields (both included and excluded) in the definition.

Record fields that are included in the message definition have a check next to them. Record fields that are not included in the message definition have a box next to them. In the previous graphic, QE_RANGE is the only record field that is not included in the QE_FLIGHTPLAN message definition.

You can view the record or field properties by clicking the record or field name.

To view the entire structure of a rowset-based message:

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

2. Select a message to view.

   The Messages-Message Definitions page appears and the entire structure of the message appears in a tree view.

3. Expand and collapse the tree to view the message structure.

Viewing Only the Records in Rowset-Based Message Definitions

You can use the Records Only page (IB_MESSAGE_TR_SEC) to view the records and subrecords in a rowset-based message definition. The following graphic shows the Records Only page:

To view only the records in a rowset-based message:

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

2. Select a message to view.

   The Messages-Message Definitions page appears.

3. Just above the tree structure view of the message structure, click the View Records Only link.

   The Records Only page appears and the records and subrecords in the message definition display in a hierarchical view.

4. Click the Return button to return to the Messages-Message Definitions page.

Viewing Only Included Record Fields in Rowset-Based Message Definitions

You can use the Included Fields Only page (IB_MESSAGE_TR_SEC) to view the included records fields for a rowset-based message definition. The following graphic shows a sample of the records and their included fields contained in the QE_FLIGHTPLAN message definition:

Included fields are denoted by a green icon in the shape of a check mark.

To view included record fields in a rowset-based message:

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

2. Select a message to view.

   The Messages–Message Definitions page appears.

3. Just above the tree structure view of the message structure, click the View Included Fields Only link.

   The Included Fields Only page appears and included records fields contained in the message display.

4. Click the Return button to return to the Messages-Message Definitions page.

Inserting Root Records

You insert a root record into a rowset-based message definition using the Add New Record page (IB_MESSAGE_TOP_SEC) 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. Access the Add New Record page.

   Select PeopleTools, Integration Broker, Integration Setup, Messages. The Messages-Message Definitions page appears. Click the Add Record to Root link.

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 (IB_MESSAGE_REC_SEC) shown in the following example:

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

1. Access the Message Record Properties page.

   (Select PeopleTools, Integration Broker, Integration Setup, Messages. The Messages-Message Definitions page appears. Click the linked record name to which to add a peer or child record.)

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 using the Message Record Properties page.

To specify a record alias:

1. Access the Message Record Properties page.

   (Select PeopleTools, Integration Broker, Integration Setup, Messages. The Messages-Message Definitions page appears. Click the linked record name to which to specify an alias.)

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.

See Also

Message Aliases and Message Versions

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. Access the Message Record Properties page.

   (Select PeopleTools, Integration Broker, Integration Setup, Messages. The Messages-Message Definitions page appears. Click the name of the record to delete.)

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.

After you exclude fields from records, the tree view of the message definition on the Message Definitions page displays a red icon in the shape of box next to the excluded fields. The following example shows that the field QE_ACNUMBER, has been excluded from the QE_FLIGHTDATA record.

To exclude fields:

1. Access the Message Field Properties page.

   1. Select PeopleTools, Integration Broker, Integration Setup, Messages. The Messages-Message Definitions page appears.

   2. Click the plus button (+) to expand the record tree structure, and locate the field to exclude from the definition.

   3. Click the name of the field to exclude.

   The Message Field Properties page appears.

2. Click the name of the field to exclude.

    

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

Use the Message Field Properties page to specify field name aliases.

To specify a field name alias:

1. Access the Message Field Properties page.

   1. Select PeopleTools, Integration Broker, Integration Setup, Messages. The Messages-Message Definitions page appears.

   2. Click the plus button (+) to expand the record tree structure, and locate the field to exclude from the definition.

   3. Click the name of the field for which to specify a field name alias.

   The Message Field 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.

Including Fields in CData Sections in Generated XML

You can specify that fields be included in CData sections in generated XML. When you select the CData Wrap box on the Message Field Properties page, the field will be wrapped in a CData section in generated XML.

The following example shows the Message Field Properties page and the CData Wrap box:

To include a field in a CData section in generated XML:

1. Access the Message Field Properties page.

   1. Select PeopleTools, Integration Broker, Integration Setup, Messages. The Messages-Message Definitions page appears.

   2. Click the plus button (+) to expand the record tree structure, and locate the field to exclude from the definition.

   3. Click the name of the field for which to specify a field name alias.

   The Message Field Properties page appears.

2. Check the CData Wrap box.

3. Click the OK button.

   The Messages–Message Definitions page appears.

4. Click the Save button.

Managing XML Message Schemas for Rowset-Based Messages

This section discusses how to:

• View XML message schemas for rowset-based messages.

• Exclude descriptions in XML message schemas.

• Choose the number of level 0 rows to include in generated XML message schema.

• Include namespaces in generated XML message schemas.

• Suppress empty XML tags in message schema.

Viewing XML Message Schemas for Rowset-Based Messages

PeopleSoft Integration Broker automatically generates message schema for rowset-based messages when you save the message definition.

After you save a message definition on the Messages-Message Definitions page, click the Schema tab to view the generated XML message schema.

Excluding Descriptions in XML Message Schemas

Message data that is used to define services can have actual database record and field names in the generated XML message schema. PeopleSoft Integration Broker provides an option where you can exclude descriptions in generated message schemas so that sensitive information is not exposed.

The Messages–Message Definitions page features an Exclude Descriptions in Schema box that enables you to suppress descriptions in generated schema.

To exclude descriptions in XML message schemas:

1. Access the Messages–Message Definition page (PeopleTools, Integration Broker, Integration Setup, Messages).

2. Select the Exclude Description in Schema box.

3. Save the changes.

   See Managing XML Message Schemas for Rowset-Based Messages.

Choosing the Number of Level 0 Rows to Include in Generated XML Message Schema

You can choose to include a single level 0 row in the generated schema or all level 0 rows in the generated schema.

When you select the Single Level 0 Row check box, PeopleSoft Integration Broker includes a single level 0 row in the XML message schema when you Save the definition. If this box is not selected, then the system includes all level 0 rows in the message in the generated schema.

By default the Single Level 0 Row check box is not selected.

If you check the Single Level 0 Row check box to generate schema with one level 0 row, the level 0 row included in the schema is the first level 0 row the system encounters in the message.

Including Namespaces in Generated XML Message Schemas

PeopleSoft Integration Broker enables you to include a namespace in XML message schemas that you generate for rowset-based messages.

When working with a rowset-based message type, the Messages–Message Definition page displays an Include Namespace box. When the Include Namespace check box is selected, you can specify a namespace to include in the generated schema on the Messages-Schema page.

The following example shows the Namespace field as it appears on the Messages–Schema page:

By default the Namespace field is populated with the namespace defined on the Service Configuration page, however you can change the namespace to use in the message schema as required.

To include a namespace in generated schema:

1. Access the Messages–Message Definition page (PeopleTools, Integration Broker, Integration Setup, Messages).

2. Check the Include Namespace box.

3. Click the Schema tab.

   The Messages–Schema page appears. By default the namespace as defined on the Service Configuration page populates the Namespace field.

4. In the Namespace field enter the namespace to use in the generated XML message schema.

5. Click the Message Definition tab.

6. Save your changes.

The system generates the message schema and includes the namespace specified.

Suppressing Empty XML Tags in Message Schema

PeopleSoft Integration Broker enables you to suppress empty XML tags in message schema of rowset-based messages.

The Messages-Message Definition page features a Suppress Empty XML Tags check box.

When you select this box, message schema generated for the message will not include any XML tags that contain empty or Null values.

Enforcing Message Record and Field Aliases in Generated WSDL

PeopleSoft Integration Broker enables you to enforce record and field aliases in generated WSDL.

The Service Configuration page features a WSDL Generation Alias Check drop-down list that enables you to set a system check level for aliases on message definition records and fields.

You can set the following check levels:

To enforce message record and field aliases in generated WSDL:

1. Access the Service Configuration page (PeopleTools, Integration Broker, Configuration, Service Configuration).

2. From the WSDL Generation Alias Check drop-down list, select a value. The valid options are:

   • Error.

   • None.

   • Warning.

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.

You may add or replace message schemas that are referenced by nonrowset-based messages in runtime tables. However, once you change a message schema for a nonrowset-based message, you must adjust the message for a successful integration.

See Also

Adding Message Definitions

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.

Deleting Nonrowset-Based XML Message Schemas

This section discusses how to:

• Delete individual nonrowset-based XML message schemas.

• Delete nonrowset-based XML message schema in bulk.

Deleting Individual Nonrowset-Based XML Message Schemas

Use the Messages-Schema page (IB_MESSAGE_BUILD2) to delete individual nonrowset-based XML message schema.

To delete an individual nonrowset-based XML message schema:

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

   The Messages-Message Definitions page appears.

2. Click the Schema tab.

   The Messages-Schema page appears.

3. Click the Delete Schema button.

Deleting Nonrowset-Based XML Message Schemas in Bulk

To delete one or more nonrowset-based XML message schemas, use the Message Schemas page (IB_HOME_PAGE6) in the Service Administration component (IB_HOME_PAGE). The following example shows the Message Schemas page:

To delete nonrowset-based XML message schemas in bulk:

1. Select PeopleTools, Integration Broker, Service Utilities, Service Administration.

2. Click the Message Schemas tab.

3. Choose the schema or schemas to delete.

   To delete an individual schema, in the Message Name field enter the name of the message that contains the schema to delete.

   To delete more than one schema, click the Search button to display all nonrowset-based message in the system than contain schema.

   The message or messages appear in the Messages with Schema grid.

4. In the Select column, check the box next to each message name that contain schema you want to delete.

   If deleting multiple schemas, use the forward and backward arrows and/or the Last and First links to page through the results and select schemas to delete.

5. Click the Delete 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 message parts can be rowset-based or nonrowset-based, the advantage of using message parts comes when working with rowset-based messages. By using nonrowset-based message parts, you cannot take advantage of PeopleSoft Integration Broker's framework for creating message definitions, use of PeopleCode, serialization, porting, and so on. The following table highlights some of the advantages of using rowset-based message parts:

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

Distinguishing Blank from Zero in Rowset-Based Part Messages

The Message Definitions page features a Message Part Default Indicator field that appears when you select or define a rowset-based message part.

When you check the box, XML that has a value of 0 (zero) passed in an integer field, when serialized to a rowset, causes the IsChanged property flag on the field to set to True.

By default an integer field has a value of 0. So if a 0 or <blank> is passed in a field, the end result is a 0 when accessing the field via the rowset. However, if you check the Message Part Default Indicator box the IsChanged property on such a field is set to True, meaning that a 0 (zero) was passed in the field.

Reusing Rowset-Based Message Parts

This section discusses how to:

• Reuse rowset-based message parts by reference.

• Reuse rowset-based message parts by copy.

Understanding Reusing Rowset-Based Message Parts

PeopleSoft Integration Broker enables you to reuse rowset-based message parts by referencing another message part or by copying another message part.

Note. You cannot reuse message parts at Level 0.

Referencing Message Parts

A reference to a message part is read-only in the message part where it is referenced. To make changes to a referenced message part, you must make the changes to the referenced message part directly. All changes are then propagated to every message in which the message part is referenced.

Copying Message Parts

If you copy a message part, the system copies all records and fields and displays them at the record level. The records and fields become permanent to the new message and you can edit all records and fields directly in the message where the copied part exists. Changes you make to a copied message part are not propagated to other copies of the message part that may exist. You must make changes to a copied message part, you do so manually to each message part that you want to change.

Reusing Rowset-Based Message Parts by Reference

This section discusses how to:

• Reuse a message part by reference.

• Check for recursion.

• View referenced message part information.

• View where message parts are referenced.

• Modify referenced message parts.

• Delete referenced message parts

Reusing a Message Part by Reference

To reuse a message part by reference:

1. Create a rowset-based message part.

2. Add records to the message part per your requirements. At a minimum, you must add a Level 0 record.

3. In the tree view of the message part definition, click the name of the record off of which to add the reused message part.

   The Message Record Properties page appears.

4. In the Action box, click Add Part Reference.

5. Identify if the message part is a peer part reference or a child part reference.

   If you are working off the Level 0 record, these fields are read only and Child Part Reference is selected by default.

6. In the Reference Message Version field, click the Lookup button to select the message that the system should reference.

7. Click the OK button.

   The Messages-Message Definition page appears.

The reference part is identifiable in the tree view for the message part definition by the highlighted color on the root record of the referenced part. Since this is a reference, you can only view the reference part data structure. To make any modifications to the referenced part, you must open the message part directly and make your changes there. The system will propagate the changes to all messages that reference the message part.

Checking for Recursion

By default, the system checks up to 20 levels for recursion to ensure that no message part references itself. You can modify this setting to check for recursion in as few as three levels of records and as many as 50 levels.

This parameter is set on the System Setup Options page (IB_SYSTEMSETUP). The following example shows the page:

To modify the recursion checking level:

1. Access the System Setup Options page (select PeopleTools, Integration Broker, Configuration, System Setup Options)

2. In the Message Builder Depth Limit field, enter a value between 3 and 50.

3. Click the Save button.

Viewing Referenced Message Part Information

A referenced message part appears highlighted in the tree structure for a message. The following example shows that the message record QE_ARMAMENT is a referenced message part in the message FLIGHTDATA.

Note. You can make changes to a message part that is referenced in another part or subpart, as long as the message part is not in the runtime tables, has not been exported as WSDL, or is a restricted message.

If you click a referenced message part, the Part Reference page (IB_MESSAGE_PARTS2) appears, as shown in the following example:

You can use the Part Reference page to view general information about the referenced message part as well as view the complete definition for the message part.

You can also use this page to delete the reference to the message part. Deleting a part reference is discussed elsewhere in this section.

See Deleting Referenced Message Parts.

To view the complete message definition for a referenced message part, on the Part References page click the View Definition link. The Messages-Message Definitions page for the referenced message part appears, like the one shown in the following example:

You can use the page to view details about the record structure, view the generated message schema, and so on.

Modifying Referenced Message Parts

To make a modification to a referenced message part, you must make the modification in the message part definition itself. You cannot modify a referenced message part from a message in which it is referenced.

Deleting Referenced Message Parts

You delete a referenced message part in the message where the part is referenced.

To delete a referenced message part:

1. Open the message definition that contains the referenced message part to delete.

2. In the tree structure view of the message definition, click the name of the referenced message part to delete.

   The Part Reference page appears.

3. Check the Delete Part Reference box.

4. Click the OK button.

Managing Container Messages

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

• Add message parts to container messages.

• Add and get container message attributes.

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

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

When working with container messages that contain rowset-based message, PeopleSoft Integration Broker enables you to add attributes and attribute values to the container messages. Adding attributes to container messages enables you to provide integration partners with data and information, without the need to modify or provide the information in the container message definition or in any of the part message definitions.

Understanding Including Level 0 Rows for Message Parts in Container Messages

When you are working with a container message that holds rowset-based message parts, you can specify the minimum and the maximum number of level 0 rows for each message part.

When you are working with a container message, the Message Definition page, the Parts grid displays the following fields:

Example: Message XML when Maximum Occurs is Set to a Non-Default Value

The section contains a example of a container message with three message parts: QE_PART_1, QE_PART_2, and QE_PART_3.

Each part contains only one record (level 0 record).

As described earlier in this section, the Maximum Occurs value is 1 by default.

In the following example QE_PART_1 is defined on the container with a Maximum Occurs value of 2 and what is actually published in this case is two rows on the level 0 record for QE_PART_1, as shown in the example.

<?xml version="1.0"?>
<QE_PARTS xmlns="http://xmlns.oracle.com/Enterprise/Tools/schemas/
  QE_PARTS.VERSION_1">
  <QE_PART_1>
    <QE_NAVIGATION class="R" xmlns="http://xmlns.oracle.com/Enterprise/
      Tools/schemas/QE_PART_1.VERSION_1">
      <QE_ACNUMBER>100</QE_ACNUMBER>
      <QE_WAYPOINT_NBR>10</QE_WAYPOINT_NBR>
      <QE_BEARING/>
      <QE_RANGE/>
      <QE_ALTITUDE/>
      <QE_LATITUDE/>
      <QE_LONGITUDE/>
      <QE_HEADING/>
      <QE_VELOCITIES/>
      <QE_NAVDESC/>
    </QE_NAVIGATION>
  </QE_PART_1>
  <QE_PART_1>
    <QE_NAVIGATION class="R" xmlns="http://xmlns.oracle.com/Enterprise/
      Tools/schemas/QE_PART_1.VERSION_1">
      <QE_ACNUMBER>100</QE_ACNUMBER>
      <QE_WAYPOINT_NBR>20</QE_WAYPOINT_NBR>
      <QE_BEARING/>
      <QE_RANGE/>
      <QE_ALTITUDE/>
      <QE_LATITUDE/>
      <QE_LONGITUDE/>
      <QE_HEADING/>
      <QE_VELOCITIES/>
      <QE_NAVDESC/>
    </QE_NAVIGATION>
  </QE_PART_1>
  <QE_PART_2>
    <QE_RADAR_PRESET class="R" xmlns="http://xmlns.oracle.com/Enterprise/
      Tools/schemas/QE_PART_2.VERSION_1">
      <QE_ACNUMBER>2</QE_ACNUMBER>
      <QE_RADAR_SELECTION>1</QE_RADAR_SELECTION>
      <QE_RADARMODE>TWS</QE_RADARMODE>
      <QE_RADAR_OPERMODE>N</QE_RADAR_OPERMODE>
      <QE_BARSCAN>4B</QE_BARSCAN>
      <QE_RADARRANGE>40</QE_RADARRANGE>
      <QE_TGTAGE>8</QE_TGTAGE>
      <QE_CHANNELSET>B</QE_CHANNELSET>
      <QE_AZIMUTH>80</QE_AZIMUTH>
      <QE_PRF>H</QE_PRF>
    </QE_RADAR_PRESET>
  </QE_PART_2>
  <QE_PART_3>
    <QE_ARMAMENT class="R" xmlns="http://xmlns.oracle.com/Enterprise/Tools/
      schemas/QE_PART_3.VERSION_1">
      <QE_ACNUMBER>2</QE_ACNUMBER>
      <QE_STATION_NBR>1</QE_STATION_NBR>
      <QE_AGMODE>CCIP</QE_AGMODE>
      <QE_BIT>SBIT</QE_BIT>
      <QE_WEAPONSPECS/>
    </QE_ARMAMENT>
  </QE_PART_3>
</QE_PARTS>

Adding Message Parts to Container Messages

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

Use the Messages - Message Definitions page to add message parts to a container message. 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 (IB_MESSAGE_PARTS) 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. Select PeopleTools, Integration Broker, Integration Setup, Messages.

2. Select a container message to which to add message parts.

   The Messages - Message Definitions page appears.

3. Click the Add Parts link.

   The Add Parts page appears.

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

5. Click the OK button.

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

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

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

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

9. In the Unbound Maximum drop-down list, select whether to include all level 0 rows from the part in the container message.

   Note. If you select Y, note that the Maximum Occurs field no longer displays on the page, as all rows are included in the container message.

The Minimum Occurs, Maximum Occurs and Unbound Maximum fields are described elsewhere in this section.

See Understanding Including Level 0 Rows for Message Parts in Container Messages.

Adding and Getting Container Messages Attributes

This section discusses how to:

• Add the language code of the message sender as an attribute to a container message.

• Add attribute names to a container message.

• Populate attribute values for container message attributes.

• Get attribute names and values from a container message.

This section also provides a summary of PeopleCode that you can use to populate attribute values and get attribute data from container messages.

Understanding Adding, Populating, and Getting Container Message Attributes

You can add attributes to container messages that contain rowset-based message parts to provide integration partners with data and information, without adding the information to the message definition.

To add attributes to a container message, you first define the attribute name, length, and required flag in the container message definition in the PeopleSoft Pure Internet Architecture. This information appears in generated container message schema. At runtime the attributes appear at the root level of the generated XML. Next you use PeopleCode to populate the attribute values using the IBInfo object. At runtime, PeopleSoft Integration Broker validates the attribute values against the lengths you defined in the container message definition.

PeopleSoft provides a number of IBInfo object methods to get attributes from container messages.

Adding Language Codes of the Message Senders as Attributes to Container Messages

The language code of the user who executed the publish or sync request is a common attribute to add to a container message. As such, PeopleSoft provides an Include Language Code attribute box, that when selected automatically includes the information as an attribute name and value in the container message.

The Include Language Code attribute box appears on the Container Attributes page shown in the following example:

To add the language code of the message sender as an attribute:

1. Access the Container Attributes page (PeopleTools, Integration Broker, Integration Setup, Messages and click the Container Attributes link).

2. Select the Include Language Code box.

3. Click the OK button.

4. The Messages–Message Definitions page appears.

Adding Attribute Names to Container Messages

After you add one or more rowset-based message parts to a container message and save the message, a Container Attributes link appears on the Messages-Message Definition page under the Message Type group box. When you click the Container Attributes link, the Container Attributes page (IB_MESSAGE_ATT_SEC) shown in the following example appears:

To add an attribute name to a container message:

1. Access the Container Attributes page (PeopleTools, Integration Broker, Integration Setup, Messages and click the Container Attributes link).

2. In the Attribute Name field, enter a name for the attribute.

3. In the Length field, enter a numeric field length value.

4. (Optional.) Check the Required box if you want the attribute name to be required.

5. Click the OK button.

   The Messages–Message Definitions page appears.

Populating Attribute Values for Container Message Attributes

PeopleSoft provides several IBInfo object methods within the Message object to populate container message attributes.

Here is an example of how to populate attributes. The attribute values will be validated at runtime against the defined lengths.

&MSG = CreateMessage(Operation.MY_SVC_OPERATION);

&ret = &MSG.IBInfo.AddContainerAttribute("MessageImportance", "Medium");
&ret = &MSG.IBInfo.AddContainerAttribute("DeveloperID", "mdawson");

Additional IBInfo objects that you can use for working with container message attributes are described elsewhere in this section.

Getting Attribute Names and Values from Container Messages

PeopleSoft provides several IBInfo object methods within the Message object to Get attribute information from container messages.

Note that if you attempt to read attributes within an Integration Broker event, such as OnNotify, OnRequest, and so on, you must first Get a part rowset to load the attributes into the Message object from the XML.

The following code snippet shows one example of how to read attributes from a container message:

RowSet = &MSG.GetPartRowset(1);
&index = &MSG.Ibinfo.GetNumberOfContainerAttributes();

For &i = 1 To &index
   
   &attrName = &MSG.Ibinfo.GetContainerAttributeName(&i);
   &attrValue = &MSG.Ibinfo.GetContainerAttributeValue(&i);
   
End-For;

Additional IBInfo objects that you can use for working with container message attributes are described elsewhere in this section.

Summary of PeopleCode Use for Working With Container Message Attributes

The following table summarizes the PeopleCode methods that you can use for working container message attributes.

&Integer = &MSG.IBInfo.GetNumberOf⇒
ContainerAttributes();

&String = &MSG.IBInfo.GetContainer⇒
AttributeName(Integer nIndex);

&String = &MSG.IBInfo.GetContainer⇒
AttributeValue(Integer nIndex);

&Bool = &MSG.IBInfo.AddContainer⇒
Attribute(string name, string⇒
 value);

&Bool = &MSG.IBInfo.DeleteContainer⇒
Attribute(string name);

&MSG.IBInfo.ClearContainer⇒
Attributes();

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. To access the page, select PeopleTools, Integration Broker, Integration Setup, Messages and click the Schema tab.

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.

Managing Document Messages

After you add a document message to the system, you manage the document using the Document Builder and the document utilities.

See Also

PeopleSoft Documents Technology Preface

Viewing Service Operations that Reference Messages

Use the Service Operation References page (IB_MESSAGE_SO_SEC) to view a list of service operations that contain a message. The Messages-Message Definitions page provides a link to this page. To access the page, select PeopleTools, Integration Broker, Integration Setup, Messages, and click the Service Operation References link.

The following example shows the Service Operation References page:

The following page elements appear on the Service Operation References page:

Resolving Inconsistencies in Exported WSDL and WADL Documents

This section discusses how to:

• View service operations with exported WSDL or WADL inconsistencies.

• Clear exported WSDL/WADL status flags.

Understanding Using Project Copy and Exported WSDL and WADL

When you generate WSDL or WADL for a service operation, the system sets an internal flag on the service operation that indicates that WSDL/WADL has been generated or exported for the specific service operation.

The system uses the same repository for WSDL and WADL documents. The WSDL metadata object is used for project copy of WSDL and WADL. There is no WADL metadata object only WSDL.

You may later decided to use Project Copy to copy the service operation to a new database. But you may decide not to or simply neglect to copy the exported WSDL or WADL to the new database.

Even though you have not copied the WSDL/WADL to the new database, the internal flag that says WSDL/WADL has been generated is still set on the service operation. As a result, the system expects WSDL/WADL to exist in the new database, when it does not. When this condition exists, the system displays a status message on the message definition(s) of messages referenced in the service operation.

When this condition exists, the options are:

• Clear the internal WSDL/WADL exported flag on the service operation.

  Information about how to perform this task is discussed in this section.

• Use Project Copy to copy the WSDL/WADL to the new database.

  See Copying Projects and Definitions.

• Regenerate the WSDL/WADL on the new database using the Provide Web Service wizard.

  See Providing Services.

Viewing Services Operations with Exported WSDL/WADL Inconsistencies

If the system detects a WSDL/WADL flag inconsistency, the following status message appears on the Messages-Message Definitions page for those message definitions referenced in the service operation for the WSDL/WADL in question:

Exported WSDL flag inconsistency detected. WSDL does not exist.

The following graphic shows an example of the Messages-Message Definitions page displaying the status message:

In addition, an Exported WSDL Inconsistency link appears on the Messages-Message Definitions page. Click this link to view the Exported WSDL Inconsistencies page (IB_HOME_PAGE7_SEC). The following graphic shows an example of the page:

The page displays service operations that exist in the database that are flagged as having WSDL/WADL exported, yet no WSDL/WADL exists in the database for them. The Exported WSDL Inconsistencies page features a Service Admin link. Clicking the link opens the Service Administration-WSDL page (IB_HOME_PAGE7). The Service Administration-WSDL page provides a options to clear internal exported WSDL flag.

Clearing Exported WSDL/WADL Status Flags

The Clear WSDL Status page (IB_HOME_PAGE7_SEC) enables you to clear the internal exported WSDL/WADL status flag for service operations that contain specific messages, or for all service operations in the database.

Note. Clearing the internal exported WSDL/WADL status flag on a service operation is one way to resolve a WSDL/WADL flag inconsistency. Other options for resolving this condition are discussed elsewhere in this chapter.

See Understanding Using Project Copy and Exported WSDL and WADL.

The following example shows the Clear WSDL Status page:

Up to this point, this section has demonstrated accessing the Clear WSDL Export Status page starting from the Export WSDL Inconsistency link on a message definition, and then clicking on the Service Admin link from the Exported WSDL Inconsistencies page. When you access the page using this navigation, only the service operations that reference the message definition that you were originally viewing on the Messages-Message Definitions page appear. Further, those service operations that appear are those that are flagged has having WSDL/WADL exported, but for which there is none in the database.

You can also clear the WSDL/WADL export status flag for all service operations in the database that are in the inconsistent state of having been flagged as having WSDL/WADL generated, but no WSDL/WADL exists in the database for them. You can do so by accessing the Service Administration-WSDL page and clicking the Clear WSDL Export Status link. The Clear WSDL Export Status page appears populated with all service operations in the database that have inconsistent WSDL.

The following example shows the Clear WSDL Export Status page accessed from the Clear Export Status link on the Service Administration-WSDL page.

To clear the WSDL/WADL exported status flag:

1. Access the WSDL Export Status page using one of the following methods:

   • From a message definition that displays the “Exported WSDL flag inconsistency” status message: Click the Exported WSDL Inconsistency link. The Exported WSDL Inconsistencies page appears. Click the Service Admin link.

   • From the PeopleTools menu: Select PeopleTools, Integration Broker, Service Utilities, Service Administration. The Service Administration page appears. Click the WSDL tab. Click the Clear WSDL Export Status link.

      

2. Click the Clear Export Status button.

Renaming and Deleting Message Definitions

You can rename and delete messages using the Messages page (IB_HOME_PAGE5) 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 Configuring PeopleSoft Integration Broker for Handling Services.

Renaming Message Definitions

To rename a message definition:

Note. Renaming a message definition renames all versions.

1. Access the Services Administration - Messages page.

   Select PeopleTools, Integration Broker, Service Utilities, Service Administration. Click the Messages tab.

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

When you delete a message definition the system also deletes it's associated schema.

To delete a message definition:

1. Access the Services Administration - Messages page.

   Select PeopleTools, Integration Broker, Service Utilities, Service Administration. Click the Messages tab.

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.