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.