Creating Deployment Packages for Embed Apps
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:
[FOLDER] branding/
- favicon.ico
- splash.png (or .gif)
- splash_narrow.png (or .gif)
- header.png (or .gif)
[FOLDER] databases/
- app.bacpac
- tenant.bacpac
manifest.json
The following sections explain how to build the deployment package.
Creating the database BACPACs using Docker
We strongly recommend you run Business Central on Docker using the BCContainerHelper PowerShell module to prepare the BACPAC files.
Important
You must only use the sandbox artifacts (Get-BcArtifactUrl -type sandbox) for your online deployments.
With the Docker container, you can:
- Attach your own database and publish necessary extensions into the application database
- Synchronize the schema of the tenant template database with the schema defined in the application
- Ensure that all objects are compiled
- Test your solution before creating the deployment package.
For more information about these and other things you can do, see BCContainerHelper PowerShell module.
About the databases
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. Fore more information about requesting and using prefixes and suffixes, see Benefits and Guidelines for using a Prefix or Suffix. 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: 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: 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.
|
| 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. |
Sample manifest
Sample of the manifest.json file.
{
"manifestSchemaVersion":"3.0",
"id": "201e5067-99cc-4974-900a-b50bd4fbe777",
"name": "Fabrikam Rentals",
"description": "Harness the power of the most feature-rich office furniture rentals solution from Fabrikam.",
"publisher": "Fabrikam",
"version": "16.1.50043.50321",
"branding": {
"productName": "Fabrikam Rentals",
"productNameShort": "Rentals",
"marketingName": "Fabrikam Rentals",
"images": {
"appleTouchIconPath": "branding/appletouch.ico",
"faviconPath": "branding/favicon.ico",
"headerPath": "branding/header.png",
"splashLandscapePath": "branding/web-wide.png",
"splashPortraitPath": "branding/web-narrow.png"
}
},
"databases": {
"applicationDacpacPath": "app.dacpac",
"tenantTemplateDacpacPath": "tenant.dacpac"
},
"links": {
"baseHelpUrl": "https://help.fabrikam.com/help/",
"baseHelpSearchUrl": "https://help.fabrikam.com/help/",
"communityUrl": "https://fabrikam.com/au/contact",
"feedbackUrl": "https://fabrikam.com/au/contact",
"legalUrl": "https://fabrikam.com/au/legal",
"privacyUrl": "https://fabrikam.com/au/privacy",
"signInHelpUrl": "https://fabrikam.com/au/contact",
"comingSoonUrl": "https://go.microsoft.com/fwlink/?linkid=2047422",
"blogUrl": "https://go.microsoft.com/fwlink/?linkid=2076643",
"contactSalesUrl": "https://go.microsoft.com/fwlink/?linkid=828707"
},
"apps": [
{
"id": "63ca2fa4-4f03-4f2b-a480-172fef340d3f",
"initialVersion": "16.1",
"name": "System Application",
"publisher": "Microsoft",
"allowedUpdates":"hotfix",
"publishOnly": false,
"blockUninstall": true
},
{
"id": "6d4391a2-9cae-41e9-a270-136af8acfbc7",
"initialVersion": "16.1.5",
"name": "Fabrikam Rentals Add-on",
"publisher": "Fabrikam",
"allowedUpdates":"minor",
"publishOnly": false,
"blockUninstall": true
},
{
"id": "201e5067-99cc-4974-900a-b50bd4fbe777",
"initialVersion": "16.1.50043.50321",
"name": "Fabrikam Rentals",
"publisher": "Fabrikam",
"allowedUpdates":"minor",
"publishOnly": false,
"blockUninstall": true
}
]
}
Creating the deployment package zip file
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:
[FOLDER] branding/
- favicon.ico
- splash.png (or .gif)
- splash_narrow.png (or .gif)
- header.png (or .gif)
[FOLDER] databases/
- app.bacpac
- tenant.bacpac
manifest.json
Now, you can deploy your package to Business Central Online service. See Managing Embed Apps in Microsoft Lifecycle Services for more information.
Related information
Embed App Overview Qualification and Onboarding Managing Embed Apps in Microsoft Lifecycle Services