Setup Artifacts to Import on Startup

Artifacts are configured in the AL-Go settings. The defined artifacts are automatically installed in the containers during the container startup.

Two types of artifacts are supported:

  1. Artifacts from a NuGet feed
  2. Artifacts from a URL

Parameters

Optional parameters available for all artifacts:

Element Type Value
target string Specify the Artifact Target in the container and import action.
targetFolder string This folder is used for "target": "dll" as optional subfolder: <serviceTierFolder>/Add-Ins/<targetFolder>
appImportScope string Specify the import scope for apps. The value can be Global (default) or Tenant.
appImportSyncMode string Specify the import sync mode for apps. The value can be Add (default), Clean, Development or ForceSync.
ignoreIn string[] Specify in which container setup this artifact should be ignored. The value is an array of: dev and/or build.

Artifact Types

NuGet feed

Define NuGet packages of BC Apps as artifacts.

The dependencies of a NuGet package are included automatically but can be overwritten by also defining them as artifacts.

By default all Microsoft NuGet feeds are available for AL-Go, but only the feed for the Microsoft Apps is used for containers. Trusted NuGet feeds can either be configured in the AL-Go settings or per-user by specifying custom nuget feeds in the Alpaca settings in VS Code.

  1. Find out the name and version of the NuGet package you want to use (e.g. from the Packages View).
  2. Add the artifact to alpaca.artifacts in your AL-Go settings:
{
    "alpaca": {
        "artifacts": [
            {
                "name": "CosmoConsult.COSMORental.b945e3cd-da15-4575-990e-37ff46875f27",
                "version": "5.2.270944.0"
            }
        ]
    }
}

Parameters

Element Type Value
type string optional Type of the artifact. Default when not specified is nuget.
name string mandatory The name of the artifact.
version string optional The version of the artifact. (latest - when not specified)

You can use the VS Code extension to help you create the required entries for a NuGet package.

  1. Open the workspace of the repository in Visual Studio Code
  2. Open COSMO Alpaca extension
  3. Expand/Update the "Packages" view
  4. Expand the entry of the required package (e.g. "COSMO Advanced Manufacturing Pack")
  5. Expand the version and its dependencies to find a valid version for your case (e.g. version installed in the customer environment)
  6. Right click on the wanted version, choose Copy and select Alpaca artifact JSON
  7. Add the copied JSON to alpaca.artifacts in your AL-Go settings
  8. Repeat from 4. for each required product
  9. (Optional) Remove version of added artifacts in the cosmo.json to always use the latest versions
  10. Commit/push the changed AL-Go configuration

URL

Define URLs of APP or ZIP files as artifacts.

ZIP files are automatically extracted after they are downloaded.

  1. Find out which url you want to use.
  2. Add the Artifact to alpaca.artifacts in your AL-Go settings:
{
    "alpaca": {
        "artifacts": [
            {
                "type": "url",
                "name": "myapp",
                "url": "https://my.blob.core.windows.net/test/myapp/myapp_1.2.3.4.app?sv=2019-02-02&..."
            }
        ]
    }
}

Parameters

Element Type Value
type string mandatory The type of the artifact. Must be url for fileshare/URL artifacts.
name string mandatory The name of the artifact. Informational only.
version string optional The version of the artifact. Informational only.
url string mandatory The url to download the artifact.

Use Alpaca fileshare

Upload files into the Alpaca fileshare, share them and define their download urls as url artifacts.

  1. Open the Alpaca fileshare. Please contact the Alpaca support if you don't have access yet.
  2. Copy your artifact to the fileshare. One option to organize your folder structure could look like this, but if you have some other structure already in place in your organization, it also might be a good idea to use that:
    • product-artifacts used by multiple projects: /common/<product>
    • artifacts related to a customer project: /<customer-name>/<project-name>
  3. Create a share link for a file or folder (without duration and without password)
  4. Get the download url from the share link
    1. Open the share link (https://.westeurope.cloudapp.azure.com/filebrowser/share/)
    2. Copy the download link (https://.westeurope.cloudapp.azure.com/filebrowser/api/public/dl/)
  5. Add the Artifact to alpaca.artifacts in your AL-Go settings:
{
    "alpaca": {
        "artifacts": [
            {
                "type": "url",
                "name": "myapp",
                "url": "https://<cluster>.westeurope.cloudapp.azure.com/filebrowser/api/public/dl/<id>"
            }
        ]
    }
}

Artifact Target

The target specifies what should happen with the artifact.

Target(s) Import
app The Artifact content will be imported as an App. This is the default target, so you can omit the target for apps.
rapidStart The Artifact content will be imported as a RapidStart package.
bak The first (not ignored) bak Artifact is used as database backup file during container creation.
saasbak Backup file from an online SaaS environment, converted from bacpac to bak, cannot be combined with bak.
dll or add-ins The Artifact will be imported as a DLL or Add-In.
font or fonts The Artifact will be imported as a Font.

The order of import is:

  1. DLL(s) and Add-Ins
  2. Font(s)
  3. App(s)
  4. RapidStart package(s)

Examples

Add Fonts as Artifacts

Adding an additional font to a container requires you to add also the default fonts as an additional artifact. This is because there are not fonts installed in the container and your Business Central Reports might use your additional font as default font for your reports.

Here is an example how to add additional fonts as artifacts. Please note the ignoreIn setting as you probably won't need the fonts in a build pipeline and as they require a restart of the service tier, they make the pipeline slower and can cause issues with symbol loading in hybrid dev setups.

{
    "alpaca": {
        "artifacts": [
            {
                "type": "url",
                "name": "Default-Fonts",
                "url": "https://my.blob.core.windows.net/test/fonts/default.zip?sv=2019-02-02&...",
                "target": "fonts",
                "ignoreIn": ["build"]
            },
            {
                "type": "url",
                "name": "Additional Fonts for Barcode Printing",
                "url": "https://my.blob.core.windows.net/test/fonts/barcode.zip?sv=2019-02-02&...",
                "target": "fonts",
                "ignoreIn": ["build"]
            }
        ]
    }
}