Get/Publish extensions with the Business Central API.
Property
Value
Task name (Azure DevOps)
ALOpsExtensionAPI@3
Action name (GitHub)
alops-extensionapi
Version
3.0.0
Category
Utility
OS requirement
Both
Preview
yes
Get, publish, or batch-publish Business Central extensions via the BC Automation REST API. Supports SaaS environments (OAuth2 client credentials, client certificate, or user impersonation) and on-premises (basic or Windows authentication). Use 'get' to list installed extensions, 'publish' for a single .app file, or 'batch' for multiple .app files in dependency order.
Authentication method for the API connection. oauth uses Azure AD service-to-service tokens (recommended for SaaS). basic and usernamepassword use user credentials. windows uses Windows integrated authentication (on-premises only, Windows agents only). Options: oauth, basic, windows, usernamepassword.
azure_tenant_id
Text
no
(empty)
Both
Azure Active Directory tenant ID (GUID or domain) of the Business Central SaaS tenant.
azure_app_client_id
Text
no
(empty)
Both
Application (client) ID of the Azure AD app registration used for OAuth authentication.
azure_app_client_secret
Secret
no
(empty)
Both
Client secret of the Azure AD app registration. Store this value in a pipeline secret variable or Azure Key Vault, never in plain text.
azure_app_client_certificate
Text
no
(empty)
Both
Path, base-64 encoded content, or certificate store reference (CERT:...) of the certificate (.pfx) used instead of a client secret for Azure AD app authentication.
azure_app_client_certificate_password
Secret
no
(empty)
Both
Password protecting the client certificate. Store this in a pipeline secret variable.
username
Text
no
(empty)
Both
Business Central user account name. Used for basic or usernamepassword authentication, or for on-behalf-of OAuth flow. Leave empty for Service-to-Service (app-only) OAuth authentication.
password
Secret
no
(empty)
Both
Password for the Business Central user account. Store this in a pipeline secret variable.
API operation to perform. get lists extensions currently installed on the environment. publish deploys a single .app file. batch deploys multiple .app files in dependency order. Options: get, publish, batch.
api_endpoint
Text
yes
(empty)
Both
Base URL of the Business Central API, for example https://api.businesscentral.dynamics.com/v2.0/{tenant}/Sandbox/api for SaaS or http://server:port/BC/api for on-premises.
dev_endpoint
Text
no
(empty)
Both
URL of the Business Central development endpoint used when deploying via the DEV port, for example http://server:7049/BC/dev. When set, extensions are published to this endpoint instead of the automation API.
apiversion
Text
yes
v1.0
Both
Version of the Business Central Automation API to use. Supported values are beta, v1.0, and v2.0. Use v2.0 for access to schedule and schema sync mode features.
bccompany
Text
no
(empty)
Both
Name or GUID of the Business Central company context for the API call. Leave empty to use the default (first) company.
Schema update mode when publishing via the DEV endpoint. synchronize adds new schema objects. recreate drops and recreates tables. forcesync allows breaking changes. Options: synchronize, recreate, forcesync.
dev_dependencypublishingoption
PickList
no
none
Both
Dependency handling when publishing via the DEV endpoint. none skips dependencies. default resolves them automatically. ignore skips dependency checks. strict fails if any dependency is missing. Options: none, default, ignore, strict.
replacepackageid
Boolean
no
false
Both
Generate a new package GUID for each deployment. This forces Business Central to treat each deploy as a fresh installation rather than an upgrade.
blocksymbolsonly
Boolean
no
false
Both
When enabled, the task checks whether the .app is a symbols-only package and blocks deployment if it is, preventing accidental publishing of placeholder apps.
schedule
PickList
no
current
Both
Deployment schedule for the extension. current deploys immediately. nextminor schedules for the next minor BC update. nextmajor schedules for the next major update. Requires API version 2.0. Options: current, nextminor, nextmajor.
schema_sync_mode
PickList
no
add
Both
Schema synchronization mode for the extension deployment. add only adds new schema objects. forcesync allows breaking schema changes. Requires API version 2.0. Options: add, forcesync.
install_published_apps
Boolean
no
false
Both
When the same app version is already published but not installed, install that published package instead of uploading it again. Also installs an app that the deployment left published but uninstalled. API mode only.
When enabled, the task polls and displays the extension deployment status after publishing until the operation completes or times out.
checksecondsdelay
Text
no
30
Both
Number of seconds to wait between polls when checking deployment status. Increase this for environments with slower deployment operations.
maxtries
Text
no
20
Both
Maximum number of deployment status polls before the task times out. Multiply by Check Delay to calculate the total maximum wait time.
verify_installed
Boolean
no
true
Both
After a 'Completed' deployment, check that the app version is really installed and fail the task when it is not. An app that was already published-only before the run only gets a warning. Requires showdeploymentstatus. API mode only.
Folder containing the .app files to deploy, scanned recursively and narrowed by artifact_filter. In publish mode the first matching .app file is deployed. In batch mode every matching .app file is deployed in dependency order. Empty uses the workspace folder.
artifact_filter
Text
no
*.app
Both
File-name glob that selects the .app files under artifact_path, for example *.app or Hodor_*.app. Applies to both publish and batch mode; in batch mode the dependency order of the selected apps is kept.
Version of the ALTool NuGet package to install for app metadata extraction. Required for publish and batch interactions. Leave empty to skip installation (get interaction only).
-task:ALOpsExtensionAPI@3displayName:'ALOpsExtensionAPI'inputs:authentication:oauth# Authentication method for the API connection. oauth uses Azure AD service-to-service tokens (recommended for SaaS). basic and usernamepassword use user credentials. windows uses Windows integrated authentication (on-premises only, Windows agents only). $(authentication)azure_tenant_id:# Azure Active Directory tenant ID (GUID or domain) of the Business Central SaaS tenant. $(azure_tenant_id)azure_app_client_id:# Application (client) ID of the Azure AD app registration used for OAuth authentication. $(azure_app_client_id)azure_app_client_secret:# Client secret of the Azure AD app registration. Store this value in a pipeline secret variable or Azure Key Vault, never in plain text. $(azure_app_client_secret)azure_app_client_certificate:# Path, base-64 encoded content, or certificate store reference (CERT:\...) of the certificate (.pfx) used instead of a client secret for Azure AD app authentication. $(azure_app_client_certificate)azure_app_client_certificate_password:# Password protecting the client certificate. Store this in a pipeline secret variable. $(azure_app_client_certificate_password)username:# Business Central user account name. Used for basic or usernamepassword authentication, or for on-behalf-of OAuth flow. Leave empty for Service-to-Service (app-only) OAuth authentication. $(username)password:# Password for the Business Central user account. Store this in a pipeline secret variable. $(password)interaction:get# API operation to perform. get lists extensions currently installed on the environment. publish deploys a single .app file. batch deploys multiple .app files in dependency order. $(interaction)api_endpoint:# Base URL of the Business Central API, for example https://api.businesscentral.dynamics.com/v2.0/{tenant}/Sandbox/api for SaaS or http://server:port/BC/api for on-premises. $(api_endpoint)dev_endpoint:# URL of the Business Central development endpoint used when deploying via the DEV port, for example http://server:7049/BC/dev. When set, extensions are published to this endpoint instead of the automation API. $(dev_endpoint)apiversion:v1.0# Version of the Business Central Automation API to use. Supported values are beta, v1.0, and v2.0. Use v2.0 for access to schedule and schema sync mode features. $(apiversion)bccompany:# Name or GUID of the Business Central company context for the API call. Leave empty to use the default (first) company. $(bccompany)dev_schemeupdatemode:synchronize# Schema update mode when publishing via the DEV endpoint. synchronize adds new schema objects. recreate drops and recreates tables. forcesync allows breaking changes. $(dev_schemeupdatemode)dev_dependencypublishingoption:none# Dependency handling when publishing via the DEV endpoint. none skips dependencies. default resolves them automatically. ignore skips dependency checks. strict fails if any dependency is missing. $(dev_dependencypublishingoption)replacepackageid:False# Generate a new package GUID for each deployment. This forces Business Central to treat each deploy as a fresh installation rather than an upgrade. $(replacepackageid)blocksymbolsonly:False# When enabled, the task checks whether the .app is a symbols-only package and blocks deployment if it is, preventing accidental publishing of placeholder apps. $(blocksymbolsonly)schedule:current# Deployment schedule for the extension. current deploys immediately. nextminor schedules for the next minor BC update. nextmajor schedules for the next major update. Requires API version 2.0. $(schedule)schema_sync_mode:add# Schema synchronization mode for the extension deployment. add only adds new schema objects. forcesync allows breaking schema changes. Requires API version 2.0. $(schema_sync_mode)install_published_apps:False# When the same app version is already published but not installed, install that published package instead of uploading it again. Also installs an app that the deployment left published but uninstalled. API mode only. $(install_published_apps)showdeploymentstatus:True# When enabled, the task polls and displays the extension deployment status after publishing until the operation completes or times out. $(showdeploymentstatus)checksecondsdelay:30# Number of seconds to wait between polls when checking deployment status. Increase this for environments with slower deployment operations. $(checksecondsdelay)maxtries:20# Maximum number of deployment status polls before the task times out. Multiply by Check Delay to calculate the total maximum wait time. $(maxtries)verify_installed:True# After a 'Completed' deployment, check that the app version is really installed and fail the task when it is not. An app that was already published-only before the run only gets a warning. Requires `showdeploymentstatus`. API mode only. $(verify_installed)artifact_path:# Folder containing the .app files to deploy, scanned recursively and narrowed by `artifact_filter`. In `publish` mode the first matching .app file is deployed. In `batch` mode every matching .app file is deployed in dependency order. Empty uses the workspace folder. $(artifact_path)artifact_filter:*.app# File-name glob that selects the .app files under `artifact_path`, for example `*.app` or `Hodor_*.app`. Applies to both `publish` and `batch` mode; in `batch` mode the dependency order of the selected apps is kept. $(artifact_filter)altool_package_version:18.0.33.65164-beta# Version of the ALTool NuGet package to install for app metadata extraction. Required for publish and batch interactions. Leave empty to skip installation (get interaction only). $(altool_package_version)