Unit of Work API

The heart of the Backendless Transactions API is a request called UnitOfWork. It used by the client applications to compose a transaction. Composing a transaction means adding various database operations to a unit of work. These operations may be "linked" between each other by using the output/result on one operation as the input for another.

When the server receives a UnitOfWork request, it starts processing its operations. The server executes all operations one-by-one in the context of a single database transaction. If any of the operations fails, Backendless rolls back all the changes and returns the information about the result of each operation to the client. However, if all operations succeeded, the entire database transaction is committed. This means the data will be finalized in the database.

Running a Transaction

Use the API below to run a transaction in Backendless:

Method

POST

Endpoint URL

The xxxx.backendless.app is a subdomain assigned to your application. For more information see the Client-side Setup section of this documentation.

https://xxxx.backendless.app/api/transaction/unit-of-work

Request Headers

Content-Type:application/json  
user-token: value-of-the-user-token-header-from-login

where:

Argument	Description
Content-Type	Must be set to application/json. This header is mandatory.
user-token	Optional header. Contains a value returned by Backendless in a preceding user Login API call. If the header is present, the operation will be executed with the security policy associated with the currently logged in user. This means all permissions associated with the user and the roles assigned to the user will be enforced by Backendless.

Request Body

{
  "isolationLevelEnum" : "REPEATABLE_READ" | "READ_COMMITTED" | "READ_UNCOMMITTED" | "SERIALZABLE",
  "operations": [
    {
      "operationType": "CREATE" |  "CREATE_BULK" | "UPDATE" | "UPDATE_BULK" | "DELETE" | "DELETE_BULK" | "FIND" | "ADD_RELATION" | "SET_RELATION" | "DELETE_RELATION",
      "table": "TABLENAME",
      "opResultId": "OPRESULT-ID",
      "payload": {
          PAYLOAD VARIES BETWEEN OPERATIONS
      }
    },
    {

    },
    {

    }
  ]
}

where:

Argument	Description
isolationLevelEnum	A property containing a value which sets the isolation level for this transaction. Supported values are: "REPEATABLE_READ","READ_COMMITTED", "READ_UNCOMMITED", "SERIALZABLE". For more information about transaction isolation levels, see the Isolation Level section.
operationType	A property containing a string value indicating the type of the operation object. Supported values are: "CREATE"  - saving a single object operation "CREATE_BULK"  - saving multiple objects operation "UPDATE" - updating a single object operation "UPDATE_BULK" - updating multiple objects operation "DELETE" - deleting a single object operation "DELETE_BULK" - deleting multiple objects operation "FIND" - retrieving objects operation "ADD_RELATION" - an operation for adding child objects to a parent for a relation "SET_RELATION" - an operation for setting child objects to a parent for a relation "DELETE_RELATION" - an operation for disconnecting child objects from the parent for a relation
table	A string property which must contain the name of the table where the operation will be performing its work. For example, if it is an operation to store an object in a table called Person, then the value of the table property must be "Person".
opResultId	An optional property. If present must contain a unique string value identifying the operation. For more information see the OpResult Id section below.
payload	A JSON object with the details specific to each operation. See the sections describing supported operations for details about the payload format.

Return Value

A JSON object of the following format:

{
  "success": true | false,
  "error": null | string-value,
  "results": {
    "operationResultId1": {
      "type": "OPERATION-TYPE",
      "result": VALID-JSON,
    "operationResultId2": {
      "type": "OPERATION-TYPE",
      "result": VALID-JSON
    }
  }
}

where:

Argument	Description
success	Is a property indicating whether the entire transaction has completed successfully or failed and thus had been rolled back.
error	If the transaction resulted in an error, this property contains the error message.
operationResultId1..N	Reference to a transaction operation. The name of the property is the same as the value as in the opResultId property from the corresponding operation in the request.
type	Type of the operation, it contains the same value as the operationType property in the corresponding operation in the request.
result	A JSON value which is the result of the specific operation identified by the operationResultId1..N property.

Codeless Reference

You can run transactions using the following Codeless block:

where:

Argument	Description
transaction	Expects an object containing transaction details, this includes: operation type and data.
return result	When this box is checked, the operation is set to return an object containing the operation result.
throw error	Check this box to return an error in case if the operation cannot be executed.

Find the example in the OpResult Id section below to learn more about how this block is used in the Codeless logic.

Operations

UnitOfWork supports the following database operations. Each operation is described in detail in the sections of this guide that follow.

• Retrieving objects - retrieves data from the database. Can use all data querying features of Backendless: with a where clause, using paging, sorting, pre-loading of relations, retrieving specific properties, etc.
• Saving a single object - stores a new object in the database.
• Saving multiple objects - stores one or more new objects in the database.
• Updating a single object - updates an existing object in the database.
• Updating multiple objects - updates one or more existing objects in the database.
• Deleting a single object - deletes a single object from the database.
• Deleting multiple objects - deletes one or more objects from the database.
• Setting a relation between objects - sets child objects in a relation with the parent object. All other child objects the parent might have had in the relation are disconnected from the parent.
• Adding objects to a relation - adds child objects to a relation with the parent object. Any child objects the parent had the relation with remain in the relation.
• Removing objects from a relation - disconnects child objects from the parent for a relation.

OpResult Id

Every operation in a transaction can be identified with a property called opResultId. It is a free form, string value which you can assign to an operation for the following purposes:

1. An operation with the opResultId property can be referred to from another operation. This is done to indicate that the results of one operation should be used as the input argument in another one.
2. When the transaction is complete, you can see the results of each operation. These results are mapped to the value of the opResultId property.

The opResultId property is not required, when it is not present in an operation object, server generates and assigns a value using the following pattern:

operation name + table where operation is performed + sequential number

For additional details about OpResult ID, see the Operation Result chapter of this guide.

Codeless Reference

The example below saves a new object to the Person data table using the "Create" Operation Codeless block. After the Codeless logic runs, the operation assigns the operation reference to the opResultId variable. Refer to the Saving a single object topic to learn more about the "Create" Operation Codeless block.

Verifying Transaction Result In Codeless

Returns a boolean value indicating the transaction result.

Consider the structure of the data table called Person:

The following example creates and runs a transaction containing a "Find" Operation and returns true, indicating that the transaction is successful. Note that this block must be used after the Run Transaction Codeless block as shown below: