Difference Between MsgGet, MessageBox, & MsgGetText PeopleCode Functions

 

MsgGet(message_set, message_num, default_msg_txt [, paramlist])

Use the MsgGet function to retrieve a message from the Message Catalog and substitutes in the values of the parameters into the text message.

You can access and update messages on Message Catalog page (select PeopleTools, Utilities, Administration, Message Catalog). You can enter message text in multiple languages. The Message Catalog also enables you to enter more detailed "Explain" text about the message. The message_set and message_num parameters specify the message to retrieve from the catalog. If the message is not found in the Message Catalog, the default message provided in default_msg_txt is used. Message sets 1 through 19,999 are reserved for use by PeopleSoft applications. Message sets 20,000 through 32,767 can be used by PeopleSoft users.

The MsgGet function retrieves a message from the PeopleCode Message Catalog and substitutes
in the values of the parameters into the text message.
Example: &MsgText = MsgGet(40000, 2, "Message not found");

MessageBox
Retrieves messages from the Message Catalog but provides the
flexibility to change the severity of a message through the Message
Catalog, without modifying PeopleCode.

MessageBox(style, title, message_set, message_num, default_txt [, paramlist])
Example: MessageBox(0, "", 40000, 1, "Message not found", BUS_EXPENSE_PER.EMPLID, BUS_EXPENSE_PER.EXPENSE_PERIOD_DT);

MsgGetText is very similar to MsgGet except the message set and message number will not appear after the text of the message.

MsgGetText(message_set, message_num, default_msg_txt [, paramlist])
Example: &MsgText = MsgGetText(40000, 2, "Message not found");

The message text is limited to a maximum of 100 characters. You can pass bind values (%1, %2, %3 ... %n) to the message text using PeopleCode functions like MsgGet, MsgGetText and MessageBox. However MsgGetExplainText is to pass bind values to the explain text and not the message text.

Integration Broker Monitoring

 The PeopleTools Integration Broker has some built in tables and pages that allow you to inspect the content of messages and respond to errors. The PeopleSoft components to view this data are broken down by:

• Asynchronous
  • Overview Page: PeopleTools > Integration Broker > Service Operations Monitor > Monitoring > Asynchronous Services
  • Detail Page: PeopleTools > Integration Broker > Service Operations Monitor > Monitoring > Asynchronous Details
• Synchronous
  • Overview Page: PeopleTools > Integration Broker > Service Operations Monitor > Monitoring > Synchronous Services
  • Detail Page: PeopleTools > Integration Broker > Service Operations Monitor > Monitoring > Synchronous Details

These components offer different functionality for asynchronous versus synchronous operations and errors. The reasons for the different functionality may not be completely obvious to someone who has not worked with Integration Broker for any length of time. We will go into detail on each monitoring component and what you can and cannot do.

Asynchronous Monitor

The Asynchronous monitor gives you a view into the Asynchronous Integration Broker tables. These tables are used to store the message data that was posted to PeopleSoft or that needs to be published to external systems. It also stores the status and state of the subscription contracts and the publication contracts. Since Asynchronous Service Operations act like a “drop box” to the integration broker this data has to be stored so they can be processed in a queue at some point in the future.

First, let’s look at the overview page for Asynchronous service operations.

PeopleTools > Integration Broker > Service Operations Monitor > Monitoring > Asynchronous Services

You have to be very mindful when looking at this monitor and have some understanding of how asynchronous service operation work which are very different than synchronous service operations. You have to keep the following in mind.

• When an external system post to an asynchronous service operation an Operation Instance is created. This is the drop box. Once the data is stored the IB will respond back to the client with only an acknowledgement.
• Application server processes specific the IB continually poll for new work. These processes are generally referred to as “pub/sub” by system administrators.
  • If these pub/sub instance are active and the queue for the service operating is NOT paused then the pub/sub processes will inspect each operation instance.
• The pub/sub processes will look at each new operation instance and determine if and how many publication contracts and subscription contracts should be created.
• Once the pub and sub contracts are created they are going to be processed at some later point based on several factors like the status of the queue, errors in the queue and the amount of work in the queue.

The status of each of these contracts has to be inspected separately in the monitor:

• Operation Instances
• Subscription Contracts
• Publication Contracts

The first tab in the component gives you a count of all the service operations in those statuses. You can click the count which will take you to a filtered view of those in the other tables on the component. This will allow you to drill into the detail which we will cover.

Operation Instances Overview

In the following screenshot, we are looking at the Operation Instances view as determined by the “queue level” drop down. This is often the least helpful view into the monitor. If everything is working properly, then you should see everything in DONE status. The only time you will see issues is if a queue is paused or the pub/subs are not active. In this latter case, those service operations will be in “new” status. I don’t often seen other statuses on this page. The publication and subscription views is where you will spend most of your time.

Common Operation Instance Statuses:

• New - These are new to the integration broker and have not been processed to create subscription and publication contracts yet.
  • If messages never leave this status then you need to ensure the queue is not paused or your pub/sub domains are active.
  • If you have a high volume operation or have some batch process creating a lot of messages you can see the operation instances have a large number of operations in new status until the application server process can catch up.
• Done - These are operation instances that have been processes and pushed to any publication or subscription contracts. Those contacts have their own status and are processed later.
  • Do not get confused by this status. Operation instances in Done status do not mean the local system has subscribed to the message or that remote systems have received the message. It just means the contract has been created.

Subscription Contracts Overview

In the next screenshot, we have changed the queue level to sub contracts and this will display the summary of all the subscription contracts in the system. In this example, everything is “clean” and in done status.

What sort of statuses would you see on a subscription contract and what can you do? Let’s go over the most common. We are going to intentionally leave a few out that are NOT common.

Subscription Contracts Common Statuses:

• Error - A subscription handler (normally PeopleCode) failed processing the message contents. The error is dependent on the handler. It could be anything from SQL, security or configuration issues. You can drill into the detail to determine the error.
• New - These are new subscription contracts that are waiting to be processed. They will eventually be processed depending on the queue partitioning setup.
• Started - These are subscription contracts that have started to process. They will not stay in this status very long.
• Working - These are subscription contracts that are actively running and processing code.
• Done - These are processed and completed contracts.
• Retry - These are contracts that were resubmitted and are retrying
• Timeout - Subscription contracts that may have hit a timeout limit. To be honest I can’t remember if I have ever seen this on a subscription contract. If you have some DB lock or infinite loop in the handler you could see this.
• Edited - If a message failed you can edit the contents of the message in the detail section. If you have done that and NOT resubmitted it, they will reflect this status.
• Cancelled - These are subscription contracts that someone cancelled. (See section below about cancelling messages.)

Publication Contracts Overview

The next screenshot has the “publication contracts” selected. In this screenshot, we have 1 in error and 2 in new. The way this queue is setup that one error will prevent all other messages from processing. It acts as a roadblock and no other messages in that queue will process until the failure is cleared.

Publication Contracts Common Statuses:

• Error - A publication contract failed and could not be processes
  • There could be many reasons like the receiving system is down or it rejected the message.
  • If the system is temporarily down then you can easily just resubmit these.
• New - These are new publication contracts that are pending to be sent to a remote system. They will eventually be processed depending on the queue partitioning setup (TODO: Link in article).
• Started - These are publication contracts that have started to process. They will not stay in this status very often.
• Working - These are publication contracts that are actively running and contacting the external system.
• Done - These are processed and completed contracts.
• Retry - These are contracts that were resubmitted and are retrying
• Timeout - Publication contracts that may have hit a timeout limit.
  • You can generally try to resubmit theses.
• Edited - If a message failed out you can edit the contents of the message in the detail section. If you have done that and NOT resubmitted it, they will reflect this status.
• Cancelled - These are publication contracts that someone cancelled. (See section below about cancelling messages.)

Asynchronous Details

The Asynchronous Details page allows you to view the detail on what work occurred for a particular instance of a message. If you know the GUID of the message, you can navigate straight to the detail page.

PeopleTools > Integration Broker > Service Operations Monitor > Monitoring > Asynchronous Details

However, you will often link to the details page from the overview page. In this screenshot, we are looking at a publication contract error. By clicking the details link you will be taken to the details of that operation.

The detail page for one service operation is shown below.

The detail page loads information about one single operation instance. This was on “post to the drop box”. Every Service Operation is setup different and every PeopleSoft institution does something different with their publications. Let’s look at our example and see what we can see about this operations.

• The top section I highlighted in red, is information about the Operation Instance.
  • You can view the raw XML (or other payload) that was posted into the service.
  • You can also view the operation instance status.
  • This red section is normally not very useful because operation instances are just the drop box. The real work gets done on the publication and subscription contracts.
• The section I highlighted in green, are the publication contracts.
  • If the operation does not have any contracts this grid will be hidden. Additionally, if the pub/subs are down or the queue is paused the publication contracts have not been created yet. So this grid will NOT be visible.
  • There will be one row for every publication that needs to occur. In this screenshot, there is only one node that is going to receive this message. If you had your system setup to publish to 5 different nodes, there would be 5 rows there.
  • If the publication was in a failure status, you can drill into the details here to view the error message.
• The section in yellow are the subscription contracts.
  • If the operation does not have any contracts this grid will be hidden. Additionally, if the pub/subs are down or the queue is paused the subscription contracts have not been created yet. So this grid will NOT be visible.
  • An operation can have any number of subscription contracts. You generally just see one for inbound integration. However, there are many use cases where you may want more than one subscription handler to trigger. This screenshot shows where there are 2 handlers running.
  • If one of the subscription handlers was in a failure status, you could view the messages here. There are many times that the errors messages can be extremely vague from many of the delivered handlers especially if they are doing updates with component interfaces.

Synchronous Monitor

The Synchronous monitor has limited functionality. Remember that the interaction with a synchronous is real-time. If there is a failure, then the failure is reported back to the client in real time. That attempted interaction is done and it cannot be recreated.

• There is nothing for an Administrator to do to take action on Synchronous errors. There are more for later logging or troubleshooting a client sending in “bad” requests. If the message is in ERROR, there the only thing you can do is “archive” the message.
• Additionally, most Synchronous service operations do NOT have logging turned so you will often not see anything on the monitor even though you may be pushing thousand of synchronous operations.
  • The routing configuration of the operation controls if the header and/or the body is logged.
  • Failures are always logged.

The overview page is here:

PeopleTools > Integration Broker > Service Operations Monitor > Monitoring > Synchronous Services

When you drill into the detail you will get here:

PeopleTools > Integration Broker > Service Operations Monitor > Monitoring > Synchronous Details

This page allows you to view the inbound message as well as archive it.

Cancelling Asynchronous Messages

If you do not have this knowledge then be very wary of cancelling messages on the subscription queue. If another message comes in behind that message for the same piece of data it can cause data corruption as generally messages need to process in order. If you cancel a message it will “release” the other messages to process. In some service operations there is no way to reproduce the message again in the publishing database if you cancel the message. In other cases it can be trivial to produce the exact same message again.

PeopleTools tables

Here are a listing of PeopleTools tables involved in the IB.

• PSAPMSGPUBHDR
• PSAPMSGPUBDATA
• PSAPMSGPUBCON
• PSAPMSGSUBCON
• PSAPMSGPUBERR
• PSAPMSGPUBERRP
• PSAPMSGPUBCERR
• PSAPMSGPUBCERRP
• PSAPMSGSUBCERR
• PSAPMSGSUBCERRP
• PSAPMSGPCONDATA
• PSAPMSGSCONDATA
• PSIBERR
• PSIBERRP
• PSIBDEBUGLOG
• PSAPMSGIBATTR
• PSIBAEATTR
• PSAPMSGDOMSTAT
• PSAPMSGDSPSTAT
• PSIBLOGHDR
• PSIBLOGDATA
• PSIBLOGERR
• PSIBLOGERRP
• PSIBLOGIBINFO

Troubleshooting

• All operations are in “NEW” Status"
  • Make sure the queues are not paused
  • Make sure the pub/subs are active. 
• I am not seeing anything in the Subscription contracts for a message that as posted.
  • Make sure your handlers are active and make sure you have inbound or local to local routings.
• I am not seeing the message get into the publication contracts
  • Make sure your publication contracts are active
• I am not seeing any messages in the Synchronous monitor
  • The service operation does not have any logging turn on. Check the routing to ensure there is at least header logging

Application Engine Action Plugins – The Complete Guide

 An Application Engine Action Plugin is a relatively new PeopleTools feature that can be used to alter SQL or PeopleCode actions in any App Engine program.

Say you have a delivered App Engine A and want one of the PeopleCode actions in it to behave differently.

Traditionally, in this case, you would customise the delivered code.

But as we all know, this approach will turn out to be costly during upgrades.

Instead, let’s look at a different approach.

You write the desired code into a PeopleCode action in a new custom App Engine B.
Then put some configuration in place so that the PeopleCode in App Engine B gets executed instead of the PeopleCode in A.

Instead of completely replacing the delivered code, you may choose to have your code executed before or after the delivered code as well.

This is what an App Engine action plugin lets you do.

You can do this for SQL actions as well.

So this is similar to Event mapping but for App Engines.

Configuring App Engine Action Plugin

App Engine plugins can be configured online through the AE Action Plugins page.
Navigation: PeopleTools > Application Engine > AE Action Plugins

Open the App Engine that needs to have a plugin configured.

Select the Section, Step and Action that needs a plugin.

Now, Select the Plugin App Engine, its Section, Step and Action

Select the Mode

The plugin can be configured to execute before or after the execution of the existing code. The plugin can also replace the existing code. These are configured through the Mode field.

If the same Section/Step/Action of an App Engine has a plugin each configured for Modes Before, After and Replace, upon save, these rows would be sorted to have the Before row first, then the Replace row and then the After row.

Order within Mode

This field is relevant only when configuring more than one plugin for the same Section/Step/Action of an App Engine for execution using the same Mode. When this is the case, ‘Order within Mode’ becomes mandatory and the order of execution is decided by this field.

What configurations are allowed?

The plugin action type needn’t match the action type you selected for configuration. This means you can replace an SQL action with PeopleCode or vice-versa.

*Action Y/Action X can both or either be SQL or PeopleCode.

Action plugins are not intended to add new sections/steps to an existing program. But you can have multiple plugin actions for an action type that you have selected for configuration. So you can replace an SQL action with more than one SQLs, PeopleCode or a combination of these.

The same plugin action can be configured for multiple App Engine Actions.

Application Libraries

Application Libraries are Applications Engines without the Main Section. These can only be called from another App Engine.

AE Plugins are compatible with Application Libraries.

Call Section Action and SQL Action

In App Engines, within a Step, Call Section Action and SQL Action are mutually exclusive. However, I noticed that this is not enforced while using an AE Action plugin.

For example, you can have a Step with a PeopleCode Action and Call Section Action. You then configure a plugin to replace the PeopleCode Action with an SQL Action from another App Engine.

Now you essentially end up with an SQL Action and a Call Section Action within the same step of the original program.

What configurations are not allowed?

An App Engine Action that already has a plugin configured cannot be used as a plugin.

A plugin cannot be configured for an App Engine Action that is already being used as a plugin.

These are enforced even when an entry is not marked as Enabled.

How does it show up in App Designer?

I’ve configured some plugins for my test App Engine. Let’s look at how this is displayed within App Designer.

Definition view

There are no indicators in the Definition view to alert the developer that the App Engine has a plugin configured for an Action. It would have been helpful to have this at the AE Level.

Program Flow view

The Program Flow shows a red flash on the PeopleCode or SQL actions that have plugins configured.

Code Pane

The code pane uses colour coding to visualise how the plugin is altering the code.

If the changes don’t show up in the program flow, purging cache directories from the Configuration Manager can help.

Sharing State Records and Temporary Tables

The State records and Temp tables of the configured App Engine are available for use within the Plugin Action.

Tracing

When an App Engine that has a plugin configured is traced, the entire process (including the plugin) is traced.

Related System Variables

%AECallerApplId
Within an App Engine plugin, this system variable can be used to identify the App Engine that has invoked the plugin.
This could be useful when a plugin is used in more than one App Engine and you need to know where it was called from to trigger some specific logic.

Organising App Engine Action Plugins

Naming suggestion

To easily identify an App Engine Action Plugin, I’ve been adding _PLG to the name – for example RX_TACLD_PLG

Although a plugin can be reused with multiple App Engines, for our use cases so far, I’ve been creating a 1:1 relation – that is, one Plugin App Engine for every App Engine that is configured.

Within the plugin, I also use the same Section/Step name as the configured App Engine where possible.

Identifying changes during a PUM Upgrade

There is no Application Lifecycle Management (LCM) support yet for App Engine Action plugins. It would have been good for the compare reports to be aware of the existence of the AE action plugin and show some sort of indication to alert the developer looking at them.

In the absence of LCM support, we will have to put some development practices in place to easily identify the affected AEs during a PUM upgrade.

A simple SQL to query the AE Plugin table + Project item table to get a list of project items that have plugins configured would be a good start.

SELECT PRJ.PROJECTNAME, PLG.AE_APPLID, PLG.PTAE_SECTION, PLG.PTAE_STEP, PLG.PTAE_ACTION_TYPE FROM PSPROJECTITEM PRJ, PS_PTAE_ACT_PLUGIN PLG WHERE PRJ.PROJECTNAME = '<Your PUM project name>' AND ((PRJ.OBJECTTYPE = 30 AND REPLACE(PRJ.OBJECTVALUE1, ' ', '') = PLG.AE_APPLID ||PLG.PTAE_SECTION ||PLG.PTAE_STEP ||PLG.PTAE_ACTION_TYPE) OR (PRJ.OBJECTTYPE = 43 AND PRJ.OBJECTVALUE1 = PLG.AE_APPLID AND TRIM(SUBSTR(PRJ.OBJECTVALUE2, 1, 8)) = PLG.PTAE_SECTION AND PRJ.OBJECTVALUE3 = PLG.PTAE_STEP AND PRJ.OBJECTVALUE4 = 'OnExecute') ) ;

Migrating App Engine Action Plugins

The configurations for App Engine plugins can easily be migrated using the Data Migration Workbench.

The data set name for
Application Engine Action Plugins is PT_AE_ACTION_PLUGIN

After adding PT_AE_ACTION_PLUGIN, search for the Program and select the required plugins.

Add this to your Data Migration Workbench project and you are ready to copy the DMW project to a file!

Conclusion

Application Engine Action Plug-ins are a great way to isolate customisations. Together with Even mapping and Page and Field configurator, these can go a long way in speeding up your upgrades and thereby reducing your Total Cost of Ownership.

During upgrade time, be mindful that there is no LCM support for AE action plugins yet. Until this is available, a SQL may be used to identify App Engines that have plugins configured.