ErrorInfo data type & Collectible Errors

by Jan 7, 2022AL Language

Home 9 Development 9 AL Language 9 ErrorInfo data type & Collectible Errors

A major change to AL Language development is here! Collectible errors can hugely improve any validation procedures. And what’s new? Everything is about a new data type ErrorInfo.

ErrorInfo data type

ErrorInfo is a new data type introduced in Microsoft Dynamics 365 Business Central 2021 wave 2 (autumn 2021). This new data type greatly improves error management, user readability of these errors and also enhance information users can get from these errors.

Before this data type, the only way how a developer could raise an error was using the Error(Text) procedure. Once this error was called, the system break the current activity (except if raised inside the Try function, but it’s a different topic).

Now developers have another method Error(ErrorInfo). That means the Error method now accept two different data types as its parameter (Text and also ErrorInfo).

What’s ErrorInfo

ErrorInfo is a complex data type. It contains many methods using which you can enhance the information provided to users or admins. The complete list of all available methods is at Microsoft Doc (https://docs.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/methods-auto/errorinfo/errorinfo-data-type).

As a developer, you can use (for the rest of the available methods see Microsoft Docs above):

Message([String])
– Specifies the message that will be sent to telemetry / appear in the client.

DetailedMessage([String])
– Specifies a detailed error message. This message is shown in the client under the “Detailed Information” section, once it is expanded.

CustomDimensions([Dictionary of [Text, Text]])
– You can define Dictionary of Text/Text to show additional information to users. For example, you can add information about the current record or about any calculation.

Verbosity([Verbosity])
– Specifies the severity level of the error. Values include ‘Critical’, ‘Error’, ‘Warning’, ‘Normal’, and ‘Verbose’.

There are other methods (Callstack(), FieldNo([Integer]), Verbosity([Verbosity]), …) which allow defining additional information for users/admins or to read information about the error itself by developers (for example Callstack() returns the whole call stack when the error was raised).

Collectible Errors

Collectible errors are another news that is available with ErrorInfo data type. Using collectible errors we can do more advanced validations and raise the error (or ALL ERRORS) at the end of the whole procedure. This means with only one error visible in the client, users can be notified about all validation errors. In my opinion, this is one of the greatest enhancements of the Business Central usability for many years.

Let’s see some details and examples.

Standard error

The standard error (non-collectible Error(ErrorInfo) or Error(Text)) breaks current activity and show the error message in the client / send it to telemetry. For example, the code below shows an error message containing “Error no. 1”.

local procedure StandardErrorProcedure()
var
    Counter: Integer;
begin
    for Counter := 1 to 5 do
        Error('Error no. %1', Counter);
end;

Collectible Errors

With collectible errors, the system does not break the current activity (even if one or more errors are raised) until the end of the procedure that is defined using ErrorBehavior annotation. Once the method ends and there were errors raised, the error message that contains the first error in the main section and all others in the “Detailed Information” section is raised.

To create a collectible error, the method must be annotated with ErrorBehavior(ErrorBehavior::Collect) syntax and ErrorInfo instances must be set as Collectible(true). See the example below.

[ErrorBehavior(ErrorBehavior::Collect)]
local procedure CollectibleErrorProcedure()
var
    MyErrorInfo: ErrorInfo;
    Counter: Integer;
begin
    for Counter := 1 to 5 do begin
        Clear(MyErrorInfo);
        MyErrorInfo := ErrorInfo.Create(StrSubstNo('Error no. %1', Counter));
        MyErrorInfo.DetailedMessage(StrSubstNo('The error was raised. This is error number %1', Counter));
        MyErrorInfo.Collectible(true);
        Error(MyErrorInfo);
    end;
end;

Handling Collectible Errors

You can also handle collectible errors by yourself using three new system methods:

GetCollectedErrors([Boolean]): List of [ ErrorInfo ]
– Using this method you can get a list of all raised Errors marked as collectible. The method accepts a boolean parameter that specifies whether the collected errors should be cleared. If you specify TRUE, it has the same behaviour as calling GetCollectedErrors(false) + ClearCollectedErrors().

HasCollectedErrors(): Boolean
– Returns true if there are any collected errors.

ClearCollectedErrors()
– Clear memory for collected errors. If you clear collected errors, the activity won’t be interrupted at the end of the method and hence no rollback will be performed.

Recent Articles from the category

Connect to Azure Function in BC 2022 wave 2 (v21)

Connect to Azure Function in BC 2022 wave 2 (v21)

The new version of the Microsoft Dynamics 365 Business Central brought a new system module "Azure Functions" that makes integration with Azure Functions much easier and straightforward. The typical scenario, why to use Azure Functions together with Business Central,...

read more
Collectible Errors?! Is it already in use?

Collectible Errors?! Is it already in use?

Collectible Errors?! Is it already in use? This is the second part of my new article series about Collectible Errors. Let's check out the first part here: Collectible Errors?! | Microsoft Dynamics 365 - Ing. Tomáš Kapitán (kepty.cz) or you might be interested in my...

read more
Collectible Errors?!

Collectible Errors?!

Collectible Errors?! It has been already almost a year since ErrorInfo datatype & CollectibleErrors were introduced (I already have an article about basic structure: ErrorInfo data type & Collectible Errors). This article was released for the first time in...

read more
Substituting standard reports

Substituting standard reports

Report objects cannot be extended in versions previous to the Business Central 2021 release wave 1 version when ReportExtensions object was introduced. Since then, many of changes we need to do in reports can be done without creating a new copy of object. On the other...

read more
Isolated events

Isolated events

With Business Central 2022 wave 1, a new setting for event publishers was introduced. Until this version, any error in any event subscriber caused interruption to the current running process and stopped the whole activity. In some cases (such as log-in), this is...

read more
Custom Filter Tokens

Custom Filter Tokens

As a user of the Business Central you have some constants you can use to filter or insert values. These constants contain useful values for data manipulation such as t / today for date field - return current dateq / quarter for date field filters - return range of the...

read more
1D & 2D Barcodes in Business Central 19.1

1D & 2D Barcodes in Business Central 19.1

Business Central (cloud-only!) includes one-dimensional (1D) barcode fonts since Microsoft Dynamics 365 Business Central 2020 wave 2 (17.0) was released in October 2020. It is a great improvement to how developers can handle requirements from their clients to print...

read more

Sign Up for News

Certifications

Highest certification
Microsoft Data Management and
also in D365 Business Central

Microsoft Certified: Dynamics 365 Business Central Functional Consultant Associate

See other certifications here