To deploy an Embed App, you'll need a deployment package and your apps. This article describes how to create a deployment package for an Embed App.
The apps are the individual extensions that make up your application. Apps are delivered as .app files, which you upload to the App Repository via the App Management API. For information about this task, see App Management API.
Once you've created the deployment package and uploaded your apps, you then upload the deployment package to a registered project in Microsoft Lifecycle Services.
Deployment package overview
Creating a deployment package prepares the Embed app code and data for deployment on Business Central Online service. The deployment package is a .zip file that contains components required for any Embed app.
At a high level, a deployment package consists of the following components:
ISV branding elements, like images, icons, names, and so on
An application database and tenant template databases as BACPAC files
A manifest-json file that provides additional metadata and deployment instructions
The deployment package has the following structure:
Business Central Online service runs exclusively in multi-tenant mode. Each customer environment is a separate database, but sharing the same application. So the deployment package has to include two databases, which are compiled into BACPAC format:
App.bacpac - includes the application database. The application database contains your application data, like permissions, entitlements, report layouts, and so on.
Tenant.bacpac - includes the tenant template database, which may also contain initial tenant data.
Requirements for the application database
Requirement
Condition
Description
Running on a supported Business Central platform
Always
The Business Central platform version is updated with every major update. You're responsible for updating the Embed App to operate with the updated version of Business Central. The Embed App must run on a supported build (platform) of Business Central, namely, the current platform version of Business Central or the preceding platform version. Earlier versions of Business Central platform are out of support and can't be used for Embed app deployments.
Unique Base Application ID, Name, and Publisher
If any change is applied to the Microsoft Base Application objects
Create and assign your own unique App ID for it in the app.json file. Also, change the Publisher property and the Application name to your own in the app.json file. You can't use the original values of the Microsoft Base Application unless you've extracted all your customizations from that app into your own app(s).
Use System Application
Always
Your Embed app must be built on top of the Microsoft System Application. The System Application must not be customized and must be used as a dependency for your customized or non-customized Base Application.
Use Microsoft_Application.app file
If you use customized Base Application
Use Microsoft_Application.app to encapsulate references to your own customized Base Application, instead of referencing that app as a direct dependency in each extension separately. This will also allow other apps (like AppSource apps) to refer to your solution via the Microsoft_Application.app. For more information about the Microsoft_Application.app, see The Microsoft_Application.app File.
Solution prefix or suffix
Always
Register a prefix or suffix to be used by your solution. Apply the prefix or suffix to all objects, while you're still preparing your apps on-premise. The prefix or suffix must be used for all your app objects and also for your tables, controls, fields, actions, and groups that remain inside of Microsoft's Base Application. There's no need to apply this prefix or suffix to Microsoft objects and fields in the customized Base Application.
Once your apps are deployed to Business Central service, it won't be possible to rename fields and objects, because it would be a breaking change. Breaking changes aren't permitted in the online version of Business Central. While still preparing your apps on-prem, you can use the Sync-NAVApp cmdlet with -Force parameter to add prefix or suffix to your objects and fields.
Entitlements
Always
It's important that the application database also contains Microsoft unmodified records in the following tables:
Membership Entitlement
Entitlement Set
Entitlement
No users can sign in to your service if these tables are empty. You can't add new records or modify existing records in these tables. For more information about these tables, see Business Central entitlements explained.
The entitlements can be copied from the standard Business Central Demo Database available in sandbox Docker containers. Make sure you update the entitlements when you uptake a new version of Business Central application. Consult the entitlements documentation and parameters provided for the Clean-BCContainerDatabase and New-BCContainer commands included with the BcContainerHelper PowerShell module.
Permissions
Always
The application database must contain Microsoft unmodified records in the following tables:
Permission Set
Permission
You can't modify the existing records in these tables. If you need to add your own permission sets and permissions for the objects used by your own solution, include these with your extension instead. For more information, see Exporting Permission Sets.
Don't include customer-specific permission sets and permissions in your database, these permissions must be added within the customer environment instead. For more information, see how to create or modify a permission set in the Business Central Application help.
Custom .NET add-ins
If your solution uses custom .NET Server components (.NET add-ins)
Import components into the Add-in table in the application database. You register the control add-ins, import and manage the files by using the New-NAVAddin cmdlet, Set-NAVAddin cmdlet, Get-NAVAddin, or Remove-NAVAddin cmdlets from the Business Central Administration Shell.
IMPORTANT Using custom .NET Server components option is being deprecated. So refactor your code to remove custom .NET components as soon as you can. For example, use Azure Functions instead.
Requirements to the tenant template database
While you are testing your Embed app solution in a Docker container, you can publish and install all the apps you need for your customers. When you're done testing, we recommend you to uninstall (including removing the data) and unpublish all apps, including Microsoft apps, before you export the application and tenant template databases.
Instead of keeping the apps pre-published and pre-installed in your databases, they must be uploaded to the service by using the App Management API and listed in the [apps] section of the manifest.json file. This way the apps will be automatically published and installed later, during deployment, following the list you provide in the manifest.json file that you include with your deployment package.
We recommend you to use RapidStart packages to populate the new companies with the demo data or initial setup data.
Exporting application and tenant databases
You export the databases to .bacpac and .dacpac format by using the Export-BCContainerDatabasesAsBacpac command adding the -includeDacPac flag from the BcContainerHelper PowerShell module.
We strongly recommend using this command for creating the .bacpac and .dacpac files you're planning to deploy to the Business Central service. To simplify exporting the data, the command also does a number of clean-up steps on the databases. It cleans up sessions, database connection, list of tenants, imported license, and more. It also verifies that the schemas of the application and tenant databases are synchronized, which is essential for deployment. We keep enhancing this command with more cleanup and validation steps as we discover .dacpac-related issues with deployments. So, remember to update the BcContainerHelper PowerShell module for every new iteration.
Providing deployment instructions in the manifest.json
The manifest.json file, supplied within the deployment package, contains important properties used by the deployment routine to configure the application version according to the Embed app ISV requirements.
Setting
Type
Description
manifestSchemaVersion
String, <major>.<minor>
Schema version of the manifest. Current manifest schema version is 4.0.
id
GUID
Unique ID of the Embed solution. Used for informational purposes, not used in the runtime. As a best practice it's recommended to use the Id of your main app in this field.
name
String
Short marketing name of the app. Used for informational purposes, not used in the runtime.
description
String
Short marketing description of the app. Used for informational purposes, not used in the runtime.
publisher
String
Name of the ISV organization that owns the Embed app. Used for informational purposes, not used in the runtime.
version
String. <major>.<minor>.<build>.<revision>
Version of the deployment package being uploaded. This version is displayed in the Application Version list in LCS, it has no other purpose or application in the runtime. Remember to update this version for every new deployment, so you can distinguish the deployments in the LCS UI.
branding
Object
Object that contains paths to the branding elements of the ISV included with the deployment package. See the "branding" section below.
databases
Object
Object that contains paths to the application and tenant template BACPAC files of the ISV solution included with the deployment package. See the "databases" section below.
links
Object
Object that contains paths to various URLs to be used in the Business Central Web Client. See the "links" section below.
apps
Array
Array that contains the list of apps and their dependencies, which are uploaded by the ISV via the App Management API. See the "apps" section below.
"branding"
Setting
Type
Description
productName
String
Official marketing name of your Embed app. This name will be displayed in the title bar of the Business Central Web Client.
productNameShort
String
Short version of Embed app marketing name. It's displayed in the areas of the UI where full Product Name can't be displayed.
marketingName
String
Longer (full) marketing name of your Embed app.
images
Object
Object that contains paths to the branding images included with the package. See the "images" section below.
"images"
Important
The combined size of all images you include with the deployment package must not exceed 490 KB.
Setting
Type
Description
appleTouchIconPath
String
Format: PNG. Dimensions: 114x114
faviconPath
String
Format: ICO. Dimensions 16x16, 32x32, 48x48 & 64x64. Used on the Browser tab and bookmark icon.
headerPath
String
Formats: PNG, GIF. Dimensions: 558x107. Displayed on "Minimal Layout" pages, like the Microsoft Office add-in sign-in; Authentication / Permission errors ("You don't have access to Business Central", "You've successfully signed out.")
splashLandscapePath
String
Formats: PNG, GIF. Dimensions: 2048x272. Splash screen on devices with large screen space, for example, full screen browser, tablet in landscape mode.
splashPortraitPath
String
Formats: PNG, GIF. Dimensions: 960x320. Splash screen on devices with limited screen space, for example, small browser, phones, tablets in portrait orientation.
"databases"
Setting
Type
Description
applicationDacpacPath
String
Path to the application database (.dacpac) included with the deployment package.
tenantTemplateDacpacPath
String
Path to the tenant template database (.dacpac) included with the deployment package.
"links"
Setting
Type
Description
baseHelpUrl
String
Link to your online Help server or web page.
baseHelpSearchUrl
String
Link to your online Help server or web page.
communityUrl
String
Link to your community blog page.
feedbackUrl
String
Link to your product feedback page.
legalUrl
String
Link to your product legal and privacy terms.
signInHelpUrl
String
Link to your sign-in help URL.
comingSoonUrl
String
Link to your product announcements page.
blogUrl
String
Link to your product blog page.
contactSalesUrl
String
Link to your sales page.
"apps"
This section of the manifest.json file must list all the apps used by your solution and their dependencies. Even if the dependency app belongs to a different publisher, for example Microsoft, you must include it. This list will be used by the deployment routine to publish and install these apps to your service and for your environments.
Setting
Type
Description
id
String
Unique ID of the app. Use the same Id as listed in the app.json file.
name
String
Name of the app. Use the same Name as listed in the app.json file.
publisher
String
Name of the ISV organization that owns the app. Use the same Publisher as listed in the app.json file.
initialVersion
String
Minimum required and compatible version of the app.
If "allowedUpdates" is set to "none", then the exact version of the app you specify must be available in the App Repository. In this case, a full initial version number must be specified.
For other "allowedUpdates" values, it's enough that an app with a higher or equal [build].[revision] part of the version is available in the App Repository. You don't need to specify a full version number -- [major].[minor] and [major].[minor].[revision] are also accepted. This applies to the App versions uploaded either by you or by other publishers who own the apps.
allowedUpdates
Enum
Allowed values: none, hotfix, minor, all.
You can set up rules that determine which app version to use for the new signups. You can also specify whether updating of the installed app is allowed.
"none": It won't be possible to apply any new versions to this app inline (only side by side). Only the application version that exactly matches the specified initial version number will be used for the new signups.
"hotfix": You allow hot fixing this app with newer hotfix versions, that is, versions with a higher build and revision numbers than in the "initialVersion", but with the same major and minor version. New signups and environments you upgrade to this deployment will automatically get the latest available hotfix version of the app installed.
"minor": Customers can view and install newer applicable minor (or hotfix) versions of the app via the Business Central Administration Center. New signups and environments that you upgrade to this deployment will automatically get the latest available hotfix version of the app installed. Minor updates won't be automatically installed. They must be installed by the newly signed-up customers using the Business Central Administration Center.
"all": Customers can view and install all newer applicable versions of the app via the Business Central Administration Center. New signups and environments that you upgrade to this deployment will automatically get the latest available hotfix version of the app installed.
blockUninstall
Boolean
Allow or disallow the app to be uninstalled using the Extension Management page.
publishOnly
Boolean
Specifies whether to only publish (true) that app to the service. Customers can then install it manually through the Admin Center API. If false, the app is automatically installed for all new environments and environments updated to this deployment.
IMPORTANT Dependencies of an app with "publishOnly": "false" must also be marked with "publishOnly": "false", otherwise the app that depends on them will fail to be installed.
After you have all the components of the deployment package ready, you can package them into a .zip archive. The deployment package (.zip) can't include any additional subfolders and files and must have the following structure: