Business Central 2025 wave 1 (BC26.1): New method to add SecretText values to JSON objects – WriteWithSecretsTo

Hi, Readers.
Dynamics 365 Business Central 2025 wave 1 (BC26) is generally available. More details: General Available: Dynamics 365 Business Central 2025 release wave 1 (BC26).
And minor update 26.1 for Business Central 2025 release wave 1 has been released for Business Central online. More details: Cumulative Update Summary for Microsoft Dynamics 365 Business Central (May, 2025)

I will continue to test and share some new features that I hope will be helpful. This new feature is not yet documented in the Business Central 2025 release wave 1 (BC26) release plan but is mentioned in AL Language extension changelog Version 15.0.

New method to add SecretText values to JSON objects – WriteWithSecretsTo:

A new method was added to the JsonObject type, which allows developers to add SecretText values. To use it, the AL developer first creates a JSON object with placeholder values for their secret values. Then they provide paths to the values in the JPath format as well as the values themselves. Finally, the method produces a new SecretText value with the credentials replaced.
https://marketplace.visualstudio.com/items/ms-dynamics-smb.al/changelog

In Business Central 2023 wave 2 (BC23), Microsoft introduced a new SecretText type to protect credentials and sensitive textual values from being revealed.

More details: Business Central 2023 wave 2 (BC23): Use SecretText type to protect credentials and sensitive textual values from being revealed (New SecretText type)

And we also mentioned this new data type recently. More details: Dynamics 365 Business Central: How to use OAuth 2.0 in AL with SecretText (Using codeunit 501 OAuth2)

With this minor update (BC26.1), Microsoft has added a new method to add SecretText values to JSON objects – WriteWithSecretsTo.

procedure WriteWithSecretsTo(Secrets: Dictionary of [Text, SecretText], var Result: SecretText): Boolean: Replaces the placeholder value in the path with the secret and then serializes and writes the content of the JsonObject to a SecretText.

Here is an example from Microsoft:

    procedure CreateSecretBody(ApiKey: SecretText; SecretSalt: SecretText): SecretText
    var
        JsonBody: JsonObject;
        Secrets: Dictionary of [Text, SecretText];
        Result: SecretText;
    begin
        // Create a debuggable body
        JsonBody.Add('type', 'Some type');
        JsonBody.Add('api_key', 'placeholder');
        JsonBody.Add('salt', 'placeholder');

        // Prepare the replacements
        Secrets.Add('$.api_key', ApiKey);
        Secrets.Add('$.salt', SecretSalt);

        // Produce the secret body
        JsonBody.WriteWithSecretsTo(Secrets, Result);
        exit(Result);
    end;

Simply put, only three steps are needed:

Create a JsonObject with placeholder values for their secret value – debuggable body (Can include value that do not require encryption such as type in the example.)
Define the paths to these placeholders in JSONPath format (In dot-notation: $.event.data.name)
Using new WriteWithSecretsTo method to produce the secret body

Another simple example:

Note:

‘WriteWithSecretsTo’ is not available in runtime version ‘15.0’. The supported runtime versions are: ‘15.1’ or greater. AL AL0666

Very simple. Give it a try!!!😁

END

Hope this will help.

Thanks for reading.

ZHU