Using the Message Schema Builder

This chapter provides an overview of the Message Schema Builder and describes how to:

• Set permissions for accessing the Message Schema Builder.

• Select and view data in the Message Schema Builder.

• Build message schemas for rowset-based messages.

• Import message schemas for nonrowset-based messages.

• Modify message schemas.

• Validate message schemas at runtime.

Understanding the Message Schema Builder

The Message Schema Builder enables you to build, import, modify and delete XML message schemas.

Note. The terms message schema, XML message schema, and schema are used interchangeably in this chapter.

In addition, you can use the Message Schema Builder to enable runtime schema validation for specific messages and message versions.

To test message schemas during development, use the Schema Tester utility.

See Also

Using the Schema Tester Utility

Message Schemas

An XML message schema describes a model for the arrangement of tags and text in a valid XML document. A schema provides a common vocabulary for a particular application that exchanges documents.

Building, Importing, Modifying and Deleting Message Schemas

You can use the Message Schema Builder to build message schemas for rowset-based messages in the application database.

In addition, you can use the Message Schema Builder to import message schemas into PeopleSoft Integration Broker to associate them with nonrowset-based messages, as well as modify those schemas.

You can use the Message Schema Builder to delete message schemas associated with rowset and nonrowset-based messages.

Validating Messages Against Message Schemas

Validating messages against message schemas can ensure that during integration development, no changes or deletions were inadvertently made to a record. You can use schema validation on outbound and inbound messages, provided that you enable schema validation.

During runtime schema validation, PeopleSoft Integration Broker checks messages to ensure that the XML structure is valid according to the specified message schema. If Integration Broker encounters a message with a message structure that does not adhere to the specified message schema, message delivery fails and Integration Broker generates an error message on the target application server. You can view the error details on the source application server, using the Message Details Error tab in Integration Broker Monitor.

When schema validation is enabled the structure of a message cannot be changed.

Setting Permissions for Accessing the Message Schema Builder

You should limit access to the Message Schema Builder to users with the role Integration Administrator.

To limit access to the Message Schema Builder, remove the component (IB_SCHEMABUILD) from permission list PTPT1200. The component is in the menu APPMSGMONITOR. Then, create a new permission list that contains only the IB_SCHEMABUILD component and assign it to the Integration Administrator role. As a result, only users assigned to the Integration Administrator role will be able to enable or disable schema validation or replace schemas.

Selecting and Viewing Data in the Message Schema Builder

When you access the Message Schema Builder, a search engine displays that you use to search for messages and message schema data with which to work and view.

To access the Message Schema Builder, select PeopleTools, Integration Broker, Integration Setup, Message Schema Builder.

Selecting Data in the Message Schema Builder

The Message Schema Builder provides the following options for searching for data with which to work and view in the application database.

Viewing Message Schema Builder Data

This section discusses viewing Message Schema Builder data, including message details and schema data.

Viewing Message Details

When you search for data in the Message Schema Builder, message detail results appear in the Message Schema grid.

Message	Message name returned from the search of the application database.
Version	Version of the message returned from the search of the application database.
Structured	Indicates the structure of the message. The valid values are: Yes. Indicates that the message is a structured rowset-based message. No. Indicates that the message is an unstructured nonrowset-based message.
Exists	Indicates whether a schema has been built for the message. The valid values are: Yes. A schema has been built for the message. No. A schema has not been built for the message.
Updated On	Timestamp of the last update of the record. A new timestamp displays when a schema is generated or deleted for a message.
Build Results	Displays the results of actions performed on a schema.
Validate	Indicates whether schema validation is enabled for the selected message. The valid values are: Yes. Schema validation is enabled for the message. No. Schema validation is not enabled for the message.
Enable Validation/Disable Validation	Click the toggle button to enable validation if disabled, or disable validation if enabled. When validation is enabled the message is locked. You can add and modify any PeopleCode associated with the record, but you cannot add or change record or field values, add or modify versions of the record, and so on..
Build Selected Schemas	Click the button to build schemas for the selected messages.
Delete Selected Schemas	Click the button to delete schemas that exist for the selected messages.

Viewing Message Schema Data

If a message schema exists for a message, click the message name in the Message Schema grid to view the schema details.

Note. For easier viewing, highlight the data with your cursor.

Message schemas for rowset-based messages are read-only. Message schemas for nonrowset-based messages are editable.

Building Message Schemas for Rowset-Based Messages

To build a message schema for a rowset-based message:

1. Search the application database for the message or messages for which to build schemas.

2. Check the box next to the message or messages for which to build schemas.

3. Click the Build Selected Schemas button.

When the schema is built successfully, a timestamp appears in the Updated On field and the Build Results field displays Successful Schema Build.

Importing Message Schemas for Nonrowset-Based Messages

To import schemas for nonrowset-based messages:

1. Use the Message Schema Builder search engine to locate the message for which you want to import a schema.

2. In the Message Schema grid, check the box next to the message for which you want to import a schema and click the message name link.

3. Import the schema.

   • Import a schema from a file.

     You can import a schema from a file by using the Upload Schema from File button and selecting the file to import. After you import the file, the contents displays in the Schema text box.

     Note. If you receive the error, “Error retrieving the file from database,” verify that one of the variables PS_FILEDIR or PS_SERVDIR is defined in the system variables on your machine.

   • Direct data entry.

     You can also enter the schema directly in the Schema text box.

4. Click the Save button.

   The Schema Builder page appears.

A timestamp appears in the Updated On field and the Build Results field displays Successful Schema Built.

Modifying Message Schemas

You can modify the content of message schemas built for nonrowset-based messages.

To modify a schema, you can edit it directly in the Message Schema Builder, or you can export to make changes.

To modify a schema in the Message Schema Builder:

1. Use the Message Schema Builder search engine to locate the message with which you want to work.

2. In the Message Schema grid, click the message name link.

   A new page displays with the message schema populated in a text box.

3. Modify the schema as needed.

   • Modify the schema directly in the text box, or

   • Modify the schema in the editor of your choice.

     Use your cursor to highlight the contents of the text box and use the keyboard command CTRL + C to copy the contents of the text box. Paste the contents into your editor using the keyboard command CTRL + V. Modify the content as needed. Import the content back into Message Schema Builder using the instructions described in the Building Message Schemas for Nonrowset-Based messages presented earlier in this chapter.

4. Click the Save button.

The Schema Builder page displays and the Updated On field displays the date and time of the modification, and the Build Results field displays the results of the new schema build.

Deleting Message Schemas

To delete message schema use only the Delete Selected Schemas button on the Schema Builder page. Do attempt to delete message schemas by deleting content in the Schema text box in the schema details view; if you save the changes, PeopleSoft Integration Broker will attempt to validate the blank schema at runtime.

To delete a message schema:

1. Select PeopleTools, Integration Broker, Integration Setup, Message Schema Builder.

   The Schema Builder page appears.

2. In the Message Schema section, check the boxes next to the message names that contain schemas you want to delete.

3. Click the Delete Selected Schemas button.

Validating Message Schemas at Runtime

This section provides an overview of how PeopleSoft Integration Broker validates inbound and outbound messages against message schemas at runtime and how to enable message schema validation.

Prerequisites for Validating Message Schemas at Runtime

Before you can enable message schema validation, you must build or import a message schema for the message and message version.

Understanding Validating Message Schemas at Runtime

You can enable message schema validation at runtime using the Message Schema Builder..

Message Schema Validation and PeopleCode Validation Precedence

Message schema validation and PeopleCode validation precedence is as follows.

• If schema validation is enabled for a message version and PeopleCode validation is enabled, the schema will be used for validation.

• If schema validation is enabled for a message version and PeopleCode validation is disabled, schema validation will occur.

• If schema validation is disabled for a message version and PeopleCode validation is enabled, when an event is run, PeopleSoft Integration Broker compares the message structure against the defined message structure. The validation can occur on the sending node or the receiving node, depending on the node that is running a PeopleCode message event.

• If schema validation is disabled for a message version and PeopleCode validation is disabled, no validation takes place.

Enabling Message Schema Validation at Runtime

This section discusses how to enable message schema validation at runtime.

Note. When working with synchronous messaging, you should enable schema validation for synchronous responses and synchronous requests to ensure that the data is loaded into the XML parser correctly.

To enable message schema validation at runtime:

1. In the Message Schema Builder, search for the message and version for which you want to enable validation.

2. In the Message Schema grid, click the Enable Validation button.

   The button label changes to Disable Validation and the Validate field displays Yes.

Viewing Schema Validation Status

When schema validation is enabled, you can view the enabled status is the PeopleSoft Pure Internet Architecture and in PeopleSoft Application Designer.

In the PeopleSoft Pure Internet Architecture, in the Message Schemas section of the Message Schema Builder page, the Validate field displays Yes when validation is enabled.

In PeopleSoft Application Designer on the message properties Use tab for the message, the Validate Structure group box features a read-only Schema field that is checked when validation is enabled.