Skip to main content

First steps and activation

After installation the app is installed but inactive. Activation is fail-closed: it only succeeds when the readiness check reports ready: true.

1. Prepare roles​

The installable role set is pinned by a baseline contract in the source repository (contracts/security/roles_baseline_v1.json). The roles you need first:

RolePurpose
Insurance Broker AdministratorSetup, activation, and technical administration. Only this role can call the activation and readiness endpoints.
Insurance Broker Setup ManagerSetup and technical configuration. Cannot activate Company Settings.
Insurance Broker AdvisorAdvice and recommendations.
Insurance Broker OperationsMandates, policies, and operational cases.
Insurance Broker ComplianceDisclosure, privacy, and compliance evidence.
Insurance Broker Commission Reconciler and Insurance Broker Commission ApproverMaker and independent checker for commission work.
Insurance Broker Sensitive ClaimsExplicit access to sensitive claim files.
Insurance Broker Privacy OfficerPrivacy rights, data subject requests, legal holds.
Insurance Broker Read OnlyRead-only viewer for non-restricted records.

More roles exist (for example Auditor, Claims, Import Operator); the role model lists all of them. Grant least privilege and assign maker and checker to different people. Test link search, reports, exports, print, and file downloads with real roles, not only as Administrator.

2. Configure the company​

Open Insurance Broker Company Settings and create exactly one record per ERPNext Company. Provide:

  • country and isolation mode;
  • registration and role evidence;
  • privacy and capability configuration;
  • tax and security configuration;
  • backup, test export, and test import evidence.

Keep accounting_strategy at None unless a posting strategy has been admitted separately. See Core domains for what the accounting posture means.

3. Check readiness​

Run as a user with the Insurance Broker Administrator role:

bench --site SITE_NAME execute insurance_broker_core.api.activation.readiness \
  --kwargs COMPANY_KWARGS

COMPANY_KWARGS stands for the keyword-argument dictionary with the single key company set to the name of your company, quoted exactly as in the activation guide.

Resolve every finding code. Do not bypass the gate and do not edit activation_state directly. A missing attestation field returns IBC-ACT-REQ-001, and an accounting strategy that is not admitted is reported as IBC-ACT-ACC-001.

4. Activate​

Only ready: true permits activation:

bench --site SITE_NAME execute insurance_broker_core.api.activation.activate \
  --kwargs COMPANY_KWARGS

The stored configuration_hash binds the activation to the reviewed state. Re-run the readiness check after every security-relevant configuration change.

5. Regulatory context stays an operator decision​

The app ships its regulatory rule contracts as unapproved. The bundled country profiles for DE, AT, and CH are technical references, not legal approval. Without a valid regulatory context a distribution decision is rejected with IBC-REG-CONTEXT-001. The regulatory engine is off by default. The operator remains responsible for legal review.

Find your way around​

The Insurance Broker workspace links to the Insurance Broker Cockpit page. After you choose an authorised ERPNext Company, the cockpit loads a permission-scoped read model with:

  • active policies and renewals within 90 days;
  • overdue regulatory and contractual deadlines;
  • open advice cases and submissions;
  • open claims (only if you hold claims permission);
  • unmatched or exceptional commission reconciliations;
  • missing disclosure delivery evidence;
  • status distributions and drill-down lists that open the authoritative record.

The cockpit is a projection. It does not create a second policy, claim, task, or accounting record. Restricted claim data is not loaded for users without read permission; the cockpit then shows a restricted state instead of a count or amount. The workspace also exposes the tender workflow (tenders, tender invitations, submissions, quote comparisons).

After a migration, reload the Desk page once to fetch a refreshed sidebar.

Next steps​