ErrorInfo data type & Collectible Errors

by Oct 7, 2021AL 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). 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

Exploring CosmosDB with Business Central, part 2

Exploring CosmosDB with Business Central, part 2

This part explains how to connect to Azure Cosmos DB from your Business Central extension using AL Language and how to get some values from the database.------------------------------------------------------------------------------------------------------------------...

read more
DynamicsCon 2021 session recording available!

DynamicsCon 2021 session recording available!

Finally, recordings from DynamicsCon 2021 Autumn edition are available! Check the official youtube channel. It was a great conference with over 250 people during my live session! I definitely hope I will be able to attend the next in-person DynamicsCon as a speaker...

read more
Directions EMEA day 0 ;)

Directions EMEA day 0 😉

Directions4Partners EMEA 2021 is still in progress here in Milan. I want to share all details about each day, but unfortunately, there are so many amazing things to see, watch and try I have almost no time. So today just a few words about the day before the...

read more
Working with Translation Files (XLIFF)

Working with Translation Files (XLIFF)

How does the translation file work? In Microsoft Dynamic 365 Business Central, displaying different languages is done using the XLIFF files extension (.xlf). The generated XLIFF files have strings that are specified in properties like Captions, Tooltips......

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
Field Level Permissions (Restricted Fields)

Field Level Permissions (Restricted Fields)

I just add a new project to my GitHub repositories. It is a new extension for Business Central that extends security functionalities with field-level permission. Using this extension, users are able to define who can or can not change specific fields in any table in...

read more
How to let users choose field(s) properly

How to let users choose field(s) properly

When some complex functionality is developed, it is sometimes necessary to let users choose a specific field. This can be required for field permissions, mapping imported values or any similar process. Earlier, the usual way was to create a link on the Field table...

read more