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.

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

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.

"branding"

"images"

"databases"

"links"

"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.

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.

See Also

Embed App Overview Qualification and Onboarding Managing Embed Apps in Microsoft Lifecycle Services