proxmox/scripts/omnl/README.md

OMNL Fineract scripts

Scripts for the OMNL tenancy (omnl.hybxfinance.io). Load env from omnl-fineract/.env or repo root .env (see OMNL_FINERACT_CONFIGURATION.md).

Script	Purpose
omnl-gl-accounts-create.sh	Create the five migration GL accounts (1000, 1050, 2000, 2100, 3000) via POST /glaccounts. Idempotent (skips if exists). Run before ledger post. See OMNL_GL_ACCOUNTS_REQUIRED.md.
omnl-gl-accounts-fx-gru-create.sh	Create FX and GRU (M00) GL accounts from Chart of Accounts (12xxx/13xxx, 21xxx, 42xxx/52xxx). See OMNL_GL_ACCOUNTS_FX_GRU.md.
omnl-discovery.sh	GET offices, clients, savings/FD/RD products and accounts; output JSON. Set OUT_DIR=<dir> to write files.
omnl-ledger-post.sh	Post ledger allocation entries T-001–T-008 per LEDGER_ALLOCATION_POSTING_RUNBOOK.md. Resolves GL from GET /glaccounts. DRY_RUN=1, TRANSACTION_DATE, OFFICE_ID=1 optional.
omnl-ledger-post-from-matrix.sh	Post journal entries from omnl-journal-matrix.json (matrix + full GL + IPSAS). Resolves glCode→id; posts to OMNL Hybx. JOURNAL_MATRIX=<path>, DRY_RUN=1, TRANSACTION_DATE optional. See OMNL_JOURNAL_LEDGER_MATRIX.md.
omnl-deposit-one.sh	Post a single deposit to an existing savings account. ACCOUNT_ID=<id> AMOUNT=<number> [DATE=yyyy-MM-dd]. Use discovery output for account IDs; for bulk, loop over a CSV or discovery JSON.
omnl-client-names-fix.sh	Set client firstname/lastname to canonical entity names when blank. DRY_RUN=1 to print only. See OMNL_CLIENT_NAMES_FIX.md.
omnl-entity-data-apply.sh	Apply full entity master data (name, LEI, address, contacts) from OMNL_ENTITY_MASTER_DATA.json. ENTITY_DATA=<path> optional; DRY_RUN=1 to print only. See OMNL_ENTITY_MASTER_DATA.md.
omnl-clients-create-9-15.sh	Create clients 9–15 in Fineract (FIDIS, Alpha Omega Holdings, …). Idempotent. DRY_RUN=1 to print only. (Deprecated if using entities as offices instead.)
omnl-offices-populate-15.sh	Populate the 15 entities as Offices (Organization / Manage Offices): update office 1 name, create offices 2–15 as children. Uses OMNL_ENTITY_MASTER_DATA.json. DRY_RUN=1 to print only; OPENING_DATE=yyyy-MM-dd optional.
omnl-clients-remove-15.sh	Remove the 15 clients (ids 1–15). Run after populating entities as offices. Requires CONFIRM_REMOVE=1; DRY_RUN=1 to preview.
omnl-user-shamrayan-office-create.sh	Create Staff for office 2 (Shamrayan) and User shamrayan.admin with full admin access to that office only. Requires OMNL_SHAMRAYAN_ADMIN_PASSWORD. See OMNL_OFFICE_LOGINS_AND_CREDENTIALS.md.
omnl-office2-access-security-test.sh	Security test: office-2 user must not see other offices’ data or achieve path traversal/command injection. Set office-2 user and password (e.g. OMNL_OFFICE2_TEST_USER, OMNL_OFFICE2_TEST_PASSWORD). See OMNL_OFFICE_2_ACCESS_SECURITY_TEST.md.
omnl-office-create-samama.sh	Create Office for Samama Group LLC (Azerbaijan) and post 5B USD M1 from Head Office (Phase C pattern: HO Dr 2100 Cr 2410; office Dr 1410 Cr 2100). Idempotent by externalId. SKIP_TRANSFER=1 to create office only. See SAMAMA_OFFICE_AND_5B_M1_TRANSFER.md.
omnl-office-create-pelican.sh	Create Office for Pelican Motors And Finance LLC (Chalmette, LA). Idempotent by externalId PEL-MOTORS-CHALMETTE-LA. Use with omnl.hybx.global by setting OMNL_FINERACT_BASE_URL. See PELICAN_MOTORS_OFFICE_RUNBOOK.md.
resolve_ids.sh	Resolve GL IDs (1410, 2100, 2410) and payment type; write ids.env. Run before closures/reconciliation/templates. See OPERATING_RAILS.md.
omnl-gl-closures-post.sh	Post GL closures for Office 20 and HO (idempotent). CLOSING_DATE=yyyy-MM-dd, DRY_RUN=1. See OPERATING_RAILS.md.
omnl-reconciliation-office20.sh	Snapshot Office 20 (offices + GL + trial balance), timestamp, sha256. OUT_DIR=./reconciliation. See OPERATING_RAILS.md.
omnl-operator-rail.sh	One-command rail: resolve IDs, closures, verify, reconciliation, A/B/C readiness, print templates. SKIP_CLOSURES=1 / SKIP_RECON=1 optional. See OPERATING_RAILS.md.
omnl-audit-packet-office20.sh	Audit packet: snapshot.json, snapshot.meta, computed_balances.json, recent_journal_entries.json, manifest.json. See OFFICE_20_AUDIT_PACKET.md.
omnl-je-reverse-by-reference.sh	Reverse JE by referenceNumber. REFERENCE_NUMBER=... See OFFICE_20_DR_RUNBOOK.md.
omnl-je-maker.sh / omnl-je-checker.sh	Maker-checker: maker writes payload + sha256; checker validates and posts.
omnl-monitor-office20-movement.sh	Exit 2 if Office 20 movement in last N days (alert payload).
omnl-config-hash.sh	Output hashes of payment types, GL, office 20 (drift detection).
validate-rail.sh	CI: .gitignore (ids.env, reconciliation), resolve_ids pattern, shellcheck.

Populate 15 entities as Offices (remove as Clients)

From repo root with omnl-fineract/.env set:

# 1. Populate entities as offices (update office 1, create offices 2–15)
DRY_RUN=1 bash scripts/omnl/omnl-offices-populate-15.sh
bash scripts/omnl/omnl-offices-populate-15.sh

# 2. Remove the 15 clients (requires confirmation)
DRY_RUN=1 bash scripts/omnl/omnl-clients-remove-15.sh
CONFIRM_REMOVE=1 bash scripts/omnl/omnl-clients-remove-15.sh

Complete all clients (1–15) in one go (only if keeping entities as clients)

From repo root with omnl-fineract/.env set (OMNL_FINERACT_BASE_URL, OMNL_FINERACT_PASSWORD):

# 1. Create clients 9–15 in Fineract (no-op if they already exist)
bash scripts/omnl/omnl-clients-create-9-15.sh

# 2. Set names for all 15 + apply LEI/address/contacts from OMNL_ENTITY_MASTER_DATA.json
bash scripts/omnl/omnl-entity-data-apply.sh

Optional: run DRY_RUN=1 before each step to preview. To only fix names (no LEI/address/contact), run bash scripts/omnl/omnl-client-names-fix.sh after step 1.

Run from repo root:

# 1. Create GL accounts (run first; idempotent)
bash scripts/omnl/omnl-gl-accounts-create.sh

# 2. Post ledger entries (T-001–T-008) — from runbook or from matrix JSON
bash scripts/omnl/omnl-ledger-post.sh
# Or from matrix (full GL + IPSAS): omnl-ledger-post-from-matrix.sh
DRY_RUN=1 bash scripts/omnl/omnl-ledger-post-from-matrix.sh
bash scripts/omnl/omnl-ledger-post-from-matrix.sh

# Discovery (list products, clients, accounts)
bash scripts/omnl/omnl-discovery.sh
OUT_DIR=./output/omnl-discovery bash scripts/omnl/omnl-discovery.sh

# Ledger dry run (print payloads only)
DRY_RUN=1 bash scripts/omnl/omnl-ledger-post.sh

# Single deposit (ACCOUNT_ID from discovery)
ACCOUNT_ID=1 AMOUNT=100 DATE=2026-02-10 bash scripts/omnl/omnl-deposit-one.sh

# Fix blank client names (set canonical entity names)
DRY_RUN=1 bash scripts/omnl/omnl-client-names-fix.sh
bash scripts/omnl/omnl-client-names-fix.sh

# Apply full entity data (names + LEI + address + contacts from OMNL_ENTITY_MASTER_DATA.json)
ENTITY_DATA=docs/04-configuration/mifos-omnl-central-bank/OMNL_ENTITY_MASTER_DATA.json DRY_RUN=1 bash scripts/omnl/omnl-entity-data-apply.sh
bash scripts/omnl/omnl-entity-data-apply.sh

# Create clients 9–15 (idempotent)
DRY_RUN=1 bash scripts/omnl/omnl-clients-create-9-15.sh
bash scripts/omnl/omnl-clients-create-9-15.sh

# Populate 15 entities as offices (Organization / Manage Offices)
DRY_RUN=1 bash scripts/omnl/omnl-offices-populate-15.sh
bash scripts/omnl/omnl-offices-populate-15.sh

# Remove the 15 clients (after populating as offices)
CONFIRM_REMOVE=1 bash scripts/omnl/omnl-clients-remove-15.sh

# Samama Group LLC — create office and 5B USD M1 transfer (Phase C interoffice)
DRY_RUN=1 bash scripts/omnl/omnl-office-create-samama.sh
bash scripts/omnl/omnl-office-create-samama.sh
# Office only (no transfer): SKIP_TRANSFER=1 bash scripts/omnl/omnl-office-create-samama.sh

# Pelican Motors And Finance LLC — create office (omnl.hybx.global or omnl.hybxfinance.io)
DRY_RUN=1 bash scripts/omnl/omnl-office-create-pelican.sh
bash scripts/omnl/omnl-office-create-pelican.sh

Requirements: curl, jq (for ledger posting and pretty-print in discovery).