New CRM SDK Feature - Transactional Batching

19 April 2015

Daniel Cai

Data integrity is critical to business. Transactional support is one of the important ways to ensure data integrity, which is something that you often run into in your CRM data integration project. The introduction of "Transaction Batching" feature in CRM Online 2015 Update 1 release is one important step forward as it enables an important integration scenario, which was not possible in previous CRM versions.

The Transactional Batching feature works in the following all or none fashion.

You put a batch of multiple individual requests into one ExecuteTransaction request, which contain a collection of CRM records that you want CRM server to process as a batch.
You submit the ExecuteTransaction request to CRM server.
CRM server process each record in the batch in the sequence as they came in within a single db transaction.
If all records have been successfully processed, the whole batch is committed; otherwise if any of the record fails, the whole batch is rolled back (all or none fashion)

Now let me show you how to put this in action. Say I am trying to create 10 account records, they should be all in CRM or none of them. The following snippet shows you how to utilize ExecuteTransaction request to achieve this.

using (var service = new OrganizationService(crmConnection))
{
    var request = new ExecuteTransactionRequest()
    {
        Requests = new OrganizationRequestCollection()
    };

    for (int i = 1; i <= 3; i++)
    {
        var account = new Entity("account");
        account["name"] = string.Format("Test Account {0}", i);

        var createRequest = new CreateRequest() { Target = account};
        request.Requests.Add(createRequest);
    }

    var response = (ExecuteTransactionResponse)service.Execute(request);

    foreach (var responseItem in response.Responses)
    {
        var createResponse = (CreateResponse)responseItem;
        Console.WriteLine("Account created: {0}", createResponse.id);
    }
}

As you can see, ExecuteTransactionRequest works very similarly to ExecuteMultipeRequest (It might have been a better alternative if Microsoft Dynamics CRM team has designed the Transactional Batch feature to work as an option of ExecuteMultipleRequest).

Some Closing Notes

An ExecuteMultipleRequest can contain ExecuteTransactionRequest messages, and each ExecuteTransactionRequest is responsible for all records in its own batch by running them in one single transaction.
An ExecuteTransactionRequest cannot contain any ExecuteTransactionRequest or ExecuteMultipleRequest messages. If you try to do so, you will get an error indicating "ExecuteMultiple or ExecuteTransaction Requests cannot be executed inside another ExecuteTransaction request!"
CRM transactional batching request (ExecuteTransactionRequest) is constrained by the same limits that are imposed on ExecuteMultipleRequest.
- The maximum allowed batch size is 1000.
- CRM online has a throttling of 2 concurrent batch requests. If you try to send more than 2 simultaneous batch requests to CRM online server, you will get an error indicating the server is busy.
In the case when an ExecuteMultipleRequest contains ExecuteTransationRequest messages, the batch size of the ExecuteMultiple request is calculated by the total of all individual items.
The requests that make up the ExecuteTransactionRequest do not have to be of the same type. You can have a mix of CreateRequest, UpdateRequest messages in the same batch.
In the case that you need transactional support when creating records for a master/detail scenario (such as salesorder, salesorderdetail entities), you should continue to use RelatedEntities approach. Using ExecuteTransactionRequest is not going to help in this particular case, as there is no way to establish the relationship since the master record's ID is not known.
Using ExecuteTransactionRequest means that the db transaction will take longer to commit, and it can block other operations in the system. So use it with discretion!
For more details about this feature, please check out CRM SDK documentation page: Execute messages in a single database transaction.