SECAs and Error/Failure Management

This is based on REV 1163468, and my interpretation of the code. I may have misunderstood something, so don't bet anything important on this document being correct.

In the first section I'll describe some general rules that apply most of the time. The second section will describe what happens in what order during a typical run, highlighting some exceptions to the general rules given in the first section. Sync and Async services are handled slightly differently, so I'll cover them separately. In the third section I'll list more exceptions to the rules given in the first section.

When I talk about the service chain, I am referring to the chain or list of services that may actually (attempt to) run when one service with SECAs is run. All services in the service chain, except the main one, are defined in action elements in SECAs. The order they run is determined primarily by the value of the event attribute for a SECA. See the Sync and ASync sections below for the order.

I am completely ignoring global-commit and global-rollback events, eca conditions, and set actions.

General Rules

• Failures and errors are treated the same way, except that an error triggers a transaction rollback while a failure will commit the transaction as if it had succeeded. Of course, they can be made to work slightly differently by setting the ignore-failure/ignore-error, run-on-failure/run-on-error pairs differently.
• If an action element has ignore-failure/ignore-error set to true (the default), then that specific service will usually not let other services know it failed/errored, and hence later eca's run-on-fail/run-on-error does not apply if it did fail/error. However there is an exception to this, relating to the use of result-to-result, and described under Exceptions.
• If an eca has run-on-fail/run-on-error set to false (the default), it means that if any earlier service in the chain admits to failure/error, this action service will not run. There are exceptions, resulting from the timing of checks for error/failure. See the Typical Run section.
• If an eca has run-on-fail/run-on-error set to true, it means that the action service will still run even if a prior service in the chain admitted to failure/error. This does not, however, apply to the main service, which will never run if an earlier service admitted to a failure or error.
• If an eca is for invoke, in-validate or auth, and its action service is called async or in a new transaction, the action service might be called more than once. This seems to be related to deadlock handling.
• For a given event type, a specific service will only run once, even if it is named in multiple SECAs.

Typical Run

The order of the items in the service chain and when errors/failures are checked differs slightly depending on whether the service was called sync or async. The two service chains are summarised below. In these chains, the word action refers to a service named in the action element of a seca for the relevant event, and the word event refers to the actual event. check signifies that any errors or failures so far admitted are noted, and the remaining services will be made aware of them.

Sync

For a Sync service, the service chain runs as follows:

1. auth action
2. check
3. auth event
4. in-validate action
5. check
6. validate event (skipped if any admitted errors or failures so far)
7. invoke action
8. check
9. actual service run (skipped if any admitted errors or failures so far)
10. check
11. out-validate action
12. validate event
13. commit action
14. check
15. global-commit-post-run action
16. release locks, end transactions, commit unless there has been an error, in which case rollback
17. return action

The locations of the check are important when managing errors/failures. An admitted error or failure in a service will not affect later services until there's a check. For example, if the out-validate action service admits to an error or failure, the commit action will not alter its behaviour, as it will not be notified of the failure/error.

The comment "(skipped if any admitted errors or failures so far)" applies irrespective of the settings of run-on-error and run-on-failure.

ASync

For an Async service, the service chain is:

1. auth action
2. auth event
3. in-validate action
4. check
5. validate event (skipped if any admitted errors or failures so far)
6. submit service to JobManager (skipped if any admitted errors or failures so far)

The JobManager appears to eventually submit the service to the Sync code. Presumably this means auth and in-validate will be run a second time (unconfirmed).

Notice that unlike the Sync version, the ASync service chain does not have a check after the auth action.

Exceptions

• If result-to-result for an action is true, then the settings for both ignore-failure and ignore-error are ignored. Neither failures nor errors will be ignored.
• If any of the services prior to the main service (i.e. auth, in-validate, invoke actions) fail or error, the main service will not be run, irrespective of the values of run-on-error or run-on-failure. However I think later services in the chain will still be called if their configuration allows it. For example, the commit action service will be run if run-on-failure is true and an earlier service admitted failure.

See Also

There are several other documents that discuss SECAs in OfBiz. This document repeats some of the same information, but with a different slant aimed at understanding how to use run-on-error/run-on-failure/ignore-error/ignore-failure.

For further information on SECAs, try:

• OFBiz Tutorial - A Beginners Development Guide
• ofbiz-user: Seca run-on-error help (note that this explanation is only strictly correct for events that run after the main service, such as commit and return)
• Service Engine Guide (very important reading if you need any information about anything to do with the service engine)

Don't make the mistake I did, and assume "the service" referred to in some of the above documents is the main service referred to in the eca tag. If you think of it as meaning "any service in the service chain" you will be closer to the truth.

Also refer to the relevant schema (service-eca.xsd) in OFBiz, for attributes not documented above.