Transaction Management

Use these APIs to start and end a transaction that requires more than one API call. The primary use case is when adding a scheduler. If a transaction is started and never ended, the transaction will become invalid after a timeout period of 60 minutes (editable in config tool).

Requests

You can use the following transaction management requests:

Type=[String]

{
"startIndex": [Integer],
"maxSize": [Integer],
"available": [Integer],
"results": [
{
“meta”: {
“type”: “APITransaction”,
“id”: [String],
“uri”: “http://.../apitransaction/{id}
},
“transactionType”: [String],
“schedulerId”: [String],
“expirationTime”: [TimeStamp],
“state”: [String]
}]}

{
“schedulerId” : [String],
"transactionType" : [String]
}

{
 "meta": {
    "type": “APITransaction”,
    "id": [String],
    "uri": "http://.../apitransaction
/{id}"
}

{
“success” : [Boolean],
“message” : [String]
}

{
“success” : [Boolean],
“message” : [String]
}

Transaction Management Data Dictionary

• scheduler

  Allowed values: Any valid AAI schedulerId

• transactionType

  Allowed values: addScheduler

• Type

  Allowed values:

  • addScheduler
  • event
  • schedulerDefinition

  For information about the query parameter, see Appendix A - Query Parameters

Recommendations: Closing a Transaction

A PUT request is used to close a transaction. This request can take a long time when using AAI for versions up through 5.8.1. It starts the JAWS converter and completes once the converter is finished. In certain situations, the converter time-to-run can be very long and, as a result, the observed time of the PUT request can be very long as well.

A few questions arise when the PUT request is unexpectedly long. These are given below and answered. Recommendations to using PUT to close a transaction are provided:

1. How long should a user wait before retrying a PUT request to close a transaction?

   If a PUT request for closing a transaction has not completed, then the user should wait for the transaction to finish.

2. How does a user know if a PUT request to close a transaction is still in progress?

   A schedulerId is needed to determine if a PUT request for closing a transaction is still in progress. A schedulerId is provided when creating an empty scheduler with the POST request to /schedulers. It can be retrieved by a GET request to /schedulers.

   The PUT request to close a transaction will be in progress if the associated transactionId can be retrieved. A user can retrieve the transactionId for a scheduler with a GET request to /apitransaction/{schedulerId}. This GET request will return any active transactionId associated with the given schedulerId. The PUT request to close a transaction remains in progress if the return value from the GET request is not an empty array; the ‘non-empty’ array could include the line, ‘ “state” : “CLOSED” ’, but still the transaction remains in progress. In contrast, an empty array indicates that the transaction is complete.

3. What happens when a user submits a transaction and there is a PUT transaction in progress?

   A user should always wait for a PUT request for closing a transaction to finish before attempting to start another transaction. If a POST request is made to /apitransaction for a scheduler with a transaction in progress, the request will fail, and the response will indicate ‘Transaction in progress".