🔧 Troubleshooting Queries

Query Errors Before 180-Second Timeout

Check the following possible causes:

• PHP timeout: default_socket_timeout in php.ini might be too small.
• Apache/IIS timeout: May be shorter than expected.
• Wildfly worker thread pool: Might be too small.
• IIS PHP FastCGI Activity Timeout: Often set to 30s by default.
  (Go to IIS → FastCGI Settings → Edit)

Tips for Optimizing i2b2 Query Speed

PostgreSQL:

• Avoid using % in concept codes (it prevents index usage).
• Consider table partitioning for large datasets.

SQL Server (MSSQL):

• Use clustered columnstore indexes on the observation_fact table.

All Platforms:

• For extremely large observation_fact tables, consider splitting into multiple fact tables.

i2b2 running with SHRINE:

• Some sites have found that truncating pm_user_login and pm_user_session dramatically speeds up queries. These can be rotated (backed up and truncated) on a regular basis to keep queries fast. pm_user_login is an audit log of login events, and pm_user_session tracks active sessions. (Note that completely truncating pm_user_session will log out all users.)

🔐 Access & Authentication

I Can Log In, but Nothing Else Works

• Check Wildfly logs for "invalid session" errors.
  → Your database and Wildfly servers might have different system time settings.
  Ensure both the time and timezone match.

A User is Locked Out — How to Restore Access

• Run:

  DELETE FROM pm_project_user_params WHERE user_id='[your user]' AND param_name_cd='LOCKEDOUT';
  

• Obfuscated users may be locked out after repeating the same query too often (default is 7 times).
  → Controlled by edu.harvard.i2b2.crc.lockout.setfinderquery.count in hive_cell_params.

To allow the user to rerun the query that locked them out, delete entries from:

DELETE FROM qt_query_master WHERE user_id = '[user_id]';

Using Active Directory with SQL Server

Update db.properties:

<connection-url>jdbc:sqlserver://localhost:1433;IntegratedSecurity=true;Trusted_Connection=Yes</connection-url>

• Leave the <password> field empty — it will be ignored.

🌐 Webclient Issues

PM Cell or Address is Incorrect

Troubleshooting steps:

• Check that the URL for the PM cell is correct in i2b2_config_data.js.
• SELinux may be blocking access.
  Check /var/log/audit/audit.log for DENY messages.

Solutions:

• Not Recommended: Disable SELinux:
  sudo setenforce 0 (resets on reboot)
• Preferred: Allow network connect:
  setsebool -P httpd_can_network_connect 1 (persistent)

📊 Encounter Sets and Breakdown Failures

Encounter Set Breakdowns Fail, Others Work

• Check row count in QT_PATIENT_ENC_COLLECTION:

  SELECT max(PATIENT_ENC_COLL_ID) FROM QT_PATIENT_ENC_COLLECTION;
  

• If it has over 2 billion rows, generating new sets will fail.
  → Solution: Delete old or unneeded encounter sets.

🔐 HTTPS and Inter-cell Communication

Using HTTPS with Wildfly (Inter-cell SSL)

• Enable Inter-cell SSL to secure communication between i2b2 cells.
  → See the 1.7.11 Release Notes for setup instructions.

🤝 Contributing to i2b2

How to Contribute

1. Create a JIRA issue
2. Make a GitHub Pull Request and reference the JIRA issue
   (e.g., CORE-589: Fixed hyperspeed drive rotor)
3. Attest to the DCO (e.g., include:
   'I attest to https://developercertificate.org/')
4. Email a core developer (e.g., Mike Mendis or Jeff Klann)

Your contribution must:

• Be tested
• Include unit tests (for new features)
• Include documentation (can be in the PR)