Upgrading CognitixERP: v3.0.0 → v3.1.0

This guide explains how existing v3.0.0 users move to v3.1.0. v3.1.0 is a feature and refinement release: biometric attendance device support, journal-entry and expense reversal reporting, invoice enhancements (authorized-signature image and localized amount-in-words), consolidated per-module master-data screens, and a significantly improved Approval module. Your existing data (customers, invoices, stock, ledgers, POS, HRM, payroll, etc.) is fully preserved — this is an additive upgrade, not a re-install.

In short: replace the source with the v3.1.0 package, keep your existing appsettings and database connection, rebuild, and start the API. No data is deleted.

Aspect	Detail
From → To	v3.0.0 → v3.1.0
Type	Minor feature release (new features + fixes) — backward compatible with your data
Databases	PostgreSQL, MySQL, SQL Server — all three supported
Data migration	Additive only — three new optional columns are added to the Currency table; no existing table or row is modified destructively
Downtime	Short — the duration of a rebuild + restart (typically a few minutes)
Re-activation	Not required — your existing license activation continues to work

What's New in v3.1.0

New features

Biometric attendance device: register and manage biometric attendance devices in HRM, with secure device API-key provisioning for pushing attendance punches into the system.
JE & Expense reversal reporting: journal-entry and expense reversals now appear in the Financials reports, so reversed transactions are fully traceable.
Invoice — authorized signature image: sale and purchase invoice PDFs can now render a configured authorized-signature image.
Invoice — amount in words (currency-driven & localized): invoice totals are spelled out in words, driven by the document currency. Each currency defines its numbering system — Western (thousand / million / billion) or South Asian (thousand / lakh / crore) — plus spoken unit and sub-unit names. The words are localized to the active interface language (English, Bengali, French, Arabic) along with the digits.
Module Masters hubs: each major module now gathers its prerequisite master-data screens into a single tabbed Masters page (for example /inventory/masters, /hrm/masters, /financials/masters, /crm/masters), making first-time module setup faster. The original individual screens and routes still work.

Improvements & fixes

Approval module: significantly improved for more practical and reliable approval workflows across documents.
HRM module: further refinements to align its processes more closely with real-world business operations.
Role & Permission seed data: fixed a seed-data error affecting role and permission provisioning.
PDF typography: bundled Noto Sans Arabic and a multi-script font fallback chain so invoice/receipt PDFs render Arabic, Bengali, and Latin text together correctly.
Several inconsistencies and bugs identified in v3.0.0 have been fixed and refined, plus additional stability, usability, and workflow improvements across the system.

Database

One small, additive migration for the Currency table (three new optional columns that drive invoice amount-in-words).
Shipped for all three database engines (PostgreSQL, MySQL, SQL Server) and applied automatically on upgrade — see Step 5.

Before You Start

Confirm your current install is v3.0.0 and running normally.
You have the v3.1.0 package (CognitixERP-v3.1.0.zip) extracted somewhere safe.
You know your database connection details (they will be reused — nothing changes).
You have access to your build environment (.NET 10 SDK) — the same one used for the original install.
Plan a short maintenance window and tell users the system will restart.

Your license is safe: upgrading does not require re-activation. The existing activation on your database continues to work with v3.1.0.

Step 1 — Back Up (do not skip)

Always back up before any upgrade. Two things must be backed up:

Your database. Take a full backup of the database CognitixERP uses.
- PostgreSQL: pg_dump -U postgres -d YourDbName -F c -f cognitix_backup.dump
- MySQL: mysqldump -u root -p YourDbName > cognitix_backup.sql
- SQL Server: use SSMS → right-click database → Tasks → Back Up…
Your current install folder — especially your appsettings.json / appsettings.Production.json (they hold your connection string, JWT key and license config). Copy the whole v3.0.0 folder to a safe location so you can roll back if needed.

Why the config matters: your connection string, JWT signing key and license settings live in appsettings. Keeping them is what lets v3.1.0 connect to your existing database and stay activated.

Step 2 — Replace the Source

CognitixERP is self-hosted (you build and run it yourself), so upgrading means replacing the code with the v3.1.0 version and rebuilding.

Stop the running CognitixERP API and WebApp (stop the service / site / process).
Extract CognitixERP-v3.1.0.zip.
Replace your old source tree with the v3.1.0 Source/CognitixERP tree.
Do not overwrite your appsettings.Production.json (and appsettings.json connection string) — see Step 3.

Licensing is DLL-only: like v3.0.0, the v3.1.0 package ships the Licensing module as protected DLLs in lib/Cognitix.Licensing/ — there is nothing extra to configure for licensing during the upgrade.

Step 3 — Keep Your Existing Configuration

This is the most important step for a smooth upgrade. Carry over your v3.0.0 settings so v3.1.0 points at the same database and stays licensed.

Setting	File	Action
Connection string	`appsettings.json` → `ConnectionStrings:DefaultConnection`	Keep your v3.0.0 value
Database provider	`appsettings.json` → `Database:Provider`	Keep the same engine (PostgreSQL / MySQL / SQL Server)
JWT signing key	`appsettings.json` → `Jwt:Key`	Keep your v3.0.0 value (changing it logs everyone out)
Licensing	`appsettings.Production.json` → `Licensing`	Keep your v3.0.0 values (ApiKey, HmacSecret, ProductSlug)

Tip: the simplest approach is to copy your saved v3.0.0 appsettings.Production.json back into the v3.1.0 API folder after replacing the source.

Step 4 — Rebuild

Build the v3.1.0 source the same way you built v3.0.0 (.NET 10 SDK).

Open a terminal in the API project folder (src/Cognitix.API).
Restore and build in Release:
dotnet build -c Release
Publish/deploy as you did for v3.0.0 (same host, same process model — nginx same-origin, service, IIS, etc.).

Buyers building from the package: the Licensing DLL references are already wired in the package, so a normal dotnet build works — no extra flags needed.

Step 5 — Database Migration (adds Currency amount-in-words columns)

v3.1.0 adds three new optional columns to the Currency table that drive the invoice amount-in-words feature: numbering system (Western / South Asian), unit name, and sub-unit name. This is additive — no existing table or row is dropped or modified destructively, and the new columns default sensibly for currencies you already have. There are two ways the migration is applied; pick the one that matches how you run CognitixERP.

Option A — Automatic on startup (recommended)

Because your install is already set up (Setup Wizard completed in v3.0.0), CognitixERP applies pending migrations automatically when the API starts. Just start the v3.1.0 API against your existing database and the new Currency columns are added on first run.

How it works: on startup the API detects the new pending migration for your selected engine and applies it. The migration is idempotent — running it again (for example on a re-deploy) is safe and does nothing if the columns already exist. Your data is untouched.

Option B — Fresh install via Setup Wizard

If instead you are doing a clean install on a new/empty database (not upgrading in place), the Setup Wizard creates all schemas — including the latest Currency columns — for whichever engine you select (PostgreSQL, MySQL or SQL Server). No manual migration commands are needed.

All three engines covered: v3.1.0 ships this migration for PostgreSQL, MySQL and SQL Server, so selecting any engine produces a complete, up-to-date schema.

Step 6 — Verify the Upgrade

Open the app and log in as before (your users and passwords are unchanged).
Check the version endpoint: GET /api/system/version should report 3.1.0. The product version also appears on the main dashboard.
Confirm your existing data is intact — open a few invoices, stock items and ledgers.
Open a module's new Masters page (for example /financials/masters) to confirm the consolidated master-data screens load.
Open Financials → Currency Management, edit a currency, and confirm the new Amount in Words fields (Numbering System, Unit Name, Sub-Unit Name) are present.
Download a sale or purchase invoice PDF and confirm the Amount in Words line renders below the totals.

If a page errors with a missing-column message: the migration did not run yet. Restart the API (Option A) or complete the Setup Wizard (Option B), then retry.

Step 7 — Give Users Access to New Features

The new screens are permission-gated like every other feature. After upgrading, an administrator grants access where needed:

Go to Settings → Users & Roles (Users & Security).
Edit the role(s) that should use the new features.
Enable the pages your team needs — for example the module Masters hubs and the HRM Biometric Device management screen.
Save. Users with the updated role will see the new menu items after their next login.

Admin sees everything: the built-in administrator role has full access automatically — use it to explore the new features before assigning granular permissions to other roles.

No setup required for amount-in-words: currencies keep working as before. The amount-in-words line uses smart defaults from the currency's ISO code and only changes if you edit the new fields on a currency.

Rollback (if something goes wrong)

Because you backed up in Step 1, rolling back is straightforward:

Stop the v3.1.0 API/WebApp.
Restore your database from the Step 1 backup.
Restore your saved v3.0.0 source folder and configuration.
Rebuild and start v3.0.0 as before.

Note: the v3.1.0 migration only adds three optional Currency columns. If you roll the code back to v3.0.0 without restoring the database, those extra columns simply sit unused and are harmless — but restoring the backup is the clean path.

Upgrade FAQ

Will I lose any data?

No. The upgrade is additive — it only adds three optional Currency columns. Existing modules and their data are untouched. Always keep the Step 1 backup regardless.

Do I need to re-activate my license?

No. Your existing activation continues to work in v3.1.0. Keep your Licensing settings from v3.0.0.

Do I have to run migration commands manually?

Usually no. If your install was completed with the Setup Wizard (all v3.0.0 installs are), the pending migration applies automatically on startup.

Does this work on MySQL and SQL Server, not just PostgreSQL?

Yes. v3.1.0 ships the migration for all three engines, so it works whichever database you selected.

Do I have to configure amount-in-words for every currency?

No. Each currency is pre-filled with sensible defaults based on its ISO code (for example BDT → South Asian / Taka / Poisha; USD → Western / Dollars / Cents). You only edit the fields if you want to override them.

Can I keep using v3.0.0 and upgrade later?

Yes. v3.1.0 is optional; nothing forces the upgrade. When you're ready, follow this guide.

Need help?

Contact support at support@cognitivebd.com or WhatsApp +18632279760 with your purchase code and the database engine you use.