Transaction Management

Overview

Integration Server considers a transaction to be one or more interactions with one or more resources that are treated as a single logical unit of work. The interactions within a transaction are either all committed or all rolled back. For example, if a transaction includes multiple database inserts, and one or more inserts fail, all inserts are rolled back.

Integration Server supports the following kinds of transactions:

  • A local transaction (LOCAL_TRANSACTION), which is a transaction to a resource's local transaction mechanism.
  • An XAResource transaction (XA_TRANSACTION), which is a transaction to a resource's XAResource transaction mechanism.

Integration Server can automatically manage both kinds of transactions, without requiring the adapter user to do anything. Integration Server uses a container-managed (implicit) transaction management approach based on the Connector Architecture standard, and also performs some additional connection management because adapter services use connections to create transactions. For more information about implicit transactions, see Implicit Transactions.

However, there are cases where you need to explicitly control the transactional units of work. For more information about explicitly managing transactions, see Explicit Transactions.

To support transactions, Integration Server relies on a transaction manager. The transaction manager is responsible for beginning and ending transactions, maintaining a transaction context, enlisting newly connected resources into existing transactions, and ensuring that local and XAResource transactions are not combined in illegal ways.

The transaction manager only manages operations performed by adapter services, a transacted JMS trigger, or a built-in JMS service that uses a transacted JMS connection alias. Since the transaction manager cannot manage operations performed by any other service, a commit or rollback is not applicable for operations performed by those services.

Important: You cannot step or trace a flow that contains a transacted adapter service.

Implicit Transactions

With implicit transactions, Integration Server automatically manages both local and XAResource transactions without requiring you to explicitly do anything. Integration Server starts and completes the implicit transaction.

An implicit transaction context, which the transaction manager uses to define a unit of work, starts when an adapter service is encountered in a flow execution. The connection required by the adapter service is registered with the newly created context and used by the adapter service. If another adapter service is encountered, the transaction context is searched to see if the connection is already registered. If the connection is already registered, the adapter service uses this connection. If the connection is not registered, a new connection instance is retrieved and registered with the transaction.

Note that if the top level flow invokes another flow, adapter services in the child flow use the same transaction context. When the top level flow completes, the transaction is completed and is either committed or rolled back, depending on the status (success or failure) of the top level flow.

A single implicit transaction context can contain any number of XA_TRANSACTION connections but no more than one LOCAL_TRANSACTION connection. If you choose to provide dynamic user credentials at run time, all the adapter services using the LOCAL_TRANSACTION connection within a single transaction must use the same user credentials. For example, if you have two adapter services, s1 and s2, configured using the LOCAL_TRANSACTION connection c1 in a single transaction context, both s1 ands2 must either use the same dynamic credentials at run time or the default configured credentials provided at design time. For more information about providing dynamic user credentials for a service's associated connection, see “Changing the User Credentials of a Service's Associated Connection at Run Time”.

For more information about designing and using flows, see IBM webMethods Service Development Help.

Implicit Transaction Usage Cases

Manging a flow implicitly requires any of the following:

If a flow contains multiple local transactions, you must explicitly control the transactional units of work, as described in Explicit Transaction Usage Cases.

One Local Transaction

In this example, a flow with two adapter services interacts with the same local transaction resource. The flow performs two inserts into two tables of a database: 

BEGIN FLOW 
INVOKE insertDatabase1TableA // Local Transaction Resource1 
INVOKE insertDatabase1TableB // Local Transaction Resource1 
END FLOW

Integration Server starts the transaction when insertDatabase1TableA is invoked. It opens a connection to the resource, enlists it in the transaction, and performs the insert into TableA. When insertDatabase1TableB is invoked, Integration Server reuses the same connection to insert data into TableB. When the request is complete, Integration Server closes the connection and commits the transaction.

The following flow is illegal because it tries to interact with two local transaction resources as follows: 

BEGIN FLOW 
INVOKE insertDatabase1TableA // Service for Resource1 
INVOKE insertDatabase2TableA // Service for Resource2 
END FLOW

Three XAResource Transactions

The following flow is valid because a flow can contain any number of XAResource transactions. 

BEGIN FLOW 
INVOKE insertDatabase1TableA // XAResource Transaction Resource1 
INVOKE insertDatabase2TableA // XAResource Transaction Resource2 
INVOKE insertDatabase3TableA // XAResource Transaction Resource3 
END FLOW

One Local Transaction and One XAResource Transaction

Continuing with the previous case, notice this additional insert to a different database that accepts XAResource transactions as follows: 

BEGIN FLOW 
INVOKE insertDatabase1TableA // Local Transaction Resource1 
INVOKE insertDatabase1TableB // Local Transaction Resource1 
INVOKE insertDatabase2TableA // XAResource Transaction Resource1 
END FLOW

When Integration Server invokes insertDatabase2TableA, a transaction is already in progress with the first database enlisted. It then establishes a second connection (to Database2), enlists the new connection in the XAResource transaction, and performs the insert to tableA.

When the request is complete, Integration Server closes both connections and the Transaction Manager performs a local commit for the non-XAResource and then a two-phase commit for the XAResource enlisted in the transaction.

Explicit Transactions

You use explicit transactions when you need to manually control the transactional units of work. To do this, you use built-in services in your flow services.

An explicit transaction context starts when the pub.art.transaction:startTransaction service is executed. The transaction context is completed when either the pub.art.transaction:commitTransaction or pub.art.transaction:rollbackTransaction service is executed. For information about the services, see Built-In Services for Transaction Management.

When you define an explicit transaction, it is nested within the implicit transactions that are controlled by the transaction manager. You can have more than one explicit transaction defined within an implicit transaction. You can also nest explicit transactions within each other.

As with implicit transactions, a single explicit transaction context can contain any number of XA_TRANSACTION connections but no more than one LOCAL_TRANSACTION connection. If you choose to provide dynamic user credentials at run time, all the adapter services using the LOCAL_TRANSACTION connection within a single transaction must use the same user credentials. For example, if you have two adapter services, s1 and s2, configured using the LOCAL_TRANSACTION connection c1 in a single transaction context, both s1 and s2 must either use the same dynamic credentials at run time or the default configured credentials provided at design time. For more information about providing dynamic user credentials for a service's associated connection, see “Changing the User Credentials of a Service's Associated Connection at Run Time”.

A new explicit transaction context can be started within a transaction context, provided that you ensure that the transactions within the transaction context are completed in the reverse order they were started. The last transaction to start should be the first transaction to complete, and so forth.

The following example shows a valid construct. 

pub.art.transaction:startTransaction 
   pub.art.transaction:startTransaction 
      pub.art.transaction:startTransaction 
      pub.art.transaction:commitTransaction 
   pub.art.transaction:commitTransaction 
pub.art.transaction:commitTransaction

The following example shows an invalid construct. 

pub.art.transaction:startTransaction 
   pub.art.transaction:startTransaction 
pub.art.transaction:commitTransaction 
   pub.art.transaction:commitTransaction
Note: With explicit transactions, you must be sure to call either a commitTransaction or rollbackTransaction for each startTransaction. Otherwise, you will have dangling transactions that will require you to reboot Integration Server.

For more information about designing and using flows, see IBM webMethods Service Development Help.

Explicit Transaction Usage Cases

To include multiple local transactions in a single flow, you must explicitly start and end each transaction except the first one.

Depending on what the flow needs to accomplish, you may explicitly start and end XAResource transactions as well. This way, you can create a flow that includes multiple local transactions and multiple XAResource transactions.

For example, the following flow includes a local transaction nested within another local transaction: 

BEGIN FLOW                       // start transaction 1           
.           
.           
.           
    INVOKE startTransaction(2)      // start transaction 2           
    .           
    .           
    .           
    INVOKE commitTransaction(2)     // commit transaction 2           
END FLOW                         // commit transaction 1

A nested transaction must adhere to the same rules that apply to container-manager transactions. That is, a nested transaction can contain one of the following:

  • One local transaction, interacting with one resource
  • One or more XAResource transactions, where each transaction can interact with one or more resources
  • One or more XAResource transactions and one local transaction

Following are some examples of explicit transactions.

Two Local Transactions

To make this flow work properly, explicitly start and commit the nested local transaction, using the startTransaction and commitTransaction services as follows: 

BEGIN FLOW                     // start transaction 1           
INVOKE interactWithResourceA   // service for transaction 1           
           
   INVOKE startTransaction(2)     // start transaction 2           
   INVOKE interactWithResourceB   // service for transaction 2           
   INVOKE commitTransaction(2)    // commit transaction 2           
           
END FLOW                       // commit transaction 1

The flow executes as follows:

  1. When interactWithResourceA is invoked, Integration Server starts transaction 1 and enlists ResourceA.
  2. Transaction 2 executes as follows:
    1. When startTransaction(2) is invoked, Integration Server starts a new, nested transaction.
    2. When interactWithResourceB is invoked, ResourceB is enlisted in transaction 2.
    3. When commitTransaction(2) is invoked, the connection to ResourceB is closed, and transaction 2 is committed. At this point, only the work done on ResourceB is committed; transaction 1 is still open, and the work done with ResourceA is not yet committed.
  3. When the flow ends, Integration Server closes the connection for transaction 1 and commits its work to ResourceA.
Note: Each transaction is a separate unit of work. Transaction 1 could be rolled back (or the commit could fail), while transaction 2 remains committed (or vice versa).

Alternatively, to achieve the same result, you can explicitly start transaction 1 before the adapter service is invoked, and explicitly commit it as follows: 

BEGIN FLOW           
INVOKE startTransaction(1)     // start transaction 1           
INVOKE interactWithResourceA   // service for transaction 1           
INVOKE startTransaction(2)     // start transaction 2           
INVOKE interactWithResourceB   // service for transaction 2           
INVOKE commitTransaction(2)    // commit transaction 2           
INVOKE commitTransaction(1)    // commit transaction 1           
END FLOW

Two XAResource Transactions

The following flow includes two XAResource transactions: one that interacts with ResourceA, and a nested transaction that interacts with ResourceB and ResourceC. 

BEGIN FLOW                      // start transaction 1           
INVOKE interactWithResourceA    // service for transaction 1           
           
   INVOKE startTransaction(2)      // start transaction 2           
   INVOKE interactWithResourceB    // service for transaction 2           
   INVOKE interactWithResourceC    // service for transaction 2           
   INVOKE commitTransaction(2)     // commit transaction 2           
           
END FLOW                        // commit transaction 1

The flow executes as follows:

  1. When interactWithResourceA is invoked, Integration Server starts transaction 1 and enlists ResourceA.
  2. Transaction 2 executes as follows:
    1. When startTransaction(2) is invoked, Integration Server starts a new, nested transaction.
    2. When interactWithResourceB and interactWithResourceC are invoked, both resources are enlisted in transaction 2.
    3. When commitTransaction(2) is invoked, the connections to ResourceB and ResourceC are closed, and transaction 2 is committed. At this point, only the work done on ResourceB and ResourceC is committed; transaction 1 is still open, and the work done with ResourceA is not yet committed.
  3. When the flow ends, Integration Server closes the connection for transaction 1 and commits its work to ResourceA.

One XAResource Transaction and Two Nested Local Transactions

The following flow includes three transactions: one XAResource transaction that interacts with two resources, and two nested local transactions that interact with one resource each. 

BEGIN FLOW                        // start XAResource transaction 1           
INVOKE interactWithXAResourceA    // service for XAResource transaction 1           
INVOKE interactWithXAResourceB    // service for XAResource transaction 2           
   INVOKE startTransaction(2)         // start local transaction 1           
   INVOKE interactWithLocalResourceA  // service for local transaction 1           
   INVOKE commitTransaction(2)        // commit local transaction 1           
   INVOKE startTransaction(3)         // start local transaction 2           
   INVOKE interactWithLocalResourceB  // service for local transaction 2           
   INVOKE commitTransaction(3)        // commit local transaction 2           
END FLOW                          // commit XAResource transaction 1

The flow executes as follows:

  1. When interactWithXAResourceA is invoked, Integration Server starts transaction 1 and enlists XAResourceA.
  2. When interactWithXAResourceB is invoked, Integration Server enlists XAResourceB in transaction 1.
  3. Transaction 2 is executed as follows:
    1. When startTransaction(2) is invoked, Integration Server starts a new, nested transaction.
    2. When interactWithLocalResourceA is invoked, LocalResourceA is enlisted in transaction 2.
    3. When commitTransaction(2) is invoked, the connection to LocalResourceA is closed, and transaction 2 is committed. At this point, only the work done on LocalResourceA is committed; transaction 1 is still open, and the work done with XAResourceA and XAResourceB is not yet committed.
  4. Transaction 3 is executed as follows:
    1. When startTransaction(3) is invoked, Integration Server starts a new, nested transaction.
    2. When interactWithLocalResourceB is invoked, LocalResourceB is enlisted in transaction 3.
    3. When commitTransaction(3) is invoked, the connection to LocalResourceB is closed, and transaction 3 is committed. At this point, only the work done on LocalResourceA and LocalResourceB is committed; transaction 1 is still open, and the work done with XAResourceA and XAResourceB is not yet committed.
  5. When the flow ends, Integration Server closes the connection for transaction 1 and commits its work to XAResourceA and XAResourceB.

One XAResource Transaction and One Nested Local and XAResource Transaction

The following flow includes two transactions: one XAResource transaction that interacts with two resources, and one nested transaction that interacts with one local resource and one XAResource. 

BEGIN FLOW                        // start XAResource transaction 1           
INVOKE interactWithXAResourceA    // service for XAResource transaction 1           
INVOKE interactWithXAResourceB    // service for XAResource transaction 2           
           
   INVOKE startTransaction(2)           // start transaction 2           
   INVOKE interactWithLocalResourceA    // service for transaction 2           
   INVOKE interactWithXAResourceC       // service for transaction 2           
   INVOKE interactWithLocalResourceA    // service for transaction 2           
   INVOKE commitTransaction(2)          // commit transaction 2           
           
END FLOW                          // commit XAResource transaction 1

The flow executes as follows:

  1. When interactWithResourceA is invoked, Integration Server starts an XAResource transaction 1 and enlists ResourceA.
  2. When interactWithResourceB is invoked, Integration Server enlists ResourceB in transaction 1.
  3. Transaction 2 is executed as follows:
    1. When startTransaction(2) is invoked, Integration Server starts a new, nested transaction.
    2. When interactWithLocalResourceA is invoked, LocalResourceA is enlisted in transaction 2.
    3. When interactWithXAResourceC is invoked, XAResourceC is enlisted in transaction 2.
    4. When interactWithLocalResourceA is invoked, LocalResourceA is enlisted in transaction 2.
    5. When commitTransaction(2) is invoked, the connection to both resources of transaction 2 is closed, and transaction 2 is committed. At this point, only the work done on LocalResourceA and XAResourceC is committed; transaction 1 is still open, and the work done with XAResourceA and XAResourceB is not yet committed.
  4. When the flow ends, Integration Server closes the connection for transaction 1 and commits its work to XAResourceA and XAResourceB.

Built-In Services for Transaction Management

Use the following built-in services to manage explicit transactions and set the transaction timeout interval for implicit and explicit transactions.

pub.art.transaction:commitTransaction

Commits an explicit transaction.

Input Parameters

Name Description
commitTransactionInput Document List Information for each commit request.
Key Description
transactionName String The name of an explicit transaction that you want to commit. The transactionName must have been previously used in a call to pub.art.transaction:startTransaction.

This value must be mapped from the most recent pub.art.transaction:startTransaction that has not previously been committed or rolled back.

Output Parameters

None.

Usage Notes

This service must be used in conjunction with the pub.art.transaction:startTransaction service. If the transactionName parameter was not provided in a prior call to pub.art.transaction:startTransaction, a run-time error will be returned.

pub.art.transaction:rollbackTransaction

Rolls back an explicit transaction.

Input Parameters

Name Description
rollbackTransactionInput Document List Information for each rollback request.
Key Description
transactionName String The name of an explicit transaction that you want to roll back. The transactionName must have been previously used in a call to pub.art.transaction:startTransaction.

This value must be mapped from the most recent pub.art.transaction:startTransaction that has not previously been committed or rolled back.

Output Parameters

None.

Usage Notes

This service must be used in conjunction with the pub.art.transaction:startTransaction service. If the given transactionName parameter was not provided in a prior call to pub.art.transaction:startTransaction, a run-time error will be returned.

pub.art.transaction:setTransactionTimeout

Manually sets a transaction timeout interval for implicit and explicit transactions.

Input Parameters

Name Description
timeoutSeconds Integer The number of seconds that the implicit or explicit transaction stays open before the transaction manager marks it for rollback.

Output Parameters

None.

Usage Notes

This service is available only if your adapter supports built-in transaction management services, which you can confirm by checking the user guide for the adapter.

When you use this service, you are temporarily overriding the Integration Server transaction timeout interval.

You must call this service within a flow before the start of any implicit or explicit transactions. Implicit transactions start when you call an adapter service in a flow. Explicit transactions start when you call the pub.art.transaction:startTransaction service.

If the execution of a transaction takes longer than the transaction timeout interval, all transacted operations are rolled back.

This service only overrides the transaction timeout interval for the flow service in which you call it.

pub.art.transaction:startTransaction

Starts an explicit transaction.

Input Parameters

Name Description
startTransactionInput Document List Information for each start transaction request.
Key Description
transactionName String Optional. Specifies the name of the transaction to be started. If you leave this parameter blank, Integration Server will generate a name for you. In most implementations it is not necessary to provide your own transaction name.

Output Parameters

Name Description
startTransactionOutput Document List Information for each start transaction request.
Key Description
transactionName String The name of the transaction the service just started.

Usage Notes

This service is available only if your adapter supports built-in transaction management services, which you can confirm by checking the user guide for the adapter.

This service is intended for use with the pub.art.transaction:commitTransaction or pub.art.transaction:rollbackTransaction service. The transactionName value returned by a call to this service can be provided to pub.art.transaction:commitTransaction (to commit the transaction) or pub.art.transaction:rollbackTransaction (to roll back the transaction).

Changing the Integration Server Transaction Timeout Interval

About this task

The Integration Server default transaction timeout is no timeout (NO_TIMEOUT). To change the server's transaction timeout interval, add the watt.art.tmgr.timeout parameter to the server.cnf file.

The watt.art.tmgr.timeout transaction timeout parameter does not halt the execution of a flow. It is the maximum number of seconds that a transaction can remain open and still be considered valid. For example, if your current transaction has a timeout value of 60 seconds and your flow takes 120 seconds to complete, the transaction manager will roll back all registered operations regardless of the execution status.

For more information about modifying the server.cnf file, see IBM webMethods Integration Server Administrator’s Guide.

To change the server's transaction timeout level

Procedure

  1. Shut down Integration Server.
  2. Open the server.cnf file in a text editor.
  3. Add the following parameter to the server.cnf file: 
    watt.art.tmgr.timeout=TransactionTimeout

    where TransactionTimeout is the number of seconds before transaction timeout.

  4. Restart Integration Server.