Install and upgrade

This page explains what you need before you install Bitta Commission, what installation creates, and how an upgrade from Core 1.0 to Release 1.1 works.

Before you start

Business Central version. Release 1.1 requires Business Central 28 or later (application and platform 28.0, AL runtime 17).
Deployment. The app is built for Business Central online. If you run Business Central on-premises, contact Bitta Apps before you plan an installation.
Dependencies. The app has no dependencies on other extensions.
Package. Bitta Apps provides the extension package and installation instructions for your environment. The AppSource listing is pending, so the app is not available from AppSource yet.
People. A Business Central administrator installs the extension. A user with the Bitta Commission Setup Administrator permission set (BAA Comm Setup Admin) configures it afterwards.
A test environment. Install in a sandbox first and follow Try it with demo data before production.

Install the extension

Install the package with your administrator's standard Business Central extension process.
Assign the Bitta Commission Setup Administrator permission set to the person who will configure the app. See Roles and permissions.
Open Bitta Commission Setup and activate your trial or subscription. See Activate a license.
Run Set Up Bitta Commission. See Guided setup wizard.

What installation creates

Installation prepares each company with technical defaults only. It creates no plans, participants, calendars, earnings or postings.

For each company, installation:

Creates the Bitta Commission Setup record with safe defaults: calculation precision 0.01, rounding to the nearest value, closed-period corrections set to Block, a default evidence retention period of seven years, background calculation off and native capture off.
Records the installed app version and data schema version for later upgrade checks.
Creates the module switches shown in Commission Feature Management. The core engine is on. Every optional module starts off, unless the company already holds data of that module (for example after a reinstall).
Registers the upgrade tags, so a later upgrade knows which steps already ran.

Companies you create after installation are prepared the same way.

Business defaults, such as the commission number series, a monthly calendar with this year's periods, an immediate eligibility policy and an expense-when-earned accounting policy, are created later, when you run the wizard or choose Prepare Company Defaults on the setup checklist.

Upgrade from Core 1.0

Release 1.1 upgrades Core 1.0 data in place. The upgrade runs once per company and keeps existing plans, ledgers, settlements, statements and postings.

What the upgrade does

Checks the data version first. If the company's stored data schema version is newer than the app supports, the upgrade stops with BAA-UPG-PRECONDITION-001. Downgrades are rejected.
Runs the per-company upgrade steps that are not yet recorded as upgrade tags. Each step runs once.
Switches on modules you already use. Release 1.1 introduces switchable modules. For each module, the upgrade checks whether the company already holds data that only that module creates, for example quota targets, cash-based eligibility policies, disputes or scenarios. Every module in use is switched on, so users keep every capability they rely on. Nothing is switched off.
Refreshes navigation, so the role center shows the pages of the switched-on modules.
Records an upgrade verification for the company.

Check the upgrade verification

After the upgrade, open Commission Upgrade Verifications. The app adds one row per company for each upgrade. The checks are read-only:

Field	What it tells you
Triggered By Code	Whether an upgrade or a user started the verification.
Result	Whether every check passed.
Result Code	The first failing check, or BAA-UPG-VERIFY-OK.
Running App Version, Installed App Version	The version that ran the check and the version recorded in the company.
Data Schema Version	The stored data schema version.
Upgrade Tags Expected, Upgrade Tags Present	How many upgrade tags the version registers and how many are recorded for the company.
Sampled Entry Count, Hash Mismatch Count	How many ledger entries were hash-sampled and how many failed verification.
Table Count Hash, Entry Hash	SHA-256 values that identify the table counts and this verification row.

Choose Table Counts to see record counts per table, compared with the previous verification. Choose Run Verification at any time to append a new report row.

If a verification fails, the result code tells you which check failed: data version, schema, upgrade tags, hash sample or record counts. Keep the row and contact Bitta Apps support. Do not try to repair commission tables directly.

NOTE

Review Commission Feature Management after the upgrade. Modules that the company already used are on. Switch on further modules only when you need them.

After installation or upgrade

Confirm the license state on Bitta Commission Setup.
Run Check Setup on Bitta Commission Setup Checklist.
Review the native capture settings and job queue entries before you enable capture. See Business Central sales sources.
Test one invoice and one partial return end to end in a sandbox.

What to check if it goes wrong

Symptom	What to do
BAA-UPG-PRECONDITION-001 during upgrade	The company data comes from a newer app version. Install the matching or newer version.
A module you use is missing after the upgrade	Open Commission Feature Management and switch it on. Data created while it was on is kept.
Upgrade verification failed	Note the result code, open Table Counts, and contact Bitta Apps support.
Assign the Bitta Commission Setup Administrator permission set before preparing commission number series	Assign BAA Comm Setup Admin to the user in this company.

Commission Upgrade Verifications list with a passed verification row

Each upgrade appends a read-only verification row per company.