IBM Support

Common steps to resolving issues with undercover agents in IBM Business Process Manager (BPM)

Product Documentation


Abstract

During the development or running of undercover agents (UCAs) in IBM Business Process Manager, application errors or unexpected behavior might occur. This document outlines some common things to check and provides information about related APARs.

Content

This document contains commonly known issues with UCAs. In addition to this document, there may be additional answers out on the BPM developerWorks dw Answers forum for problems that you encounter.

UCAs are dependent on the event manager and database settings. First check to see if the event manager is currently running. It might have been turned off in a blackout period during a snapshot installation. See the following product documentation for the event manager:
The IBM Business Process Manager system is dependent on accurate system time. Ensure that all IBM Business Process Manager server nodes and the Process Server database are all on the same time. All servers must be within 5 minutes. It is recommended that you use a common network time protocol (NTP) server to have all servers on the same time clock. When time clocks are not synchronized, scheduled UCAs do not fire at the expected time. For example if the scheduled execution time is midnight (12:00am / 00:00) and the servers clocks are not synced, the UCA may run at 11:59pm on the preceding day. In this case as well, if the date of the execution is important, scheduling at 12:05am (00:05) is a good alternative.


Scheduled UCAs
Scheduled UCAs do not automatically run in the Process Center. For testing, click Run Now in IBM Process Designer.

The next scheduled event displays on the Event Manager screen of the Process Admin console for a Process Server. For each scheduled UCA, it shows the last time it was executed and the next scheduled execution. If the time does not display, go to the Installed Apps tab, click the application name, then look under the exposing section for the UCA sub section. Check and re-check the box. Go back to the Event Manager page. Does the UCA show the correct next time to start? If not, turn on diagnostic tracing, repeat the steps, and send the log files to IBM Business Process Manager Support.

The following example is a screen capture of the Exposing section for UCAs.
  • Multiple entries in the event manager show the scheduled UCA has not fired and the events are in the past

    Shut down and restart all BPM AppTarget (process server) JVMs. Check and see if the older entries are removed and the next occurrence of the UCA is scheduled. If this does not resolve it, next go to the Installed apps section and uncheck and re-check the scheduled UCA.
Notes:
  • Scheduled UCAs only operate on their scheduled time in a Process Server environment. For a Process Center, click RUN NOW on the UCA implementation to test.
  • Scheduled UCAs only operate on the DEFAULT snapshot. If you have more than one active snapshot, only the code implementation in the default snapshot fires.

Event Based UCA
  • Start Message Event (SME)
    Is the correct correlation value selected? Are the correct values being passed into the start of the business process definition (BPD)? Verify that the correct values are mapped at the call of the UCA and the receiving end of the UCA.

    The following screen capture shows an example Start Message Event in IBM Business Process Manager V8.5 with data mapping.
  • Using start message events (SME) when there are multiple active snapshots

    When multiple snapshots of the same application are installed, with a SME only the UCA in the default snapshot will be called. So even when you call the exposed service in the latest (non-default) snapshot, the UCA in the default snapshot would be triggered. See the following graphic for an example. A Human Service is exposed to users. Within this graphic, there is a call to a start message event (SME) on another BPD.




    Starting in V8.5, there is a new feature to have the UCA trigger on the snapshot from which it is calling. This feature is useful to have if you plan to have multiple active snapshots and use UCAs. To use this feature, check the Target the snapshot of the installed process application that contains this service box. For more information, see the Setting the target for a UCA message event topic in the product documentation.


  • Using a condition in a start message event

    Start message events can have a condition. If the condition evaluates to false, then the SME will not get triggered. There is no failure (exception) when it does not evaluate. Check to make sure the condition evaluates to true. Here is an example: tw.local.message == "BPML2-SME-UCA2"

  • Change in UCA variable (business object) causes a mismatch when trying to consume the message.

    If the definition of the UCA has a changed variable type, name, added variables or removed variables, the following message may appear in the SystemOut.log when a SME or IME listener tries to consume a message.

    CWLLG0297W: The intermediate event with ID BpdEvent.007c734d-1d78-12cc-bf84-1ba5100d1fcf can never receive a message from UCA UCA.5697d748-33d6-4a24-9ab4-c5258988869a because it is correlated on an invalid output parameter.

    Please see the Development strategies for migrating instances product documentation under the Variables section for tips on how to avoid this.

    Possible workarounds:

    Scenario: Migrated all instances to new snapshot (application) version. New instances work fine, previously inflight ones fail with CWLLG0297W

    Solutions:
    I)Use the moveToken REST API to move the token on the IME to the same location as it currently is located. This will allow the token to be refreshed with the current definition and allow new tokens to go through
    II) The source that send the UCA message, the REST API, outside JMS, internal invocation of the UCA, needs to be updated to the current variable structure so the messages can be successfully processed.
  • Intermediate Message Event (IME)
    An Intermediate Message Event listens for a specific value. This value is mapped from the UCA to the designated correlation ID on the Intermediate Message Event implementation. Ensure that the desired variable is mapped in the diagram. This variable is usually an instance ID or some other unique identifier.

    The following screen capture is an example Intermediate Message Event. Note if you have Consume Message or Durable Subscription checked. (V8.5)


Note: If you implement a Start Message Event or an Intermediate Message Event in more than one location, when the broadcast message is sent out from the calling UCA, all corresponding Start Message Events or an Intermediate Message Events are triggered.
  • UCA Payload with complex variables

  • If your UCA variable payload has a complex variable (business object) has a variable which contains a list may result in a type mismatch. JR52726 resolves this issue.
  • Stuck tokens on activity with IME

    Take the scenario where an IME is attached to Activity1 and it is set to close the activity (interrupt). When the IME is triggered it is to go to Activity 3. If Activity1 finishes first then it goes to Activity2. Take a case where the IME message comes in at same time that Activity1 is being actively processed. The IME processes faster than than Activity1 and should close the Activity1 to go to Activity 3. However what happens is Token #3 is consumed and Token #2 is left there with no where to go. In addition to this, the tasks associated with Activity 1 are all closed (state = 32). This causes the instance to be stuck as the instance is active and all tasks are closed.

    The short term solution is to use the REST API move token to move token #2 to the appropriate activity. There is a code fix for this case with JR52533 and JR53167.

    Sample diagram:

Durable Messages
The purpose of the durable message subscription is so you can send a message (letter) to a UCA before the BPD tokens reach that location. This scenario essentially has a message waiting when the next token arrives. When you use the durable message subscription, the keys used to correlate on the BPD should be unique. If the keys are not unique, then the LSW_INST_MSG_EXCL and LSW_DUR_MSG_RECIVED become very large. To clean up previous UCA durable messages, use the BPMDeleteDurableMessages command (V8.5.0 Fix Pack 1 and later).

If the table LSW_DUR_MSG_RECEIVED contains many persisted messages, which might have accumulated over a longer period of time, with the same correlation value, and a matching event is reached and the correlation value is the same, then entries are written to the LSW_INST_MSG_EXCL table for all these persisted messages.

Tuning and Capacity for UCA Operation

UCAs run on the async or sync queues as defined in the the event manager configuration. By default, UCAs run on the async queue

Fixes and Support content related to UCAs

This is only a sample set of fixes for resolving UCA issues. It is recommended to be at latest BPM fix levels for fixes. This also shows the types of issues which have been reported and fixed with defects.
Issue, error, or problem Possible Solution
Durable subscription messages are not picked up with intermediate message events JR48482 - IBM Business Process Manager V8.0.1.x and later
Scheduled UCAs are not canceled upon snapshot deactivation JR41966 - IBM Business Process Manager V7.5.1
All UCAs stop working JR46969. For more information, see After using wsadmin script BPMDeleteSnapshot undercover agents (UCA) no longer work in IBM Business Process Manager (BPM).
UCAs execute more than once and possibly multiple times unexpectedly. Duplication of UCA activity
  1. Verify that the database and the Process Server clock are synchronized.
  2. Verify that the coding logic for the application code only intends to call the UCA once.
  3. Apply the following fixes to your environment:
The event queue becomes full and events cannot process. Event UCA reaches the maximum <re-execute-limit> value and is discarded. In the event manager console, these events are scheduled for execution on "1/2/99" or "2099-02-01" depending on localization. JR47860 holds the event tasks until they can be executed with the BPMReplayOnHoldEMTasks wsadmin command.

BPM 8.5.7.0 CF2017.03 can now delete these tasks safely with BPMDeleteOnHoldEMTasks.
Data sent in the UCA is not as expected. JR47428 - This APAR resolves an issue with new line characters in UCA messages.
JR56100 - IME CORRELATION VALUE IS REPLACE WITH THE VALUE FROM THE UCA (UCA does not properly match on trailing white space)
UCAs work on the process center, but do not work on the process server with the send message REST API. Adding the snapshot name resolves this issue. JR49068 - Resolves an issue as there is not a TIP in process server.
Scheduled UCAs fire once and then do not fire again. See APAR JR50384: INCOMPLETE EVENT MANAGER TASK FOR TIME BASED UCA CANCELS ALL OTHER TIME-BASED UCAs
Instance is stuck on activity with attached IME Install JR52533 and JR53167 as this is a race condition between the IME closing the activity and the activity closing itself.
UCA payload has a complex "list" type object. Exception of CWLLG0203E with TeamWorksException: Type mismatch. Value "

" must be array. Java class found: java.lang.String
JR52726 INVOKING A UCA ASSOCIATED WITH A COMPLEX TYPE VARIABLE THAT CONTAINS AT LEAST ONE LIST FIELD COULD FAIL

JR55205 .E. TW.SYSTEM.SERIALIZER.FROMXML BEHAVIOR CHANGE IN IBM BPM V8.5.6 CF02 CAUSES APPLICATION FAILURE
Using an intermediate message event to listen for a message from SCA. In a clustered environment no correlation is possible. JR53548 SCA MESSAGES SENT TO AN IME ON A BPD CANNOT BE CORRELATED
Database lock timeout when running a UCA JR55646 - YOU MIGHT RECEIVE A LOCKTIMEOUT EXCEPTION WHEN YOU USE MICROSOFT SQL SERVER
Intermediate events with the Durable Subscription option checked, do not behave as expected
  • It takes some time for the message to be registered before an Intermediate Message Event can actively pick up and execute the UCA.
  • The durable message data might need to be purged.The BPMDeleteDurableMessages command is available for V8.5.0 Fix Pack 1 and V8.0.1 Fix Pack 2. Previous versions require a manual purge of the LSW_DUR_MSG_RECEIVED database table.

If these steps and suggestions do not resolve the issue, see the Collect troubleshooting data for undercover agent (UCA) problems in IBM Business Process Manager (BPM) document.

[{"Product":{"code":"SSFTDH","label":"IBM Business Process Manager Standard"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Component":"Undercover Agent (UCA)","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF016","label":"Linux"},{"code":"PF033","label":"Windows"}],"Version":"8.5;8.0.1;8.0;7.5.1;7.5","Edition":"","Line of Business":{"code":"LOB45","label":"Automation"}},{"Product":{"code":"SSFTDH","label":"IBM Business Process Manager Standard"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Component":"Undercover Agent (UCA)","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF016","label":"Linux"},{"code":"PF033","label":"Windows"}],"Version":"8.5;8.0.1;8.0;7.5.1;7.5","Edition":"","Line of Business":{"code":"LOB45","label":"Automation"}},{"Product":{"code":"SSFTBX","label":"IBM Business Process Manager Express"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Component":"","Platform":[{"code":"PF016","label":"Linux"},{"code":"PF033","label":"Windows"}],"Version":"8.5;8.0.1;8.0;7.5.1;7.5","Edition":"","Line of Business":{"code":"LOB45","label":"Automation"}}]

Product Synonym

BPM

Document Information

Modified date:
31 March 2022

UID

swg27041883