App identity

Apps built using AL extend the functionality of Business Central. The app.json file is, together with the launch.json file, automatically generated when you create a new AL project. The app.json file contains information about the app that you are building, such as publisher information and specifies the minimum version of base application objects that the extension is built on. Often the app.json file is referred to as the manifest. The app.json file contains numerous project settings, but a few of them constitutes the actual identity of the app that you are creating.

Note

With Business Central 2021 release wave 2, name and publisher are no longer considered part of the app identity and can therefore be changed to reflect branding or acquisition, for example. If the name and/or publisher information is changed, the version must also be incremented. If you are using workspaces with multiple projects and change the name or publisher of an extension in the workspace, the dependencies in the app.json file must be updated with the new name and publisher or you may encounter issues with reference resolution. For more information, see Working with Multiple Projects and Project References.

Important

In cases where the Application app is substituted with another application app, the name is still used as identification. For more information, see The Microsoft_Application.app File.

Setting	Example	Description
id	"id": "ef4dabfc-1de7-4d90-b948-4a9c2933d794"	The id, also known as the app ID. This is a GUID which is auto-generated when the project is created. The app ID is also bound to how tables are named in Business Central and how the identity of an application is computed. Changing the app ID may have severe consequences, such as the app not functioning properly, or data not being available.
version	"version": "1.0.0.0"	The version is used to distinguish between different iterations of your app. The version number should increase as you make changes to your app.

For more settings, see JSON Files.

For apps published in the Global scope, see Publish NAVApp, such as AppSource and 1st party applications, the id and the version identify a unique application package. The Business Central service uses these tuples to refer to apps in different flows. To prevent issues, it is required that the id remains the same after an app is uploaded to the Business Central service, and that you only increment the version.

For apps published in the Tenant scope, see Publish NAVApp, such as per-tenant customizations, in addition to the id and version, the tenant ID is also used to uniquely identify an app.

When is it okay to change the ID of an app?

The id of an app is automatically generated by the AL Language extension when you create a new app or if you use the AL: Generate manifest command.

If you have copied the app or the manifest from another app, you must change the id before publishing it to the online service as a per-tenant extension or AppSource app.

After the app has been published, you should only change the id if you intend to use the code base to develop a new app. You will not be able to upgrade from the app with the old id to the app with the new id because the system does not have knowledge about the correspondence.

If you have published your app as a per-tenant extension, but you are now considering publishing it to AppSource, you must assign a new id to the AppSource app, as well as ensure that it follows all the technical requirements for publishing to AppSource. For more information, see Moving Between Extension Scopes.

It is recommended to use a different id for the app that you publish from Visual Studio Code or to the container. Once you are satisfied with the quality of your app and ready to publish it to AppSource, it is recommended to use a different id. If you do not follow this approach, the app that you have published from Visual Studio Code to a developer sandbox will be automatically unpublished if another user tries to install the AppSource app. For more information, see Moving Between Extension Scopes.

When is it okay to change the name of an app?

If you are targeting only Business Central 2021 release wave 2 or later, the name of an app can be changed at any point also after it has been published. If the name is changed, the version must be incremented as well.

If you are targeting versions of Business Central prior to 2021 release wave 2, then the name of an app cannot be changed after it has been published.

When is it okay to change the publisher of an app?

If you are targeting only Business Central 2021 release wave 2 or later, the publisher of an app can be changed at any point also after it is published. If the publisher is changed, the version must be incremented as well.

If you are targeting versions of Business Central prior to 2021 release wave 2, then the publisher of an app cannot be changed after it has been published.

When is it okay to change the version of an app?

The version must be incremented any time a new version of your app is uploaded to AppSource or as a per-tenant extension. While developing it in Visual Studio Code, you can keep using the same version and iterate on your code.

Note

In a Visual Studio Code workspace an app's name, publisher, and version are part of identifying a project and a project dependency. Therefore, if any of these properties change, it is recommended that you reload the workspace.

See Also

JSON Files
Publish NAVApp
Working with Multiple Projects and Project References