How to Setup Your Own OpenProject CDE (Bring Your Own OpenProject)

Purpose

This guide walks administrators through deploying, configuring, and connecting a dedicated, self-hosted or private cloud OpenProject instance to Digital Index for enterprise BIM issue tracking and data quality management.

Architecture Overview

Digital Index utilizes a Zero-Token-Burden architecture:

sequenceDiagram
    autonumber
    actor User as Engineer / Information Manager
    participant DI as Digital Index UI
    participant Backend as Digital Index Backend Proxy
    participant OP as Your BYO OpenProject Server

    User->>DI: Triage / Assign / Push Issues
    DI->>Backend: POST /api/bcf-bridge/[iTwinId]/topics
    Note over Backend: - Injects backend Bot API Token securely (No client token handling) -
    Backend->>OP: POST /api/v3/projects & POST /api/v3/work_packages
    OP-->>Backend: Created Work Package #101
    Backend-->>DI: Returns deep-link [ 🔗 #101 ↗ ]
    User->>OP: Clicks [ 🔗 #101 ↗ ] (Opens OpenProject with JIT Member Access)

Preconditions

  1. A deployed OpenProject instance (Community Edition, BIM Edition, or Cloud).
  2. Administrator access to your OpenProject instance.
  3. Digital Index with Author entitlement (to configure BCF settings) and Publish entitlement (to push issues).
  4. Outbound network reachability from Digital Index to your OpenProject domain over HTTPS.

Step 1: Deploy OpenProject (If Not Already Running)

If you do not already have an active OpenProject instance, deploy via Docker Compose:

version: '3.8'

services:
  openproject:
    image: openproject/openproject:14-bim
    container_name: openproject-cde
    restart: always
    ports:
      - "8080:80"
    environment:
      OPENPROJECT_HOST__NAME: "opencde.yourdomain.com"
      OPENPROJECT_HTTPS: "true"
      OPENPROJECT_SECRET_KEY_BASE: "generate-a-secure-random-64-character-secret"
      DATABASE_URL: "postgres://postgres:secure_db_pass@db:5432/openproject?pool=10"
      OPENPROJECT_RAILS__CACHE__STORE: "redis"
      OPENPROJECT_REDIS__CACHE__URL: "redis://cache:6379/0"
    volumes:
      - op_data:/var/openproject/assets
    depends_on:
      - db
      - cache

  db:
    image: postgres:15-alpine
    restart: always
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: secure_db_pass
      POSTGRES_DB: openproject
    volumes:
      - pg_data:/var/lib/postgresql/data

  cache:
    image: redis:7-alpine
    restart: always

volumes:
  op_data:
  pg_data:

Step 2: Create a Dedicated Service Bot Account

To enable zero-token user management and automated project provisioning, create a backend bot user in OpenProject:

  1. Log in to your OpenProject instance as an Administrator.
  2. Navigate to Administration > Users and permissions > Users.
  3. Select + User and enter:
    • Email: digital-index-bot@yourdomain.com
    • First Name: Digital Index
    • Last Name: Bot
    • Administrator: Check Yes (required for creating ring-fenced projects and inviting project members).
  4. Save the user and set a secure password.
  5. Sign in as digital-index-bot@yourdomain.com (or generate the token directly as administrator).
  6. Go to My Account > Access tokens > API token and select Generate token.
  7. Copy the generated API Key (e.g., 4a7b9c...).

Step 3: Configure the BCF Bridge in Digital Index

  1. Open Digital Index and select your target iTwin.
  2. Navigate to Asset Index > Configure Asset Index (Tab 2).
  3. Scroll to Section 7: BCF Bridge & OpenCDE Issue Integration.
  4. Configure the parameters:
Field Setting for BYO OpenProject
Preset / Tier Select Custom / Bring Your Own (BYO)
Server URL https://opencde.yourdomain.com (Must include https://)
BCF API Version 2.1
Default Project ID 1 (or leave blank to auto-create ring-fenced iTwin projects)
Auth Scheme apikey
Auth Token Paste your bot's API Key from Step 2
Push on Harvest Optional (Enable to auto-publish new issues after each harvest run)
  1. Select Verify Connection.

A green Connected lozenge confirms that:

  1. Select Save Configuration (or Publish to share with your organization).

Step 4: Security & Ring-Fencing Best Practices

Digital Index enforces strict data confidentiality:

  1. Private Projects (public: false):
    • Digital Index automatically provisions a private project matching your active iTwin name (e.g., Testing iModels).
    • Private projects are completely invisible to non-members.
  2. Standard Member Role (ID 4):
    • When issues are assigned to team members (e.g., engineer@contractor.com), OpenProject adds them as standard Member (not Administrator).
    • Standard members cannot access system administration, view other private projects, or alter global settings.
  3. Just-In-Time (JIT) iTwin Navigation:
    • When an authenticated user in Digital Index clicks an issue link [ 🔗 #40 ↗ ], Digital Index verifies their project membership in the background, ensuring they never receive a 404 error.

Step 5: Testing Your BYO Pipeline

  1. Go to Asset Index > Data Quality & Issues Register (Tab 3) (or the /issues page).
  2. Group issues by Model Name or Severity.
  3. Select → BCF on any issue.
  4. Verify that:
    • The issue publishes upstream within seconds.
    • The button transforms into a green [ 🔗 #issueId ↗ ] badge.
    • Clicking the badge opens the work package in your private OpenProject instance.
  5. In the toolbar, click OpenProject CDE to open your OpenProject project overview in a new tab.

Troubleshooting

Symptom Cause Solution
Connection Failed: 401 Unauthorized Invalid or expired bot API token Regenerate the API token in OpenProject under My Account > Access tokens and re-paste into Section 7.
Error 404 on Deep Link User is not a member of the private project Click the link from an authenticated Digital Index session to trigger Just-In-Time (JIT) membership registration.
CORS Errors in Browser Console Direct browser requests to external CDE Handled automatically: Digital Index routes all client requests through the /api/bcf-bridge/[iTwinId]/topics backend proxy.
Work Packages Missing Fields OpenProject statuses not mapped Digital Index dynamically maps OPEN $\rightarrow$ New, IN_REVIEW $\rightarrow$ In progress, RESOLVED $\rightarrow$ Closed, IGNORED $\rightarrow$ Rejected. Ensure standard statuses exist in your OpenProject instance.