Issue with CSV Master Catalog Bootstrap Loading in OpenELIS Global (v2/v3)

1

Hi everyone,

I am setting up a standalone instance of OpenELIS Global using Docker Compose (openelisglobal-webapp), and I am having trouble getting the backend to pick up and process my custom master catalog files (tests.csv, test-sections.csv, sample-types.csv, dictionaries.csv, test-results.csv).

My Environment & Configuration:

  • Deployment: Docker Compose (using openelisglobal-webapp container and a separate PostgreSQL container).
  • Instance ID: Standalone setup. No specific organization ID is being used (ORG_OPENELISGLOBAL_CONFIGURATION_INSTANCE_ID is omitted, so it should fall back to root folder loading).
  • Volume Mapping:
    - ./configs/configuration:/var/lib/openelis-global/configuration
  • File Structure inside Container: Verified via ls -l at /var/lib/openelis-global/configuration/backend/:
    • test-sections/test-sections.csv
    • sample-types/sample-types.csv
    • tests/tests.csv
    • dictionaries/dictionaries.csv
    • test-results/test-results.csv
  • SystemConfiguration.properties configuration:
    org.openelisglobal.configuration.bootstrap.enabled=true
    org.openelisglobal.configuration.bootstrap.forceUpdate=true

The Problem:

Every time I enable the bootstrap loader in SystemConfiguration.properties and clear the *-checksums.properties files, the application gets stuck in a Crash Loop. The container boots up, logs Bootstrapping Spring Data JPA repositories in DEFAULT mode, passes through AuditTrailServiceImpl config comparisons, and then crashes and restarts automatically after exactly 60-90 seconds.

If I run a filtered log, the specific OpenELIS classes (ConfigurationLoader or FileConfigurationProvider) are not printing any row parsing or execution messages. The only thing that loads fine from a fixed path CSV is the Odoo product mapping plugin (TestProductMapping).

Additionally, we tried running a manual console load via java -cp ... org.openelisglobal.common.util.DirectCsvLoader, but it returned a ClassNotFoundException, meaning this class might have been deprecated or refactored in this specific release. Our web interface does not expose a visual “Data Import” module either.

Questions:

  1. Has the root/fallback folder strategy for standalone bootstrap loading changed or been deprecated in favor of mandatory instanceId scopes?
  2. Why would the webapp trigger an abrupt crash/restart shortly after loading Spring JPA when the configuration bootstrap properties are set to true?
  3. Is there a new default class name or a recommended alternative script/endpoint to force the database seed from these local CSV files without manual SQL \copy routines?

Any guidance on how to properly debug or trigger the Bootstrapper background worker for master catalogs in this architectural variant would be highly appreciated.

Thanks in advance!

Regards,

Alex de la Cruz

2

Hi @Aleckgt , welcome!

The property/class names in your setup guide (bootstrap.enabled, ConfigurationLoader, DirectCsvLoader, etc.) don’t actually exist in openelis-global.

The real mechanism is ConfigurationInitializationService, it’s on by default (org.openelisglobal.configuration.autocreate=true), needs no special flags, and your CSV folder layout already matches what it expects.

Do you mind sharing the link you are building from?

3

Hi mhernan22,

I wanted to share the solution that worked for my setup in case anyone else faces the same issue. Thanks to the advice from the forum, the master catalog was successfully imported.

Here are the specific fixes that resolved the crash loop and enabled the bootstrap loader:

1. Add Missing Global Variable

The property org.openelisglobal.configuration.autocreate is not explicitly defined in the default SystemConfiguration.properties file. I had to manually append it to the end of the file to awaken the deep bootstrap service:

properties

org.openelisglobal.configuration.autocreate=true
org.openelisglobal.configuration.bootstrap.enabled=true
org.openelisglobal.configuration.bootstrap.forceUpdate=true

Usa el cĂłdigo con precauciĂłn.

2. CSV File Naming Convention & Header Hygiene

The background ConfigurationLoader matches file names and headers strictly using Java regex patterns. I had to:

  • Strip out any custom headers or comment blocks inside the CSV files.
  • Ensure the first line of the files strictly starts with the required English database columns (e.g., testSectionName, description, testName, isActive).

3. Linux File Directory Permissions (Permission Denied)

Even if Docker can read the CSV files, the backend Bootstrapper class attempts to generate dynamic dynamic tracker files (like address-hierarchy-checksums.properties or ChangedSystemConfiguration.properties) back into the host mounted folders.

Because the host directory lacked write permissions for the container’s internal Tomcat user, Java threw a FileOutputStream (Permission denied) exception, triggering the abrupt 60-second container crash loop. Fixing the host folder permissions solved this completely:

bash

chmod -R 777 ./configs/configuration/backend/
chmod -R 777 ./configs/properties/

Usa el cĂłdigo con precauciĂłn.

Final Logs Validation:

After applying these adjustments and performing a clean docker compose down && docker compose up -d, the logs confirmed a flawless database seed execution:

  • Successfully loaded 2 test sections from example-test-sections.csv
  • Successfully loaded 2 sample types from example-sample-types.csv
  • Created new test: CBC Narrative(Whole Blood)
  • Successfully loaded 1 test results from example-test-results.csv

Once the database was populated, I set org.openelisglobal.configuration.autocreate=false to avoid rebuilding indexes on every container restart.

Thanks again to the community for pointing me in the right direction!

1 Like
5

Subject: Update: Misread variable in common.properties / Issue Fully Resolved

Hi everyone,

After double-checking the files with a fresh eye and following the developer documentation guidelines, I realized I had misread the variable name in my earlier post.

The parameter org.openelisglobal.configuration.autocreate is indeed present in common.properties, but it was explicitly set to false by default out-of-the-box (org.openelisglobal.configuration.autocreate=false), not true.

Conclusion of the Behavior:

  • The Override worked perfectly: When I manually added org.openelisglobal.configuration.autocreate=true to SystemConfiguration.properties, the framework behaved exactly as architected by the developers: the system configuration layer loaded later and successfully overrode the default false statement from common.properties.

The issue is now completely resolved. Thank you to everyone for your support and for pointing out the correct parameters!