Dynamics 365 Business Central: Method Commit Behavior (CommitBehavior Attribute)

Hi, Readers.
Today I would like to talk briefly about Method Commit Behavior in Business Central.

When a codeunit begins, it automatically enables write transactions to be performed. When an AL code module completes, it automatically ends the write transaction by committing the updates made by the AL code.

This means that if you want the codeunit to perform a single write transaction, it is automatically handled for you. However, if you want the codeunit to perform multiple write transactions, you must use the Commit method to end one write transaction before you can start the next. The Commit method separates write transactions in an AL code module.
More details: Database.Commit() Method

In short, Commit method will end the current write transaction. Therefore, even if an error occurs after the Commit method, the writing transaction before the Commit method has been completed and will not roll back to the original state.
For example, the customer’s name will be modified.

In fact, we can specify the behavior of a commit call inside the method scope via CommitBehavior Attribute.

CommitBehavior Attribute: Specifies if a commit must be ignored or throw an error. The options are: Ignored or Error.

Applies To: Method

Syntax: [CommitBehavior(Behavior: CommitBehavior)]

PS: You can find it in some standard code, for example, codeunit 80 “Sales-Post”:

Let’s look at a specific example. I created a simple method to change the customer name, then added three different commit behaviors to call this method. Each of these ends up throwing an error.

For easy testing, these three behaviors are added as 3 actions.

Test:
1. No CommitBehavior Attribute: This is valid, and commit call will be executed.

The customer name will be modified.

2. CommitBehavior::Ignore: This call will be silently ignored.

The customer name will not be modified.

3. CommitBehavior::Error: This will throw an error. No further code will be executed and the user will see a dialog to contact the system administrator.

Commit is prohibited in the current scope. The operation cannot continue. Contact your system administrator.

The customer name will not be modified.

Test Video:

Give it a try!!!😁

Note:
It’s only possible to assign a more restrictive commit behavior. That is, if CommitBehavior::Ignore is attempted on a method scope, but the method calling the current method, for example, the parent method is actually running with CommitBehavior::Error, then the current method will continue running with CommitBehavior::Error, even though the Ignore attribute was specified.

Note:
The CommitBehavior only lasts for the method scope. Regardless of whether the method finishes successfully or if an error causes the method to exit prematurely, the CommitBehavior reverts to the standard behavior, where commit statements will commit to the database.

Test Code:

pageextension 50101 CustomerListExt extends "Customer List"
{
    actions
    {
        addfirst(processing)
        {
            action(AllowCommit)
            {
                Caption = 'Allow Commit';
                Promoted = true;
                PromotedCategory = Process;
                PromotedIsBig = true;
                PromotedOnly = true;
                ApplicationArea = All;
                Image = ExecuteBatch;

                trigger OnAction()
                begin
                    FunctionAllowCommit();
                end;
            }
            action(IgnoreCommit)
            {
                Caption = 'Ignore Commit';
                Promoted = true;
                PromotedCategory = Process;
                PromotedIsBig = true;
                PromotedOnly = true;
                ApplicationArea = All;
                Image = ExecuteBatch;

                trigger OnAction()
                begin
                    FunctionIgnoreCommit();
                end;
            }
            action(ErrorCommit)
            {
                Caption = 'Error Commit';
                Promoted = true;
                PromotedCategory = Process;
                PromotedIsBig = true;
                PromotedOnly = true;
                ApplicationArea = All;
                Image = ExecuteBatch;

                trigger OnAction()
                begin
                    FunctionErrorCommit();
                end;
            }
        }
    }

    local procedure FunctionAllowCommit()
    begin
        ModifyCustName();
        Commit(); // This is valid, and commit call will be executed.
        Error('This is an error');
    end;

    [CommitBehavior(CommitBehavior::Ignore)]
    local procedure FunctionIgnoreCommit()
    begin
        ModifyCustName();
        Commit(); // This call will be silently ignored.
        Error('This is an error');
    end;

    [CommitBehavior(CommitBehavior::Error)]
    local procedure FunctionErrorCommit()
    begin
        ModifyCustName();
        Commit(); // This will throw an error. No further code will be executed and the user will see a dialog to contact the system administrator.
        Error('This is an error');
    end;

    local procedure ModifyCustName()
    var
        Cust: Record Customer;
    begin
        if Cust.Get('C00030') then begin
            Cust.Validate(Name, 'Test' + Format(Random(100)));
            Cust.Modify();
        end;
    end;
}

END

Hope this will help.

Thanks for reading.

ZHU