Implementing Handlers Using Application Engine Programs

This section provides and overview of implementing handlers using application engine programs and discusses how to:

  • Specify application engine implementation details.

  • Retrieve service operation content from application engine programs.

  • View subscription contract status.

Application engine handlers are available for notification events (OnNotify) and schedule an application engine program to run within PeopleSoft Process Scheduler to process service operation content. This handler is a good alternative for long-running programs or service operations that have large amounts of data to process, since processing is performed by PeopleSoft Process Scheduler and not in the PeopleSoft Integration Broker runtime environment.

After the service operation is invoked, you can track the process by viewing the subscription contract in the Service Operations Monitor.

When you implement a handler using an application engine program, you must retrieve the transaction ID that you use to get message data from within the application engine program. The run control record PSIBRUNCNTL is populated with the transaction ID prior to scheduling the actual application engine program. Note that it is not required to retrieve the transaction ID, therefore any application engine program can be scheduled that does not require initialization parameters via a run control table.

The process for implementing a handler using and application engine program is:

  1. Develop the application engine program.

    Developing application engine programs is discussed elsewhere in the PeopleTools product documentation.

    See Application Engine Overview

  2. Add a handler to the service operation.

    This process is discussed elsewhere in this topic.

    See Adding a Handler to a Service Operation.

  3. Specify general handler details.

    This process is discussed elsewhere in this topic.

    See Specifying General Handler Details.

  4. Specify application engine handler implementation details.

    This process is discussed in this section.

    See Specifying Application Engine Handler Implementation Details.

  5. Retrieve service operation content from the application engine program.

    This process is discussed in this section.

    See Retrieving Service Operation Content from Application Engine Programs.

  6. View subscription contract status.

    This process is discussed in this section.

    See Viewing Subscription Contract Status.

Before specifying application engine handler implementation details, you must first create the application engine program to process the service operation, add a handler to the service operation definition, and specify general handler details.

To specify application class implementation details:

  1. On the Service Operations – Handlers tab, in the Handlers section, click the Details link.

    The Action Details page appears.

  2. In the Program Name field, click the Lookup button to locate the name of the application engine program to use.

  3. Click the OK button.

  4. Click the Save button.

This section discusses how to:

  • Retrieve a transaction ID from an application engine program.

  • Instantiate a Message object using a transaction ID.

Understanding Retrieving Service Operation Content from Application Engine Programs

Within the application engine program, you can retrieve the transaction ID and thereby get an instantiated Message object to retrieve the content data respectively.

Retrieving Transaction IDs from Application Engine Programs

Use the GetIBTransactionIDforAE method on the %IntBroker object to get the transaction ID or simply write the SQL to retrieve the ID.

The following examples show how to get the transaction ID from an application engine program and instantiate a Message object.

Method from %IntBroker Object: 

StrTransaction = %IntBroker.GetIBTransactionIDforAE
(string OperID, string Run Control ID);

&MSG = %IntBroker.GetMessage(StrTransaction, %IntBroker_SUB);

Or, you can write code within a SQL step similar to the following:

%SelectInit(IBTRANSACTIONID) 
 SELECT IBTRANSACTIONID 
  FROM PSIBRUNCNTL 
 WHERE OPRID = %Bind(OPRID) 
AND RUN_CNTL_ID = %Bind(RUN_CNTL_ID)

Or, you can perform a simple SQLExec as follows:

SQLExec("select ibtransactionid from psibruncntl where oprid = :1 and
 run_cntl_id = :2",

j_book_aet.oprid, j_book_aet.run_cntl_id, &ibtransid);

Instantiating Message Objects Using Transaction IDs

The following code example shows how to instantiate a Message object using the transaction ID from an application engine program:

&MSG = %IntBroker.GetMessage(J_BOOK_AET.IBTRANSACTIONID, %IntBroker_SUB);

The following table lists the possible contract statuses that may display in the Service Operations Monitor when implementing a handler using an application engine program:

Service Operations Monitor Status

Description

Working

At runtime, the Service Operations Monitor shows a status of Working for the subscription contract when it is picked up by the subscription contract handler.

Submit

After the application engine program is scheduled successfully, the state of contracts changes to Submit in the Service Operations Monitor. This status indicates that the application engine program has been successfully submitted and a process instance has been returned.

Error

  • If the program does not get scheduled successfully, the status is set to Error

  • A Process Monitor status of Error will change the subscription contract status in the Service Operations Monitor to Error. You must read the error details from the Process Monitor Details page, since the Service Operations Monitor does not have access to the Process Monitor error tables.

Done

When the application engine program has been processed successfully, the status of the contract in the Service Operations Monitor is Done.

Cancel

  • For application engine programs that have Process Monitor status of Cancel or Delete, the status of the subscription contract in the Service Operations Monitor is changed to Cancel.

  • If the instance is deleted from the process scheduler table then the status of the subscription contract is Cancel. This will clear out the contract in the partitioned queue so that the next contract in sequence can be processed.

Note: In the Service Operations Monitor the Submit status has the same behavior as the Working status, thus proper queue partitioning behavior is maintained. Therefore, intelligent queue partitioning should be taken into account for service operations using the application engine handler.

A Subscription Contract processing an application engine handler cannot be cancelled or resubmitted from the Service Operations Monitor, but rather must be done in the Process Monitor. Once you resubmit or cancel the program in the Process Monitor, the status is updated for the subscription contract. Refresh the Service Operations Monitor page to view the updated status. Note that there could be a delay from when the time you cancel or resubmit the application engine program in the Process Monitor and when the update is seen in the Service Operations Monitor. In addition, at least one Pub/Sub domain must be active for this status update to happen.