ALOps Package Import¶

Import RapidStart configuration packages into Business Central.

Property	Value
Task name (Azure DevOps)	`ALOpsPackageImport@3`
Action name (GitHub)	`alops-packageimport`
Version	`3.0.0`
Category	Utility
OS requirement	Both
Preview	yes

Import Business Central RapidStart configuration packages (.rapidstart files) into a BC instance. Supports three connection modes: local (BC Management DLLs on the agent), docker (BC inside a container), and api (BC Automation REST API with OAuth, basic, windows, or username/password authentication). Auto mode detects the best connection method from the inputs provided. Generates XUnit test reports and verifies package import errors.

Inputs¶

connection¶

Name	Type	Required	Default	Platform	Description
`connection_mode`	PickList	yes	`auto`	Both	How to connect to Business Central. auto detects the mode from inputs: if fixed_tag is set, uses docker; if api_endpoint is set, uses api; otherwise uses local. Set explicitly to avoid ambiguity. Options: `auto`, `local`, `docker`, `api`.
`nav_serverinstance`	Text	no	`BC`	Both	BC server instance name for local and docker modes. Typically 'BC' for modern versions.
`fixed_tag`	Text	no	(empty)	Both	Docker container label value used to locate the target container. Only used in docker mode.

authentication¶

Name	Type	Required	Default	Platform	Description
`authentication`	PickList	yes	`oauth`	Both	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.
`password`	Secret	no	(empty)	Both	Password for the Business Central user account. Store this in a pipeline secret variable.

api¶

Name	Type	Required	Default	Platform	Description
`api_endpoint`	Text	no	(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. Required for API mode.
`apiversion`	Text	yes	`v1.0`	Both	Version of the Business Central Automation API to use. Supported values are beta, v1.0, and v2.0.
`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.

packages¶

Name	Type	Required	Default	Platform	Description
`package_path`	Text	no	(empty)	Both	Folder to scan for RapidStart package files. Defaults to the workspace directory when empty.
`package_filter`	Text	no	`*.rapidstart`	Both	Glob filter for discovering RapidStart package files in the package path.
`package_config`	Text	no	(empty)	Both	Path to a rapidstart.json configuration file that specifies packages to import. When set, overrides package path scanning.
`delete_before_import`	Boolean	no	`true`	Both	Delete the existing configuration package (by code) before creating and importing the new one.

polling¶

Name	Type	Required	Default	Platform	Description
`checksecondsdelay`	Text	no	`30`	Both	Number of seconds to wait between polls when checking async import/apply status in API mode.
`maxtries`	Text	no	`20`	Both	Maximum number of status polls before the task times out. Multiply by Check Delay to calculate total maximum wait time. Prevents infinite loops.

reporting¶

Name	Type	Required	Default	Platform	Description
`generate_test_report`	Boolean	no	`true`	Both	Generate an XUnit XML test report summarizing the import results for each package.
`test_report_path`	Text	no	(empty)	Both	Custom output path for the XUnit test report. Defaults to a temporary directory when empty.
`publish_test_report`	Boolean	no	`true`	Both	Upload the generated XUnit test report as a build artifact via Publish-ALOpsArtifact.

advanced¶

Name	Type	Required	Default	Platform	Description
`verify_after_import`	Boolean	no	`true`	Both	Query ConfigurationPackageErrors after import to detect and report individual field/record errors.
`fail_on_package_errors`	Boolean	no	`true`	Both	Fail the task when any package has import errors. When disabled, errors are reported as warnings.

Outputs¶

Name	Description
`ALOPS_PACKAGEIMPORT_RESULT`	JSON result summary of all packages processed.
`ALOPS_PACKAGEIMPORT_STATUS`	Final status: Succeeded, PartiallySucceeded, or Failed.
`ALOPS_PACKAGEIMPORT_REPORT_PATH`	Path to generated XUnit test report.

Usage¶

Azure DevOpsGitHub Actions

- task: ALOpsPackageImport@3
  displayName: 'ALOps Package Import'
  inputs:
    connection_mode: auto                    # How to connect to Business Central. auto detects the mode from inputs: if fixed_tag is set, uses docker; if api_endpoint is set, uses api; otherwise uses local. Set explicitly to avoid ambiguity. $(connection_mode)
    nav_serverinstance: BC                   # BC server instance name for local and docker modes. Typically 'BC' for modern versions. $(nav_serverinstance)
    fixed_tag:                               # Docker container label value used to locate the target container. Only used in docker mode. $(fixed_tag)
    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. $(username)
    password:                                # Password for the Business Central user account. Store this in a pipeline secret variable. $(password)
    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. Required for API mode. $(api_endpoint)
    apiversion: v1.0                         # Version of the Business Central Automation API to use. Supported values are beta, v1.0, and v2.0. $(apiversion)
    bccompany:                               # Name or GUID of the Business Central company context for the API call. Leave empty to use the default (first) company. $(bccompany)
    package_path:                            # Folder to scan for RapidStart package files. Defaults to the workspace directory when empty. $(package_path)
    package_filter: *.rapidstart             # Glob filter for discovering RapidStart package files in the package path. $(package_filter)
    package_config:                          # Path to a rapidstart.json configuration file that specifies packages to import. When set, overrides package path scanning. $(package_config)
    delete_before_import: True               # Delete the existing configuration package (by code) before creating and importing the new one. $(delete_before_import)
    checksecondsdelay: 30                    # Number of seconds to wait between polls when checking async import/apply status in API mode. $(checksecondsdelay)
    maxtries: 20                             # Maximum number of status polls before the task times out. Multiply by Check Delay to calculate total maximum wait time. Prevents infinite loops. $(maxtries)
    generate_test_report: True               # Generate an XUnit XML test report summarizing the import results for each package. $(generate_test_report)
    test_report_path:                        # Custom output path for the XUnit test report. Defaults to a temporary directory when empty. $(test_report_path)
    publish_test_report: True                # Upload the generated XUnit test report as a build artifact via Publish-ALOpsArtifact. $(publish_test_report)
    verify_after_import: True                # Query ConfigurationPackageErrors after import to detect and report individual field/record errors. $(verify_after_import)
    fail_on_package_errors: True             # Fail the task when any package has import errors. When disabled, errors are reported as warnings. $(fail_on_package_errors)

- name: ALOps Package Import
  uses: HodorNV/ALOps-V3/alops-packageimport@v3   <!-- TODO: confirm action repo path -->
  with:
    connection_mode: 'auto'
    nav_serverinstance: 'BC'
    fixed_tag: ''
    authentication: 'oauth'
    azure_tenant_id: ''
    azure_app_client_id: ''
    azure_app_client_secret: ''
    azure_app_client_certificate: ''
    azure_app_client_certificate_password: ''
    username: ''
    password: ''
    api_endpoint: ''
    apiversion: 'v1.0'
    bccompany: ''
    package_path: ''
    package_filter: '*.rapidstart'
    package_config: ''
    delete_before_import: 'true'
    checksecondsdelay: '30'
    maxtries: '20'
    generate_test_report: 'true'
    test_report_path: ''
    publish_test_report: 'true'
    verify_after_import: 'true'
    fail_on_package_errors: 'true'