Rules and Guidelines for AL Code
This page defines the rules and guidelines to follow when writing AL code in an extension package for Dynamics 365 Business Central. The rules and guidelines are grouped according to two importance levels: critical errors that must be resolved, and important errors that should be resolved. Errors that are not resolved must include an explanation and justification for the error.
- Code uses encryption key functions such as IMPORTENCRYPTIONKEY, EXPORTENCRYPTIONKEY, CREATEENCRYPTIONKEY, and DELETEENCRYPTIONKEY. (It is fine to use the ENCRYPT and DECRYPT methods.)
- Code uses ASSERTERROR.
- External data connections do not properly handle sensitive data.
- It does not encrypt sensitive table data. (i.e. credit card info, passwords, etc.).
- Temporary files are not cleaned up after use.
- Code uses codeunits that require printers to be selected.
- Code uses a specific time zone or locale.
To help you save time, we're sharing a list of the top 15 common pitfalls that regularly lead to app validation failures.
One of the app requirements is for you to reserve a prefix/suffix for your app. This is needed to ensure a healthy app ecosystem by avoiding collision amongst apps. This common failure occurs due to not setting your prefix/suffix in some or all required places. For more information, see Benefits and Guidelines for using a Prefix or Suffix.
DataClassification missing or set incorrectly
Due to GDPR requirements, fields of field class Normal must use the DataClassification property, and its value must be different from ToBeClassified. This applies to fields in tables and table extensions. Use the AppSourceCop tool for detecting this.
Required translation files missing
There are many countries today that where Dynamics 365 Business Central is available, and that you can support as well with your app. For specifying additional languages, we no longer support Caption ML. You must use xliff translation files instead. For more information, see Working with Translation Files.
Microsoft provides a free translation tool that you can access from https://lcs.dynamics.com. To support a specific country, you must include a translation file per for each language code. For example, to support Switzerland, you must provide fr-CH, de-CH, and it-CH.
Missing permission sets
Your app must provide one or more permission sets so that users can use your app's functionality. Your app must never require the SUPER permission set.
For your app to be a good citizen in Dynamics 365 Business Central, permission errors must not appear unless it is a necessary reason for showing the error.
It is acceptable to throw an error to a user that does not have your permission set marked and tries to access your page object. It is not acceptable to throw an error to that same user trying to access Business Central pages in the base application, or to throw an error to a user who is not trying to access your app's functionality.
Missing application area tagging
Tag in which part your app participates. Pages, controls, actions, and fields will not appear in Dynamics 365 Business Central if the Application Area property has not been set.
Usage Category not set
You enable a page or report to be available through search in Dynamics 365 Business Central by using the UsageCategory property. For more information, see Using Tell Me to Find Features and Information.
Due to their performance impact, OnBeforeCompanyOpen and OnAfterCompanyOpen cannot be used. For more information, see Replacing OnBeforeCompanyOpen and OnAfterCompanyOpen.
Make sure that your app can be upgraded properly. For more information, see Upgrading extensions.
Do not insert into the Profile table. Use the Profile object instead.
App file not properly code signed
Your app file must be digitally signed with a certificate from a third-party certification authority trusted by Windows.
You tested your app on an obsolete Dynamics 365 Business Central version (or never even tested it)
Make sure that your app is properly tested on the correct version. For more information, see Current Build - Developing for Dynamics 365 Business Central on the Collaborate site.
You tested using SUPER permissions
You tested your app, but your user had SUPER permissions. This can hide critical errors. You must test with a user that doesn't have the SUPER permissions. The user must have the ESSENTIAL license. For more information, see Testing your Extension.
User scenario document unclear
Our validation team is testing your app functionality manually, so we need to be able to understand the core functionality of your app. If your user scenario document is missing important details that are needed for us to properly walk through your app's setup and usage scenarios, we cannot validate your app successfully. For more information, see User Scenario Documentation.
The .json file is incorrect
There are many values in the app.json file that may not be mandatory to compile your app, but are mandatory for your app to be in AppSource. For example, your app cannot be published to a production tenant if the target value is set to OnPrem. It must be set to Cloud. For information, see JSON Files.