This blog post, as part of this blog series, refers to the recently introduced Conditional Start feature in SAP NetWeaver BPM available with SAP NetWeaver 7.3 EHP 1 SP 06 and higher.
Dude, Where’s My Message?
Conditional Start
processes use the same web service endpoint for the start event as well as for the intermediate message event by utilizing a reusable message trigger. Both events define restrictions (start condition or correlation condition) that define which messages to accept and which to reject. Sometimes it might not be clear at first sight what happened to a message that was sent to SAP NetWeaver BPM: Did it reach the system? Did it correlate with a process? Did it start another process instance? Or to put it short: Dude, where's my message?
For that purpose, logging was introduced to ensure traceability throughout the complete life cycle.
Duties of the Doorman: Accept or Reject
A message sent to the web service endpoint will be attempted to be correlated to a running process. In case the message payload does not satisfy any correlation condition or there is no process running, the system rejects it for correlation. Referring to the example of part 1 (Conditional Start: Introduction), the process might only be interested in colored pencils. If a message for a white pencil is sent to the system it will be discarded as white is obviously not a color :wink:
This event is written to the business log of the SAP NetWeaver Administrator, which can be accessed in the SAP NetWeaver Administrator by choosing Troubleshooting > Processes and Tasks > Business Logs (Quick link: http://host:port/nwa/bpm-bizlog).
Figure 1: Business log entry for a message that could not be matched to any process
ℹ Note that the container type is NOT_APPLICABLE and the container ID is 32x0 as there is no process (container) and subsequently no ID the business log entry could be mapped to.
:!: Be aware that the messaging related business log entries require at least "Standard" as global business log level. Otherwise they won't be logged. Increasing the severity is always a trade-off between fine grained information and better performance. More details about using the business log and the various business log levels can be found in our official documentation of SAP NetWeaver BPM.
Up to this point, there is no difference to traditional correlation. But Conditional Start goes one step further: As a next step, SAP NetWeaver BPM determines whether the message payload matches the start condition. If this is the case, another business log entry can be found indicating that a new process was started.
Figure 2: Business log entry for a newly started process
This time, the container type is PROCESS and the container ID corresponds to the ID of the started process. Hence, this information is also available in the Manage Processes application (http://host:port/nwa/bpm-processes).
ℹ Note the linked message ID inside the details. It is available if a message is coming from SAP Process Integration or SAP NetWeaver BPM. It allows tracing a particular message across the systems using the best available monitoring application. For more details refer to "Monitoring Messages Across PI and BPM in the BPM Log Viewer" which is part of our official documentation of SAP Process Orchestration.
Figure 3: Business log entry in the 'Manage Processes' application
Having this information at hand, it could easily be told whether an incoming message made it into the system or was already rejected at the door.
Received vs. Consumed - What’s the Deal?
Assuming that there is a running process and the message payload fulfills the correlation condition, it will be further processed. As explained in the documentation on the SAP help portal, SAP NetWeaver BPM differentiates between message receipt and message consumption. This is also expressed by two different events in the history/business log of a process.
Figure 4: Business log entries for a message that was received and consumed in the 'Manage Processes' application
As with any business log entry, this could also be monitored using the Business Log Viewer.
Figure 5: Business log entries for a message that was received and consumed in the 'Business Log Viewer'
The delay between the two entries depends on various factors such as the process state or the asynchronous processing of incoming messages. In case a message was expected to be consumed, but was not yet, SAP NetWeaver BPM provides a monitor to check the progress. High load or custom system configuration could increase the processing time and cause a delay in consuming the message. In order to find out, one could check the BPM Action Monitor, which is part of the SAP NetWeaver Administrator and can be accessed by choosing Troubleshooting > Processes and Tasks > BPM Actions (Quick link: http://host:port/nwa/bpm-actions).
Figure 6: The 'BPM Action Monitor' provides a look behind the scenes helping to identify delays in asynchronous processing
At a glance, an administrator sees the number of queued, failed or disabled actions plus SAP NetWeaver BPM configuration settings for asynchronous processing. In the case that an action has failed, the technical exception can be examined. After the maximum number of attempts, the action will be disabled and no longer being processed until explicitly being reset. This allows administrators to correct the underlying problem without having interferences before restarting the processing.
ℹ Note that Correlation/Conditional Start is not the only component creating BPM actions, hence other actions could be part of that list as well. More details about the BPM Action Monitor can be found in our official documentation of SAP NetWeaver BPM.
:!: Be aware that this view is not intended to trace your incoming messages from their origin to their destination. Normally messages reside in this queue for a very limited amount of time (depending on your system configuration). Only if things go wrong this view might provide more insights why you cannot find follow-up business log entries for messages received and accepted by SAP NetWeaver BPM.
Hasta la Vista, Process!
One specialty of Conditional Start is the leftover message handling that was already mentioned in a part 1 (Conditional Start: Introduction). Upon process termination, every received but not consumed message will produce another business log entry highlighting this. As this information is logged in the context of a process, one will find it in the tab History in the Manage Processes application.
Figure 7: Business log entry for a message that was not consumed before process termination
Following the Conditional Start paradigm, such message will either correlate with another running instance or start a new instance if it fulfills the start condition (Duties of the Doorman: Accept or Reject).
In case an administrator suspects unexpected leftover messages for a process, a better approach might be formulating an advanced query using the Business Log Viewer.
Figure 8: Specifying an advanced query in the Business Log Viewer
Thereby all leftover messages and the corresponding processes can be determined.
Houston, We Have a Problem!
Conditional Start must allow a maximum of one process that is ready to receive messages for the used web service endpoint, for example, to enable the aggregator enterprise integration pattern. The pattern might was highlighted in part 2 (Conditional Start: Typical Examples). What’s worth mentioning is that the SAP NetWeaver BPM has a mechanism to detect this and prohibit further processing. So, in the unlikely event of multiple matches, a business log entry is written for each affected process allowing the administrator to analyze the situation, correct the problem and clean up the affected system.
Figure 9: A business log entry for multiple matches, which is prohibited for Conditional Start processes
ℹ Note that unlike the other business log entries mentioned so far, this one is logged with severity FAILURE instead of STANDARD to indicate the wrong usage of the Conditional Start pattern.
One More Thing: The Application Log
The business log should be the primary choice when tracing a message and its life cycle in the system. In case that’s not sufficient, SAP NetWeaver BPM provides additional means to increase supportability. Using the application log more detailed entries are immediately written for the category /Applications/BPM/Correlation.
| Event | Severity | Text |
| Message received | Info | Message received on endpoint <E> was correlated with BPM process instance <P>. |
| Message received | Info | Message previously received on endpoint <E> and correlated with BPM process instance <P> was rolled back. |
| Message received | Debug | Message received on endpoint <E> cannot be correlated to a running BPM process instance of definition version <D> (compiled to use Correlation Adapter). |
| Message received | Error | Message received via endpoint <E> matched with multiple process instances (<P>, …, <P>) which is prohibited for 'Conditional Start' scenarios. |
| Message received | Fatal | The transaction identifying multiple matches in a 'Conditional Start' scenario was not rolled back, but successfully committed. |
| Message received | Fatal | Persisting business log entries for multiple matches in a 'Conditional Start' scenario failed: <E> |
| Message received | Fatal | Error while leaving the transaction level: <E> |
| Message consumed | Info | Message consumed by BPM process instance <P> via Intermediate Message Event <I>. |
| Message consumed | Info | Consumption of message by BPM process instance <P> via Intermediate Message Event <I> was rolled back. |
Table 1: An overview of application logs provided for Correlation
As application logs are written without transactional scope, some log entries might be irrelevant when a certain transaction is rolled back.
Combining the application log and the default trace helps analyzing situations where side effects or preceding exceptions had an influence on Conditional Start. Both are part of SAP NetWeaver Administrator and can be accessed by choosing Troubleshooting > Logs and Traces > Log Viewer (Quick Link: http://host:port/nwa/logs).
Disclaimer: Navigation paths, quick links, log texts, figures or tables highlighted in this blog post might differ from actual SAP NetWeaver BPM installations.
- SAP Managed Tags:
4 Comments
