Introduction to Message Objects

We introduced the Message object in the Terminology Section. Messages are an integral part of a service operation. They hold a pointer to the “payload” of the message for both the request and response. Often this is XML but it can be other encodings. A message is required on every service operation even if you are not using the full depth of functionality available in that object. You can make your messages an integral part of your service operation providing the encoding and decoding of data or have them as nothing but a “shell” and your handler PeopleCode can do all of the work. When integrating with non-PeopleSoft systems, I often just use “shell” (nonrowset) messages and do all the encoding and decoding in PeopleCode.

Messages are defined here:

A message object has a “type” defined when you create it. It cannot be changed later. Each message type has a different use case and different functionality. Additionally, the PeopleCode classes that you use to interact with the message in your handler will changed based on the type chosen. There are pros and cons of each message type and each has it’s own use case.

• Rowset - This is a message type that is backed completely by the structure of PeopleSoft records and rowset objects.
  • Consider using this type when you want to input or output data that is structured in the exact same format as the PeopleSoft table(s). However, for a non-PeopleSoft systems a container message with a rowset part is a better option.
  • This type is generally reserved for PeopleSoft to PeopleSoft syncs as the structure of the messages have some embedded metadata that PeopleTools automatically maintains.
  • This type is useful when transferring data between two PeopleSoft systems. This breaks down if you need to add custom XML attributes or XML nodes outside of what is on the tables.
• Nonrowset - This messages type is use when your want to have dynamic XML (or JSON) content.
  • Use this type when you want complete control over parsing or encoding the data in PeopleCode. You are responsible for creating the structure in validating input structure.
  • You can use this type of encode or decode any format that PeopleCode can handle: CSV, JSON, XML, etc.
• Container - This is a wrapping containing different “parts”. A container can only have either Rowset or nonRowset based parts. You can’t mix and match. I wish you could and this seems like a limitations that removes the usefulness of message parts. I have not found that this has been very useful.
  • Part Nonrowset - This is a reusable “part” that is not backed by tables. This is similar to the “Nonrowset” above.
  • Part Rowset - This is a reusable “part” that is not backed by tables. This is similar to the Rowset type above. However, this types does not come with the metadata attributes and the output format is slightly different.
  • I recommend this type if you are trying to send PeopleSoft data to external systems in the exact format as they exists on the database. If there is any variation in the field names or record names or you need to add new xml fields and attributes, this is NOT a good choice.
• Document - This is a message that is backed by the “Document” technology.
  • The “document” technology is a “new-ish” piece of functionality in PeopleTools. It was supposed to be used to encode or decode JSON. However, I have found that there are soooooo many issues with this and it does not give the API developer flexibility. It also cause redundant code violating the DRY principle.
  • I advise against using this type.

In the bullets above, I nested the “part” types under the container type. This is because a container is comprised of one or more “parts”. A “part” is not tied directed to a service operation. It is sort of like a building block.

In the sections to come we will look at how we can use these different types to encode and decode data.