Warning: number_format() expects parameter 1 to be float, string given in /data/web/virtuals/7298/virtual/www/wp-includes/functions.php on line 412

ErrorInfo data type & Collectible Errors

by Oct 7, 2021AL Language

Home 9 Development 9 AL Language 9 ErrorInfo data type & Collectible Errors ( Page )

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). As of 05.10.2021, insider preview W1 19.0 (Platform 19.0.29480.29907 + Application 19.0.29956.0), the method Error(ErrorInfo) is available for OnPremise only. If you have an AL project with the “target”: “Cloud” setting you won’t be able to use Error(ErrorInfo) method (unknown method error). This is confirmed as a bug and will be fixed by Microsoft as soon as possible (already working on the hotfix).

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. As of 01.10.2021, insider preview W1 19.0 (Platform 19.0.29480.29907 + Application 19.0.29956.0), the detailed message is not shown (probably a bug).

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’. As of 04.10.2021, the documentation is a bit unclear. The description of DataClassification([DataClassification]) contains values of Verbosity([Verbosity]) instead of its own. The fix of the Microsoft documentation is on the way.

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

Returning complex types in AL Language

Returning complex types in AL Language

In Microsoft Dynamics 365 Business Central 2021 w1 (released in May 2021), a profound change was introduced to ways how we can design our applications Until this version, the only way to return complex data types (like records, codeunits, Lists etc.) was using the var...

read more
Import various file types with Interfaces

Import various file types with Interfaces

A few weeks ago, I described a solution for importing an Excel file to the Business Central using Excel Buffer in AL Language (see here). In today's article, we will look at how to build a more complex solution that can be used for file imports without the needs to...

read more
How to import Excel files using Excel Buffer

How to import Excel files using Excel Buffer

Last week, I saw a question about importing data from Excel file to Business Central using AL Language. A few years ago, the only solution was to use DotNet integration. However, with the Business Central, there is a much quicker and better approach. All functions for...

read more