Blogs

How to use SecretText Data type in Business Central

Admin, May 17, 2024 1350 Views

Dynamics 365 Business Central is a powerful Enterprise Resource Planning (ERP) solution that offers a wide range of customization options to meet the unique needs of your business. One such customization is to set the shipment date as blank when creating a new sales order in Business Central. This customization can be particularly useful when you want to allow manual entry of the shipment date and prevent the system from automatically populating this field.

Prerequisites

• Access to a Microsoft Dynamics 365 Business Central instance.
• Basic knowledge of AL (Application Language) code.
• Visual Studio Code with AL Language extension installed.

Requirement

With an increasing amount of integrations to external systems, it’s not uncommon in AL code in Dynamics 365 Business Central Solutions to work with secrets such as credentials and other sensitive textual values. Given the need to protect these from being revealed through debugging, the latter has often been blocked through resource exposure policies, at the cost of easy troubleshooting. To support enabling debugging, while protecting credentials and other sensitive textual values from being revealed, we are introducing a new SecretText type for variables. In addition, some of the common scenarios in the system app will get support for passing in SecretText parameters for credentials—for example, the HttpClient and Isolated Storage types.

 

Solution (Implementation Steps)

A new type, SecretText, has been added to protect credentials and other sensitive textual values from being revealed through debugging. The declaration syntax will be similar to the Text data type, with the sole difference that it won’t support constraints on the length.

As you can see there is an error when there is a limit on SecretText length.

SecretText will be usable as a:

• Variable value:

Here, you cannot implicitly convert the type ‘Text’ to ‘SecretText’.

However, you can use the Format method to solve this issue.

You can also convert the ‘Text’ type to ‘SecretText’ by storing the ‘Text’ value in a ‘Text’ variable and assigning that variable to the ‘SecretText’ type.

Any text type will be assignable to the SecretText type as long as it can be converted to     the Text type. The SecretText type encapsulates a Text type.

• Return Value:

You can also use the SecretText type as a return value of a procedure.

• Parameter value:

You can use the SecretText type as a Parameter of a procedure.

Use of the SecretText type will be limited to carrying, for example, credentials from the point of creation to the destination method. The destination method must accept a SecretText value.

It’s also possible to convert Code type to SecretText type.

If a Code or other text type is to be stored, it’ll be converted into the Text type. A Dotnet string type will also be convertible to SecretText. However, constant or other types won’t be assigned to a SecretText type.

Also, it’s not possible to use the SecretText type in a message directly. It will show an error.

When you debug the SecretText type it will be shown as <HiddenValue>.

The following methods are available on the SecretText data type.

• IsEmpty(): Returns a value indicating whether the secret text contains any content.

• SecretStrSubstNo(): Replaces %1, %2, %3… and #1, #2, #3… fields in a string with the values you provide as optional parameters.

• UnWrap(): Returns the text contained text inside the secret text as a plain text value. This method exists for compatibility reasons and its use is discouraged as it can lead to secret exposure.

Note: The application object or method ‘Unwrap’ has scope ‘OnPrem’ and cannot be used for ‘Extension’ development.

Initially, events won’t support SecretText parameters; however, triggers will. The latter scenario is to support the case of control add-ins like the OAuth control add-in to return the credentials in a secure container.

In the system app, HttpClient will get support for passing SecretText parameters—for example, for credentials.

In the following example, the return value and parameter will not be debuggable: