Merge pull request #1651 from virtualcell/mark-published-models

Add publish endpoint and webapp UI for marking models as published

Author: jcschaff

.github/workflows/ci_cd.yml

@@ -85,14 +85,6 @@ jobs:
           java -version
           mvn --batch-mode clean install dependency:copy-dependencies -DskipTests=true
 
-      - name: Add jython
-        shell: bash
-        run: |
-          curl https://repo1.maven.org/maven2/org/python/jython-installer/2.7.4/jython-installer-2.7.4.jar -o jython-installer.jar
-          mkdir .temp_holding
-          mv /home/runner/.m2/repository/org/python/jython/2.7.4/* .temp_holding
-          java -jar jython-installer.jar -s -d /home/runner/.m2/repository/org/python/jython/2.7.4
-
       - name: Test building of docker image
         run: |
           docker build \
@@ -178,15 +170,6 @@ jobs:
           java-version: '17'
           cache: 'maven'
 
-      - name: Add jython
-        shell: bash
-        run: |
-          curl https://repo1.maven.org/maven2/org/python/jython-installer/2.7.4/jython-installer-2.7.4.jar -o jython-installer.jar
-          mkdir .temp_holding
-          mkdir -p /home/runner/.m2/repository/org/python/jython/2.7.4
-          (mv /home/runner/.m2/repository/org/python/jython/2.7.4/* .temp_holding) || true
-          java -jar jython-installer.jar -s -d /home/runner/.m2/repository/org/python/jython/2.7.4 
-
       - name: Maven Build and run Test group ${{ matrix.test-group }}
         shell: bash
         run: |

CLAUDE.md

@@ -0,0 +1,133 @@
+# VCell - Virtual Cell Project
+
+Computational cell biology simulation platform (since 1997). Java monorepo with Python and TypeScript components, deployed on Kubernetes.
+
+**Repo:** `git@github.com:virtualcell/vcell.git`
+**License:** MIT
+**Main branch:** `master`
+
+## Build & Test
+
+```bash
+# Full build (skip tests)
+mvn clean install -DskipTests
+
+# Fast unit tests only
+mvn test -Dgroups="Fast"
+
+# Quarkus REST service tests (uses testcontainers - needs Docker running)
+mvn test -pl vcell-rest
+
+# Build specific module with dependencies
+mvn compile test-compile -pl vcell-rest -am
+```
+
+**Java:** 17
+**Maven:** 3.8+
+**Quarkus:** 3.5.2 (vcell-rest, vcell-server)
+
+## Module Structure
+
+| Module | Purpose |
+|--------|---------|
+| `vcell-core` | Core simulation logic, VCML model representation |
+| `vcell-math` | Mathematical model utilities |
+| `vcell-rest` | Quarkus REST API service (the main deployed API) |
+| `vcell-restclient` | Auto-generated Java API client |
+| `vcell-server` | Server-side business logic |
+| `vcell-api` | Legacy REST API (Restlet-based, `/api/v0/`) |
+| `vcell-api-types` | Shared API type definitions |
+| `vcell-apiclient` | Legacy API client |
+| `vcell-client` | Desktop/standalone Java client |
+| `vcell-cli` | Command-line interface |
+| `vcell-admin` | Administration tools |
+| `vcell-util` | Shared utilities |
+| `vcell-vmicro` | Virtual microscopy |
+
+## OpenAPI Client Generation
+
+OpenAPI spec is generated by Quarkus SmallRye OpenAPI from `vcell-rest` and stored in `tools/openapi.yaml`. Three clients are auto-generated:
+
+```bash
+cd tools
+./generate.sh   # Generates Java, Python, and TypeScript-Angular clients
+```
+
+- **Java client:** `vcell-restclient/` (OpenAPI Generator v7.1.0)
+- **Python client:** `python-restclient/`
+- **Angular client:** `webapp-ng/src/app/core/modules/openapi/`
+
+After regenerating clients, always verify downstream compilation:
+```bash
+mvn compile test-compile -pl vcell-rest -am
+```
+
+## vcell-rest (Quarkus API)
+
+Config: `vcell-rest/src/main/resources/application.properties`
+
+- **Port:** 9000 (dev), 80 (deployed)
+- **Auth:** OIDC via Auth0 (prod/dev), Keycloak devservices (test)
+- **Databases:** Oracle (prod), PostgreSQL (dev/test via testcontainers)
+- **OpenAPI:** SmallRye OpenAPI at `/openapi`, Swagger UI at `/q/swagger-ui/`
+- **Tests:** `@QuarkusTest` with Keycloak + PostgreSQL testcontainers
+
+## Key Domain Concepts
+
+- **versionFlag** — Curation/archive status of a model (Published, Archived, Current). This is NOT privacy. Privacy/access control uses `GroupAccess`.
+- **BioModel** — Primary biological model container (VCML format)
+- **MathModel** — Mathematical model representation
+- **Simulation** — A runnable simulation configuration within a model
+
+## Python Components
+
+Python 3.10 + Poetry 1.2.2+
+
+| Package | Location |
+|---------|----------|
+| `vcell-cli-utils` | `vcell-cli-utils/` |
+| `python-restclient` | `python-restclient/` (auto-generated) |
+| `vcell-opt` | `pythonCopasiOpt/vcell-opt/` |
+| VTK integration | `pythonVtk/` |
+| Python utilities | `python-utils/` |
+| Data handling | `pythonData/` |
+
+## Frontend
+
+Angular 17 app in `webapp-ng/`. Uses auto-generated OpenAPI TypeScript client.
+
+```bash
+cd webapp-ng
+npm install
+npm start          # Dev server
+npm run build_prod # Production build
+```
+
+## Docker & Deployment
+
+- **Dockerfile** at repo root — Ubuntu Jammy + Java 17 + Python 3.10
+- **Docker Compose** in `docker/swarm/`
+- **Kubernetes** configs in separate repo: `vcell-fluxcd/kustomize/`
+  - Overlays: `prod`, `stage`, `dev`, `remote-base`, `island-base`
+  - Ingress routes `/api/v1/` → rest service, `/api/v0/` → legacy api
+
+## CI/CD
+
+GitHub Actions (`.github/workflows/ci_cd.yml`):
+
+1. **CI-Build** — Maven build + Docker image test
+2. **CI-Test** — Parallel test groups: Fast, MathGen_IT, SBML_IT, SEDML_SBML_IT, SEDML_VCML_IT, BSTS_IT, Quarkus
+3. **CD** — Docker push to `ghcr.io` on release
+
+## Validation Checklist
+
+After major changes (especially removing/renaming user-facing features):
+
+- [ ] Check `vcell-client/UserDocumentation/` for references to changed features. This is an ad-hoc XML format compiled into JavaHelp (in-app help) and HTML published at https://vcell.org/webstart/VCell_Tutorials/VCell_Help/index.html. Update documentation to stay consistent with code.
+- [ ] After regenerating OpenAPI clients (`tools/generate.sh`), compile downstream: `mvn compile test-compile -pl vcell-rest -am`
+
+## Conventions
+
+- Break changes into logically grouped commits (not one big commit)
+- Research known issues before trial-and-error config changes
+- When test output is saved to `./output.txt`, analyze it with grep/read instead of rerunning tests

docs/publications-api.md

@@ -0,0 +1,104 @@
+# Publications and Model Curation
+
+## Overview
+
+Publications in VCell link scientific papers to the computational models (BioModels and MathModels) that were used or described in those papers. The publication system also drives the **curation workflow**, which controls model visibility and permanence.
+
+## Domain Concepts
+
+### Publication
+
+A publication record represents a scientific paper and its metadata:
+
+- **title**, **authors**, **year**, **citation** - bibliographic information
+- **pubmedid**, **doi**, **url** - external identifiers and links
+- **biomodelRefs** - array of BioModel references linked to this publication
+- **mathmodelRefs** - array of MathModel references linked to this publication
+
+Publications are managed by curators (users with the `publicationEditors` special claim).
+
+### Model References (BiomodelRef / MathmodelRef)
+
+Model references are lightweight pointers to BioModels or MathModels that are associated with a publication. Each reference includes:
+
+- **key** (`bmKey` / `mmKey`) - the model's database identifier
+- **name** - model name
+- **ownerName** / **ownerKey** - the model owner
+- **versionFlag** - the model's curation status (see below)
+
+### VersionFlag (Curation Status)
+
+`VersionFlag` represents a model's position in the curation lifecycle. It is **not** access control - that is handled separately by `GroupAccess`.
+
+| State | Int Value | Description |
+|-------|-----------|-------------|
+| **Current** | 0 | Default state. Model is in active development. Can be modified or deleted. |
+| **Archived** | 1 | Model has been archived. Cannot be deleted without admin intervention. |
+| **Published** | 3 | Model has been curated and published. Cannot be deleted without admin intervention. |
+
+**Key constraint**: Archived and Published models cannot be deleted through the normal API. This ensures the permanence of curated scientific models.
+
+### GroupAccess (Access Control)
+
+`GroupAccess` controls who can view a model. It is independent of `VersionFlag`.
+
+| Type | GroupID | Description |
+|------|---------|-------------|
+| **GroupAccessAll** | 0 | Public - visible to everyone |
+| **GroupAccessNone** | 1 | Private - visible only to the owner |
+| **GroupAccessSome** | (hash) | Shared with a specific group of users |
+
+## Curation Workflow
+
+When a curator publishes models linked to a publication, two things happen atomically for each model:
+
+1. **Access is set to public**: `GroupAccess` is changed to `GroupAccessAll` (groupid = 0)
+2. **Status is set to published**: `VersionFlag` is changed to `Published` (value = 3)
+
+This is performed by `PublicationService.publishDirectly()`, which delegates to `DbDriver.publishDirectly()` to update the `vc_biomodel` and `vc_mathmodel` database tables.
+
+### Selective Publishing
+
+Curators can publish all models linked to a publication at once, or selectively choose which models to publish by providing specific model keys in the `PublishModelsRequest`.
+
+## REST API
+
+Base path: `/api/v1/publications`
+
+| Method | Path | Operation | Auth | Description |
+|--------|------|-----------|------|-------------|
+| GET | `/` | getPublications | Public | List all publications |
+| GET | `/{id}` | getPublicationById | Public | Get a single publication |
+| POST | `/` | createPublication | Curator | Create a new publication |
+| PUT | `/` | updatePublication | Curator | Update publication metadata and model links |
+| DELETE | `/{id}` | deletePublication | Curator | Delete a publication |
+| PUT | `/{id}/publish` | publishBioModels | Curator | Publish models linked to a publication |
+
+### Publish Endpoint
+
+`PUT /api/v1/publications/{id}/publish`
+
+Request body (`PublishModelsRequest`, optional):
+```json
+{
+  "biomodelKeys": [12345, 67890],
+  "mathmodelKeys": [11111]
+}
+```
+
+- If the request body is null or keys arrays are empty, **all** models linked to the publication are published.
+- If specific keys are provided, only those models are published.
+
+## Key Source Files
+
+| File | Purpose |
+|------|---------|
+| `handlers/PublicationResource.java` | REST endpoint definitions |
+| `services/PublicationService.java` | Business logic for publication CRUD and publishing |
+| `models/Publication.java` | Publication REST model |
+| `models/BiomodelRef.java` | BioModel reference REST model |
+| `models/MathmodelRef.java` | MathModel reference REST model |
+| `models/PublishModelsRequest.java` | Request body for selective publishing |
+| `vcell-core/.../VersionFlag.java` | Curation status enum |
+| `vcell-core/.../GroupAccess.java` | Access control base class |
+| `vcell-server/.../DbDriver.java` | Database-level publish logic |

docs/publications.md

@@ -0,0 +1,124 @@
+# VCell Publications and Model Curation
+
+## What is a Publication in VCell?
+
+A VCell publication links a scientific paper to the computational models (BioModels and MathModels) that support it. Publications serve two purposes:
+
+1. **Discovery** - Users can browse publications to find curated, peer-reviewed models relevant to their research.
+2. **Curation** - Publications drive the process of reviewing, approving, and permanently preserving models in the VCell database.
+
+## How Users Find Published Models
+
+In the VCell desktop client, the **Database** panel (lower left of any document window) organizes public models into three folders:
+
+- **Published** - Models created by users and linked to a scientific publication. Grouped by publication citation.
+- **Curated** - Models created by the VCell team or collaborators to reproduce results described in a publication.
+- **Uncurated** - Public models that have not been peer-reviewed or linked to a publication.
+
+Published and Curated models represent the highest quality tier - they have been reviewed, are permanently preserved, and are linked to their corresponding papers.
+
+## How to Publish a VCell Model (Author Instructions)
+
+When your paper is accepted and you want to associate your VCell model with the publication, follow these steps:
+
+### 1. Make Your Model Public
+
+Change your model's permissions in the VCell Database:
+- Navigate to **File > Permissions...**
+- Select **Public**
+- Click **OK**
+
+The model will initially appear in the **Uncurated** public models folder. You can also share with specific users by selecting **Grant Access to Specific Users** and adding their VCell usernames.
+
+### 2. Reference VCell in Your Publication
+
+Include your username and model name so readers can find your model:
+
+> "The Virtual Cell Model, *[modelname]* by user *[username]*, can be accessed within the VCell software (available at https://vcell.org)."
+
+### 3. Acknowledge the Funding Source
+
+Include this acknowledgment in your manuscript:
+
+> "The Virtual Cell is supported by NIH Grant R24 GM137787 from the National Institute for General Medical Sciences."
+
+### 4. Cite the Required VCell Papers
+
+All publications using VCell must cite:
+- Schaff, J., C. C. Fink, B. Slepchenko, J. H. Carson, and L. M. Loew. 1997. A general computational framework for modeling cellular structure and function. Biophysical journal 73:1135-1146. PMC1181013 PMID: 9284281 DOI: 10.1016/S0006-3495(97)78146-3
+- Cowan, A. E., Moraru, II, J. C. Schaff, B. M. Slepchenko, and L. M. Loew. 2012. Spatial modeling of cell signaling networks. Methods Cell Biol 110:195-221. PMC3519356 PMID: 22482950 DOI: 10.1016/B978-0-12-388403-9.00008-4
+
+Additional citations for specialized model types:
+- **Rule-Based models**: 
+  - Blinov, M. L., J. C. Schaff, D. Vasilescu, Moraru, II, J. E. Bloom, and L. M. Loew. 2017. Compartmental and Spatial Rule-Based Modeling with Virtual Cell. Biophysical journal 113:1365-1372. PMC5627391 PMID: 28978431 DOI: 10.1016/j.bpj.2017.08.022 
+- **Spatial Hybrid Deterministic-Stochastic models**: 
+  - Schaff, J. C., F. Gao, Y. Li, I. L. Novak, and B. M. Slepchenko. 2016. Numerical Approach to Spatial Deterministic-Stochastic Models Arising in Cell Biology. PLoS Comput Biol 12:e1005236. PMC5154471 PMID: 27959915 DOI: 10.1371/journal.pcbi.1005236
+
+### 5. Submit Your Publication Information
+
+Complete the [VCell Publication Submission Form](https://vcell.org/publish-a-vcell-model) with:
+- Your name, email, and VCell username
+- Article title, authors, and journal citation
+- Publication date
+- Model type (BioModel or MathModel) and model name
+
+Upon approval by the VCell team, your model will be archived, listed on the VCell website, and protected from modification or deletion.
+
+### Archiving Without Publishing (Deprecated)
+
+Previously, authors could archive models independently through the VCell desktop client by right-clicking a model in the Database panel and selecting **Archive**. Archiving protected a model from deletion or alteration but did not link it to a publication. This option was removed because it caused confusion among users about the distinction between archiving and publishing.
+
+## Model Lifecycle
+
+Every model in VCell has a **curation status** (`VersionFlag`) that tracks where it is in the curation lifecycle:
+
+```
+  Current (0)  -->  Archived (1)  -->  Published (3)
+   (default)       (protected)        (protected + public)
+```
+
+| Status | Who can see it | Can it be deleted? | Typical meaning |
+|--------|---------------|-------------------|-----------------|
+| **Current** | Depends on access settings | Yes | Work in progress or uncurated model |
+| **Archived** | Depends on access settings | No (admin only) | Preserved for reference, may or may not be linked to a publication |
+| **Published** | Everyone (public) | No (admin only) | Curated, peer-reviewed, linked to a publication |
+
+Curation status is independent from access control. A model can be publicly visible but still in "Current" status (not yet curated), or it could be archived but only visible to certain users.
+
+## Access Control (GroupAccess)
+
+Access control determines who can view a model. It is a separate concept from curation status.
+
+| Level | Description |
+|-------|-------------|
+| **Private** | Only the model owner can see it (default) |
+| **Shared** | The owner and specific named users can see it |
+| **Public** | Everyone can see it |
+
+When a model is published through the curation workflow, its access is automatically set to Public. However, a model author can independently make their model public at any time without it being "published" in the curation sense.
+
+## Curator Workflow
+
+Curators are VCell team members with the `publicationEditors` role. Curation is performed through the Angular webapp at [vcell.cam.uchc.edu](https://vcell.cam.uchc.edu). Curators are responsible for:
+
+- Creating and editing publication records (title, authors, DOI, PubMed ID, etc.)
+- Linking the correct model versions to each publication
+- Reviewing models for correctness and completeness
+- **Publishing** models - the act that makes them permanently public and protected from deletion
+
+### What Happens When a Curator Publishes Models
+
+When a curator clicks "Publish Selected Models" in the webapp (or calls the publish API), two things happen atomically for each selected model:
+
+1. **Access becomes public** - The model's access control is set to `GroupAccessAll`, making it visible to all VCell users.
+2. **Status becomes Published** - The model's `VersionFlag` is set to `Published`, protecting it from deletion.
+
+This is an intentionally irreversible operation through normal means. Published models are part of the scientific record and should not be casually removed.
+
+### Selective Publishing
+
+Curators can choose to publish all models linked to a publication at once, or selectively publish individual models. This is useful when a publication links to multiple models but only some are ready for curation.
+
+## For Developers
+
+See [publications-api.md](publications-api.md) for the REST API reference, data models, and source file locations.

lib/maven-repo/com/sun/media/jai-codec/1.1.3/jai-codec-1.1.3.jar

@@ -0,0 +1 @@
+1b0f328c9eda0992167ce503b0a5afcc

lib/maven-repo/com/sun/media/jai-codec/1.1.3/jai-codec-1.1.3.jar.md5

@@ -0,0 +1 @@
+34a67ba62097778e4695c951156bf189c2c8e016