Edit

Share via

Technical validation

  • Article

Below you find a checklist of all requirements that you must meet before submitting an extension for validation. You also find a description of how the Business Central Validation team is performing technical and manual validation and how you can implement a validation pipeline to perform the same technical validation yourself.

Tip

If you have questions around validation for your app, see Technical Validation FAQ for more information about who to contact.

Technical Validation Checklist

If you don't meet these mandatory requirements, your extension fails validation. To get code validation helping you bring your extension package to AppSource, you can enable the AppSourceCop code analyzer. For more information, see Using the Code Analysis Tool.

Requirement Example/Guidance
Develop your extension in Visual Studio Code. Developing AL Language extension for Microsoft Dynamics 365 Business Centrals
The app.json file has mandatory properties that you must include. The 'name', 'publisher', and 'version' properties must match the values set in your offer description. Here you can also read more about dependency syntax and multiple countries/regions per a single app syntax. Mandatory app.json properties
Coding of Date must follow a specific format (no longer region-specific) Use the format yyyymmddD. For example, 20170825D.
Remote services (including all Web services calls) can use either HTTP or HTTPS. However, HTTP calls are only possible by using the HttpRequest AL type. Guidance on HTTP use
Only JavaScript based Web client add-ins are supported. The zipping process is handled automatically by the compiler. Include the new AL controladdin type, JavaScript sources, and build the app. Control Add-Ins
The .app file must be digitally signed. Sign an APP Package File
Set the application areas that apply to your controls. Failure to do so will result in the control not appearing in Dynamics 365 Business Central. Application Area guidance
Permission set(s) must be created by your extension and when marked, should give the user all setup and usage abilities. A user must not be required to have SUPER permissions for setup and usage of your extension. Exporting Permission Sets
Managing Users and Permissions
Before submitting for validation, ensure that you can publish/sync/install/uninstall/reinstall your extension. This must be done in a Dynamics 365 Business Central environment. How to publish your app
Thoroughly test your extension in a Dynamics 365 Business Central environment. Testing Your Extension
Don't use OnBeforeCompanyOpen or OnAfterCompanyOpen Replacement Options
Include the proper upgrade code allowing your app to successfully upgrade from version to version. Upgrading Extensions
Pages and code units that are designed to be exposed as Web services must not generate any UI that would cause an exception in the calling code. Web Services Usage
You're required to register affixes for your publisher name and to use them in your extension. Prefix/Suffix Guidelines
You're required to register an ID range for your publisher name and to use it in your extension. Object Ranges
We strongly recommend you're using automated testing, using the AL Test Toolkit. You aren't required to include the test package with your extension. Test the advanced sample extension
DataClassification is required for fields of all tables/table extensions. Property must be set to other than ToBeClassified. Classifying Data
You must use the Profile object to add profiles instead of inserting them into the Profiles table. Profile Object
Use addfirst and addlast for placing your actions on Business Central pages. This eliminates breaking your app due to Business Central core changes. Placing Actions and Controls
The extension submitted must not be a runtime package. Creating Runtime Packages
The extension submitted must use translation files. Working with Translation Files
The extension submitted must specify the Application manifest property. The Application manifest property is required in order to compute the minimum release of Business Central targeted by your submission. For more information, see Computation of Releases for Validation
The extension submitted should have a unique AppId. Every extension should have a unique AppId and it's not allowed to submit PTEs and AppSource apps with the same AppId. Also see Constraints on extension types.

Technical validation performed by the Business Central services

The primary responsibility of the technical validation is to ensure that the Business Central online service is stable and that the apps can be installed and run without destabilizing the service.

The technical validation is fully automated and validates the requirements defined in the technical validation checklist above.

Important

It's recommended that all partners run the self-validation documented in the following steps, before submitting apps for validation to maximize chances of validation success.

  1. The manifest of all extensions in the submission is validated. If any mandatory properties or required property values are missing, the submission is rejected..
  2. The registration of affixes for the publisher name of all the extensions in the submission is validated. If the publisher name does not have any registered affixes, the submission is rejected.
  3. The signature of all extensions in the submission are validated. If any extension is not signed or its signature is not valid, the submission is rejected.
  4. The consistency of the main extension information (name, publisher, version) is validated against the offer description. If any differences are noticed, the submission is rejected.
  5. The extensions in the submission are validated. If any runtime packages are present, the submission is rejected.

Once the extension has passed these first validation steps, the minimum release for your submission is computed as described in Computation of Releases for Validation.

For each country and each release targeted by your submission, the following steps are run for each extension in the submission:

  1. If the extension with the same version has already been validated for the country, further validation for this extension is skipped.
  2. The set of dependencies for your extension is resolved. Any unresolved dependencies will cause the submission to be rejected. If you include extensions created by Microsoft in your submission, it will also be rejected.

Note

You're required to include the dependencies for your extension as part of your submission only if you're submitting a newer version for them. If you don't include them in your submission, they will be downloaded automatically if they are available in Business Central for the targeted countries/regions. If you're making your libraries available in new countries/regions, you should increase the version number.

  1. The set of baselines for your extension is resolved by using the App Management API.
  2. The extension is compiled against the set of dependencies resolved. If the compilation fails, the submission is rejected.
  3. The extension is tested against the resolved baselines using the AppSourceCop analyzer. If any violations or breaking changes are identified, the submission is rejected.
  4. If the runtime version of the extension is not supported by the release targeted, the submission is rejected.

Additionally, if the extension submitted isn't the latest version and a higher version is available in the AppSource marketplace, additional validation is performed:

  1. The next version of your extension and its dependencies are resolved using the App Management API.
  2. The next version of your extension is tested against the version you submitted using the AppSourceCop analyzer. If any violations or breaking changes are identified, the submission is rejected.

If all extensions in the submission succeed the validation for each country and release without errors, the submission is accepted..

Running technical validation yourself

With the latest version of BcContainerHelper, you can run a single command, which should perform the same validation steps and give you a good indication of whether your apps pass validation or not:

$validationResults = Run-AlValidation `
    -validateCurrent `
    -installApps @( "path/url to your foreign dependencies, apps which will not be part of the validation (or blank if this is the first)" ) `
    -previousApps @( "path/url to your previous version of the .app files (or blank if this is the first)" ) `
    -apps @( "path/url to the new version of the .app files" ) `
    -countries @( "countries you want to validate against (f.ex. us,ca)" ) `
    -affixes @( "affixes you own (f.ex. fab,con)" ) `
    -supportedCountries @( "supported countries (f.eks. us,ca)" )
$validationResults | Write-Host -ForegroundColor Red

All array parameters can also be specified as a comma-separated string. For more information, you can also check this blog post Run-AlValidation and Run-AlCops.

Include app and all library apps in both previousApps and apps and also include all countries/regions on which you want to validate.

Note

The Run-AlValidation can't see whether the affixes to specify have been correctly registered with Microsoft using your MPN ID and app publisher name, please make sure registration is in place.

Important

The computer on which you run this command must have Docker and the latest BcContainerHelper PowerShell module installed and be able to run Business Central on Docker.

If you're having issues with Business Central on Docker, you might be able to find help here: https://freddysblog.com/2020/10/12/troubleshooting-business-central-on-docker.

You can use https://aka.ms/getbc?artifacturl=bcartifacts%2fsandbox%2f%2fus%2flatest to create an Azure VM, which has all prerequisites installed to run Business Central on Docker.

Note

It's recommended that all partners set up DevOps processes to ensure that this validation process happens automatically and regularly.

You can find resources for how to set up full plug-and-play DevOps processes using AL-Go for Github: https://aka.ms/AL-Go.

How to get more information on the technical validation failures?

Detailed validation results are automatically logged to telemetry in the the Azure Application Insights resource specified in the manifest of the main extension in your submission.

In order to enable partner telemetry in your extension, you must specify the applicationInsightsConnectionString property in the manifest (app.json) of your extension. For more information about this property, see JSON files.

In order to get started on analyzing your validation results, you can use this troubleshooting guide Dynamics 365 Business Central Troubleshooting Guide (TSG) - AppSource Submission Results (SaaS).

For more information about the signals sent to telemetry during the technical validation, see Analyzing AppSource Submission Validation Telemetry.

Note

You can setup alerts on validation telemetry. For example, you can send a daily/weekly notification to Teams/email on all validation failures across all your apps. For more information, see Alerting on Telemetry.

Against which releases of Business Central is your submission validated?

Extensions submitted to the AppSource marketplace are validated for all countries/regions specified in the submission against all the release targeted by the submission. As part of the validation, the minimum release for your submission is computed. The extensions are then validated for all releases from this minimum release to the current release in production. For example, if the minimum release for your submission is 18.0 and the latest minor release in production is 18.3, your submission is validated against 18.0, 18.1, 18.2, and 18.3.

The minimum release for your submission is computed based on the application property specified in the app.json of your extension.

Note

If multiple extensions are contained in your submission, the minimum release for the submission is the highest minimal release computed for each of the extensions in the submission.

Note

The telemetry sent during the technical validation contains details about validation success/failure against each release of Business Central specified above. For more information, see Analyzing AppSource Submission Validation Telemetry.

Important

The minimum release computed for your submission also defines the availability in Business Central of all the extensions in your submission.

For example, if the minimum release computed is 18.1, your extensions will be available starting from release 18.1.

Example

If your extension's manifest is defined as follows, the minimum release where your extension can be installed is 18.0 because the manifest requires the Application extension to be available with a version higher or equal to 18.0.0.0.

{
  "application": "18.0.0.0",
}

The minimum release of the extension is then 18.0.

For AppSource extensions, it's now required to use the application property instead of explicit dependencies on the Base Application and System Application. For more information, see The Microsoft_Application.app File and AS0085.

Developing AL Language extension for Microsoft Dynamics 365 Business Centrals Analyzing AppSource Submission Validation Telemetry