FORNAV Source Control — User Guide
In the FORNAV Customizable Report Pack version 8.1, we have added source control to Business Central version 23 and later.
Source control is a way of tracking changes to all the relevant FORNAV setup tables. Every change you make to the FORNAV setup tables must be committed, and each commit must have a message describing the change. FORNAV keeps a log of all the commits per source control entry. It does not keep a detailed record of what was changed per entry (because this would take up too much space in the database).
If you want to keep a detailed record of all your changes in a safe place, FORNAV also offers the option of storing your changes in a remote repository, like GitHub. Remote repositories are great for tracking changes across files and time, and they have fewer database size constrictions than Business Central.
The workflow mirrors standard Git: you load the current configuration into the working area, review what has changed, stage the changes you want to keep, commit with a message, and optionally push to and pull from the remote provider.
IMPORTANT NOTE: When you open the Source Control page, you might not see the setup that you had in the past. In the latest release of FORNAV, we have completely rebuilt the Source Control feature. If you used source control in an earlier release, you will see a notification asking you to migrate your settings to the new release.
Table of Contents – FORNAV Source Control User Guide
- Prerequisites
- Opening Source Control
- Setting Up a Provider
- 3.1 GitHub
- 3.2 Azure DevOps
- 3.3 Backup Types
- The Source Control Page
- 4.1 Toolbar Actions
- Daily Workflow
- Comparing Changes
- Viewing All Entries and Commit History
- 7.1 All Entries
- 7.2 Commit History
- Resolving Conflicts
- Reference — Backup Types
1. Prerequisites
- Business Central 23.0 or later – Source Control requires BC 23+.
- The FORNAV Report Pack extension version 8.1.0.15+ must be installed and activated.
- You need the FORNAVAdmin permission set (or equivalent) to access and administer Source Control.
- For remote providers you need:
- GitHub – a registered GitHub App (Client ID + Secret) with access to the target repository.
- Azure DevOps – an Azure AD app registration (Tenant ID, Client ID, Client Secret) with access to the target project and repository.
2. Opening Source Control
Search for FORNAV Source Control in the Business Central search bar (it also matches the keywords GitHub, Azure DevOps, and Git). The page is listed under Administration. Alternatively, use the menu option under ForNAV in the Role Center.
3. Setting Up a Provider
To set up a provider, click Setup on the Source Control page (or navigate directly to FORNAV Source Control Setup).
3.1 GitHub
First, register a GitHub App in your GitHub account or organization. See Registering a GitHub App in the GitHub documentation. Then, fill in the following fields:
| Field | Description |
| Provider | Select GitHub. |
| Client Id | The Client ID of your GitHub App. |
| Client Secret | The Client Secret. Stored encrypted in isolated storage; shown masked after first save. |
| Organization | Your GitHub user or organization name. |
| Repository | The target repository. Use the lookup (…) to pick from available repos. |
| Base Folder | Optional sub-folder inside the repository where files will be stored. Leave empty to use the root. Must not contain \ / : * ? ” < > \|. |
| Allow Push | Enable to allow pushing commits to the remote repository from Business Central. |
3.2 Azure DevOps
| Field | Description |
| Provider | Select Azure DevOps. |
| Tenant Id | Your Azure AD tenant ID. |
| Client Id | The Client ID of your Azure AD app registration. |
| Client Secret | The Client Secret. Stored encrypted; shown masked after first save. |
| Organization | Your Azure DevOps organization name. |
| Project | The target project. Use the lookup to pick from available projects. |
| Source Provider | The source control type used by the project (for example, Git). Use the lookup to pick. |
| Repository | The target repository within the project. Use the lookup. |
| Base Folder | Optional sub-folder inside the repository. Must not contain \ / : * ? ” < > \|. |
| Allow Push | Enable to allow pushing from Business Central. |
NOTE: You can only change the provider when there are no staged or conflicted changes. Commit or discard everything before switching. Changing the provider resets source control and deletes all Source Control Entries. The Commit Entries will not be deleted.
3.3 Backup Types
The Backup Types section controls which categories of FORNAV data are included when loading the configuration into the working area. All types are enabled by default.
| Type | What it covers |
| File Storage | FORNAV File Storage records |
| Language | Language translation entries |
| Layout | Custom report layouts |
| Layout Activation | Layout activation selections |
| Setup | FORNAV Setup fields (watermarks, defaults, and so on) |
| Text Storage | HTML text storage records |
| Report Replacement | Report replacement rules |
| Report Selection | Report selection entries |
| Text Template | FORNAV text templates |
| Email Template | FORNAV email templates (BC 25+ only) |
| Bank Account Selection | Bank account selection rules |
Disable a type to exclude it from future loads. Existing entries will be marked as deleted.
4. The Source Control Page
The main FORNAV Source Control page has these areas:
| Area | Purpose |
| General | Shows the active Branch (click to look up and switch branches) and the Commit Message field (editable when staged changes exist). |
| Staged Changes | Changes marked for inclusion in the next commit. |
| Changes | Unstaged changes — detected differences not yet staged. |
| Conflict | Visible instead of Staged Changes/Changes when there are conflicting entries that must be resolved first. |
4.1 Toolbar Actions
| Action | When enabled | Description |
| Reload Setup | Always | Reads the current FORNAV configuration and updates the working entries. Run this after making changes in Business Central that you want to capture. |
| Show All | Always | Opens the FORNAV Source Control Entries list with all tracked files. |
| Commit | When staged changes exist and no conflicts | Creates a local commit from all staged changes using the commit message. |
| Push | When Allow Push is on and the local branch is in sync with remote | Pushes all local commits to the remote repository. |
| Pull | When all changes are committed and no conflicts | Fetches the latest state from the remote and updates local entries. |
| Setup | Always | Opens the Source Control Setup page. |
5. Daily Workflow
5.1 Loading the Current Configuration
Opening the Source Control page loads the current state of all enabled backup types into the working area. To check for changes manually, click Reload Setup.
- If this is the first time you load, all entries appear as Added (new to source control).
- On subsequent loads, entries show as Modified, Added, or Deleted compared to the last committed state.
- Entries that have not changed since the last commit are not listed in the Changes panel (they are still tracked internally).
5.2 Reviewing Changes
The Changes panel lists all unstaged modifications. Each line shows:
| Column | Description |
| Type | The backup type (Layout, Language, Setup, and so on). |
| Name | The human-readable name of the item. |
| Path | The file path that will be used inside the repository. |
| Action | Add Local, Edit Local, Delete Local, Add Remote, Edit Remote, Delete Remote. |
The lines are color-coded as follows:
- Green – Added
- Yellow/Amber – Modified
- Red – Deleted
To view side-by-side differences, select any line and click Compare (from the entries list).
5.3 Staging Changes
In the Changes panel:
- To move selected items to Staged Changes, select one or more lines, then click Stage.
- To move every unstaged change at the same time, click Stage All.
In the Staged Changes panel:
- To move selected items back to Changes, select one or more lines, then click Unstage.
- To move every item at the same time, click Unstage All.
To permanently discard an unstaged change (rolling back to the last committed state), select the line in the Changes panel and click Discard. NOTE: This action cannot be undone.
5.4 Committing
To commit your changes:
- Verify the Staged Changes panel contains only the items you intend to commit.
- Type a descriptive message in the Commit Message field.
- Click Commit.
The staged entries are cleared and a commit record is stored locally. The branch is not yet updated on the remote — you need to Push for that.
5.5 Pushing to the Remote
After committing, to upload all local commits to the configured repository, click Push.
- Push is only enabled when:
- Allow Push is turned on in Setup.
- The local branch Simple Hashing Algorithm (SHA) matches the remote branch SHA (that is, you are not behind).
- A branch is selected.
If the push is rejected because the remote is ahead, you must first pull, resolve any conflicts, and then push again.
5.6 Pulling from the Remote
To download the latest state from the remote repository into the local working area, click Pull.
- Pull is only enabled when all local changes are committed (nothing staged or unstaged).
- After pulling, any entries that differ from your local committed state appear as conflicts or changes.
6. Comparing Changes
To view differences between the version stored in source control (origin) and the current version (delta):
- Click Show All to open FORNAV Source Control Entries.
- Select a line and click Compare.
The Source Control Compare page opens:
- For Text / HTML content (layouts, templates) – the Origin pane (last committed) and the Delta pane (current) are displayed, side-by-side. Lines are color-coded. Unchanged lines are in black, deleted lines are highlighted in red, and inserted lines are in green.
- For Binary content (images, PDFs) – the Origin File Size and the Delta File Size are displayed in bytes. To download the file, click the size.
7. Viewing All Entries and Commit History
7.1 All Entries
To view a list of every tracked file, click Show All > FORNAV Source Control Entries. You can see the following information:
| Column | Description |
| Type | Backup type |
| Name | Human-readable name |
| Path | Repository path |
| Action | Current diff action |
| Sync Required | Whether the entry needs to be pushed/pulled |
| Conflict | Whether there is an unresolved conflict |
| SHA Origin / SHA Delta | Hash values of the stored vs. current content |
| Remote SHA Origin / Remote SHA Delta | Hash values of the remote content |
7.2 Commit History
From the Entries list, use the History menu:
- Commit Entries – shows all commits for the selected file/type combination (entry no., type, path, commit message, committed by, date/time).
- All Commit Entries – shows the full commit log across all files.
8. Resolving Conflicts
A conflict occurs when both the remote and the local copy of the same file have changed since the last common ancestor (that is, after a pull finds diverging content).
When conflicts exist, the Source Control page only shows the Conflict panel; the Staged Changes and Changes panels are hidden.
For each conflicting entry, you must choose an outcome:
| Action | Effect |
| Use Local Version | Keeps the local version and discards the remote change. |
| Use Remote Version | Accepts the remote version and discards the local change. |
After all conflicts are resolved, the Conflict panel disappears and normal staging/committing resumes.
TIP: Click Compare from the Entries list to review both versions before deciding which to keep.
9. Reference — Backup Types
The following types map to FORNAV data categories:
| Backup Type | Business Central data |
| File Storage | FORNAV File Storage records (logos, PDFs, binaries) |
| Language | FORNAV Language Setup translation entries |
| Layout | Custom report layouts (FORNAV Report Layout) |
| Layout Activation | Tenant Report Layout Selection (active layout per report) |
| Setup | FORNAV Setup table fields (watermarks, VAT type, fonts, and so on) |
| Setup UTF8 | Text fields from Setup, stored as UTF-8 (auto-generated alongside Setup) |
| Text Storage | FORNAV Text Storage HTML blobs |
| Report Defaults | FORNAV Report Defaults (language, format region per report) |
| Report Replacement | FORNAV Report Replacement rules |
| Report Selection | Report Selections and Report Selection Warehouse |
| Text Template | FORNAV Text Template records including HTML content |
| Email Template | FORNAV Email Template records |
| Bank Account Selection | FORNAV Bank Account Selection records |
| Extension | FORNAV AL extensions (.app files via zip2app conversion) |
All types are enabled by default in the Source Control Setup. Disable individual types to exclude data categories you do not want to track.