Dynamics 365 Business Central: automatically update library apps when updating your main app

Yesterday I had a chat with a Partner that was stuck with a problem on some SaaS tenants. Problem can be resumed as follows:

Step 1: They have published on AppSource a MAIN app together with a library app LIBRARY1.

Step 2: They have installed the MAIN app on the customer tenant from AppSource and the LIBRARY1 app was automatically installed on the tenant.

Step 3: They have installed on some customer tenants an app APP1 that uses the LIBRARY1 library app published on AppSource.

Step 4: A new version of the MAIN app was published on AppSource , now with a second library app LIBRARY2 used to handle new functionalities (MAIN has dependencies from LIBRARY1 and LIBRARY2).

Step 5: They have created a new version of APP1 by adding the dependency also from LIBRARY2.

Step 6: The upgrade of APP1 in the customer tenant failed for missing dependencies (LIBRARY2 not found on the tenant).

Why this?

Unfortunately, at the moment newly added library apps are not automatically installed or upgraded when installing updates from the Admin Center interface.

Workarond that they have found?

They have uninstalled and installed the MAIN app (without removing data) from the Extension Management page and all the libraries was updated. But as you can imagine, this is quite noisy. Obviously, you can wait the tenant upgrade from Microsoft to a new version (the tenant upgrade refresh all apps and dependencies with the latest version available) but this was not possible (they cannot wait).

How to force the upgrade of library apps when an app that has dependencies is upgraded on a customer tenant then?

Solution to this task is to use the Admin Center APIs. I think that you already know that the Business Central Administration Center API enables administrators to programmatically do administrative tasks for a Business Central tenant and one of these tasks is to manage apps that are installed on the environment (installing, uninstalling, updating apps).

From Powershell, you can use the Admin Center APIs for example to retrieve the available updates for apps currently installed on the environment. This can be dobe by performing a GET operation to the following endpoint:

GET https://api.businesscentral.dynamics.com/admin/v2.6/applications/{applicationFamily}/environments/{environmentName}/apps/availableUpdates

and this call gives you a JSON response with the list of available updates of apps published on AppSource. In this list, you don’t have library apps listed.

With the Admin Center API, you can update an app by sending a POST request to the following endpoint:

Content-Type: application/json
POST 

https://api.businesscentral.dynamics.com/admin/v2.6/applications/{applicationFamily}/environments/{environmentName}/apps/{appId}/update

and in the body of the request you need to pass a JSON containing the target version for the upgrade. As an example, this is the Powershell script to upgrade an app to version 2.0.0.0

$appIdToUpdate = "YOUR_APP_ID"
$appTargetVersion = "2.0.0.0"
$response= Invoke-WebRequest `
    -Method Post `
    -Uri    "https://api.businesscentral.dynamics.com/admin/v2.6/applications/businesscentral/environments/$environmentName/apps/$appIdToUpdate/update" `
    -Body   (@{
                 "targetVersion" = $appTargetVersion
                 
              } | ConvertTo-Json) `
    -Headers @{Authorization=("Bearer $accessToken")} `
    -ContentType "application/json"

Please remember that the targetVersion parameter is always required, you cannot automatically update to the lates version available but you need to set here the version where you want to upgrade.

The update performed with the above script does not update dependencies and/or library apps. If you want to force the update of all the dependency chain, in the latest version of the Admin Center API (2.6 at the moment of writing this post) there’s a new parameter available for the /update API: installOrUpdateNeededDependencies.

The installOrUpdateNeededDependencies parameter is a boolean parameter that can be used to specify whether any other app dependencies should be installed or updated when upgradig the selected app. If it’s set to false, information about missing app dependencies will be returned as error details.

To force the upgrade of library apps with the Admin Center API, you can now use a Powershell script like the following:

$appIdToUpdate = "YOUR_APP_ID"
$appTargetVersion = "2.0.0.0"
$response= Invoke-WebRequest `
    -Method Post `
    -Uri    "https://api.businesscentral.dynamics.com/admin/v2.6/applications/businesscentral/environments/$environmentName/apps/$appIdToUpdate/update" `
    -Body   (@{
                 "targetVersion" = $appTargetVersion
                 "installOrUpdateNeededDependencies" = $true
                 "useEnvironmentUpdateWindow" = $false
              } | ConvertTo-Json) `
    -Headers @{Authorization=("Bearer $accessToken")} `
    -ContentType "application/json"

useEnvironmentUpdateWindow is another new boolean parameter that you can specify in the body. If set to true, the operation will be executed only in the environment update window (it will appear as “scheduled” before it runs in the window). If it’s set to false, the update is immediately executed.

I think that in the near future you will have an option to set the installOrUpdateNeededDependencies parameter also from the Admin Center UI (missing feature here, maybe Microsoft will add a flag or something similar in the portal UI), but for the moment please remember this tip if you need to solve tasks like what is described in this post.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.