Advanced Portal Designer Documentation
Index

Installation

This guide walks you through installing Advanced Portal Designer in your Business Central environment.

Installing from AppSource

The recommended way to install APD is through Microsoft AppSource.

Step-by-Step Installation

  1. Open your Business Central environment
  2. Navigate to Extension Management (search for "Extension Management" in the Tell Me search)
  3. Click Manage → Get More Apps
  4. Search for "Advanced Portal Designer"
  5. Click Free trial or Get it now (depending on your license status)
  6. Follow the prompts to install the extension

Installation Progress

The installation process typically takes 5-10 minutes. You can monitor progress in:

  1. Extension Management page - shows installation status
  2. Extension Installation Status page - for detailed progress

Post-Installation

After installation completes:

  1. Sign out and sign back in to Business Central
  2. In the Tell Me search, search for "Advanced Portal Designer" (this is the only APD page registered for search — it is the entry point from which you reach Setup, Actions, Users, Security, etc.)
  3. The Advanced Portal Designer menu page should open without errors
  4. From there, click Setup to verify the setup page loads

Dependencies

APD automatically installs its dependency:

Extension Description
AL Compiler and Interpreter Required for script execution

You don't need to manually install dependencies - they're handled automatically.

Azure WebApp Setup

APD requires an Azure WebApp to serve content to browsers. This acts as a middleware between end users and Business Central.

Creating the Azure WebApp

  1. Log in to Azure Portal
  2. Click Create a resource
  3. Search for "Web App" and select it
  4. Click Create

Configure the Web App

Setting Recommended Value
Subscription Your Azure subscription
Resource Group Create new or use existing
Name Your portal name (e.g., mycompany-portal)
Publish Code
Runtime stack .NET 10 (LTS)
Operating System Windows
Region Choose closest to your users
App Service Plan B1 for development, S1+ for production

Deploying the APD WebApp

You deploy the APD WebApp to your Azure App Service using your preferred deployment method (FTP/FTPS, GitHub Actions, Azure DevOps, Local Git, or az webapp deploy). The WebApp itself is a .NET application — you do not need to hand-edit any JavaScript or HTML before deploying.

Configuring the WebApp

Configuration is done through environment variables (App Service → Settings → Environment variables), not by editing files in the deployed package. See the Documentation/AzureWebApp/Azure WebApp.md reference for the full list. The most important variables are:

Variable Purpose
serverUrl URL of the Business Central API endpoint that handles portal requests
authentication s2s (Entra ID service-to-service) or basic
tenantId, clientId, clientSecret Required when authentication=s2s
basicUser, basicPassword Required when authentication=basic
serviceRoot Optional path prefix for portal routes (e.g. /portal)

About the APD JavaScript library

APD's JavaScript helper library (formerly distributed as a static apdscript.js file) is now served by Business Central itself as a built-in action. Reference it from your templates with <script src="<?action('apdscript')?>"></script>. APD generates the script per request, populating RootLocation and other settings from your APD Setup automatically — there is no file to deploy or edit.

Verifying Installation

Check Extension Status

  1. Go to Extension Management
  2. Verify "Advanced Portal Designer" shows status "Installed"
  3. Verify "AL Compiler and Interpreter" is also installed

Test the Setup Page

  1. In Tell Me, search for "Advanced Portal Designer" and open the menu page
  2. Click Setup — the Advanced Portal Designer Setup page should open
  3. You should see configuration options for:
    • Server settings
    • Language settings
    • Security settings

Create a Test Action

  1. From the Advanced Portal Designer menu page, click Actions
  2. Create a new action with type "File"
  3. Assign a simple HTML template
  4. Try accessing it through your Azure WebApp

Troubleshooting Installation

Extension Won't Install

If the extension fails to install:

  1. Check Extension Installation Status for error details
  2. Verify you have sufficient permissions
  3. Ensure no conflicting extensions are installed
  4. Contact support with the error message

Missing Dependency

If you see errors about missing "AL Compiler and Interpreter":

  1. The dependency should install automatically
  2. If not, manually install it from AppSource first
  3. Then install APD

Azure WebApp Connection Issues

If your portal can't connect to Business Central:

  1. Verify the serverUrl environment variable on the App Service points at the correct Business Central endpoint
  2. Verify the authentication environment variables (authentication, plus tenantId/clientId/clientSecret for s2s, or basicUser/basicPassword for basic) are correct
  3. Ensure Business Central web services are published and accessible
  4. Test the web service URL directly (e.g. via curl/Postman) using the same credentials

Updating APD

When updates are available:

  1. Go to Extension Management
  2. Find "Advanced Portal Designer"
  3. Check if an update is available
  4. Click Update to install the latest version

Update Considerations

  • Review release notes before updating
  • Test in a sandbox environment first
  • Back up your templates before major updates
  • Some updates may require template recompilation

Uninstalling APD

If you need to uninstall APD:

  1. Go to Extension Management
  2. Find "Advanced Portal Designer"
  3. Click Uninstall

Warning

Uninstalling APD will:

  • Remove all APD configuration data
  • Delete all templates stored in Business Central
  • Remove all portal user records
  • Delete session data

Back up any important data before uninstalling.