
lutecepowers-v8
Lutece 8 development toolkit for coding agents: skills, path-scoped rules, reference sources, migration and review workflows.
Install
/plugin install lutecepowers-v8@lutece-pluginsRun it inside Claude Code after adding the marketplace with /plugin marketplace add lutece-platform/lutece-dev-plugin-claude.
Contents
Discovered from sourceSkills 18
Brainstorming — Turning Ideas Into Designs
Mandatory trigger: You MUST use this skill before any creative work — creating features, building components, adding functionality, or modifying behavior. Explore user intent, requirements and design before implementation.
Process Overview
Phase 1: Context → understand project state
Phase 2: Discovery → ask questions one at a time to refine the idea
Phase 3: Reuse scan → check if existing Lutece modules/plugins already cover the need
Phase 4: Explore → propose 2-3 approaches with trade-offs
Phase 5: Design → present design in small validated sections
Phase 6: Document → write the validated design to docs/plans/
Phase 7: Handoff → set up for implementation (optional)
Interaction Model
| Situation | Tool |
|---|---|
| Yes/No, pick one, pick many | Ask the user (multiple choice) |
| Open-ended input (names, descriptions, context) | Text prompt in conversation |
| Design section validation ("looks right so far?") | Ask the user (multiple choice) with Approve / Needs changes / Go back |
Rule: Only ONE question per message. If a topic needs more exploration, break it into multiple questions.
Phase 1 — Understand Project Context
Before asking anything, silently gather context:
- Read project structure —
pom.xml,webapp/WEB-INF/conf/plugins/, existing Java packages - Check recent commits —
git log --oneline -10to understand current momentum - Scan existing features — plugin descriptor XML, existing XPages, JspBeans, services
- Identify Lutece version — v7 (Spring) or v8 (CDI/Jakarta) from dependencies
Store findings internally. Do NOT dump them on the user — use them to ask smarter questions.
Phase 2 — Discovery (One Question at a Time)
Ask questions to understand purpose, constraints, and success criteria.
Question priorities
- What — What does this feature do? What problem does it solve?
- Who — Back-office users? Front-office visitors? Both? API consumers?
- Where — New plugin? Existing plugin extension? Module?
- Scope — What is explicitly OUT of scope? (Apply YAGNI ruthlessly)
- Constraints — Must integrate with existing workflows? RBAC requirements? Performance targets?
- Data — New business objects? Relationships to existing entities? Parent-child?
Example question flow
Message 1:
Ask the user (multiple choice):
question: "What type of component are you building?"
options:
- "New plugin from scratch"
- "New feature in an existing plugin"
- "Module extending another plugin"
- "XPage (front-office functionality)"
Message 2 (adapts based on answer):
Ask the user (multiple choice):
question: "Who will use this feature?"
options:
- "Back-office administrators only"
- "Front-office visitors only"
- "Both back-office and front-office"
- "REST API consumers"
Message 3 (open-ended when needed):
Can you describe in a few words what this feature should do?
What problem does it solve for users?
Continue until you have enough clarity to propose approaches. Typically 4-8 questions.
Phase 3 — Reuse Scan (Existing Modules Check)
Before building anything, check if Lutece already has it. Many features exist as plugins or modules on lutece-platform or lutece-secteur-public. Reusing or extending an existing module is always preferable to building from scratch.
Where to search
| Source | What to look for | How |
|---|---|---|
| Lutece Platform GitHub | Official plugins and modules | Search the web for site:github.com/lutece-platform [feature keywords] |
| Lutece Secteur Public GitHub | Public-sector-specific modules | Search the web for site:github.com/lutece-secteur-public [feature keywords] |
| Local references | Already-cloned v8 repos | Search the references in ~/.lutece-references/ |
| Lutece dev wiki | Architecture notes, existing module docs | Search the web for site:dev.lutece.paris.fr [feature keywords] |
| Maven artifacts | Published Lutece modules | Search for fr.paris.lutece.plugins + keywords |
Search strategy
- Identify keywords from the Discovery phase (e.g. "notification", "workflow", "form", "directory", "appointment")
- Search GitHub orgs — search the web in both
lutece-platformandlutece-secteur-public:site:github.com/lutece-platform [keyword] plugin OR module site:github.com/lutece-secteur-public [keyword] module - Check local references — scan
~/.lutece-references/for related code - Read README / plugin descriptor of any promising match to assess fit
Present findings to user
If matches are found, present them:
## Existing Modules Found
### module-xyz (lutece-platform)
- **Repo:** github.com/lutece-platform/lutece-xyz-module-abc
- **What it does:** [1-2 sentences]
- **Covers your need?** Fully / Partially / Tangentially
- **Lutece 8 ready?** Yes / Needs migration
### plugin-abc (lutece-secteur-public)
- **Repo:** github.com/lutece-secteur-public/lutece-abc-plugin-def
- **What it does:** [1-2 sentences]
- **Covers your need?** Fully / Partially / Tangentially
- **Lutece 8 ready?** Yes / Needs migration
Then ask:
Ask the user (multiple choice):
question: "How do you want to proceed?"
options:
- "Use [module-xyz] as-is (just integrate it)"
- "Extend [module-xyz] to add what's missing"
- "Build from scratch (none of these fit)"
- "I need more details on one of these modules"
If "Use as-is" → skip to Phase 6 (Document) with an integration plan instead of a full design. If "Extend" → Phase 4 & 5 focus on the extension only, not a full build. If "Build from scratch" → continue normally to Phase 4. If "More details" → fetch the module's README, plugin descriptor, and key source files, then re-ask.
If nothing found
Briefly inform the user:
No existing Lutece plugin or module found for this need on lutece-platform or lutece-secteur-public. We'll design it from scratch.
Then proceed to Phase 4.
Phase 4 — Explore Approaches (Build vs Extend)
Propose 2-3 different approaches with trade-offs. Lead with your recommendation.
Format
## Approach A — [Name] (Recommended)
**How it works:** [2-3 sentences]
**Pros:** [bullet list]
**Cons:** [bullet list]
**Fits Lutece patterns:** [which existing patterns this follows]
## Approach B — [Name]
**How it works:** [2-3 sentences]
**Pros:** [bullet list]
**Cons:** [bullet list]
## Approach C — [Name] (if applicable)
**How it works:** [2-3 sentences]
**Pros:** [bullet list]
**Cons:** [bullet list]
Then ask:
Ask the user (multiple choice):
question: "Which approach do you prefer?"
options:
- "Approach A — [Name] (Recommended)"
- "Approach B — [Name]"
- "Approach C — [Name]"
If the user picks "Other", explore their alternative before continuing.
Lutece-specific considerations
When proposing approaches, evaluate against:
- Existing Lutece patterns — consult
~/.lutece-references/for real implementations - Plugin descriptor constraints — what the XML descriptor supports
- CDI scope implications —
@ApplicationScopedvs@Dependentvs@RequestScoped - DAO/Home layer conventions —
rules/dao-patterns.md - Template conventions — Freemarker macros, admin theme, front-office skin
- Workflow integration — does this need workflow states?
- RBAC — does this need permission management?
- Cache — does this benefit from caching?
Phase 5 — Present the Design
Once the approach is chosen, present the design in sections of 200-300 words. After each section, validate with the user.
Section order
- Architecture overview — layers, components, data flow diagram
- Business objects — entities, fields, relationships
- DAO / Home layer — persistence strategy, SQL queries
- Service layer — business logic, CDI beans, scopes
- Web layer — JspBeans (back-office) and/or XPages (front-office)
- Templates — admin HTML templates, front-office Freemarker
- Plugin descriptor — XML entries needed
- Error handling & validation — user input validation, error messages
- i18n —
messages.propertieskeys - Testing strategy — unit tests, integration points
Skip sections that don't apply. Not every feature needs all 10 sections.
After each section
Ask the user (multiple choice):
question: "Does this section look right?"
options:
- "Looks good, continue"
- "Needs changes (I'll explain)"
- "Go back to a previous section"
If "Needs changes", ask what to change, revise, and re-validate before moving on.
Phase 6 — Document the Design
Once all sections are validated:
-
Create the design document:
docs/plans/YYYY-MM-DD-<topic>-design.mdStructure:
# Design: [Feature Name] **Date:** YYYY-MM-DD **Status:** Draft | Approved **Plugin:** [plugin-name] **Lutece version:** 8.x ## Context [Problem statement, 2-3 sentences] ## Decision [Chosen approach and rationale] ## Design [All validated sections from Phase 5] ## Files to Create/Modify [Checklist of files with what each one needs] ## Out of Scope [Explicitly excluded items] -
Do not commit. Tell the user the file path. The user decides when and how to commit.
Phase 7 — Handoff to Implementation (Optional)
Ask the user (multiple choice):
question: "Ready to set up for implementation?"
options:
- "Yes, let's start implementing"
- "Not yet, I want to review the design first"
- "No, just the design for now"
If yes:
- Relevant skills — point to the skills needed for implementation:
rules/dao-patterns.mdfor the DAO/Home layer/lutece-patternsfor architecture patterns/lutece-workflowif workflow integration is needed/lutece-rbacif RBAC is needed/lutece-cacheif caching is needed
- Create a task list — use your task-tracking tool to break the design into implementation tasks
Key Principles
| Principle | Rule |
|---|---|
| One question at a time | Never overwhelm with multiple questions in one message |
| Multiple choice preferred | Easier to answer than open-ended when possible |
| YAGNI ruthlessly | Remove unnecessary features from all designs |
| Explore alternatives | Always propose 2-3 approaches before settling |
| Incremental validation | Present design in sections, validate each one |
| Be flexible | Go back and clarify when something doesn't make sense |
| Reuse-first | Search lutece-platform and lutece-secteur-public for existing modules before building |
| Lutece-first | Always check ~/.lutece-references/ for existing patterns before inventing |
| Context before questions | Read the project state silently before asking anything |
Lutece 8 Cache Implementation
Before implementing cache, consult
~/.lutece-references/lutece-form-plugin-forms/— specificallyFormsCacheService.java.
Architecture Overview
AbstractCacheableService<K, V> (lutece-core, JSR-107 JCache)
↑ extends
MyCacheService (@ApplicationScoped, @PostConstruct initCache)
↓ used by
Home / Service (put, get, remove, resetCache)
↓ invalidated by
CDI Events (@Observes)
Step 1 — Cache Service Class
The JCache methods inherited from AbstractCacheableService (get(), put(), remove(), getAll(),
putIfAbsent(), …) are safe on a disabled cache, the default state in the datastore: a read misses, a write is
ignored. Only invoke() and invokeAll() throw IllegalStateException then. isCacheEnable( ) tells whether the
cache is active; there is no isCacheAvailable( ) method, do not write one, it does not compile.
import fr.paris.lutece.portal.service.cache.AbstractCacheableService;
import jakarta.annotation.PostConstruct;
import jakarta.enterprise.context.ApplicationScoped;
@ApplicationScoped
public class EntityCacheService extends AbstractCacheableService<String, Object>
{
private static final String CACHE_NAME = "myplugin.entityCacheService";
@PostConstruct
public void init( )
{
initCache( CACHE_NAME, String.class, Object.class );
}
@Override
public String getName( )
{
return CACHE_NAME;
}
}
Rules:
@ApplicationScoped— singleton CDI bean, one instance per application@PostConstructcallsinitCache( name, keyClass, valueClass )— registers the cache withCacheService- Cache name convention:
pluginName.entityCacheService - Generic types:
<String, Object>is the standard — key is always String, value is the cached object - Do not override
put/get/removeto guard them: the core already does
Step 2 — Cache Key Builders
Define static methods for consistent key generation:
@ApplicationScoped
public class EntityCacheService extends AbstractCacheableService<String, Object>
{
private static final String KEY_PREFIX = "myplugin.entity.";
// Key for a single entity
public static String getEntityCacheKey( int nIdEntity )
{
return KEY_PREFIX + nIdEntity;
}
// Key for the full list
public static String getListCacheKey( )
{
return KEY_PREFIX + "list";
}
// Key with parameters (e.g., filtered list)
public static String getFilteredCacheKey( int nIdCategory, int nPage )
{
return KEY_PREFIX + "category." + nIdCategory + ".page." + nPage;
}
// ...
}
Step 3 — Usage in Home or Service
Access pattern: @Inject (CDI-managed beans) vs CDI.current().select() (static contexts)
| Context | Pattern | Example |
|---|---|---|
CDI-managed bean (@ApplicationScoped, @RequestScoped, etc.) | @Inject | Service class |
| Static context (Home class, static utility) | CDI.current().select() direct field init | Home class |
No getInstance() on the cache service (rules/service-layer.md).
Pattern A — @Inject in a CDI-managed Service (preferred)
@ApplicationScoped
public class EntityService
{
@Inject
private EntityCacheService _cacheService;
public Entity findByPrimaryKey( int nId )
{
String strCacheKey = EntityCacheService.getEntityCacheKey( nId );
Entity entity = (Entity) _cacheService.get( strCacheKey );
if ( entity == null )
{
entity = EntityHome.findByPrimaryKey( nId );
if ( entity != null )
{
_cacheService.put( strCacheKey, entity );
}
}
return entity;
}
public Entity update( Entity entity )
{
EntityHome.update( entity );
_cacheService.remove( EntityCacheService.getEntityCacheKey( entity.getId( ) ) );
_cacheService.remove( EntityCacheService.getListCacheKey( ) );
return entity;
}
public void remove( int nId )
{
EntityHome.remove( nId );
_cacheService.remove( EntityCacheService.getEntityCacheKey( nId ) );
_cacheService.remove( EntityCacheService.getListCacheKey( ) );
}
}
Pattern B — CDI.current().select() in a static Home class
Use direct field initialization — no lazy-init getters. This is the pattern used by all Home classes in lutece-core (RoleHome, PageHome, FileHome) and in the Forms plugin (FormHome, StepHome). The CDI container is fully initialized before plugin classes are loaded.
import jakarta.enterprise.inject.spi.CDI;
public class EntityHome
{
private static IEntityDAO _dao = CDI.current( ).select( IEntityDAO.class ).get( );
private static EntityCacheService _cacheService = CDI.current( ).select( EntityCacheService.class ).get( );
private static final Plugin _plugin = PluginService.getPlugin( "pluginname" );
private EntityHome( )
{
}
public static Entity findByPrimaryKey( int nId )
{
String strCacheKey = EntityCacheService.getEntityCacheKey( nId );
Entity entity = (Entity) _cacheService.get( strCacheKey );
if ( entity == null )
{
entity = _dao.load( nId, _plugin );
if ( entity != null )
{
_cacheService.put( strCacheKey, entity );
}
}
return entity;
}
}
Step 4 — Cache Invalidation via CDI Events
Observe domain events to automatically invalidate cache:
import fr.paris.lutece.portal.business.event.ResourceEvent;
import jakarta.enterprise.event.Observes;
@ApplicationScoped
public class EntityCacheService extends AbstractCacheableService<String, Object>
{
// ...
public void onResourceEvent( @Observes ResourceEvent event )
{
if ( isCacheEnable( ) && "MYPLUGIN_ENTITY".equals( event.getTypeResource( ) ) )
{
resetCache( );
}
}
}
For finer-grained invalidation (remove specific key instead of full reset):
public void onResourceEvent( @Observes ResourceEvent event )
{
if ( isCacheEnable( ) && "MYPLUGIN_ENTITY".equals( event.getTypeResource( ) ) )
{
String strId = event.getIdResource( );
if ( strId != null )
{
remove( EntityCacheService.getEntityCacheKey( Integer.parseInt( strId ) ) );
remove( EntityCacheService.getListCacheKey( ) );
}
else
{
resetCache( );
}
}
}
Cache Operations Reference
| Method | Usage |
|---|---|
put( key, value ) | Add or update an entry |
get( key ) | Retrieve (returns null on miss) |
remove( key ) | Delete a single entry |
resetCache( ) | Clear all entries |
enableCache( boolean ) | Toggle cache on/off |
isCacheEnable( ) | Check if cache is active |
getCacheSize( ) | Current entry count |
getKeys( ) | List all keys |
containsKey( key ) | Check key existence |
Optional — Prevent Global Reset
If your cache should survive when an admin clicks "Reset all caches":
@Override
public boolean isPreventGlobalReset( )
{
return true;
}
Use sparingly — only for caches that are expensive to rebuild (e.g., configuration caches).
Configuration (properties)
Cache behavior can be tuned via caches.properties or datastore:
# Default settings (apply to all caches without specific config)
lutece.cache.default.maxElementsInMemory=1000
lutece.cache.default.eternal=false
lutece.cache.default.timeToIdleSeconds=1000
lutece.cache.default.timeToLiveSeconds=1000
# Per-cache override
core.cache.status.myplugin.entityCacheService.eternal=true
core.cache.status.myplugin.entityCacheService.enabled=1
Cache enabled/disabled state is persisted in the datastore database with key: core.cache.status.{cacheName}.enabled
File Checklist
| File | What to add |
|---|---|
EntityCacheService.java | New class in service/cache/, @ApplicationScoped, extends AbstractCacheableService, key builders |
EntityService.java | @Inject EntityCacheService, cache-through logic (get → miss → load → put) |
beans.xml | Already present (required for CDI) |
No changes needed in plugin.xml or messages.properties — cache is infrastructure, not UI.
Reference Sources
| Need | File to consult |
|---|---|
| CDI cache service (v8 pattern) | ~/.lutece-references/lutece-form-plugin-forms/src/java/fr/paris/lutece/plugins/forms/service/cache/FormsCacheService.java |
| Core AbstractCacheableService | ~/.lutece-references/lutece-core/src/java/**/service/cache/AbstractCacheableService.java |
| Core CacheService (static facade) | ~/.lutece-references/lutece-core/src/java/**/service/cache/CacheService.java |
| Cache manager (JSR-107) | ~/.lutece-references/lutece-core/src/java/**/service/cache/Lutece107CacheManager.java |
| Cache configuration | ~/.lutece-references/lutece-core/src/java/**/service/cache/CacheConfigUtil.java |
Lutece checkup
A read-only health check. It changes nothing; the user decides what comes next.
1. Run
bash ${LUTECEPOWERS_ROOT}/tools/lutece-check.sh <project-dir>
A few seconds once the project is assembled (the scanner and the i18n check assemble it with
mvn lutece:exploded-lite the first time; a project without webapp/, a jar library, is not applicable to them and
is not assembled). Full outputs land in <project>/target/checkup/.
Exit 1 means at least one blocking finding.
2. Report
Give the user, in their language, three short groups taken from the script's output only:
- Blocking: every FAIL of verify-migration, unresolved i18n keys, templates that do not parse, a tool that stopped before its end (and why).
- To fix: every WARN, grouped by code, with the files.
- To decide: the INFO codes and their counts.
The meaning of a code and how to fix it: bash ${LUTECEPOWERS_ROOT}/tools/lutece-check.sh --explain CODE.
Never add a finding the tools did not print, never drop one.
3. Ask
Ask the user what to do, with these options: bring the project to the supported level with the lutece-update-plugin skill
(every finding, the build, the review and the e2e bench, gate green), fix the blocking findings only, explain one
finding, or stop here. Fixing findings only follows the skill that owns the files (lutece-patterns for Java,
lutece-update-template-bo / -fo for templates), and ends by running this checkup again.
Lutece e2e — one bench, every screen, one command
What this produces, and who writes what
An e2e/ folder in the project under test holding only its configuration (e2e.conf, the scenarios, the
fixtures, the bench's own seeds and site files), and one command, lpe2e, run from the project. The bench code stays
in this skill and runs from ~/.lutecepowers-e2e, installed at its first use: one MariaDB, one mail sink and one
generic Open Liberty image for every bench of the machine, the assembled sites cached by composition, warm test
workers. A run packages the artefact, lays out its site from the cache, starts it on a fresh database (the
application's own Liquibase creates the schema), seeds it, inventories every back-office screen and action, runs
the suites, profiles the server and writes artifacts/summary.md: about 35 seconds for a plugin.
The harness is a starter kit and presumes nothing about the target: it seeds no reference row, no account,
no volume, and ships no scenario. Everything target-specific is written by the agent — the seed rows its
screens need, the accounts its rights tests require, the volume for the tables it reads, and the scenarios.
On lutece-core that yields a core bench; on a FAQ plugin, FAQ rows and FAQ scenarios. Never hard-code either:
the idioms live in templates/scenarios-example.yaml and templates/scenarios-negative-example.yaml.
The agent writes only e2e.conf, the YAML scenarios and the bench's own seeds. Everything else is shipped here.
Every Lutece artefact of the bench site (the core, plugin-liquibase, mylutece, the extra plugins) is the latest
Lutece 8 snapshot of the repositories, read at build time (tools/latest-lutece.py); a new snapshot published since
the last run reassembles the site. e2e.conf pins a version only to reproduce a case.
e2e/ is never committed. It is a local test tool, not a deliverable of the plugin: init-e2e.sh adds it
to the project's .gitignore. Hand over what it produced (summary.md, review.md) as
attachments to the report, never as files of the repository.
Prerequisites: Docker, Maven 3.9.x (not 4) with the Lutece repositories, JDK 17+ on the host, network access to the
Lutece repositories and Maven Central at the first run. The artefact resolves the latest published lutece-core
(tools/v8-floor.conf); lpe2e build stops with rc=10 otherwise.
The first assembly of a site installs the artefact under test in ~/.m2, where it shadows the published snapshot
for every other project on the machine. The v7 site of lpe2e upgrade only reads ~/.m2: its install and downloads
go to the bench's own repository.
Run it as bash ${LUTECEPOWERS_ROOT}/skills/lutece-e2e/lpe2e <command> from the project (an alias lpe2e is
convenient). Supported: a plugin or module (E2E_TARGET=plugin) and a site (E2E_TARGET=site: assembled with
its own pom and E2E_SITE_PROFILE, the latest Lutece 8 core and plugin-liquibase forced over its BOM, every screen
of the site tested), with the stand-ins of external systems (E2E_FAKES=1) and the real search engines
(E2E_SEARCH=1) beside the application. The core is not supported: lpe2e refuses it (rc=2). A tool of
tools/ run by hand works on the project's e2e folder (E2E_DIR, else the current directory) and refuses the
skill's own folder.
Additional resources
Read these only when the case applies — none is needed for a plain bench.
- The traps that fake a green run — screens opened without their parameters, a front-office assertion that passes on the site menu, a seed that lands after the cache froze, REST endpoints, scenario ordering: reference/traps.md. Read at PHASE 2.
- Proving the database upgrade of a migration or an update (
lpe2e upgrade): the previous version's database (a v7 site installed and seeded, a recette dump, or the previous v8 version), brought under Liquibase as the environments will, taken over by the bench site, then the suites on it: reference/upgrade.md. The v7 data is proven kept by a witness row ofseed7-*.sqlasserted with thev7_witnessstep: exactly 1 on a database born in v7 (the core changeset 7.9.9-8.0.0 inDATABASECHANGELOG), exactly 0 on a fresh install, against a value written in the query. - External systems (CAS, OIDC, identity store, notifygru, ANTS, CRM, TIPI, Solr, Elasticsearch) and running
against a deployed instance (
external): reference/external-systems.md. - Scope of a plugin bench — what extra artefacts to assemble (
E2E_PLUGINS,E2E_ENABLE), front-office coverage, how the mechanics measure: reference/scope.md. Read at PHASE 1. - How the shared bench works and why each choice: reference/DESIGN.md. Read before changing the bench. Its § Traps lists the platform traps the bench already works around — do not re-diagnose them; fix the bench if one resurfaces.
What you can run, and when
lpe2e with no argument runs the whole chain and ends on artifacts/summary.md. That is the command for the first
run and for the last one. In between, a fix is applied and checked by lpe2e watch, in seconds.
| Command | What it does | When |
|---|---|---|
(none), all | build if needed, start, inventory, crawl, smoke, suites, perf, report, visual review, stop | first and last run |
watch | the hot loop on a running bench (KEEP=1 lpe2e first): a web file or a test page of e2e/harness/site/webapp is served at once, a Java method body is redefined in the running JVM, anything else (bundles included) packages the jar and webapp zip again and restarts the JVM; then the tests the change can break (a changed scenario file: its scenarios), then every suite | while fixing |
selftest | proves on a running bench that watch misses no bug: a baseline verdict, then a template bug and a Java bug injected through watch's own path right after a render, each required red, reverted and required green; the sources are restored; SELFTEST PASSED or exit 1 | after changing the hot loop, or before trusting it on a new project |
build | packages the artefact and lays out the bench site (the assembled site is cached) | after a source change, to work step by step |
up | builds when the sources changed, starts the bench on a fresh database, waits for the application, seeds | to work step by step |
inventory | reads the sources: every screen, action, right and REST endpoint | to see what there is to cover |
discover | crawls the running site and completes the inventory | after up |
test | every suite against the running bench | after up |
test <pytest args> | one pytest call, e.g. test /bench/tests/test_scenarios.py -k <id> (seconds) | while writing a scenario |
perf | server timings, SQL digests; E2E_JFR=1 adds the JFR hot methods | after the suites |
report | rebuilds summary.md and report.html from the artefacts already there | free, anytime |
review | the screen-by-screen visual gate | before handing over |
key | the key a green run stamps (artifacts/pass-*): sources, configuration, bench code, the local repository copies of the Lutece jars the bench site carries (no other artefact or version) | read by final-gate.sh |
logs, status, port, sh, py | the application log, the containers, the host port, a shell, a script in the runner | while diagnosing |
upgrade | the previous version's database taken over by the bench site, then the suites on it (reference/upgrade.md) | a migration or an update, before handing over |
down | removes the bench's containers and database; the shared server stays for the other benches | when done |
PHASE 1 — Write the bench configuration (1 minute)
bash ${LUTECEPOWERS_ROOT}/skills/lutece-e2e/scripts/init-e2e.sh <project-dir>
It writes e2e/e2e.conf, the scenario skeletons, the fixtures, harness/app.env and harness/server-errors-allow.txt,
and adds e2e/ to the project's .gitignore; no bench code is copied. Then edit e2e/e2e.conf:
E2E_PLUGINSextra artefacts to assemble (groupId:artifactId, comma-separated; a version only to pin one) — the plugin's runtime dependencies that are not pulled transitively (workflow, genericattributes…).E2E_ENABLEplugin names to mark installed inplugins.dat(v8 default is not installed).
No port, no container name, no version to choose: the shared server gives the bench its own database and host port
(lpe2e port), and the site takes the latest Lutece 8 snapshots.
Front-office authentication comes with the bench. plugin-mylutece and module-mylutece-database are
assembled and enabled by default (E2E_MYLUTECE=1; the v7 site of upgrade gets the last v7 releases), the plugin's own mylutece.properties turns authentication on without making the
site private, and harness/db/post-init-mylutece.sql seeds the account test / testtest (role e2e_user).
A scenario signs in with one step, login_fo: {user: test, password: testtest, provider: mylutece-database}
(it fails when the login form is still there afterwards), under anonymous: true. A bench that needs another
version names it in E2E_PLUGINS and keeps it; E2E_MYLUTECE=0 leaves authentication out. The module brings its own
XPage page=mylutecedatabase, which answers its "access denied" site message to an anonymous visitor: declare it
under skip with that reason, it is the module's behaviour and not the artefact's.
The oracle is positive, and it is tested first
tests/lutece.py::classify says what the browser shows from the DOM: screen (admin menu bar present,
no error wording), confirmation, error, warning, info, auth (session lost), login, error-page,
fo, fragment, http-NNN. A screen test passes only when the kind matches what that screen must show.
tests/test_harness.py checks the classifier on a real screen, a confirmation, a lost session, a login form
and a 404 before anything else; when it fails no other suite runs and lpe2e ends with code 3. Never weaken it: the absence of an
error marker is not a success — "please authenticate" and "Internal error" render in HTTP 200.
summary.md carries three guardrails to read on every run: the count of kinds among passed tests
(auth or error-page there means the oracle is blind), the duplicate-content alarm (different parametrised
urls, same page text), and the inventory coverage (covered / excluded with a reason / to do). Open at least
three random screenshots in report.html before calling a run green.
PHASE 2 — First run, read the summary (5–8 minutes)
KEEP=1 lpe2e # full run, bench kept up
cat e2e/artifacts/summary.md
lpe2e watch # in the background: every fix applied and tested in seconds
lpe2e test /bench/tests/test_scenarios.py -k <id> # replay one scenario while writing it
lpe2e # once at the end, then the review
lpe2e watch is the loop to fix in: run it in the background and follow its lines as events. Each batch of changes
prints how it was applied (a template or a test page served at once, a method body redefined in the running JVM, or
the jar and webapp zip packaged again and the JVM restarted), the tests related to the change (the JSP screens, test
pages included, or the front-office application that reach it; the scenarios of a changed scenario file; the
scenarios when no test is named after the change) with their verdict, then the verdict of every suite. A compile
error is printed and nothing runs until the next save. watch holds the bench only while the tests of a batch run:
lpe2e test works beside it, and a batch saved during such a run is applied, its tests left to that run. The classes watch keeps for a Java change stay in the bench site until the jar is packaged again: the next
lpe2e up packages it first, so the bench starts on the current sources.
lpe2e selftest proves that loop on the project: it breaks a template the first front-office XPage cites (else the
manage template of the first JspBean), then that class's display method, through the same hot path, and requires each
bug red and each revert green against the failures already there. One SELFTEST line per step, then SELFTEST PASSED or SELFTEST FAILED (exit 1).
Never a full run per fix. A green run leaves the key of what it judged (artifacts/pass-all, lpe2e key), and
final-gate.sh reuses it instead of playing it again. Benches on one machine share its cores: run one at a time.
Read in this order: the suite table, the failures, the console section, the server errors, the slowest
paths. A failing test is a finding, not a harness bug, until proven otherwise: the core itself shows
JSP that no longer compile, JS errors, dead links, a CSRF token missing on a confirmation form. Before
touching the harness, confirm the cause in artifacts/logs/messages.log (stack traces) and in the
screenshot referenced by the failure (artifacts/report.html).
Harness-side causes (fix them in the bench, not in the app):
- a screen needs a parameter the crawl did not find → a
paramsrule inscenarios/screens.yaml, or a seed row; - a form needs a value the generic filler cannot guess →
values:in afill_formstep; - a scenario logs out or changes the password →
isolated: true; - a session-less public screen → it is already routed to the anonymous context (
SESSIONLESS).
PHASE 3 — Scenarios (the only code the agent writes)
Mechanical rule, enforced at collection: every mutation (submit, submit_novalidate, confirm,
confirm_if, a click on a Do*/action control) must be followed, within the next three steps, by a state
oracle — sql (expect, not_expect, expect_var, not_expect_var, min), expect_dom, mail, fake_log,
http, download, and js with expect/contains for what a client-side script did. expect_text, expect_message, expect_kind and expect_html read the screen that
followed, not what the application did: alone after a mutation they are a weak oracle and the scenario is
rejected. A refusal is written expect_message: error then sql counting that nothing was created.
expect_text on a url or a JSP name is rejected too (assert on what the page says, not where it is), and
sql_exec is never allowed between a mutation and its state oracle. "The next screen
looked normal" (expect_ok) is navigation, not proof. Prefer deterministic values (a named group, a fixed
column) so the oracle can state the expected value; use sql_set before and not_expect_var after when the
value cannot be chosen. State that lives outside the database (a badge, a datastore key) is read where it is.
Coverage counts two things, and only the first is reported as achieved: proven — the pages a passing
oracle stood behind (the navigations since the previous oracle are credited when the next one passes; what
comes after the last oracle is never proven) — and merely reached (a GET by the screens suite, a fuzzed
form, a page a scenario crossed without asserting). Reached but not proven is listed as debt in summary.md.
Flags: isolated: true (own session: logout, own password), anonymous: true (public screens, no session),
serial: true (changes settings shared by every session — security parameters, e-mail pattern, feature groups,
plugin install; run alone after the parallel pass, so it cannot break a user creation running elsewhere).
A screen no link of the application reaches, opened bare because only the inventory names it, is a robustness
finding when it fails without its parameters: listed apart, never a red run. Before calling an "Internal error" on
any other screen a defect, drive the flow the way the interface does (tools/forms.sh, the links of the previous
screen).
The artefact's own actions are the point of the bench, and a run does not end green without them. A plugin
exists for one or two workflows — an import plugin imports files, a form plugin submits a form — and a bench that opens its
listings and stops has proved the menu, not the plugin. lpe2e all fails with rc=9 while an action of the
artefact (Do*, an MVC action=, an upload endpoint) is neither proven by a green scenario, tested red, nor
excluded with a written reason; COVERAGE=skip bypasses it to iterate, never to hand over. Start the scenarios
from the artefact's main workflow, played end to end the way a user plays it (upload a real file from
fixtures/, submit the wizard, read the created rows), before the CRUD of its settings screens.
Work the "à couvrir" list of summary.md down to zero: every inventory element ends up covered by a test, or
listed in scenarios/coverage-exclusions.yaml with a written reason (a defect found by the suites, a plugin
not on the bench, a dead template). Exclusions stay visible in the report as debt; they never lower the totals. A defect of the artefact itself is never an exclusion, in coverage-exclusions.yaml or under skip in screens.yaml: a screen that dies on load ("jQuery is not defined") is opened and fails red, and the defect is fixed or reported, not written down as a reason to look away. lpe2e report prints the to-do list; artifacts/causes.json holds the server exception behind each failure;
bash ${LUTECEPOWERS_ROOT}/skills/lutece-e2e/tools/forms.sh <src> <feature> prints the forms and field names of a
feature's templates. When a real defect blocks the middle of a lifecycle, split the scenario
so the actions after the defect stay covered. sql_exec arranges data the UI cannot create (a broken create screen), never asserts.
One YAML per feature in e2e/scenarios/. Aim for one CRUD lifecycle per admin feature of the artefact
(create through the real form → read back on the listing → modify → remove), with the database as the
oracle. The step vocabulary is documented at the top of tests/test_scenarios.py; artifacts/inventory.md lists
the features, screens and actions.
Rules:
req:= the Lutece right of the feature (CORE_USERS_MANAGEMENT…), shown with the scenario inreport.html.title:is what the report shows in place of the id,description:(optional) the paragraph under it: why this scenario exists, what defect it pins, what a reader should know before the steps. Write it as a>-block — a bare scalar containing:is not valid YAML and silently invalidates the whole file.- Never assert on wording that comes from i18n when a
sql:check is possible. - A list rendered by
@manageFeatureis cards, not a table: its oracle is.row-cards li(rows) and.empty(no row), nevertable tbody tr, which silently counts zero after a list migration. - Confirmation screens:
expect_message: confirmationthenconfirm:; refusals:expect_message: error. - Keep
{{rand}}in every created key so scenarios are re-runnable and parallel-safe.
PHASE 3b — Negative scenarios (mandatory)
A <artefact>-negative.yaml file must exist, covering what this artefact must refuse: a mutation called
without its CSRF token refused and the row unchanged, one duplicate-key refusal and one empty-mandatory-field
refusal per main entity (submit_novalidate bypasses the HTML5 check to reach the server-side validation), and an
unknown-id call answered gracefully. If the artefact enforces rights of its own, add a restricted account in this
bench's own harness/db/seed-<target>.sql and prove the refusal with it — the generic harness seeds no such
account, because who is restricted from what is a property of the target. templates/scenarios-negative-example.yaml
is the model.
A defect of the core the plugin must not work around (an @Action the core runs on GET without its token) is
proven by its scenario with core_defect: "<the defect>": the report lists it under the core defects not handled
and the run stays green; never add a guard in the plugin to turn it green.
The CSRF one is not waivable, and "the platform does not protect this path" is not a reason to skip it. It is
a reason to write it: a legacy path outside the automatic filter is exactly where the hole lives. A portlet
JspBean is the known case — the plugin closes it itself (lutece-update-plugin,
patterns/mvc-patterns.md §11). Cover every mutation, including the ones reached by a link: a delete behind
<a href="…Do…?id=1"> is a GET that writes.
Drive mutations through the real form, never a forged URL. goto: …DoSomething.jsp?a=1&b=2 is convenient and
it stops proving anything the day the action becomes token-protected: the call is refused, and a scenario whose
only oracle is expect_message: error stays green while the behaviour it claimed to test is never reached. Open
the screen, fill, submit the form — that is the user's path, and it is the one that carries the token. Keep
goto for what has no form: an unknown id, a missing parameter, a call without a token.
PHASE 4 — Volume and bottlenecks
The perf step of every run writes artifacts/perf.json (server timings, SQL digests), which the server-error gate
reads.
E2E_VOLUME=large E2E_JFR=1 KEEP=1 lpe2e
The generic harness seeds nothing. Bottlenecks are hunted in the tables the artefact under test actually
reads, so the agent writes harness/db/seed-<target>.sql for them — a core fills core_page/core_admin_user,
a FAQ plugin fills its questions and subjects. seed.sh applies every seed-*.sql of the bench and exposes
@users/@groups/@roles/@lists/@pages sized by E2E_VOLUME (none by default, small, large) so a
generated seed can scale itself; reference/seed-volume-example.sql shows the technique (MariaDB SEQUENCE engine,
idempotent marker row). Then read, in summary.md: server p95 per path, SQL digests with no_index and
rows_examined, JFR hot methods, pool wait. A listing screen that slows with
volume plus a digest reading the whole table = the bottleneck to report (paginate in SQL, add the index).
PHASE 4b — Visual review, screen by screen (mandatory)
The suites prove behaviour and lutece.render_check catches what a machine can see. Neither judges the
look. A screen can pass every assertion and still show an unresolved icon, an internal id in a badge, an
untranslated label, a fragment with no design system applied. Only eyes catch those, so the run does not end
until the agent has looked at every screen.
lpe2e all runs tools/review.py todo, which deduplicates the captures into groups — one group per
(url path, DOM kind), whatever the data. Every capture enters it: the crawl's, each screen a scenario step reached
(a form, a confirmation, a list holding the data the scenario created, an error message: where the rendering defects
hide, a raw Optional[…] date or an empty form card) and each explicit shot: step (the way to get a screen only a
signed-in user reaches, such as a front-office page behind a login) — and writes
artifacts/review-todo.md. The gate then calls
tools/review.py check and fails with rc=7 until artifacts/review.md carries a verdict for every group.
REVIEW=skip lpe2e all bypasses it; use that only to iterate, never to hand over. The first full run ends rc=7:
the review is written after it, on its captures, and lpe2e review then gives rc=0 and marks that run as passed:
never run the bench again only for the review. The review stays valid for every later run of the same sources, and
while its captures are unchanged. The failure capture of a core_defect scenario is not a group.
How the agent does it:
- Open the representative capture of every group with the Read tool. Not a sample, not the flagged ones only: a defect that a mechanical check could see would already have been reported.
- Judge against the five points printed in
review-todo.md: charte, mise en page, contenu, cohérence, lisibilité. - Write the
key:andshots:linesreview-todo.mdprints at the top ofartifacts/review.md, then one line per group:- [x] G012 okor- [x] G012 defect: …, then a short synthesis ordering the plugin's own defects by impact. The gate refuses a review written for other sources: once a file changes, the screens must be judged again. - Attribute, exactly like the server-error gate. A broken footer image or a mislabelled core dialog belongs to the site theme or the core, not to the artefact under test. Say so in the verdict and keep it out of the synthesis.
Before naming a rendering defect, check its cause in the source: how to do that, and the two groups this step exposes, are in reference/traps.md § Naming a rendering defect.
PHASE 5 — Freeze and hand over
baselines/aria/is seeded from the first run at delivery scope (lpe2e reportcopies the aria snapshots when it is empty andE2E_SCOPEis notall), so later runs on the same workstation diff against it. The visual review (review.py) judges the artefact's own screen families; a widened run's core screens are the environment's and are not listed.artifacts/fingerprint.json(also on the first line ofsummary.md) names what was tested: sources commit, source key (tools/source-key.py, the same for two builds of the same sources), image digests — a green run with no fingerprint is a green run of nothing in particular.- A skip is not a proof. A suite with something to prove (the fo suite when the inventory has a front-office
page of the artefact, the scenarios, the screens) whose every test is skipped fails the run with code 8. A JSP under
jsp/site/withoutpage=orpage_id=(a JSON endpoint, aDo…action) is not a page of the fo suite: the scenarios that call it prove it, and the coverage gate asks for them. An exclusion the bench declared and justified is not that silence: when every skip of the suite comes from a rule written inscenarios/screens.yamlor from a scenario'sversions, the run stays green and the summary names the reason.
Lutece 8 ElasticData DataSource Module
Before implementing a DataSource, consult
~/.lutece-references/lutece-form-module-elasticdata-forms/— the reference implementation. The framework plugin is at~/.lutece-references/lutece-elk-plugin-elasticdata/and the HTTP client library at~/.lutece-references/lutece-elk-library-elastic/.
Architecture Overview
library-elastic (HTTP/JSON wrapper around Elasticsearch REST API)
↑ used by
plugin-elasticdata (framework — already deployed)
↓ auto-discovers via CDI
module-myentity-elasticdata (@ApplicationScoped DataSource)
↓ produces
MyEntityDataObject (extends AbstractDataObject)
↓ indexed by two daemons
FullIndexingDaemon (daily, bulk reindex)
IncrementalIndexingDaemon (interval `daemon.incrementalIndexingDaemon.interval`, processes IndexerAction queue)
Incremental path:
Entity CRUD → CDI event fired
↓ observed by
MyEntityIndexerEventListener (@Observes or @ObservesAsync, as the event is fired)
↓ calls
DataSourceIncrementalService.addTask(dataSourceId, entityId, taskType)
↓ queues in DB → daemon processes
A module provides a DataSource implementation. The plugin-elasticdata framework handles Elasticsearch communication, daemon scheduling, batch processing, and action queue management.
CDI auto-discovery — any @ApplicationScoped class implementing DataSource is automatically registered:
// Inside DataSourceService (plugin-elasticdata)
CDI.current( ).select( DataSource.class ).stream( )
.forEach( source -> _mapDataSources.put( source.getId( ), source ) );
Three-layer architecture:
- library-elastic — Low-level HTTP client (uses
library-httpaccess, not the official ES Java client) - plugin-elasticdata — Generic indexing framework (daemons, action queue, bulk API)
- Your module — Domain-specific DataSource and DataObject
Step 1 — Maven Module Setup
<parent>
<groupId>fr.paris.lutece.tools</groupId>
<artifactId>lutece-global-pom</artifactId>
<version>LATEST_RELEASED_8_X</version>
</parent>
<artifactId>module-elasticdata-myentity</artifactId>
<packaging>lutece-plugin</packaging>
<dependencies>
<dependency>
<groupId>fr.paris.lutece.plugins</groupId>
<artifactId>plugin-elasticdata</artifactId>
<version>[3.0.0,)</version>
<type>lutece-plugin</type>
</dependency>
<dependency>
<groupId>fr.paris.lutece.plugins</groupId>
<artifactId>plugin-myentity</artifactId>
<version>[X.0.0,)</version>
<type>lutece-plugin</type>
</dependency>
</dependencies>
Replace LATEST_RELEASED_8_X with the latest released lutece-global-pom 8.x (check the Lutece Maven repository, never hardcode a guess). The module is never its own parent (reference: lutece-form-module-elasticdata-forms/pom.xml).
Step 2 — DataSource Implementation
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
import org.eclipse.microprofile.config.inject.ConfigProperty;
import fr.paris.lutece.plugins.elasticdata.business.AbstractDataSource;
import fr.paris.lutece.plugins.elasticdata.business.DataObject;
@ApplicationScoped
public class MyEntityDataSource extends AbstractDataSource
{
public MyEntityDataSource( )
{
}
@Inject
public MyEntityDataSource(
@ConfigProperty( name = "elasticdata-myentity.dataSource.id" ) String strId,
@ConfigProperty( name = "elasticdata-myentity.dataSource.name" ) String strName,
@ConfigProperty( name = "elasticdata-myentity.dataSource.targetIndexName" ) String strTargetIndex,
@ConfigProperty( name = "elasticdata-myentity.dataSource.mappings" ) String strMappings )
{
setId( strId );
setName( strName );
setTargetIndexName( strTargetIndex );
setMappings( strMappings );
}
// --- Return all entity IDs (for full indexing) ---
@Override
public List<String> getIdDataObjects( )
{
return MyEntityHome.findAllIds( ).stream( )
.map( String::valueOf )
.collect( Collectors.toList( ) );
}
// --- Fetch entities by ID batch (called by BatchDataObjectsIterator) ---
@Override
public List<DataObject> getDataObjects( List<String> listIds )
{
List<Integer> listIntIds = listIds.stream( )
.map( Integer::parseInt )
.collect( Collectors.toList( ) );
List<MyEntity> listEntities = MyEntityHome.findByPrimaryKeyList( listIntIds );
return listEntities.stream( )
.map( this::buildDataObject )
.collect( Collectors.toList( ) );
}
@Override
public boolean isLocalizable( )
{
return false; // true if entities have geo_point fields
}
@Override
public boolean usesFullIndexingDaemon( )
{
return true; // enable daily full reindex via FullIndexingDaemon
}
// --- Build a DataObject from an entity ---
private DataObject buildDataObject( MyEntity entity )
{
// See Step 3
}
// --- Incremental indexing helper ---
public void indexDocument( int nIdEntity, int nIdTask )
{
DataSourceIncrementalService.addTask(
getId( ),
String.valueOf( nIdEntity ),
nIdTask );
}
}
Key points:
- The no-arg constructor is required next to the
@Injectone:@ApplicationScopedbeans are proxied by their concrete class (referenceFormsDataSource.java:116) @ConfigPropertyinjects values from properties file (MicroProfile Config)getIdDataObjects()returns ALL IDs — the framework handles batching viaBatchDataObjectsIteratorgetDataObjects(List)fetches a batch of entities — keep this efficient (single SQL query for the batch)AbstractDataSourceprovidesgetDataObjectsIterator()implementation usingBatchDataObjectsIterator
Step 3 — DataObject Implementation
import com.fasterxml.jackson.annotation.JsonIgnore;
import fr.paris.lutece.plugins.elasticdata.business.AbstractDataObject;
import java.util.HashMap;
import java.util.Map;
public class MyEntityDataObject extends AbstractDataObject
{
// Typed fields (appear as JSON properties in ES document)
private int _nFormId;
private String _strEntityName;
private String _strStatus;
private String _strWorkflowState;
// Dynamic fields (flexible key-value map)
private Map<String, Object> _mapUserData = new HashMap<>( );
// --- Required by DataObject ---
@JsonIgnore // ID is used for routing, not indexed as field
@Override
public String getId( )
{
return String.valueOf( _nFormId );
}
@Override
public String getDocumentTypeName( )
{
return "myEntityResponse";
}
// --- Typed getters/setters ---
public int getFormId( )
{
return _nFormId;
}
public void setFormId( int nFormId )
{
_nFormId = nFormId;
}
public String getEntityName( )
{
return _strEntityName;
}
public void setEntityName( String strEntityName )
{
_strEntityName = strEntityName;
}
public String getStatus( )
{
return _strStatus;
}
public void setStatus( String strStatus )
{
_strStatus = strStatus;
}
public String getWorkflowState( )
{
return _strWorkflowState;
}
public void setWorkflowState( String strWorkflowState )
{
_strWorkflowState = strWorkflowState;
}
// --- Dynamic user data (serialized as nested JSON) ---
public Map<String, Object> getUserData( )
{
return _mapUserData;
}
public void setUserData( Map<String, Object> mapUserData )
{
_mapUserData = mapUserData;
}
}
Key points:
AbstractDataObjectprovidesgetTimestamp()with day/week/month extraction for analytics@JsonIgnoreongetId()— the ID is used for ES document routing, not stored as a fieldgetDocumentTypeName()— identifies the document type within the index- Typed fields become JSON properties;
Map<String, Object>allows flexible dynamic attributes - Jackson serializes all public getters to JSON for indexing
Step 4 — CDI Event Listener (Incremental Updates)
The observer follows how the event is sent (CDI 4.0, Observer resolution): fire( ) reaches only @Observes methods, fireAsync( ) only @ObservesAsync methods. An observer of the wrong kind is never called, without any error.
| Event | Sent by | Observer |
|---|---|---|
FormResponseEvent | fireAsync (lutece-form-plugin-forms/src/java/**/service/FormService.java) | @ObservesAsync (lutece-form-module-elasticdata-forms/src/java/**/FormResponseIndexerEventListener.java) |
ResourceEvent of the workflow | fire (lutece-core/src/java/fr/paris/lutece/portal/service/workflow/WorkflowService.java, registerResourceEvent) | @Observes (lutece-search-plugin-solr/src/java/**/SolrEventRessourceListener.java) |
Read how the entity's events are sent before writing the listener. The example below observes an event its own service sends with fireAsync:
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.enterprise.event.ObservesAsync;
import jakarta.inject.Inject;
import fr.paris.lutece.plugins.elasticdata.business.IndexerAction;
import fr.paris.lutece.plugins.myentity.business.MyEntityEvent;
@ApplicationScoped
public class MyEntityIndexerEventListener
{
@Inject
private MyEntityDataSource _dataSource;
public void onEntityCreated(
@ObservesAsync @Type( EventAction.CREATE ) MyEntityEvent event )
{
_dataSource.indexDocument( event.getEntityId( ), IndexerAction.TASK_CREATE );
}
public void onEntityUpdated(
@ObservesAsync @Type( EventAction.UPDATE ) MyEntityEvent event )
{
_dataSource.indexDocument( event.getEntityId( ), IndexerAction.TASK_CREATE );
}
public void onEntityDeleted(
@ObservesAsync @Type( EventAction.REMOVE ) MyEntityEvent event )
{
_dataSource.deleteDocument( event.getEntityId( ) );
}
}
Fire events from your Service layer — select the @Type qualifier to match the observer:
import fr.paris.lutece.portal.service.event.EventAction;
import fr.paris.lutece.portal.service.event.Type.TypeQualifier;
@Inject
private Event<MyEntityEvent> _entityEvent;
public MyEntity create( MyEntity entity )
{
MyEntityHome.create( entity );
_entityEvent.select( new TypeQualifier( EventAction.CREATE ) )
.fireAsync( new MyEntityEvent( entity.getId( ) ) );
return entity;
}
public void remove( int nIdEntity )
{
MyEntityHome.remove( nIdEntity );
_entityEvent.select( new TypeQualifier( EventAction.REMOVE ) )
.fireAsync( new MyEntityEvent( nIdEntity ) );
}
Task types:
IndexerAction.TASK_CREATE(1) — Index new document (also used for updates)IndexerAction.TASK_MODIFY(2) — Partial updateIndexerAction.TASK_DELETE(3) — Delete by query
The IncrementalIndexingDaemon processes the queue on the interval set by daemon.incrementalIndexingDaemon.interval (seconds; plugin-elasticdata ships 3000, and daemon.fullIndexingDaemon.interval=86400).
addTask keeps one task per resource. A DELETE on a pending CREATE removes the CREATE and queues nothing
(DataSourceIncrementalService.addTask): a document indexed before stays in the index until the next full indexing.
Queue the deletion twice: the first call cancels the CREATE, the second queues the DELETE (a DELETE on a pending
DELETE is ignored).
public void deleteDocument( int nIdEntity )
{
indexDocument( nIdEntity, IndexerAction.TASK_DELETE );
indexDocument( nIdEntity, IndexerAction.TASK_DELETE );
}
When the entity's plugin fires no event
Every write that changes an indexed field needs an event, counters included (votes, comments, views): without one, the
field is refreshed only by the full indexing. The events a plugin already sends for its search indexer
(ResourceEvent for Lucene or Solr) follow the published state: a REMOVE there can mean "unpublished", and a
non-published entity sends nothing. Do not build the index on them.
Add a typed event to the entity's plugin, fired from the service every write goes through, as forms does
(lutece-form-plugin-forms/src/java/**/service/FormService.java):
- an event class carrying the ids (
FormResponseEvent), inservice/event/; @Inject Event<MyEntityEvent>in the@ApplicationScopedservice,select( new TypeQualifier( action ) ).fireAsync( … )after the write, CREATE / UPDATE / REMOVE;fireAsyncthrowsRejectedExecutionExceptionwhile the server stops: catch it and fire again withNotificationOptions.ofExecutor( Runnable::run )(FormService.fireAsync).
A workflow action reaches the module without any change in the plugin: the core fires a ResourceEvent UPDATE whose
getTypeResource( ) is the workflow resource type (@Observes, filter on the type).
Step 5 — Elasticsearch Mappings
Provide custom mappings via @ConfigProperty or override getMappings():
{
"mappings": {
"properties": {
"timestamp": {
"type": "date",
"format": "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis"
},
"entityName": {
"type": "text",
"fields": { "keyword": { "type": "keyword" } }
},
"status": {
"type": "keyword"
},
"workflowState": {
"type": "keyword"
}
}
}
}
Default mappings from DataSourceUtils:
TIMESTAMP_MAPPINGS— timestamp field onlyTIMESTAMP_AND_LOCATION_MAPPINGS— timestamp +geo_pointfor spatial data
Use custom mappings when you need keyword fields for aggregations, specific analyzers, or nested objects.
Step 6 — Configuration Properties
# elasticdata-myentity.properties (MicroProfile Config)
# DataSource identity (injected via @ConfigProperty)
elasticdata-myentity.dataSource.id=MyEntityDataSource
elasticdata-myentity.dataSource.name=My Entity Data Source
elasticdata-myentity.dataSource.targetIndexName=myentity
elasticdata-myentity.dataSource.mappings={"mappings":{"properties":{"timestamp":{"type":"date","format":"yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis"}}}}
The Elasticsearch server connection is configured at the plugin-elasticdata level (not in your module):
# Already in plugin-elasticdata config (do NOT duplicate)
elasticdata.elastic_server.url=http://localhost:9200
elasticdata.elastic_server.login=
elasticdata.elastic_server.pwd=
elasticdata.bulk_batch_size=10000
Step 7 — plugin.xml
<plug-in>
<name>myentity-elasticdata</name>
<class>fr.paris.lutece.portal.service.plugin.PluginDefaultImplementation</class>
<version>1.0.0-SNAPSHOT</version>
<description>module.myentity.elasticdata.module.description</description>
<core-version-dependency>
<min-core-version>8.0.0</min-core-version>
<max-core-version/>
</core-version-dependency>
<db-pool-required>0</db-pool-required>
</plug-in>
<description> is an i18n key: module.description=ElasticData module for MyEntity plugin in the module bundle (rules/plugin-descriptor.md).
No daemons or admin features needed — the plugin-elasticdata framework provides them.
IDataSourceExternalAttributesProvider (Advanced)
Enrich data objects from other modules with additional attributes:
@ApplicationScoped
public class MyAttributeProvider implements IDataSourceExternalAttributesProvider
{
public void provideAttributes( DataObject dataObject )
{
// Enrich a single object
}
public void provideAttributes( List<DataObject> listDataObject )
{
// Batch enrichment (preferred for performance)
for ( DataObject obj : listDataObject )
{
// Add external attributes
}
}
}
plugin-elasticdata does not discover providers: DataSourceService calls those the data source returns from getExternalAttributesProvider( ), an empty list in AbstractDataSource unless the data source fills it with setExternalAttributesProvider( ). They are called from completeDataObjectWithFullData, on full and incremental indexing (DataSourceService, DataSourceIncrementalService).
Indexing Lifecycle
| Mode | Daemon | Interval | Trigger | What happens |
|---|---|---|---|---|
| Full | FullIndexingDaemon | daemon.fullIndexingDaemon.interval (shipped: 86400 s) | Admin button or daemon schedule | Delete index → recreate with mappings → bulk index all DataObjects |
| Incremental | IncrementalIndexingDaemon | daemon.incrementalIndexingDaemon.interval (shipped: 3000 s) | CDI events → DataSourceIncrementalService.addTask() | Process IndexerAction queue (create/update/delete) |
Transaction safety: Incremental indexing wraps ES operations + DB task removal in a single transaction. If ES fails, the task remains in queue for retry.
Verify on a bench
E2E_SEARCH=1 in e2e.conf starts a real Elasticsearch beside the application (skill lutece-e2e,
reference/external-systems.md). Then, for each write the module must follow (create, update, each counter, remove):
- do the write through the screens;
- read the queue:
jsp/admin/plugins/elasticdata/ManageElasticData.jsp?view=manageIndexerActionslists one task per resource (1create,3delete); - run "Indexation incrémentale" on
ManageElasticData.jsp, then read the document back:curl localhost:9200/<targetIndexName>/_doc/<lutece.name>_<dataSourceId>_<id>(the id isDataSourceService.getIdDocument); a removed entity answers 404.
An empty queue after a write is a missing event; a document unchanged after the incremental run is a field the DataSource does not read.
File Checklist
| File | What to create |
|---|---|
pom.xml | Maven module with plugin-elasticdata dependency |
MyEntityDataSource.java | @ApplicationScoped extending AbstractDataSource, @ConfigProperty constructor |
MyEntityDataObject.java | Extends AbstractDataObject, typed fields + Map<String,Object> |
MyEntityIndexerEventListener.java | CDI listener, @Observes or @ObservesAsync as the event is fired; DELETE queued twice |
elasticdata-myentity.properties | @ConfigProperty values (id, name, index, mappings) |
WEB-INF/plugins/myentity-elasticdata.xml | plugin.xml descriptor |
src/main/resources/META-INF/beans.xml | CDI descriptor (empty <beans> tag) |
No daemon, no DAO, no SQL table needed — plugin-elasticdata provides all infrastructure.
Reference Sources
| Need | File to consult |
|---|---|
| DataSource interface | ~/.lutece-references/lutece-elk-plugin-elasticdata/src/java/**/business/DataSource.java |
| AbstractDataSource (batch iterator) | ~/.lutece-references/lutece-elk-plugin-elasticdata/src/java/**/business/AbstractDataSource.java |
| DataObject interface | ~/.lutece-references/lutece-elk-plugin-elasticdata/src/java/**/business/DataObject.java |
| AbstractDataObject (timestamp) | ~/.lutece-references/lutece-elk-plugin-elasticdata/src/java/**/business/AbstractDataObject.java |
| DataSourceService (CDI discovery) | ~/.lutece-references/lutece-elk-plugin-elasticdata/src/java/**/service/DataSourceService.java |
| Incremental service (addTask) | ~/.lutece-references/lutece-elk-plugin-elasticdata/src/java/**/service/DataSourceIncrementalService.java |
| Complete DataSource (forms) | ~/.lutece-references/lutece-form-module-elasticdata-forms/src/java/**/FormsDataSource.java |
| DataObject example (forms) | ~/.lutece-references/lutece-form-module-elasticdata-forms/src/java/**/FormResponseDataObject.java |
| CDI event listener (forms) | ~/.lutece-references/lutece-form-module-elasticdata-forms/src/java/**/FormResponseIndexerEventListener.java |
| Elastic HTTP client | ~/.lutece-references/lutece-elk-library-elastic/src/java/**/util/Elastic.java |
| Default mappings | ~/.lutece-references/lutece-elk-plugin-elasticdata/src/java/**/service/DataSourceUtils.java |
Lutece 8 Search Indexer
Before implementing a search indexer, consult
~/.lutece-references/lutece-form-plugin-forms/src/java/fr/paris/lutece/plugins/forms/service/search/— the reference implementation.
Architecture Overview
IMyPluginSearchIndexer (interface)
↑ implements
LuceneMyPluginSearchIndexer (@ApplicationScoped, owns its Lucene index,
runs under a DB lease lock: ILuceneLockManager)
↓ triggered by
MyPluginSearchDaemon (declared in plugin.xml, interval from daemon.<id>.interval)
↓ fed by
EventListener (@ObservesAsync domain events → queues IndexerAction)
A plugin manages its own Lucene index independently from the core. This allows custom fields, sorting, filtering and dedicated search UI in the back-office.
Two constraints come from the forms reference and from the cluster rules (lutece-scalability-v8 distributed-lock.md):
- The index lives outside the webapp, on a path every node can mount (
indexInWebapp=false, absoluteindexPath).FormsPlugin.warnIfIndexPathIsNodeLocal()logs an error when the path is under the webapp orjava.io.tmpdir. - Full and incremental indexing run under a database lease lock with heartbeat (forms
LuceneLockManagerDB+LockDAO, tableforms_lucene_lock), so a daemon that fires on every node writes the index from one node at a time.
Step 1 — Indexer Interface
public interface IEntitySearchIndexer
{
/**
* Index a single document (queues an action for the daemon)
*/
void indexDocument( int nIdEntity, int nIdTask, Plugin plugin );
/**
* Add an indexer action to the queue
*/
void addIndexerAction( int nIdEntity, int nIdTask, Plugin plugin );
/**
* Process queued actions (called by daemon)
*/
String incrementalIndexing( );
/**
* Rebuild the entire index (called by daemon on flag)
*/
String fullIndexing( );
/**
* Check if index is ready
*/
boolean isIndexerInitialized( );
}
Step 2 — Lucene Indexer Implementation
The class that turns one business object into a Lucene Document and drives the IndexWriter: the full
model, with its imports, its field mapping and its incremental branch, is in
reference/indexer-implementation.md.
Step 3 — Index Factory
Manages index lifecycle (create, open, swap, close):
import jakarta.enterprise.context.ApplicationScoped;
import org.apache.lucene.index.IndexWriter;
import org.apache.lucene.index.IndexWriterConfig;
import org.apache.lucene.store.FSDirectory;
@ApplicationScoped
public class LuceneEntitySearchFactory
{
private static final String PROPERTY_INDEX_PATH = "myplugin.indexer.lucene.indexPath";
private static final String PROPERTY_INDEX_IN_WEBAPP = "myplugin.indexer.lucene.indexInWebapp";
private IndexWriter _writer;
public IndexWriter getIndexWriter( boolean bTemp )
{
Path indexPath = getIndexPath( bTemp );
FSDirectory directory = FSDirectory.open( indexPath );
IndexWriterConfig config = new IndexWriterConfig( new StandardAnalyzer( ) );
_writer = new IndexWriter( directory, config );
return _writer;
}
public void closeWriter( )
{
if ( _writer != null )
{
_writer.close( );
_writer = null;
}
}
/**
* Atomically replace main index with temp index
*/
public void swapIndex( )
{
Path mainPath = getIndexPath( false );
Path tempPath = getIndexPath( true );
Path backupPath = mainPath.resolveSibling( mainPath.getFileName( ) + "_backup" );
// Rename: main → backup, temp → main, delete backup
Files.move( mainPath, backupPath );
Files.move( tempPath, mainPath );
FileUtils.deleteDirectory( backupPath.toFile( ) );
}
public boolean isIndexExists( )
{
return Files.exists( getIndexPath( false ) );
}
private Path getIndexPath( boolean bTemp )
{
String strPath = AppPropertiesService.getProperty( PROPERTY_INDEX_PATH );
boolean bInWebapp = AppPropertiesService.getPropertyBoolean( PROPERTY_INDEX_IN_WEBAPP, false );
Path path;
if ( bInWebapp )
{
path = Paths.get( AppPathService.getWebAppPath( ), strPath );
}
else
{
path = Paths.get( strPath );
}
return bTemp ? path.resolveSibling( path.getFileName( ) + "_tmp" ) : path;
}
}
In MyPlugin.init(), log an error when indexInWebapp is true or indexPath is under java.io.tmpdir (copy FormsPlugin.warnIfIndexPathIsNodeLocal()): both are node-local and produce one diverging index per node.
Step 4 — Daemon
import fr.paris.lutece.portal.service.daemon.Daemon;
import fr.paris.lutece.portal.service.datastore.DatastoreService;
import jakarta.enterprise.inject.spi.CDI;
public class EntitySearchDaemon extends Daemon
{
private static final String DATASTORE_KEY_FULL_INDEX = "myplugin.index.full";
private final IEntitySearchIndexer _indexer = CDI.current( ).select( IEntitySearchIndexer.class ).get( );
@Override
public void run( )
{
if ( !_indexer.isIndexerInitialized( ) )
{
setLastRunLogs( _indexer.fullIndexing( ) );
return;
}
String strFullIndex = DatastoreService.getDataValue( DATASTORE_KEY_FULL_INDEX, DatastoreService.VALUE_FALSE );
if ( DatastoreService.VALUE_TRUE.equals( strFullIndex ) )
{
try
{
setLastRunLogs( _indexer.fullIndexing( ) );
}
finally
{
DatastoreService.setDataValue( DATASTORE_KEY_FULL_INDEX, DatastoreService.VALUE_FALSE );
}
}
else
{
setLastRunLogs( _indexer.incrementalIndexing( ) );
}
}
}
The daemon is instantiated by Class.forName (core DaemonEntry.loadDaemon), never by CDI: no scope annotation, dependencies through CDI.current() (forms FormsSearchIndexerDaemon).
Declare in plugin.xml (no interval element exists in plugin-digester-rules.xml):
<daemons>
<daemon>
<daemon-id>entitySearchDaemon</daemon-id>
<daemon-name>myplugin.daemon.entitySearchDaemon.name</daemon-name>
<daemon-description>myplugin.daemon.entitySearchDaemon.description</daemon-description>
<daemon-class>fr.paris.lutece.plugins.myplugin.service.search.EntitySearchDaemon</daemon-class>
</daemon>
</daemons>
Interval and startup come from properties read by AppDaemonService.registerDaemon (seconds, default 10, then persisted in the datastore):
daemon.entitySearchDaemon.interval=30
daemon.entitySearchDaemon.onstartup=1
Step 5 — CDI Event Listener
import fr.paris.lutece.plugins.myplugin.business.search.IndexerAction;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.enterprise.event.ObservesAsync;
import jakarta.inject.Inject;
@ApplicationScoped
public class EntityIndexerEventListener
{
@Inject
private IEntitySearchIndexer _indexer;
public void onEntityCreated( @ObservesAsync EntityCreatedEvent event )
{
_indexer.addIndexerAction( event.getEntityId( ),
IndexerAction.TASK_CREATE, event.getPlugin( ) );
}
public void onEntityUpdated( @ObservesAsync EntityUpdatedEvent event )
{
_indexer.addIndexerAction( event.getEntityId( ),
IndexerAction.TASK_MODIFY, event.getPlugin( ) );
}
public void onEntityDeleted( @ObservesAsync EntityDeletedEvent event )
{
_indexer.addIndexerAction( event.getEntityId( ),
IndexerAction.TASK_DELETE, event.getPlugin( ) );
}
}
Fire events from Service:
@Inject
private Event<EntityCreatedEvent> _entityCreatedEvent;
public Entity create( Entity entity )
{
EntityHome.create( entity );
_entityCreatedEvent.fireAsync( new EntityCreatedEvent( entity.getId( ), _plugin ) );
return entity;
}
Step 6 — IndexerAction queue and lock tables
The queue entity is plugin-local (business/search/IndexerAction with TASK_CREATE, TASK_MODIFY, TASK_DELETE, getIdDocument(), getIdTask()), like forms' business/form/search/IndexerAction; the core fr.paris.lutece.portal.business.indexeraction.IndexerAction belongs to the core indexer and is not used here.
src/sql/plugins/myplugin/plugin/create_db_myplugin.sql (Liquibase header required, rules/sql-liquibase.md):
-- liquibase formatted sql
-- changeset myplugin:create_db_myplugin.sql
-- preconditions onFail:MARK_RAN onError:WARN
DROP TABLE IF EXISTS myplugin_indexer_action;
CREATE TABLE myplugin_indexer_action (
id_action INT AUTO_INCREMENT,
id_document INT DEFAULT 0 NOT NULL,
id_task INT DEFAULT 0 NOT NULL,
PRIMARY KEY (id_action)
);
CREATE INDEX idx_mia_id_document ON myplugin_indexer_action ( id_document );
DROP TABLE IF EXISTS myplugin_lucene_lock;
CREATE TABLE myplugin_lucene_lock (
index_name VARCHAR(50),
instance_name VARCHAR(50),
is_locked SMALLINT,
date_begin TIMESTAMP NULL,
expired_date TIMESTAMP NULL,
uuid VARCHAR(50),
PRIMARY KEY (index_name)
);
With the corresponding IndexerAction and Lock entities, DAOs and Homes in the business/ package.
Lucene Field Types
| Type | For | Example |
|---|---|---|
StringField | Exact match, stored IDs | UIDs, type codes |
TextField | Full-text search | Title, description, content |
IntPoint | Integer range queries | IntPoint.newExactQuery(field, value) |
LongPoint | Long/date range queries | Timestamps |
NumericDocValuesField | Sorting on numbers | Sort by ID, date |
SortedDocValuesField | Sorting on strings | Sort by title |
StoredField | Store-only (no search) | Display values |
Configuration Properties
# Index location: absolute path on a volume mounted R/W by every node (NFS, PV).
# Never under the webapp nor java.io.tmpdir (node-local, one diverging index per node).
myplugin.indexer.lucene.indexPath=/var/lib/lutece/myplugin/index
myplugin.indexer.lucene.indexInWebapp=false
# Batch size for full reindex
myplugin.indexer.commitSize=100
# Lease lock TTL (ms) held in myplugin_lucene_lock; renewed while indexing runs
myplugin.index.writer.ms.timeout.lock=900000
# Daemon schedule (seconds); read by AppDaemonService, not by plugin.xml
daemon.entitySearchDaemon.interval=30
daemon.entitySearchDaemon.onstartup=1
Datastore flag for full reindex: myplugin.index.full = true triggers full reindex on next daemon run.
File Checklist
| File | What to create |
|---|---|
IEntitySearchIndexer.java | Interface in service/search/ |
LuceneEntitySearchIndexer.java | Implementation @ApplicationScoped |
LuceneEntitySearchFactory.java | Index lifecycle (open, close, swap) |
EntitySearchDaemon.java | Daemon extending Daemon (reflection-instantiated, no CDI scope) |
EntityIndexerEventListener.java | CDI @ObservesAsync listener |
IndexerAction.java + DAO + Home | Queue entity in business/search/ |
ILuceneLockManager.java + LuceneLockManagerDB.java + LockDAO.java | DB lease lock, copied from forms service/lock/ and business/form/lock/ |
create_db_myplugin.sql | Liquibase header + myplugin_indexer_action + myplugin_lucene_lock |
plugin.xml | <daemon> declaration (<daemon-class>, no interval) |
myplugin.properties | Index path outside the webapp, lock TTL, daemon.<id>.interval |
Reference Sources
| Need | File to consult |
|---|---|
| Indexer interface | ~/.lutece-references/lutece-form-plugin-forms/src/java/**/service/search/IFormSearchIndexer.java |
| Lucene implementation | ~/.lutece-references/lutece-form-plugin-forms/src/java/**/service/search/LuceneFormSearchIndexer.java |
| Index factory (swap, lock) | ~/.lutece-references/lutece-form-plugin-forms/src/java/**/service/search/LuceneFormSearchFactory.java |
| Daemon | ~/.lutece-references/lutece-form-plugin-forms/src/java/**/service/search/FormsSearchIndexerDaemon.java |
| Lease lock (interface, DB impl, DAO) | ~/.lutece-references/lutece-form-plugin-forms/src/java/**/service/lock/ and **/business/form/lock/LockDAO.java |
| Node-local index warning | ~/.lutece-references/lutece-form-plugin-forms/src/java/**/service/FormsPlugin.java (warnIfIndexPathIsNodeLocal) |
| Index and daemon properties | ~/.lutece-references/lutece-form-plugin-forms/webapp/WEB-INF/conf/plugins/forms.properties |
| CDI event listener | ~/.lutece-references/lutece-form-plugin-forms/src/java/**/service/listener/FormResponseEventListener.java |
| SearchItem (field names) | ~/.lutece-references/lutece-core/src/java/**/service/search/SearchItem.java |
Lutece 8 — Architecture Patterns
Write each layer like the reference that already does it, read in ~/.lutece-references/ (core, then
lutece-form-plugin-forms for a complete plugin): copy its shape, not a memory of it. The rule of each layer is
loaded with the files it scopes (on another harness, read it before editing). After writing, tools/lutece-check.sh
and tools/verify-file.sh report what a script can see.
JspBean / XPage web: request, validation, templates rules/web-bean.md, rules/jsp-admin.md core ThemeJspBean, forms FormJspBean
Service business logic rules/service-layer.md forms FormService
Home static facade over the DAO rules/dao-patterns.md core RoleHome, forms FormHome
DAO DAOUtil, SQL, try-with-resources rules/dao-patterns.md core RoleDAO, forms FormDAO
Entity POJO rules/java-conventions.md
Never skip a layer. Templates: skills lutece-update-template-bo / -fo. SQL: rules/sql-liquibase.md. Tests:
rules/testing.md.
Entity
Getters and setters only, Serializable with a serialVersionUID. Field prefixes: _str String, _n int, _b
boolean, _date Timestamp, _list collection. Implement RBACResource for permissions, AdminWorkgroupResource for
workgroup filtering, IExtendableResource for the extension system, only when needed.
Daemon
extends Daemon, run( ) ends with setLastRunLogs( … ). Declared in plugin.xml (<daemon-id>, <daemon-name>,
<daemon-description>, <daemon-class>, no interval tag); instantiated by the core through Class.forName, so no CDI
scope and dependencies through CDI.current( ).select( … ). Interval in properties, in seconds:
daemon.<id>.interval=3600, daemon.<id>.onstartup=0. On demand: AppDaemonService.signalDaemon( "<id>" ).
Configuration
@Inject @ConfigProperty( name = "…", defaultValue = "…" )in a CDI bean;AppPropertiesService.getProperty( … )in a static context (Home,static final, non-CDI class). A key shipped empty readsnull.DatastoreService.getInstanceDataValue( key, default )/setInstanceDataValue: a key-value store in the database, read explicitly, not a config source;#dskey{…}in a template.
Events
Fire with CDI.current( ).getBeanManager( ).getEvent( ).fire( … ) or .fireAsync( … ), qualified with
.select( new TypeQualifier( EventAction.CREATE ) ); observe with @Observes / @ObservesAsync. Core resource
events: fr.paris.lutece.portal.business.event.ResourceEvent (getIdResource( ), getTypeResource( )). Several
implementations of one interface: CDI.current( ).select( IProvider.class ).stream( ).
Security, every admin feature
@Controller( right = … ):processControllerchecks it (neverinit( )in the bean or the JSP).securityTokenEnabled = true: the core puts the token in every form and validates every@ActionPOST.securityTokenActionon confirmation views, so the confirm button carries the token of the action.RBACService.getAuthorizedCollection( )when RBAC is on;AdminWorkgroupService.getAuthorizedCollection( )for workgroups.
Lutece 8 RBAC Implementation
Before implementing RBAC, consult
~/.lutece-references/lutece-form-plugin-forms/— specificallyFormsResourceIdService.java,AbstractJspBean.java, andFormJspBean.java. Caveat:FormJspBeanstill uses the deprecatedgetModel(), manualLocalizedPaginatorpagination and manualMARK_TOKENputs although its@ControllerhassecurityTokenEnabled=true; copy its RBAC logic only, and followrules/web-bean.mdfor Models, pagination and CSRF.
Architecture Overview
Entity (implements RBACResource)
↓ getResourceTypeCode() / getResourceId()
ResourceIdService (registers type + permissions)
↓ register() → ResourceTypeManager
plugin.xml (declares <rbac-resource-type-class>)
↓
RBACService.isAuthorized(type, id, permission, user)
↓ checks user roles against RBAC table
JspBean (enforces authorization)
Step 1 — Entity Implements RBACResource
import fr.paris.lutece.portal.service.rbac.RBACResource;
public class Entity implements RBACResource
{
public static final String RESOURCE_TYPE = "MYPLUGIN_ENTITY";
private int _nId;
@Override
public String getResourceTypeCode( )
{
return RESOURCE_TYPE;
}
@Override
public String getResourceId( )
{
return String.valueOf( _nId );
}
}
Rules:
RESOURCE_TYPEis a unique constant — usePLUGINNAME_ENTITYNAMEin uppercasegetResourceId()returns the ID as a String- The entity class must also have its normal fields, getters/setters
Step 2 — ResourceIdService
import fr.paris.lutece.portal.service.rbac.Permission;
import fr.paris.lutece.portal.service.rbac.ResourceIdService;
import fr.paris.lutece.portal.service.rbac.ResourceType;
import fr.paris.lutece.portal.service.rbac.ResourceTypeManager;
public class EntityResourceIdService extends ResourceIdService
{
public static final String PERMISSION_CREATE = "CREATE";
public static final String PERMISSION_MODIFY = "MODIFY";
public static final String PERMISSION_DELETE = "DELETE";
public static final String PERMISSION_VIEW = "VIEW";
private static final String PROPERTY_LABEL_RESOURCE_TYPE = "myplugin.permission.resourceType.entity.label";
private static final String PROPERTY_LABEL_CREATE = "myplugin.permission.resourceType.entity.create";
private static final String PROPERTY_LABEL_MODIFY = "myplugin.permission.resourceType.entity.modify";
private static final String PROPERTY_LABEL_DELETE = "myplugin.permission.resourceType.entity.delete";
private static final String PROPERTY_LABEL_VIEW = "myplugin.permission.resourceType.entity.view";
public EntityResourceIdService( )
{
setPluginName( "myplugin" );
}
@Override
public void register( )
{
ResourceType rt = new ResourceType( );
rt.setResourceIdServiceClass( EntityResourceIdService.class.getName( ) );
rt.setPluginName( getPluginName( ) );
rt.setResourceTypeKey( Entity.RESOURCE_TYPE );
rt.setResourceTypeLabelKey( PROPERTY_LABEL_RESOURCE_TYPE );
Permission permission;
permission = new Permission( );
permission.setPermissionKey( PERMISSION_CREATE );
permission.setPermissionTitleKey( PROPERTY_LABEL_CREATE );
rt.registerPermission( permission );
permission = new Permission( );
permission.setPermissionKey( PERMISSION_MODIFY );
permission.setPermissionTitleKey( PROPERTY_LABEL_MODIFY );
rt.registerPermission( permission );
permission = new Permission( );
permission.setPermissionKey( PERMISSION_DELETE );
permission.setPermissionTitleKey( PROPERTY_LABEL_DELETE );
rt.registerPermission( permission );
permission = new Permission( );
permission.setPermissionKey( PERMISSION_VIEW );
permission.setPermissionTitleKey( PROPERTY_LABEL_VIEW );
rt.registerPermission( permission );
ResourceTypeManager.registerResourceType( rt );
}
@Override
public ReferenceList getResourceIdList( Locale locale )
{
return EntityHome.findReferenceList( );
}
@Override
public String getTitle( String strId, Locale locale )
{
Entity entity = EntityHome.findByPrimaryKey( Integer.parseInt( strId ) );
return ( entity != null ) ? entity.getTitle( ) : "";
}
}
Rules:
- One
ResourceIdServiceper RBAC-protected entity - Permission constants are
public static final— reused in JspBean PROPERTY_LABEL_*keys use the full prefix (plugin name included) because they are Java constants used withI18nServiceregister()creates the ResourceType, registers all permissions, and callsResourceTypeManager.registerResourceType()getResourceIdList()returns all resources for the admin RBAC configuration UIgetTitle()returns a human-readable name for a specific resource
Step 3 — plugin.xml Declaration
<rbac-resource-types>
<rbac-resource-type>
<rbac-resource-type-class>
fr.paris.lutece.plugins.myplugin.service.EntityResourceIdService
</rbac-resource-type-class>
</rbac-resource-type>
</rbac-resource-types>
Add inside <plug-in>, after <admin-features>. One <rbac-resource-type> per ResourceIdService.
Step 4 — i18n (messages.properties)
# RBAC resource type label
permission.resourceType.entity.label=MyPlugin - Entities
# Permission labels
permission.resourceType.entity.create=Create an entity
permission.resourceType.entity.modify=Modify an entity
permission.resourceType.entity.delete=Remove an entity
permission.resourceType.entity.view=View an entity
No prefix in the properties file (prefix is added in Java/templates only).
Step 5 — JspBean Authorization Checks
Check on wildcard (all resources of a type)
// Before allowing access to a CREATE form
User user = getUser( );
if ( !RBACService.isAuthorized( Entity.RESOURCE_TYPE, RBAC.WILDCARD_RESOURCES_ID,
EntityResourceIdService.PERMISSION_CREATE, user ) )
{
throw new AccessDeniedException( "Unauthorized" );
}
Check on a specific resource
// Before allowing MODIFY or DELETE on a specific entity
String strId = request.getParameter( PARAMETER_ID );
Entity entity = EntityHome.findByPrimaryKey( Integer.parseInt( strId ) );
if ( entity == null || !RBACService.isAuthorized( Entity.RESOURCE_TYPE,
String.valueOf( entity.getId( ) ), EntityResourceIdService.PERMISSION_MODIFY, user ) )
{
throw new AccessDeniedException( "Unauthorized" );
}
Pass permissions to template (for conditional display)
// In the manage view — pass permission flags to template (Models model is a method parameter, see rules/web-bean.md)
model.put( "canCreate", RBACService.isAuthorized( Entity.RESOURCE_TYPE,
RBAC.WILDCARD_RESOURCES_ID, EntityResourceIdService.PERMISSION_CREATE, getUser( ) ) );
model.put( "canDelete", RBACService.isAuthorized( Entity.RESOURCE_TYPE,
RBAC.WILDCARD_RESOURCES_ID, EntityResourceIdService.PERMISSION_DELETE, getUser( ) ) );
Template conditional display
<#if canCreate>
<@aButton href='jsp/admin/plugins/myplugin/ManageEntities.jsp?view=createEntity' buttonIcon='plus' title='#i18n{myplugin.manage_entities.buttonAdd}' color='primary' />
</#if>
<#if canDelete>
<@aButton href='jsp/admin/plugins/myplugin/ManageEntities.jsp?view=confirmRemoveEntity&id=${entity.id}' buttonIcon='trash' color='danger' title='#i18n{portal.util.labelDelete}' />
</#if>
Filter collections by permission
// Filter a list to only authorized resources
Collection<Entity> authorizedEntities = RBACService.getAuthorizedCollection(
EntityHome.findAll( ),
EntityResourceIdService.PERMISSION_VIEW,
getUser( )
);
Filter actions per entity (forms pattern)
// Each entity of the current page gets only the actions the user is authorized to perform
_pager.withListItem( EntityHome.findAll( ) ).populateModels( request, model, getLocale( ) );
for ( Entity entity : (List<Entity>) model.get( MARK_LIST ) )
{
List<EntityAction> listAuthorizedActions =
(List<EntityAction>) RBACService.getAuthorizedActionsCollection(
listAllActions, entity, (User) getUser( ) );
entity.setActions( listAuthorizedActions );
}
Requires EntityAction to implement RBACAction (return permission key via getPermission()).
Advanced — Helper Method
CSRF is handled by the core when the @Controller has securityTokenEnabled = true (rules/web-bean.md § CSRF Policy): no SecurityTokenService injection nor validate() in the bean. The helper only checks RBAC:
protected void checkUserPermission( String strResourceType, String strResourceId, String strPermission, HttpServletRequest request )
throws AccessDeniedException
{
if ( !RBACService.isAuthorized( strResourceType, strResourceId, strPermission, (User) AdminUserService.getAdminUser( request ) ) )
{
throw new AccessDeniedException( "Unauthorized" );
}
}
Usage:
@View( VIEW_CREATE_ENTITY )
public String getCreateEntity( HttpServletRequest request ) throws AccessDeniedException
{
checkUserPermission( Entity.RESOURCE_TYPE, RBAC.WILDCARD_RESOURCES_ID, EntityResourceIdService.PERMISSION_CREATE, request );
// ...
}
@Action( ACTION_CREATE_ENTITY )
public String doCreateEntity( HttpServletRequest request ) throws AccessDeniedException
{
checkUserPermission( Entity.RESOURCE_TYPE, RBAC.WILDCARD_RESOURCES_ID, EntityResourceIdService.PERMISSION_CREATE, request );
// ...
}
The forms AbstractJspBean.checkUserPermission( ..., strCsrfAction ) variant that also calls _securityTokenService.validate() is the legacy form; do not copy it into a securityTokenEnabled = true bean.
Advanced — Workgroup Authorization (forms pattern)
Workgroups are an additional authorization layer on top of RBAC. An entity can belong to an admin workgroup, and only users in that workgroup can see it.
import fr.paris.lutece.portal.service.workgroup.AdminWorkgroupService;
// Filter list by workgroup membership
List<Entity> listEntities = EntityHome.findAll( );
listEntities = (List<Entity>) AdminWorkgroupService.getAuthorizedCollection(
listEntities, (User) getUser( ) );
// Check single entity workgroup authorization
if ( !AdminWorkgroupService.isAuthorized( entity, (User) getUser( ) ) )
{
throw new AccessDeniedException( "Unauthorized" );
}
Requires the entity to implement AdminWorkgroupResource:
public interface AdminWorkgroupResource
{
String getWorkgroup( );
}
When to use: When entities need to be partitioned by admin workgroup (e.g., different departments manage different forms).
Wildcard Constants
| Constant | Meaning | Usage |
|---|---|---|
RBAC.WILDCARD_RESOURCES_ID ("*") | All resources of a type | isAuthorized(type, RBAC.WILDCARD_RESOURCES_ID, perm, user) |
RBAC.WILDCARD_PERMISSIONS_KEY ("*") | All permissions | Granted when configuring a role in admin |
Common Permissions
| Permission | Constant | When to check |
|---|---|---|
| CREATE | PERMISSION_CREATE | Before showing create form / processing create action |
| MODIFY | PERMISSION_MODIFY | Before showing modify form / processing modify action |
| DELETE | PERMISSION_DELETE | Before delete confirmation / processing delete action |
| VIEW | PERMISSION_VIEW | Before listing or viewing details |
| PUBLISH | PERMISSION_PUBLISH | Before changing visibility/status |
File Checklist
| File | What to add |
|---|---|
Entity.java | implements RBACResource, RESOURCE_TYPE constant, getResourceTypeCode(), getResourceId() |
EntityResourceIdService.java | New class extending ResourceIdService, permission constants, register() |
plugin.xml | <rbac-resource-type> with <rbac-resource-type-class> |
messages.properties | permission.resourceType.entity.label + one key per permission |
EntityJspBean.java | RBACService.isAuthorized() calls, AccessDeniedException throws, permission flags in model |
| Templates | <#if canXxx> conditionals around protected buttons/links |
Reference Sources
Forms plugin (RBAC + workgroups)
| Need | File to consult |
|---|---|
| ResourceIdService (fine-grained, 13 perms) | ~/.lutece-references/lutece-form-plugin-forms/src/java/**/service/FormsResourceIdService.java |
| checkUserPermission() helper (legacy CSRF part, see caveat above) | ~/.lutece-references/lutece-form-plugin-forms/src/java/**/web/admin/AbstractJspBean.java |
| Workgroup + RBAC combined | ~/.lutece-references/lutece-form-plugin-forms/src/java/**/web/admin/FormJspBean.java |
| Action filtering per entity | ~/.lutece-references/lutece-form-plugin-forms/src/java/**/web/admin/FormJspBean.java (getManageForms) |
| Multiple resource types | ~/.lutece-references/lutece-form-plugin-forms/webapp/WEB-INF/plugins/forms.xml |
Core
| Need | File to consult |
|---|---|
| RBACService | ~/.lutece-references/lutece-core/src/java/**/service/rbac/RBACService.java |
| ResourceIdService abstract class | ~/.lutece-references/lutece-core/src/java/**/service/rbac/ResourceIdService.java |
| ResourceTypeManager | ~/.lutece-references/lutece-core/src/java/**/service/rbac/ResourceTypeManager.java |
| AdminWorkgroupService | ~/.lutece-references/lutece-core/src/java/**/service/workgroup/AdminWorkgroupService.java |
Lutece Scalability v8 — Consolidate & Prove (Agent Teams)
Purpose
Takes a v8-compliant Lutece plugin and makes it scalable for multi-instance/cluster deployment, then proves it empirically in a real 3-instance cluster.
Unlike migration (largely mechanical), scalability is mostly semantic — it needs judgment. So this skill is: scan (detect) → triage (drop false positives) → reproduce (observe each real defect — RED) → fix (intelligent teammates + patterns) → PROVE (same reproduction, now GREEN, in the real cluster). The empirical red→green loop is the heart of the skill: a scanner finding is never a bug until it has been observed failing, and a fix is never "done" until that same observation turns green.
Prerequisites: subagent or teammate dispatch, or the sequential fallback (using-lutecepowers, section Subagents and teams). Also required: Docker + Compose; JDK 17 or later; Maven 3.9.x (not 4); access to the Lutece Maven repos (or a populated ~/.m2).
The 6 scalability axes are documented under patterns/. Reference-first rule: using-lutecepowers, Mandatory reads.
PHASE A — Scan (Lead executes directly)
A.0 — Verify v8 compliance (FIRST)
Check that the plugin is already v8-compliant:
bash ${LUTECEPOWERS_ROOT}/tools/check-v8-floor.sh .
mvn -B clean verify -DskipTests
If check-v8-floor.sh exits 1, stop: the plugin is below the Lutece 8 level lutecepowers supports; raise its lutece-core and parent as the message says. If the build FAILS, stop. Ask the user: "The plugin does not build on v8. Please run lutece-update-plugin first, then re-run this skill." — scalability work cannot begin until migration is complete and the code compiles.
If the build SUCCEEDS, proceed to A.1.
A.1 — Scope the analysis (ASK the user)
Scalability defects often live in a plugin's modules or related plugins, not the core repo — and the highest-risk one (a reminder/notification daemon that would fire once per node) typically sits in a module. But those modules/dependents may be in separate repositories, possibly across different hosts/orgs (GitHub lutece-platform, lutece-secteur-public, an internal GitLab, …). The agent cannot reliably discover them and must NOT guess from a naming convention or assume they are local.
So, before scanning, ask the user: "Should the analysis cover only this plugin, or also its modules / related plugins? If so, where are they (local paths, or repos to clone)?" Then scan each confirmed target with scan-scalability.sh <dir> and aggregate the results. If the user says "this plugin only", proceed — but state in the final report that modules were out of scope.
A.2 — Run the scanner (on EACH target from A.1)
mkdir -p .scalability
# the plugin itself:
bash ${LUTECEPOWERS_ROOT}/skills/lutece-scalability-v8/scripts/scan-scalability.sh . > .scalability/scan.json
# and one file per additional module/related repo the user confirmed in A.1:
# bash .../scan-scalability.sh <module-dir> > .scalability/scan-<module>.json
A.3 — Show the summary
Read .scalability/scan.json and present, per axis, the count + sample files. Flag the high-risk axes:
1-locks/1-id— contended resource (slot, quota, stock). Highest priority. Pick the primitive by the data model: counter column → atomic CAS UPDATE (preferred, lock-free);COUNT(*)→ DB distributed lock. Don't lock by default (patterns/distributed-lock.md).3-singleton/3-cdi-static— mutable static state diverging across nodes.2-session/2-nonserial— non-serializable / heavy session state,Future/Timerin session.2-sessionscoped— stateful@SessionScoped/@ConversationScopedbeans: whole graphSerializable+ passivation test, and the cluster MUST run LibertywriteContents="GET_AND_SET_ATTRIBUTES"— the default does not replicate in-place bean mutations, invisible until a node switch (patterns/serialization-session.md).4-cache— JVM-local cache.4-cache-contract— JCache services: cached values modified by their callers, untyped caches, incomplete keys, missing or global resets, iteration of the cache, removals skipped when the local cache is disabled, a cache enabled at startup over the saved status (patterns/cache-distributed.md).5-config/6-streams/6-threadlocal— hardcoded config, container streams, thread-locals.
A finding count is a review pointer, not an auto-fix list — scalability fixes require judgment.
PHASE A.4 — Triage & empirical confirmation (RED-before-fix) — Lead executes directly
The scanner over-reports. Most findings are false positives. Never plan a fix on a raw count. For every finding, first read the real code and assign a verdict; then, for each genuine defect, observe it failing before anyone touches it. No fix on an unobserved bug.
A.4.1 — Triage: drop false positives (with a stated reason)
Common false positives — classify and discard, recording the reason in the report:
| Axis | Looks like | Why it is usually a FALSE POSITIVE |
|---|---|---|
3-singleton | getInstance() calls | Calls to a core getInstance() that is not deprecated (SecurityService, AdminAuthenticationService) are standard; a deprecated one is a migration FAIL (DP01), not a cluster defect. Only an own getInstance() returning an instance that holds mutable static state is a defect. |
3-singleton | private static X _dao = CDI.current().select(...).get() | The Home pattern — an effectively-immutable reference resolved once at class-load. Not divergent state. |
4-cache | new HashMap<>() / new ArrayList<>() | Method-local collections are per-request stack variables, GC'd, never shared across nodes. Only a field-level or static mutable collection is state. |
4-cache | a service extending AbstractCacheableService | Already JCache-backed → cluster-capable when Hazelcast is on. The concern is the cache contract (patterns/cache-distributed.md: callers never modify a cached value, typed cache, complete key, invalidation on every event, grouped resets) + proving distribution (Phase F), not a rewrite. |
2-session | List<String> / other Serializable light values in session | Fine. Only non-Serializable or heavy/Future/Timer/Thread session state is a defect. |
1-id | SELECT MAX(...) | A defect only when the value becomes a contended business key. A PK filled by RETURN_GENERATED_KEYS (DB auto-increment) is fine. |
Also check the highest-risk axis the scanner cannot see: a daemon (extends Daemon, declared under <daemon-class> in plugin.xml, interval from daemon.<id>.interval) that would fire once per node — grep for it explicitly. If none, say so.
A.4.2 — Reproduce each genuine defect in the cluster, through the UI (capture a RED trace) — MANDATORY before Phase B
The empirical proof of this skill is a browser-driven end-to-end test against the real 3-node cluster — full stop. A scalability finding is confirmed only when the real user flow, driven through the real UI (Playwright via nginx), makes the invariant break on the unfixed baseline. This is non-negotiable and it is the same test that must later turn GREEN.
Stand the cluster up NOW — do not wait for Phase F. The cluster is built once, on the pre-fix baseline, and lives through the whole red→green loop (repro RED → fix → redeploy → repro GREEN → failover). Concretely, in this phase:
The mechanics — generate and boot the cluster, the mandatory docker-log read, the login smoke-check, copying
harness/e2e_skeleton.py and adapting it — are in
reference/cluster-runbook.md. Run it on the baseline: it must be RED.
That RED, in the cluster and through the UI, is the entry ticket to Phase B.
What does NOT count as the RED (or the GREEN): a raw-SQL/JDBC replay, a direct DAO/service call, a
pg.request.postthat bypasses the UI, a unit test. These may be used privately by the agent as a 10-second smoke-check to orient itself, but they are never the proof, never presented in the report as RED/GREEN, and never a substitute for the UI e2e. If you find yourself proving scalability with a standalone SQL script, stop — that is the exact shortcut this rule forbids.
A genuine finding that cannot be reproduced through the UI in the cluster is downgraded to theoretical and noted — do not spend a teammate on it. (Rare pure-infra concerns — e.g. Hazelcast cluster formation — are checked by
cluster-verify.sh, not by a user flow; state which is which.)
The fix's job is to turn that exact e2e from RED to GREEN.
PHASE B — Plan (Lead executes directly)
Plan fixes for the confirmed (reproduced) defects only — never for raw scan counts. Map confirmed defects → axes → teammates. Decide how many teammates (1 per non-empty axis group; merge small ones). Write a short plan per teammate listing the files it owns (no overlap — file ownership) and the RED reproduction its fix must turn GREEN.
PHASE C — Spawn Teammates
From here the lead only orchestrates and never edits files. On a harness without dispatch, execute the teammates below yourself, one after the other, in the Phase D order.
Spawn the teammates whose axes have findings:
| Teammate | Instructions | Axes |
|---|---|---|
| Locks & Concurrency | teammates/locks-concurrency.md | 1-locks, 1-id |
| CDI scopes & singletons | teammates/cdi-scopes.md | 3-singleton, 3-cdi-static, 4-cache |
| Serialization & session | teammates/serialization-session.md | 2-session, 2-sessionscoped, 2-nonserial |
| Config & robustness | teammates/config-robustness.md | 5-config, 6-streams, 6-threadlocal |
| Verifier | teammates/verifier.md | builds + runs the cluster test |
Spawn template
Replace ${LUTECEPOWERS_ROOT} by the literal absolute path from your session context before sending; a teammate does not see that context.
LUTECEPOWERS_ROOT=${LUTECEPOWERS_ROOT} (export it in your shell before running any script)
SKILL=${LUTECEPOWERS_ROOT}/skills/lutece-scalability-v8 (export it too; your instructions use it)
Read your instruction file at ${SKILL}/teammates/<file>.md.
Your findings are in .scalability/scan.json (your axes only). Own only your assigned files.
Patterns: ${LUTECEPOWERS_ROOT}/skills/lutece-scalability-v8/patterns/ — load only what you need.
Reference-first: ALWAYS read ~/.lutece-references/ (especially lutece-form-plugin-forms and lutece-core) before writing any pattern.
Run verify-file.sh after each file you change. Never commit.
PHASE D — Dependencies
CDI scopes & singletons ─┐
Serialization & session ─┤ (run first — locks/config may depend on the new beans)
│
Locks & Concurrency ──┤ (DB lock often uses a CDI-managed LockDAO/Home)
Config & robustness ──┘
│
└──→ Verifier: redeploy fix into the ALREADY-STANDING cluster (built in A.4.2)
and re-run the RED UI e2e → GREEN + failover (after ALL fixers complete)
The cluster is stood up once in A.4.2 (for the RED baseline) and reused here for the GREEN — it is not first created in Phase F.
PHASE E — Monitor
- Check task progress periodically.
- A teammate stuck > 5 min → ask it for status.
- A teammate reports a blocker → investigate, advise, or reassign.
PHASE F — Turn the RED e2e GREEN on the cluster (Verifier)
The cluster is already standing from Phase A.4.2, and the UI e2e already went RED on the baseline. Phase F's job is to redeploy the fixed code into that same cluster and re-run the same UI e2e until it is GREEN, then prove failover. Same cluster, same test, before → after. Do NOT prove the fix with anything other than that UI e2e (see A.4.2's "what does NOT count").
The eight steps the Verifier (teammates/verifier.md) runs — rebuild, redeploy, read the logs, re-run the same
e2e, prove failover, read the logs again, route failures, tear down — are in
reference/cluster-runbook.md.
Reading the server logs before AND after the functional test is a mandatory step, not optional: the console (
docker compose logs) and each node's Libertylogs/messages.logand FFDC incidents (logs/ffdc/,cluster-verify.shsection 8). Most cluster-only defects (schema not deployed, class-loader serialization, session not replicating, swallowed exceptions) are invisible from HTTP status codes; a session Liberty cannot deserialize (WELD-001435) shows only as an FFDC incident.
A green run proves: 3 instances serving, shared DB, single Liquibase migration, both Hazelcast groups formed, session replicated across nodes (no sticky) and surviving a node kill (failover), and — for a contended resource — that concurrent real operations never exceed capacity (no double-booking / oversell), with clean logs throughout.
PHASE G — Review & Final Gate
- When build,
cluster-verify.sh, the A.4.2 UI e2e (GREEN) and the failover proof are all green, spawn the v8 reviewer (${LUTECEPOWERS_ROOT}/agents/lutece-v8-reviewer.md) read-only; resolve FAIL items via teammates. - Present the summary: scan deltas, triage verdicts (false positives dropped + reason), RED→GREEN reproduction results, build result,
cluster-verify.shPASS/FAIL, files modified. - KEEP all artifacts (see retention rule) — do NOT delete
.scalability/. Disband the team only. STOP. Never commit — the user decides (they may then commit the.scalability/report, thee2e/scripts and the generated cluster).
Artifact retention — keep everything
The reproductions and the generated cluster ARE the deliverable (a reproducible proof). Nothing is auto-deleted:
.scalability/scan*.json— the scan(s), kept as the report..scalability/report.md— a short written summary (triage verdicts, RED→GREEN, files changed) — write it here.e2e/.scalability-test/— the generated 3-node cluster (gen-test-site.sh --outtarget); kept so the proof is re-runnable.e2e/*.py— the UI-driven concurrent-load / failover drivers (Playwright) — the primary deliverable; their captured RED and GREEN output goes toe2e/artifacts/.
Only ephemeral runtime is torn down: running containers (docker compose down) and any throwaway smoke-check DB. Leave every file in place; the user decides what to commit and adds .gitignore entries if they don't want the generated cluster tracked.
Strict Rules
- Run after migration — the plugin must already be v8-compliant and compile.
- Triage before planning — a raw scan count is never a fix list. Drop every false positive with a stated reason (Phase A.4.1) first.
- RED before fix, in the cluster, through the UI — a finding is not a bug until observed failing via a browser-driven e2e (Playwright over nginx) against the real 3-node cluster on the unfixed baseline (Phase A.4.2), before any teammate touches code. Unreproducible through the UI ⇒ downgrade to theoretical, don't fix. 3b. UI e2e is the ONLY proof — RED and GREEN are the same UI e2e, before and after the fix. A raw-SQL/JDBC replay, a direct DAO/service call, or an API POST that bypasses the UI is never the proof and never appears as RED/GREEN in the report — at most a private throwaway smoke-check. If you're proving scalability with a standalone script, you're doing it wrong.
- After Phase B the Lead orchestrates only and never edits files.
- Reference-first — copy the real mechanics from
~/.lutece-references/(formsLockDAO/forms_lucene_lock, core CDI/serialization), never invent. Match the primitive to the lifetime: a short critical section (a few statements) → transactionalSELECT … FOR UPDATE(auto-released on commit/crash, no orphan); a long single-writer lease (daemon/indexer) → the forms TTLLockDAO. Don't copy the TTL lease onto a short section. - File ownership — one file, one teammate.
- Prove, don't assume — a fix is "done" only when the same UI e2e that was RED turns GREEN in the cluster (+ failover). Test with Hazelcast on (ehcache hides serialization bugs).
getInstance()is removed, never bridged — delete it and migrate callers (rules/service-layer.md).- Keep all artifacts — never auto-delete
.scalability/,e2e/scripts, or the generated cluster. Tear down only running containers. - NEVER commit.
Script Locations
All in ${LUTECEPOWERS_ROOT}/skills/lutece-scalability-v8/scripts/:
| Script | Purpose | Used by |
|---|---|---|
scan-scalability.sh | Scan 6-axis anti-patterns → JSON | Lead (A) |
verify-file.sh | Per-file residual anti-pattern check | Fixer teammates |
gen-test-site.sh | Generate a disposable 3-node Docker cluster for the plugin | Verifier (F) |
cluster-verify.sh | Empirical scalability proofs against the running cluster | Verifier (F) |
Pattern Locations
All in ${LUTECEPOWERS_ROOT}/skills/lutece-scalability-v8/patterns/:
| File | Axis |
|---|---|
distributed-lock.md | 1 — concurrency, contended resources, ID generation |
cdi-scopes.md | 3 — static singletons → CDI beans |
serialization-session.md | 2 — Serializable session/cache, session state |
cache-distributed.md | 4 — JSR-107 / Hazelcast distributed cache |
config-and-robustness.md | 5 & 6 — MicroProfile config, streams, thread-locals, determinism |
Test Harness
${LUTECEPOWERS_ROOT}/skills/lutece-scalability-v8/harness/ — a proven, parameterized 3-instance cluster (Liberty + MariaDB + nginx + Hazelcast, Liquibase migrator pattern, sessionCache session replication). gen-test-site.sh templates it for the plugin under test. See harness/README.md.
Lutece 8 site — several replicas
Scope
Configures a site (packaging lutece-site, OpenLiberty image) for N replicas behind a load balancer: the files of the
site, the Kubernetes manifests, and the checks. It does not change plugin code: a plugin defect found on the way is reported
(reference/platform-versions.md); fixing a plugin is lutece-scalability-v8.
Two things must be shared between the replicas: the HTTP session and the Lutece cache. This skill writes one way of doing it, the one tested with Lutece:
- HTTP session: OpenLiberty
sessionCache-1.0over a Hazelcast member embedded in each pod. - Lutece cache (JCache): a Hazelcast client connected to the member of its own pod, with a near cache.
Other stores fit OpenLiberty and Lutece: sessions in a database (sessionDatabase-1.0), another JCache provider
(Infinispan, Redis through Redisson, a separate Hazelcast cluster). They are not tested with Lutece; when the user wants
one, follow reference/session-options.md (OpenLiberty documentation links) and keep every other rule below.
Session affinity is recommended, by a cookie the load balancer sets on the first response, never named JSESSIONID and
never a hash of JSESSIONID (the first request has no cookie: the visitor changes replica once). The session stays shared (a replica lost, its users
continue on the other one), but OpenLiberty writes it at the end of the request, after a redirect is sent: the request that
follows the redirect can reach the other replica first and read the session before the POST (back office actions and their
AdminMessage: Invalid security token). Form steps answer 200 without a redirect and pass without affinity. Measured on 2
replicas, 11-step form: −12 to −21 % CPU per request and p50 −17 to −32 % with affinity (reference/kubernetes.md).
Before writing anything
- Read the site:
pom.xml,src/main/liberty/config/*,Dockerfile,webapp/WEB-INF/conf/override/*.properties,webapp/WEB-INF/plugins/plugins.dat. - Note the site code (
<site>in the templates: cluster name, Kubernetes names), the database, the plugins. - Check
reference/platform-versions.md:lutece-platformBOM and starter 8.0.0-beta-04 or later, nothing pinned below them. - Ask the user only what cannot be read: the session store if not Hazelcast, the Kubernetes service name of the Hazelcast port and the Hazelcast version if the organisation imposes them, the ReadWriteMany storage class.
Files to write
Templates are in templates/: replace <site>, <registry>/<site>:<version>, <host>. Keep the comments language of
the site. A template marked merge goes into the existing file; the others are copied.
A complete site configured this way, built, deployed and measured on minikube: the multi-instance branch of
https://github.com/lutece-platform/lutece-guide-kubernetes-lutece (Forms starter, Liberty and Hazelcast files, Kubernetes
manifests with the Liquibase run and the ingress, README with the measures). Its mono-instance branch is the same site
on one replica, for comparison.
| File | Template | Content |
|---|---|---|
pom.xml (merge) | pom-profiles.xml | Hazelcast repository, plugin-quartz-scheduler, profile cluster (default: Hazelcast, Ehcache provided), profile local (-Dlocal: no cluster.xml) |
src/main/liberty/config/server.xml (merge) | server-xml-snippet.xml | cluster.xml include, persistTimeout, remoteIp, bounded executor, maxPoolSize on the existing data source |
src/main/liberty/config/cluster.xml | same name | sessionCache-1.0, session library, httpSessionCache, Lutece cache provider |
src/main/liberty/config/hazelcast-config-api-mode.yaml | same name | Member: cluster name, graceful shutdown, JVM hook off, immediate invalidations, fixed port, Kubernetes discovery |
src/main/liberty/config/hazelcast-client-config-api-mode.yaml | same name | Client of the Lutece cache: member of its own pod, near cache |
src/main/liberty/config/jvm.options (merge) | jvm.options | Member provider type, Hazelcast service name, --add-opens |
webapp/WEB-INF/conf/override/quartz-daemons.properties | same name | quartzscheduler.cluster.enable=true, exclusive daemons, Forms lock lease |
webapp/WEB-INF/plugins/plugins.dat | site_check.py plugins-dat <war> | Plugins installed on a fresh database |
Dockerfile | same name | Configuration, war, configure.sh (expanded war) |
| Kubernetes | kubernetes-rbac.yaml | Service account, Service on 5701, Role/RoleBinding for the discovery |
| Kubernetes | kubernetes-service.yaml | Service of the site, ReadWriteMany volume of the Forms index |
| Kubernetes | kubernetes-migration.yaml | One-replica Liquibase run, before the replicas |
| Kubernetes | kubernetes-deployment.yaml | Replicas, sizes, probes, preStop, grace period, Liquibase off, Forms index path |
| Kubernetes | kubernetes-ingress.yaml | Replay on connection errors only, session affinity (own cookie name), context root |
The Kubernetes templates are plain manifests: add the namespace and the image pull policy of the target, or turn them into the templates of the organisation's chart.
Rules that are easy to get wrong
Each one was observed; the evidence and the numbers are in reference/rules.md and reference/kubernetes.md.
- Session library = every jar of the war, and
writeContents="GET_AND_SET_ATTRIBUTES": otherwise partitions do not migrate, and@SessionScopedbeans modified in place are lost on a node switch. -Dhazelcast.jcache.provider.type=memberinjvm.options; member caches declared by exact name only, never"*"(it stops the application at the next full restart); JVM shutdown hook off and graceful shutdown on; near cache on the client, its invalidations not batched,BINARYforformsCacheService(Forms modifies the objects it reads from its cache).- Quartz:
quartzscheduler.cluster.enable=true(the plugin shipsfalse) and every daemon acting on shared state declared exclusive; the coreindexerandthreadLauncherDaemonstay local (table inreference/rules.md). - Liquibase from one replica only:
-Dliquibase.enabled.at.startup=falseon the replicas,kubernetes-migration.yamlbefore them on a fresh database and before each new war. plugins.datshipped by the site, generated from the war: a dependency's own file can disable plugins on a fresh database.- Forms index on a ReadWriteMany volume (
indexPathinJVM_ARGS,fsGroup: 0) and lock leaseforms.index.writer.ms.timeout.lock=120000. - Liberty:
persistTimeoutabove the 60 s keep-alive of the load balancer,<remoteIp/>behind the ingress, executor bounded (12 threads for a 2 CPU limit on the example Forms site; every figure of the skill is a measure of that site, so tell the user the values depend on their site and are measured under its target load),maxPoolSize12; the database user limit covers (replicas + surge + migration run) xmaxPoolSize. - Kubernetes: preStop 10 s and grace period 60 s, startup probe, readiness on the database, liveness on the webapp only, probe timeouts 5 s / 10 s, CPU limit above the request, autoscaling on CPU only.
- Data changed outside Lutece (SQL, restore): reset the caches from the back office; a rolling restart keeps them. Under
Hazelcast a Lutece cache keeps its Lutece lifetime, and its size with
library-cache-hazelcastin the cluster profile. Enabling or disabling a cache from the back office reaches the other replicas withinlutece.cache.status.refreshSeconds(30 s).
Checks
bash ${LUTECEPOWERS_ROOT}/tools/site-assemble.sh . --out .multi-instance/site
python3 ${LUTECEPOWERS_ROOT}/tools/site_check.py check . --war .multi-instance/site --k8s <manifests-or-chart-templates>
SI60-SI68 check the multi-instance configuration of the site, SI70-SI72 the manifests, SI40-SI44 plugins.dat. Every FAIL
is fixed before handing over; a WARN left is explained to the user.
bash ${LUTECEPOWERS_ROOT}/tools/lutece-check.sh --explain SI66 explains a code.
Proving it
Static checks do not prove the cluster. When the user asks for the proof, run reference/verification.md: a journey with
every step on another replica, concurrent numbering, back office session, cache invalidation, forced pod deletion and rolling
restart under load. Plain HTTP on a host other than localhost breaks the back office (CSP upgrade-insecure-requests):
test behind TLS or through localhost.
References
reference/session-options.md: Hazelcast and the other stores, OpenLiberty links.reference/rules.md: the rules with their evidence, the classification of the daemons.reference/kubernetes.md: cluster prerequisites, sizes, probes, database connections, memory and time zone.reference/platform-versions.md: the platform level carrying the plugin fixes, what the BOM cannot fix.reference/verification.md: the runtime checks and how they were run.
Lutece 8 Solr Indexer Module
Before implementing a Solr indexer, consult
~/.lutece-references/lutece-search-module-forms-solr/— the reference implementation. The main plugin is at~/.lutece-references/lutece-search-plugin-solr/.
Architecture Overview
plugin-solr (provides framework — already deployed)
↓ auto-discovers via CDI
module-myentity-solr (@ApplicationScoped SolrIndexer)
↓ builds
SolrItem (core fields + dynamic fields)
↓ writes via
SolrIndexerService.write(Collection<SolrItem>)
↓ committed to
Solr Server (HTTP/2 client)
Incremental path:
Entity CRUD → CDI ResourceEvent
↓ observed by
SolrEventRessourceListener (plugin-solr, queues SolrIndexerAction in DB)
↓ processed by
SolrIndexerDaemon → calls indexer.getDocuments(id)
A module provides a SolrIndexer implementation. The plugin-solr framework handles server communication, daemon scheduling, and action queue management.
CDI auto-discovery — any @ApplicationScoped class implementing SolrIndexer is automatically registered:
// Inside SolrIndexerService (plugin-solr)
CDI.current( ).select( SolrIndexer.class ).stream( ).toList( );
Step 1 — Maven Module Setup
<parent>
<groupId>fr.paris.lutece.tools</groupId>
<artifactId>lutece-global-pom</artifactId>
<version>LATEST_RELEASED_8_X</version>
</parent>
<artifactId>module-myentity-solr</artifactId>
<packaging>lutece-plugin</packaging>
<dependencies>
<dependency>
<groupId>fr.paris.lutece.plugins</groupId>
<artifactId>plugin-solr</artifactId>
<version>[5.0.0,)</version>
<type>lutece-plugin</type>
</dependency>
<dependency>
<groupId>fr.paris.lutece.plugins</groupId>
<artifactId>plugin-myentity</artifactId>
<version>[X.0.0,)</version>
<type>lutece-plugin</type>
</dependency>
</dependencies>
Replace LATEST_RELEASED_8_X with the latest released lutece-global-pom 8.x (check the Lutece Maven repository, never hardcode a guess). The module is never its own parent (reference: lutece-search-module-forms-solr/pom.xml).
Step 2 — SolrIndexer Implementation
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
import jakarta.enterprise.inject.Instance;
import fr.paris.lutece.plugins.search.solr.indexer.SolrIndexer;
import fr.paris.lutece.plugins.search.solr.indexer.SolrItem;
import fr.paris.lutece.plugins.search.solr.business.field.Field;
import fr.paris.lutece.plugins.search.solr.service.SolrIndexerService;
import fr.paris.lutece.portal.service.util.AppPropertiesService;
@ApplicationScoped
public class SolrMyEntityIndexer implements SolrIndexer
{
private static final String PROPERTY_INDEXER_ENABLE = "module-myentity-solr.indexer.enable";
private static final String PROPERTY_NAME = "module-myentity-solr.indexer.name";
private static final String PROPERTY_DESCRIPTION = "module-myentity-solr.indexer.description";
private static final String PROPERTY_VERSION = "module-myentity-solr.indexer.version";
private static final String SHORT_NAME = "mye";
private static final int BATCH_SIZE = 100;
public static final String RESOURCE_TYPE = "MYENTITY_ENTITY";
// Use Instance<T> for optional dependencies (e.g., workflow)
@Inject
private Instance<IStateService> _stateServiceInstance;
// --- Full reindex (called by admin "Index All") ---
@Override
public List<String> indexDocuments( )
{
List<Integer> listIds = MyEntityHome.findAllIds( );
List<String> listErrors = new ArrayList<>( );
for ( int i = 0; i < listIds.size( ); i += BATCH_SIZE )
{
List<Integer> batch = listIds.subList( i,
Math.min( i + BATCH_SIZE, listIds.size( ) ) );
List<MyEntity> listEntities = MyEntityHome.findByPrimaryKeyList( batch );
try
{
Collection<SolrItem> items = listEntities.stream( )
.map( this::buildSolrItem )
.collect( Collectors.toList( ) );
SolrIndexerService.write( items );
}
catch ( Exception e )
{
listErrors.add( e.getMessage( ) );
}
}
return listErrors;
}
// --- Incremental (called by daemon for queued actions) ---
@Override
public List<SolrItem> getDocuments( String strIdDocument )
{
MyEntity entity = MyEntityHome.findByPrimaryKey(
Integer.parseInt( strIdDocument ) );
if ( entity == null )
{
return Collections.emptyList( );
}
return List.of( buildSolrItem( entity ) );
}
// --- Resource types this indexer handles ---
@Override
public List<String> getResourcesName( )
{
return List.of( RESOURCE_TYPE );
}
// --- UID generation ---
@Override
public String getResourceUid( String strResourceId, String strResourceType )
{
if ( RESOURCE_TYPE.equals( strResourceType ) )
{
return strResourceId + "_" + SHORT_NAME;
}
return null;
}
// --- Metadata ---
@Override
public String getName( )
{
return AppPropertiesService.getProperty( PROPERTY_NAME );
}
@Override
public String getVersion( )
{
return AppPropertiesService.getProperty( PROPERTY_VERSION );
}
@Override
public String getDescription( )
{
return AppPropertiesService.getProperty( PROPERTY_DESCRIPTION );
}
@Override
public boolean isEnable( )
{
return AppPropertiesService.getPropertyBoolean( PROPERTY_INDEXER_ENABLE, false );
}
@Override
public List<Field> getAdditionalFields( )
{
return Collections.emptyList( );
}
// --- SolrItem builder (see Step 3) ---
private SolrItem buildSolrItem( MyEntity entity )
{
// See Step 3
}
}
Step 3 — Building SolrItems
private SolrItem buildSolrItem( MyEntity entity )
{
SolrItem item = new SolrItem( );
// Core fields
item.setUid( entity.getId( ) + "_" + SHORT_NAME );
item.setTitle( entity.getTitle( ) );
item.setType( RESOURCE_TYPE );
item.setSummary( entity.getDescription( ) );
item.setContent( entity.getTitle( ) + " " + entity.getDescription( ) );
item.setUrl( "jsp/site/Portal.jsp?page=myentity&id=" + entity.getId( ) );
item.setSite( SolrIndexerService.getWebAppName( ) );
item.setRole( "none" );
if ( entity.getDateCreation( ) != null )
{
item.setDate( entity.getDateCreation( ) );
}
// Dynamic fields (see table below for suffixes)
item.addDynamicField( "entity_status", entity.getStatus( ) ); // → entity_status_text
item.addDynamicFieldNotAnalysed( "entity_code", entity.getCode( ) ); // → entity_code_string
item.addDynamicField( "entity_count", (long) entity.getCount( ) ); // → entity_count_long
item.addDynamicField( "entity_update", entity.getDateUpdate( ) ); // → entity_update_date
item.addDynamicField( "entity_tags", entity.getTags( ) ); // → entity_tags_list
// Geolocation (address, longitude, latitude, docType)
// item.addDynamicFieldGeoloc( "entity_location",
// entity.getAddress( ), entity.getLon( ), entity.getLat( ), "MyEntity" );
return item;
}
SolrItem Dynamic Fields Reference
| Method | Suffix | Solr type | Use for |
|---|---|---|---|
addDynamicField(name, String) | _text | Analyzed text | Full-text searchable strings |
addDynamicFieldNotAnalysed(name, String) | _string | Keyword | Exact match, facets, filters |
addDynamicField(name, Long) | _long | Long | Numbers, counts |
addDynamicField(name, Date) | _date | Date | Dates, timestamps |
addDynamicField(name, Float) | _float | Float | Decimal numbers |
addDynamicField(name, List<String>) | _list | Multi-valued | Checkboxes, tags |
addDynamicFieldListDate(name, List<Date>) | _list_date | Multi-valued date | Multiple dates |
addDynamicFieldGeoloc(name, addr, lon, lat, type) | _geoloc + _geojson + _address_text | Geo | Map display, proximity search |
Step 4 — CDI Event Listener (Incremental Updates)
The plugin-solr framework already has SolrEventRessourceListener that observes ResourceEvent and queues SolrIndexerAction. You just need to fire the right events from your service layer.
Fire ResourceEvent from your Service when entities are created/updated/deleted. The SolrEventRessourceListener uses @Observes @Type(EventAction.X), so you must select the qualifier before firing synchronously:
import fr.paris.lutece.portal.business.event.ResourceEvent;
import fr.paris.lutece.portal.service.event.EventAction;
import fr.paris.lutece.portal.service.event.Type.TypeQualifier;
@ApplicationScoped
public class MyEntityService
{
@Inject
private Event<ResourceEvent> _resourceEvent;
public MyEntity create( MyEntity entity )
{
MyEntityHome.create( entity );
ResourceEvent event = new ResourceEvent( );
event.setIdResource( String.valueOf( entity.getId( ) ) );
event.setTypeResource( SolrMyEntityIndexer.RESOURCE_TYPE );
_resourceEvent.select( new TypeQualifier( EventAction.CREATE ) ).fire( event );
return entity;
}
public MyEntity update( MyEntity entity )
{
MyEntityHome.update( entity );
ResourceEvent event = new ResourceEvent( );
event.setIdResource( String.valueOf( entity.getId( ) ) );
event.setTypeResource( SolrMyEntityIndexer.RESOURCE_TYPE );
_resourceEvent.select( new TypeQualifier( EventAction.UPDATE ) ).fire( event );
return entity;
}
public void remove( int nIdEntity )
{
MyEntityHome.remove( nIdEntity );
ResourceEvent event = new ResourceEvent( );
event.setIdResource( String.valueOf( nIdEntity ) );
event.setTypeResource( SolrMyEntityIndexer.RESOURCE_TYPE );
_resourceEvent.select( new TypeQualifier( EventAction.REMOVE ) ).fire( event );
}
}
The SolrEventRessourceListener in plugin-solr observes these events and queues SolrIndexerAction records. The SolrIndexerDaemon processes them by calling your indexer's getDocuments(strIdDocument).
Step 5 — Plugin Class (Resource Type Registration)
If your module supports multiple resource subtypes (e.g., one per form), register them dynamically:
public class MyEntitySolrPlugin extends PluginDefaultImplementation
{
@Override
public void init( )
{
super.init( );
// Static registration (single resource type)
// Nothing needed — getResourcesName() handles it
// Dynamic registration (multiple subtypes)
List<String> listResourceTypes = new ArrayList<>( );
listResourceTypes.add( SolrMyEntityIndexer.RESOURCE_TYPE );
// Add per-entity subtypes if needed
SolrMyEntityIndexer.initListResourceName( listResourceTypes );
}
}
Most modules don't need this — getResourcesName() returning a static list is sufficient. Only use the Plugin init() pattern when resource types are dynamic (like forms-solr, which creates one type per form).
Step 6 — Configuration Properties
# module-myentity-solr.properties
# Enable/disable this indexer
module-myentity-solr.indexer.enable=true
# Display metadata
module-myentity-solr.indexer.name=MyEntity Indexer
module-myentity-solr.indexer.description=Indexes MyEntity documents into Solr
module-myentity-solr.indexer.version=1.0.0
# Batch size for full reindex (optional, default 100)
module-myentity-solr.indexer.batchSize=100
The Solr server connection is configured at the plugin-solr level (not in your module):
# Already in plugin-solr config (do NOT duplicate)
solr.server.address=http://localhost:8983/solr/
Step 7 — plugin.xml
<plug-in>
<name>myentity-solr</name>
<class>fr.paris.lutece.plugins.myentity.modules.solr.service.MyEntitySolrPlugin</class>
<version>1.0.0-SNAPSHOT</version>
<description>module.myentity.solr.module.description</description>
<core-version-dependency>
<min-core-version>8.0.0</min-core-version>
<max-core-version/>
</core-version-dependency>
<db-pool-required>0</db-pool-required>
</plug-in>
<description> is an i18n key: module.description=Solr indexer for MyEntity plugin in the module bundle (rules/plugin-descriptor.md).
No daemons or admin features needed — the plugin-solr framework provides them.
ISolrItemExternalFieldProvider (Advanced)
Add cross-cutting fields to all SolrItems before indexing (e.g., add workflow state to items from other indexers):
@ApplicationScoped
public class MyFieldProvider implements ISolrItemExternalFieldProvider
{
public void provideFields( Collection<SolrItem> solrItems )
{
for ( SolrItem item : solrItems )
{
// Add extra fields to items matching your type
if ( "MYENTITY_ENTITY".equals( item.getType( ) ) )
{
item.addDynamicFieldNotAnalysed( "extra_field", "value" );
}
}
}
}
These providers are auto-discovered via CDI and called by SolrIndexerService before writing items.
File Checklist
| File | What to create |
|---|---|
pom.xml | Maven module with plugin-solr + plugin-myentity dependencies |
SolrMyEntityIndexer.java | @ApplicationScoped implementing SolrIndexer |
MyEntitySolrPlugin.java | Plugin class (only if dynamic resource types needed) |
module-myentity-solr.properties | Indexer name, description, enable flag |
WEB-INF/plugins/myentity-solr.xml | plugin.xml descriptor |
src/main/resources/META-INF/beans.xml | CDI descriptor (empty <beans> tag) |
No daemon, no DAO, no SQL table needed — plugin-solr provides all infrastructure.
Reference Sources
| Need | File to consult |
|---|---|
| SolrIndexer interface (9 methods) | ~/.lutece-references/lutece-search-plugin-solr/src/java/**/indexer/SolrIndexer.java |
| SolrItem API (dynamic fields) | ~/.lutece-references/lutece-search-plugin-solr/src/java/**/indexer/SolrItem.java |
| SolrIndexerService (write, commit) | ~/.lutece-references/lutece-search-plugin-solr/src/java/**/service/SolrIndexerService.java |
| CDI event listener (plugin-solr) | ~/.lutece-references/lutece-search-plugin-solr/src/java/**/indexer/SolrEventRessourceListener.java |
| Complete indexer (forms-solr) | ~/.lutece-references/lutece-search-module-forms-solr/src/java/**/SolrFormsIndexer.java |
| Plugin init (forms-solr) | ~/.lutece-references/lutece-search-module-forms-solr/src/java/**/FormsSolrPlugin.java |
| External field provider | ~/.lutece-references/lutece-search-plugin-solr/src/java/**/indexer/ISolrItemExternalFieldProvider.java |
Lutece update
One job whatever the starting point: bring the artefact to the supported Lutece level (tools/v8-floor.conf). The
scripts report everything checkable; you make every change, alone and in order. One command carries the toolkit:
tools/lutece-check.sh (every check, each finding with what to do; --explain CODE for one check). A rename a check
names across many files (javax → jakarta, an annotation) is one sed over src/, then the check again. An update is
sequential (the Java needs the pom, the JSP need the beans): do it yourself, never split it between parallel agents.
Two subagents only, one after the other: the reviewer (Phase E) and the e2e bench (Phase F).
PHASE A — Scan: where the artefact starts
mkdir -p .migration
bash ${LUTECEPOWERS_ROOT}/hooks/setup-rules . >/dev/null
bash ${LUTECEPOWERS_ROOT}/tools/scan-project.sh . > .migration/scan.json
[ -s .gitignore ] && [ -n "$(tail -c1 .gitignore)" ] && echo >> .gitignore
for p in 'target/' 'logs/' 'java.io.tmpdir/' '.migration/' '*.log' 'e2e/'; do grep -qxF "$p" .gitignore 2>/dev/null || echo "$p" >> .gitignore; done
From here on the Lutece 8 rules apply, whatever the starting version: before editing a file, read the rule of
${LUTECEPOWERS_ROOT}/rules/ that matches it (.claude/rules/ holds them on Claude Code from the next session).
project.type site (packaging lutece-site: a site, a pack, a theme) is not updated here: follow the
lutece-update-site skill, which checks what the site ships and hands its plugins back to this one when they need an
update. For the other types, summary.start says the path: pre-v8 (a parent before 8: the full update, a v7 database to take over) or v8 (a
v8 parent: align it on the supported level, no database to take over). Show the user the type, artifact, version,
start, scope and persistence base (summary.persistence: JPA stays on the container's EclipseLink,
patterns/persistence-patterns.md).
Dependencies (blocker). For each Lutece dependency of the scan: available (in ~/.lutece-references/) or
published is fine; clone a published one into ~/.lutece-references/ (dependency-references rule); to-resolve
means finding its repository and its v8 branch (develop, parent 8.x). A dependency with no v8 version: stop
and tell the user.
PHASE B — First check
bash ${LUTECEPOWERS_ROOT}/tools/lutece-check.sh .
It lists every finding by code: that list is the work of the steps.
PHASE C — The steps
| Step | File (steps/) | Scope | Codes it answers |
|---|---|---|---|
| 1 | 1-config.md | pom, beans.xml, descriptors, web.xml, Spring context files, SQL, properties | V8FLOOR, PM*, PV*, WB*, SP03, SQ*, PT*, XT*, I18N* |
| 2 | 2-java.md | src/java: the Spring context to CDI, what the checks name, the designs a script cannot choose | JX*, SP*, DL*, EV*, CA*, DP*, DA*, JP*, CD*, MV*, ST*, HM*, XS*, CS*, TL*, LG*, GI*, PI*, RL*, PD*, WG*, JS04 |
| 3 | 3-templates.md | JSP, admin and skin templates, JavaScript | TM*, TD*, JS*, VL* |
| 4 | 4-tests.md | src/test | TS*, PM13 |
LE01 (a file whose line endings the work converted) belongs to no step: write files in any convention and run tools/restore-line-endings.sh . before each check, it puts every changed file back to the endings HEAD has in one pass; no conversion by hand.
pre-v8: every step, in this order.v8: only the steps with a finding oflutece-check.shin their scope, in this order; a step with none is skipped. AV8FLOORrefusal is step 1 (parent and core range).
Search ~/.lutece-references/ before writing any pattern (each clone carries its v7 branches). After each file,
bash ${LUTECEPOWERS_ROOT}/tools/verify-file.sh --brief <file> and fix what it reports; after each step,
bash ${LUTECEPOWERS_ROOT}/tools/lutece-check.sh .. A code you do not know: lutece-check.sh --explain CODE. Change
what the level requires, nothing else: no line-ending conversion, no reflow, no "modernising" what compiles.
PHASE D — Build
bash ${LUTECEPOWERS_ROOT}/tools/final-gate.sh . --no-e2e
One build with the compiler warnings and the unit tests read from surefire (BUILD SUCCESS means nothing: the parent
sets testFailureIgnore), then the checks. When the project does not assemble, verify-migration.sh reports TM08
and TM09 NOT EVALUATED: read the Maven error it printed (a dependency that does not resolve, a half-updated pom). Five build-fix rounds on the
same error, then stop and show the user the full log (/tmp/final-gate-<project>-build.log). The frequent causes:
| Symptom | Fix |
|---|---|
cannot find symbol on a Spring or javax type | the Java of step 2 |
final class cannot be proxied | drop final on that class only; legal when the bean is resolved by its interface |
UnsatisfiedResolutionException in a Home static initializer | beans.xml missing from the archive, or excluded by .gitignore (ST05) |
@Inject field null in a test | the bean is not annotated in production code |
NullPointerException in getModel( ) | @Inject Models (patterns/cdi-patterns.md §16) |
PHASE E — Reviewer
When final-gate.sh . --no-e2e is green, dispatch a read-only subagent: instructions
${LUTECEPOWERS_ROOT}/agents/lutece-v8-reviewer.md, "review this project for v8 compliance, modify nothing", with
${LUTECEPOWERS_ROOT} replaced by its literal path. It returns its report without writing a file: save it as
.migration/report-reviewer.md. Fix its FAIL items, run Phase D again, review again; fix its WARN items too.
PHASE F — e2e bench
Unit tests cover almost none of a plugin; the defects that hurt are on screen. Dispatch one subagent: "invoke the
lutece-e2e skill on this project and follow it (it reuses an existing e2e/), fixing with lpe2e watch running;
fix in the plugin or in e2e/ what the bench proves, and report each fix", with the literal
${LUTECEPOWERS_ROOT}. While it runs you edit nothing: the project has one writer at a time. Every red scenario is
attributed, to the plugin or to the core, with the evidence; a core defect the plugin must not work around (an
@Action run on GET without its token) keeps its scenario with core_defect: and goes into the hand-over, never into
a guard of the plugin. A fix the bench forced inside e2e/ is a defect of lutece-e2e: report it.
PHASE G — Gate loop
touch .migration/gate-required (the Stop hook then refuses to end a turn while the gate is red), then:
bash ${LUTECEPOWERS_ROOT}/tools/final-gate.sh .
It reuses a green bench run and upgrade (lpe2e upgrade, the v7 database taken over) of the same sources instead of
playing them again, and plays upgrade only when the bench knows a pre-v8 ancestor. The upgrade proves the v7 data
kept only through a witness asserted with the v7_witness step (lutece-e2e, reference/upgrade.md): a row of
seed7-*.sql with a value written in the query, exactly 1 when the core changeset 7.9.9-8.0.0 says the database was
born in v7, exactly 0 otherwise. Read what is red, fix it at the source (never an allowlist entry, a deleted
assertion or a scenario rewritten to expect the defect), run the gate again in full. A WARN does not block the gate,
and is fixed all the same: the gate lists each one; one stays only when its fix is impossible or outside the plugin (a
core defect, a choice of the user), with that reason in the hand-over. The only other way out of a red is a defect
attributed with evidence to something the plugin cannot fix (a core defect), carried into the hand-over. The same red
back a third time after three different fixes: stop and ask, the diagnosis is wrong.
When the gate passes: check no Spring context file remains under webapp/, then give the user the start, the gate
result, the reviewer verdict, the e2e counts with each red attributed, each WARN kept with its reason, the files
changed, and the files git does not track yet (git status --porcelain | grep '^??'), to stage with git add -A,
never git commit -a (a new beans.xml left out fails at the next clone). Never commit.
Judgement a script cannot make
- JPA entities: an
equals/hashCodeover a collection, a new object attached to a relation withoutcascade = PERSISTbefore a flush: fine with Hibernate, broken with EclipseLink (persistence-patterns.md§6). ShutdownServiceimplementations: a@PreDestroymethod on the bean whenprocess()does real cleanup; drop the interface when it does nothing. Case by case:getName()may be used elsewhere.
Patterns (patterns/, load on demand)
| File | When |
|---|---|
cdi-patterns.md | scopes, injection, producers, Models, Pager (Java, always) |
deprecation-fixes.md, core-8x-moves.md | what replaces a deprecated or moved API |
mvc-patterns.md | JspBean, XPage, portlet (HTML port §10, CSRF §11) |
events-patterns.md, cache-patterns.md, rest-patterns.md, json-patterns.md, fileupload-patterns.md, persistence-patterns.md | when the scan flags them |
rules/sql-liquibase.md (repository root) | SQL changesets and upgrade scripts |
Lutece update — site
A site owns almost no code. What it owns is a composition (parent, BOM, starter, pack, plugins) and a configuration layered over its dependencies, and that is what an update breaks without any error: a key deleted "because the pack provides it", a plugin a starter no longer brings, a Spring context v8 ignores, a per-environment directory the v8 parent no longer copies, a library that imposes its own values. So nothing here is judged on the sources or on a commit message: the site is its assembled war, before and after, and the configuration the running site resolves.
One tool carries every check and every conversion a script can make: tools/site_check.py (gate, check,
config, and the converters envconf, spring, rebase, plugins-dat; the codes are in tools/checks.md,
section Site). tools/site-assemble.sh builds the war the checks read, tools/site-bench-war.sh
the war the bench runs. Show the user the outcome of every phase before starting the next one: an update of a site
is a series of decisions that belong to its owner, not a script.
PHASE A — Where the site starts, and its before state
mkdir -p .migration
for p in 'target/' '.migration/' 'e2e/'; do grep -qxF "$p" .gitignore 2>/dev/null || echo "$p" >> .gitignore; done
- Identify the parent (
lutece-site-pomversion), the resolved core, the layer the site stands on (a pack, a starter, a theme, or an explicit list of plugins) and the archetype (reference/archetypes.md). - Ask the user for a dump of the recette database (the environment closest to production, anonymised when it holds personal data), before any change: it is the only way to prove the upgrade of the data the environments hold (phase F). Keep it outside every repository, never commit it, delete it when the update is delivered. Without one, go on, and the hand-over says in its first lines that the database upgrade is not proven.
- The before ref is the state the environments run, not the fork point of a v8 branch: for a v7 site the tip
of its v7 branch (
develop_core7,master_core7) or the tag in production; for a v8 site the tag or the commit the environments run (then no--profileand no--as-profile: a v8 war already holds every profile). Ask the user when it is not certain.checklater reports every commit of another branch after the ref (SI86). - Assemble the before state, one war per environment when the site has
src/conf/<env>/, and one without any environment profile for the bench of phase F:
bash ${LUTECEPOWERS_ROOT}/tools/site-assemble.sh . --ref <before_ref> [--profile <env>] \
--out .migration/before[-<env>] --repo .migration/m2 [--settings <settings.xml>]
A v7 pom resolves its ranges today, not on the day the environments' war was built: a range can reach a Lutece 8
artefact (a Java 17 jar), and the before state is then not what runs. The gate reports it (DRIFT); rebuild with
--pin <group>:<artifact>:<the v7 version> (the worktree pom only) until it reports none.
A private artefact (a pack, a theme, a configuration library) that no repository the build reaches serves is
built from its source tag into the same --repo; never install into ~/.m2 (it would shadow the published
snapshot for every project of the machine). A v7 build that cannot resolve its v7 parent through the user's mirror gets its own
settings file (reference/archetypes.md, Build).
PHASE B — Every artefact has a Lutece 8 version (blocking)
python3 ${LUTECEPOWERS_ROOT}/tools/site_check.py gate .migration/before --site . --bom <lutece-bom-8.x.pom> \
--m2 .migration/m2 [--repo-url <a private repository the user gives>]
--m2 reads the artefacts built into the isolated repository first (a private pack rebuilt from its tag shows as
LOCAL); --repo-url adds a repository the user names for this run (an organisation's private one). Never write
such a url into a file of the toolkit or of the site. .migration/before.tree (written by site-assemble.sh) lets
the gate say which direct dependency brings each blocker: an artefact only a replaced layer brought is a plugin
decision, not a blocker.
The target BOM is the one the site will import: the one the user names, else the one
python3 ${LUTECEPOWERS_ROOT}/tools/latest-lutece.py bom fr.paris.lutece.starters:lutece-bom gives (the published
lutece-bom that manages the highest lutece-core; the highest BOM number is not always the newest one).
Each Lutece artefact the before war ships, and each lutece-site dependency of the pom (theme, pack), gets a status:
| Status | Meaning | What to do |
|---|---|---|
BOM | managed by the target BOM | nothing: the site declares it without version |
STARTER | a starter | the version of the target BOM |
PUBLISHED | a release with a Lutece 8 parent, outside the BOM | the site pins that version |
LOCAL | a Lutece 8 version found only in the isolated repository (a private artefact rebuilt from its tag) | the site pins it; the release needs it published where the build looks |
SNAPSHOT | a Lutece 8 snapshot only, or the snapshot the target BOM manages | tell the user: a site released on it changes under its feet; pin the last release when there is one |
NO-V8 | no published version with a Lutece 8 parent | blocker |
DRIFT | a Lutece jar of the v7 before war built for Java 17 | the before state is polluted: pin and assemble it again (phase A) |
For each NO-V8, in this order: its successor, which the gate prints from tools/site-successors.tsv (public
artefacts) and from the organisation's own file ($LUTECEPOWERS_SITE_SUCCESSORS, else
~/.config/lutecepowers/site-successors.tsv: its private themes and packs, kept out of this toolkit); its v8 branch
in its repository on GitHub or GitLab (develop, with a Lutece 8 parent); otherwise it has to be migrated first. Stop and show the user the list, the dependency order, and propose to migrate each
missing artefact with the lutece-update-plugin skill, one at a time, in its own clone, then to build it into
.migration/m2. Resume the site only when the gate has no NO-V8 left, or when the user decides that an artefact
leaves the site (then it is a plugin decision of phase C, never a silent drop).
PHASE C — The target composition
Pick the layer (reference/layers.md): the organisation's pack of the family when there is one, else the starter
of the family, else an explicit list. Then map every plugin of the before war, in .migration/site-decisions.md,
one line each:
- plugin <name>: <provided by the pack | declared by the site | dropped because ...>
A plugin the before war ships and the new layer does not bring (a starter that dropped the address modules, a module moved out of the BOM) is declared by the site or dropped with the owner's agreement. Show the plan.
PHASE D — The steps
| Step | File (steps/) | Scope |
|---|---|---|
| 1 | 1-pom.md | parent, BOM import, starter or pack, versions, types, profiles |
| 2 | 2-configuration.md | overrides, per-environment conf to MicroProfile profiles, Spring contexts, database, secrets |
| 3 | 3-webapp.md | plugins.dat, template and JSP overrides, web.xml, static files |
| 4 | 4-database.md | SQL of the site, an existing database, the settings the takeover changes |
| 5 | 5-runtime.md | Liberty server.xml, server.env, jvm.options, the JDBC driver |
After each step: site-assemble.sh . into target/, then site_check.py check (phase E). Change what the level
requires, nothing else.
PHASE E — Nothing lost (the gate)
bash ${LUTECEPOWERS_ROOT}/tools/site-assemble.sh . --out .migration/after --repo .migration/m2
python3 ${LUTECEPOWERS_ROOT}/tools/site_check.py check . --war .migration/after \
--before .migration/before[-<env>] --before-ref <before_ref> [--as-profile <env>] --m2 .migration/m2
bash ${LUTECEPOWERS_ROOT}/tools/lutece-check.sh .
--as-profile <env> compares the war of one v7 environment with the v8 war read under that profile: run it once
per environment. Every difference is a FAIL until .migration/site-decisions.md answers it (- key|plugin|file|profile <id>: <reason>): an effective value the site set, or an artefact it added or removed, changed (SI80); a plugin no
longer shipped (SI81); a file of the site overlay no longer shipped or no longer the site's (SI82); a profile the
site names that appears or disappears (SI84). A key the site sets that the war no longer reads while it reads the
same key under a new name, with another default, is a setting lost (SI27 FAIL): carry it under the new name. A
reason states the evidence ("same value in the pack, read in its
war", "no form uses the address field: SELECT … returned 0"), never "provided elsewhere". Values of the core and of
the plugins that change by themselves between versions are listed apart (SI85, a file), for reading, not decisions.
Fix every FAIL at its source and every WARN, or write its reason in the hand-over. The runtime dump of phase F
(SI87) settles what the static model cannot see: the values a remote ConfigSource serves (Vault, at 500, above the
site's conf/override), the environment, the Liberty variables.
PHASE F — Run it
Dispatch one subagent: "invoke the lutece-e2e skill on this site (init-e2e.sh <site> --target site, then lpe2e)
and follow it; report the startup exceptions, the back-office login, the front-office home, the screens of every
plugin the site ships, the configuration dump and the Lutece versions the bench forced over the site's BOM". The
bench assembles the site with its own pom (E2E_SITE_PROFILE names a profile without the environments' remote
configuration source, Vault), with the latest Lutece 8 snapshots of the core and of plugin-liquibase forced over the
BOM, and tests every screen of the site. It writes artifacts/site-drift.txt when the site ships an older core than
the one tested: an older core in the BOM is a finding. The configuration probe is in the bench site:
curl "http://localhost:$(lpe2e port)/<context>/site-config-dump.jsp?token=$(cat e2e/artifacts/site-config-dump.token)"
on a running bench (KEEP=1 lpe2e). While it runs, edit nothing. Then, with the dump and the container environment
it brings back (docker exec <app> env):
python3 ${LUTECEPOWERS_ROOT}/tools/site_check.py config .migration/after --against <dump> --env <env file> [--profile <p>]
It must report no disagreement: the model of phase E is trusted only where the container agrees with it. The bench
runs without the profiles of the environments: it never reaches their systems (identity provider, search cluster,
notification gateway). A fresh install proves nothing about an upgrade: a v7 site writes the scripts of its takeover
(site_check.py takeover .migration/before-default .migration/after --out .migration/takeover, SI13-SI14), then runs
lpe2e upgrade with E2E_V7_WAR (its v7 war, assembled without profile, carrying plugin-liquibase of the v7 line), E2E_V7_DUMP (the recette dump of phase
A) and E2E_TAKEOVER (.migration/takeover): the v7 site starts once on the dump with plugin-liquibase, the v8 site takes it over the way
reference/database.md §1 describes (core first, then the components), and artifacts/datastore-lost.txt lists the
settings the takeover changed or removed, to set again (§2). The takeover scripts are not a bench device: they set what
plugin-liquibase cannot read on a v7 database installed with Ant (the version of a component it could not resolve,
the former identity of a renamed one), and an environment that starts without them can lose tables. Hand them over;
E2E_TAKEOVER on a directory of two empty files shows the start without them (reference/upgrade.md of lutece-e2e). A v8 site runs lpe2e upgrade with E2E_BEFORE_WAR (the war
site-bench-war.sh .migration/before <file> writes): the version the environments run creates its database, the
new one takes it over; every plugin artifacts/upgrade-disabled.txt lists is disabled after the deployment (a
renamed plugin still listed in plugins.dat under its former name, SI43), every name upgrade-orphans.txt lists
has status keys nothing reads any more.
PHASE G — Hand over
Give the user, copied from the tools and never summarised from memory: whether the database upgrade was proven on
a recette dump (and the settings datastore-lost.txt lists), the two takeover scripts the environments' databases
need, the gate table, the check result with the
decisions file, the runtime comparison, the bench result with each failure attributed (site, plugin, core), the
profile each environment must set, the secrets to put in Vault (SI30), and git status --porcelain. Never
commit. A commit message the user writes from this is true by construction: it lists what the tools listed.
An example of a v8 site on the BOM and a starter, with its Open Liberty configuration and Kubernetes manifests: the
mono-instance branch of https://github.com/lutece-platform/lutece-guide-kubernetes-lutece.
A site that must then run as several replicas: lutece-site-multi-instance (example: the multi-instance branch of the
same repository).
Rules the tools cannot enforce
- Never delete a key, a file or a dependency because "the pack, the starter or a configuration library provides
it" before
checkproves the effective value, the plugin or the file is the same after (SI80-SI82). - Never rename a MicroProfile profile, or introduce one, without the user confirming the profile each environment
sets (
mp.config.profile/MP_CONFIG_PROFILE, often outside the repository): SI84. - Never write a secret into the repository, even as a draft:
envconfleaves secrets out, and so does every file you write. List them for Vault or the environment. - A library that imposes configuration (a ConfigSource in a jar) is a set of decisions: each key it changes appears
in SI80 and is kept or overridden in
conf/override, deliberately. - Never convert what never applied: a file of
src/conf/<env>/placed where v7 read nothing (SI32), a context v7 never loaded. Carrying it would change the environment's behaviour; list it for the owner instead. - The site's
webapp/wins over every dependency, but two dependencies shipping the same file land in an unspecified order (SI57): the site ships its own copy when it matters.
Updating a Lutece BO template
Replace raw HTML with the admin FreeMarker macros. This skill does not list the macros — the core sources do, and they are the only current version. Read them.
Step 0 — Discover the macros
Root: ~/.lutece-references/lutece-core/webapp/WEB-INF/templates/admin/themes/tabler/
(reference clones are synced at session start; see using-lutecepowers).
One file per macro, the filename is the macro name, grouped by domain. Start here:
cd ~/.lutece-references/lutece-core/webapp/WEB-INF/templates/admin/themes/tabler
ls -d */*/ # every domain: components, forms, layout, elements, pages, utilities...
grep -rh '^<#macro' components/table/ # every signature of one domain, with all its parameters
grep -rl '^<#macro *modal\b' . # which file defines one macro
sed -n '1,25p' components/box/box.ftl # its documented parameters and a snippet
Every .ftl opens with a header block — Macro:, Description:, Parameters: with type and whether
optional. That header is the contract.
Read a macro's file before using it for the first time in a session. A wrong parameter name renders an empty element without raising an error.
If the clone is missing, the theme also ships in any assembled site under
target/lutece/WEB-INF/templates/admin/themes/tabler/.
Steps
- Read the target template.
- For each block of raw HTML, find the domain that covers it (step 0) and read the signatures.
- Rewrite using only macros.
- Do not touch the i18n files unless asked.
Additional resources
- Situational patterns — bulk actions, search and filter headers, editor toolbars, modals: reference/patterns.md
- Complete page examples to copy from: reference/examples.md
- List layout, messages and i18n keys that exist:
rules/template-back-office.md
Mandatory conventions
Detect and ignore email templates
Some .html files present in webapp/WEB-INF/templates/admin/plugins/<plugin>/ are not BO templates — they are email body templates rendered by Java code (e.g. MyNotificationService.java, MyEntityJspBean.sendMail) and sent to end users. These templates must remain pure table-based HTML for compatibility with mail clients (Outlook, Gmail, Apple Mail, etc.) — never migrate them to the BO macros.
Signs to detect an email template:
- The file contains
<table cellpadding="0" cellspacing="0">,<td>with inlinestyle="...", comments<!--[if mso]>or<!--[if gte mso 9]> - Presence of a
<meta name="x-apple-disable-message-reformatting">, of classes likeemail-bg,darkmode-bg,email-container - Variables like
${content_1},${content_2},${mail_content},${unsubscribe_key},${recipient_email} - The file name contains
model_,send_,confirm_mail,notification_ - Loaded from Java via
AppTemplateService.getTemplate(TEMPLATE_XXX, ...)then sent viaMailService.sendMail*
Action: leave the file strictly unchanged and report it to the user as "out of BO migration scope". Common examples:
confirm_mail.html,confirm_mail_css.html— subscription confirmation emailsend_my_mail.html— sent email bodytemplates/model_my_mail.html,templates/model_my_section.html— email fragments (sections)
Overall structure of a BO page
- Always structure:
<@pageContainer>→<@pageColumn>→<@pageHeader>→ content - The
<@pageHeader>contains the page title and the main action buttons nested (create, filter, etc.) - The main content is in a
<@box>+<@boxBody>or directly in a<@manageFeature> - Never use a
<@box>as the root container of a full page (recap, confirmation, dedicated form). A template that starts with<@box>instead of<@pageContainer>must be restructured with the standard hierarchy<@pageContainer>→<@pageColumn>→<@pageHeader>, the<@box>becoming a content container under the header - Editor page exception: the
<@tform>may wrap the<@pageHeader>and the content (see the editor toolbar pattern in reference/patterns.md) - Embedded panels/fragments exception: templates loaded as tab content or fragments included in a parent page do not use
<@pageContainer>/<@pageColumn>/<@pageHeader>. They structure their content directly with<@box>/<@boxHeader>/<@boxBody>. Each logical section is a separate<@box>with a title in<@boxHeader>and the action buttons viaboxTools=true.
When to use @table vs @manageFeature
Rule: rules/template-back-office.md § List Layout. @manageFeature for entity lists with CRUD actions (core and forms manage pages), @table for tabular data (several data columns, reports, child-entity tables). Convert an existing @table to @manageFeature only when its rows are entities with edit/delete actions.
@manageFeature - Entity lists
- Each item is a card with flexible columns
- Core after 8.0.2-beta-04:
<@manageFeature layout='list'>renders the items as rows of one box (plugin-workflowmanage_workflow.html); on 8.0.2-beta-04 the parameter is dropped (TD16) - Main column (name/title):
<@manageFeatureItemColumn auto=true flex=false>(withflex=falsefor multi-line content) - Secondary columns with label:
<@manageFeatureItemColumn auto=true flex=false valign='top'>with a<@p class='fw-bold fs-3'>as column title - Actions column:
<@manageFeatureItemColumn align='end'>(right-aligned) - Checkbox column (selection):
<@manageFeatureItemColumn auto=true>with<@checkBox orientation='switch' /> - No need for
<@box>/<@boxBody>around it,@manageFeatureItemgenerates its own cards
@tform boxed=true - Replacing @box
- When a
<@box>/<@boxBody>only contains a<@tform>or a<@manageFeature>, remove the<@box>and addboxed=trueto the<@tform> - Same when a
<@box>only contains a<@table>: the table comes out of the box and the box is removed
@empty - Empty state (MANDATORY)
- Always test whether the list is empty before displaying a
<@manageFeature>or a<@table>with iterated data - When the list is empty, display a message with
<@empty>in a<@card> - Params:
title,iconName,subtitle,actionTitle,actionUrl,actionBtn,actionIcon - Choose an
iconNamerelevant to the business context (e.g.:calendar-offfor appointments,users-minusfor users,inbox-offby default) - Standard pattern (full page):
<#if list?has_content> <@manageFeature>...</@manageFeature> <#else> <@card> <@empty title='#i18n{...noResult}' iconName='inbox-off' subtitle='#i18n{...help}' actionTitle='#i18n{...buttonCreate}' actionUrl='...' /> </@card> </#if> - Simplified pattern (widget/dashboard, without action button):
<#if list?has_content> <@manageFeature>...</@manageFeature> <#else> <@empty title='#i18n{...empty}' iconName='inbox-off' /> </#if>
@tform - Forms
type='horizontal'for standard forms (label on the left, input on the right)type='inline'only for a hidden form holding a single submit button (Import, Export actions)boxed=truewhen the form replaces a<@box>wrapper (see convention above)- Use
<@formGroup>to group label + input withlabelKey,helpKey,mandatory
@messages - Info/error messages
- Place
<@messages infos=infos![] errors=errors![] warnings=warnings![] />at the top of the main content (after<@pageHeader>); in the editor pattern the errors call goes in the relevant form ![]is mandatory: the variables are absent until a message is added (rules/template-back-office.md§ Messages)- Do not duplicate
<@messages>: a single call per type
@alert - Contextual alerts
- Use
<@alert color='...' title=... />(self-closing withtitle) for simple messages - When the alert content is conditional (e.g.: validation error message), precompute the text in a variable then pass it via
title:<#if error.mandatoryError> <#assign errorMsg = error.errorMessage> <#else> <#assign errorMsg = '#i18n{plugin.message.mandatory.entry}'> </#if> <@alert color='danger' title=errorMsg /> - Do not use
<@alert>content</@alert>when a simpletitleis enough — prefer the self-closing form color:'danger','warning','info','success'iconTitleto add an icon:<@alert color='warning' iconTitle='exclamation-circle'>dismissible=trueto allow manual closing
@checkBox - Checkboxes
- Always add
orientation='switch'on all<@checkBox>to use the standard switch (toggle) style of the Tabler theme - Do not use the
labelForparameter on<@checkBox>when anidis already present (redundant)
@button / @aButton - Buttons
<@button>for form actions (submit)<@aButton>for links styled as buttons (navigation)buttonIconuses the Tabler icons (without prefix):'edit','trash','plus','check','times'hideTitle=['all']for icon-only buttons in listshideTitle=['xs','sm', 'md', 'lg']for toolbar buttons (icon-only except on large screens)- The Cancel button of a form:
<@aButton href='…' title='#i18n{portal.util.labelCancel}' buttonIcon='x' color='light' />; the header back link:labelBack,color='light'. Nevercancel=true(TD51) nor a cancel without colour (TD56) color:'primary','light','success','danger','warning','info'. The neutral button iscolor='light':aButton.ftl/button.ftlturncolor='secondary'andcancel=trueinto the classbtn-default, which no admin stylesheet defines (rules/template-back-office.md§ Back-office macro bugs)
@paginationAdmin - Pagination
- Always place after the
<@table>or<@manageFeature> combo=1to show the selector of the number of items per page- Condition the display on the number of items:
<#if list?size gte 10><@paginationAdmin ... /></#if>
@columns - Responsive grid
- Use the named parameters:
<@columns sm=9>,<@columns md=6 lg=4> - For an auto column:
<@columns>without a size parameter offsetMdfor the offset:<@columns md=2 offsetMd=5>
@icon - Tabler icons
- The
ti ti-prefix is added automatically <@icon style='edit' />→<i class="ti ti-edit">- Additional classes via
class:<@icon style='check' class='me-1' />
i18n
- All displayed texts must use
#i18n{plugin.key} - Do not write hardcoded text in the template
- Reuse existing
portal.util.*keys; the list of existing keys and of the ones that do NOT exist (labelActive,labelInactive,labelSave,labelAdd):rules/template-back-office.md§ i18n
Navigation, dialogs and forms (blocking: verify-migration.sh TM10/TM12, scanner TD48/TD50)
- No offcanvas, ever. Content written in the page itself (a search form, a small creation form, properties) goes
in a modal opened by a button:
<@button type='button' title='#i18n{portal.util.labelSearch}' buttonIcon='search' params='data-bs-toggle="modal" data-bs-target="#searchModal"' /> <@modal id='searchModal'> <@modalHeader modalTitle='#i18n{portal.util.labelSearch}' /> <@modalBody><@tform action='…'>…</@tform></@modalBody> </@modal> - Content that is another page (a create or modify screen) is reached by a plain link to that page; the page
is a full screen with its own back link:
<@aButton href='jsp/admin/plugins/myplugin/ManageItems.jsp?view=createItem' buttonIcon='plus' title='#i18n{myplugin.manage_items.buttonCreate}' /> - No inline form (three fields or more side by side):
rules/template-back-office.md§ No inline form.
What NOT to do
- Do not use raw HTML when a macro exists
- Do not add JavaScript unless requested
- Do not wrap a
<@manageFeature>in a<@box>(the items are already cards) - Do not use
<@table>for an entity list with CRUD actions → convert to<@manageFeature>; keep@tablefor tabular data (rules/template-back-office.md§ List Layout) - Do not put the creation form in a separate column → link to the creation page, or a
<@modal>for a short form - Do not use
<@offcanvas>→<@modal>for content of the page, a plain<@aButton href>for another page - Do not duplicate
<@messages>(a single call per message type) - Do not wrap a
<@tform>in a<@box>when the box only serves to contain the form → useboxed=true - NEVER iterate a list (
<#list>) without first testing whether it is non-empty (?has_content) and displaying a<@empty>otherwise
Updating a Lutece FO template
Replace raw HTML with the skin FreeMarker macros. This skill does not list the macros — the core sources do, and they are the only current version. Read them.
Step 0 — Discover the macros
Root: ~/.lutece-references/lutece-core/webapp/WEB-INF/templates/skin/themes/macros/
(reference clones are synced at session start; see using-lutecepowers).
One file per macro, the filename is the macro name, grouped by domain. Every FO macro name starts
with c — cForm, cBtn, cAlert, cCard, cSelect. A name without that prefix is almost always
a Back Office macro: it resolves (the admin commons are auto-included everywhere) but renders admin
markup in a site page. Treat it as a defect.
A macro file is loaded only when skin/themes/theme_commons_macros.ftl registers it (<@cMacro name=...>):
a .ftl present in the tree but absent from that list is unreachable.
cd ~/.lutece-references/lutece-core/webapp/WEB-INF/templates/skin/themes/macros
ls -d */*/ # every domain: components/…, forms/…, elements/…, layout/…
grep -rh '^<#macro' forms/inputs/ # every signature of one domain, with all its parameters
grep -rl '^<#macro *cBtn\b' . # which file defines one macro
sed -n '1,25p' components/card/cCard.ftl # its documented parameters and a snippet
Every .ftl opens with a header block — Macro:, Description:, Parameters: with type and whether
optional. That header is the contract.
Read a macro's file before using it for the first time in a session. A wrong parameter name renders an empty element without raising an error.
If the clone is missing, the theme also ships in any assembled site under
target/lutece/WEB-INF/templates/skin/themes/macros/.
Steps
- Read the target template.
- For each block of raw HTML, find the domain that covers it (step 0) and read the signatures.
- Rewrite using only macros.
- Do not touch the i18n files unless asked.
Additional resources
- Per-macro and situational rules — inputs, selects, checkboxes, steps, cards, figures, lists, tables, jQuery to vanilla JS: reference/patterns.md
- Complete page examples to copy from: reference/examples.md
- Front-office conventions:
rules/template-front-office.md
Cross-cutting conventions
Global structure
- Always wrap a page template in
<@cTpl>...</@cTpl>: it is the theme override hook (skin/themes/<code>/tpl/<same path>,global_theme_commons.ftl). Page-local<#macro>and<#assign>live inside it; FreeMarker hoists macro definitions, their position is style - A page is
<@cTpl>→<@cContainer>→<@cRow>→<@cCol cols=...>→ content: the shape of every coreskin/site/*.html(examples.md § Page skeleton). Only a fragment included by another template (portlet body, component) skipscTplandcContainer - Titles:
level=2for the page title (theh1belongs to the frameset),level=3below - Forms:
<@cForm>→<@cField for= required=true>→ input → a<@cRow>of<@cBtn>at the end. No<@cFieldset>around a whole form - Models to copy:
~/.lutece-references/lutece-core/webapp/WEB-INF/templates/skin/site/*.htmlandskin/search/search_results.html - The theme ships component CSS under
webapp/themes/skin/lutece/css/{components,layout}andthemes/skin/shared/css(bl-*,search-*,tile*,lutece-ds-empty): target those classes throughclass=, never inline styles
Bootstrap 3 → Bootstrap 5 classes
help-block→form-text(help text under a field)control-label→ remove (handled by the macro)col-xs-*→col-*(BS5 has noxsbreakpoint)has-error→is-invalid(validation)btn-default→btn-secondary
FreeMarker HTML entities
- Replace
>withgtin FreeMarker conditions:<#if list?size gt 0>(not>) - Replace
<withltin FreeMarker conditions:<#if value lt 10>(not<)
FreeMarker ternary operator
- FreeMarker does NOT support the C-style ternary operator
condition ? a : b - Always use
condition?then(a, b):<#-- INCORRECT — causes a ParseException --> <#assign myClass = 'base' + (hasError ? ' error' : '')> <#-- CORRECT --> <#assign myClass = 'base' + hasError?then(' error', '')> - For boolean expressions, put the condition in parentheses if necessary:
(x != '')?then('a', 'b')
cForm - Forms
- Attributes not covered by the parameters via
params:params='name="createAccount"'
i18n
- All displayed text must use
#i18n{plugin.key} - Do not write hardcoded text in the template
Code readability
- Expand the
<#list>with conditional logic across multiple lines, do not leave compact inline blocks when they contain nested<#if>
BO vs FO macros - Do not mix
- Never use BO macros (admin/Tabler) in an FO (skin) template: any macro whose name does not start with
c(<@p>,<@div>,<@ul>,<@li>,<@h>,<@messages>,<@aButton>,<@button>,<@box>,<@formGroup>,<@tform>,<@select>,<@option>...). They do resolve in a skin template, because the admin commons are auto-included for the whole FreeMarker configuration (core.xmlfreemarker-macro-files,CommonsService), which is exactly why the misuse is silent: the page renders with admin markup and admin CSS hooks - BO
<@p>→<@cText>,<@div>→<@cBlock>,<@ul>/<@li>→<@chList>/<@chItem>,<@h level=n>→<@cTitle level=n>,<@icon style=>→<@cIcon name=> - Exception, the cross-context fragment: a skin file included by an admin template (of this plugin or another — grep the references for
<#include "/skin/<path>") keeps thec*macros but dropscTpl,cContainerandcForm. The first two are the page-override hooks of a site page and a fragment is not a page;cForminjects the front-office validation modules, which an admin page does not load. Every otherc*macro emits the same Bootstrap 5 in both contexts. - BO → FO equivalents:
<@messages infos=infos errors=errors />→<#list (infos![]) as info><@cAlert type='info' title=info /></#list> <#list (warnings![]) as warning><@cAlert type='warning' title=warning /></#list> <#list (errors![]) as error><@cAlert type='danger' title=error.message! /></#list>infosandwarningsareSet<String>(${info.message}throws),errorsareMVCMessage/ParamErrorobjects:rules/template-front-office.md§ Model Messages.<@aButton href='...' size='sm'>→<@cBtn href='...' class='outline-secondary btn-sm'>(choose the color according to the context:outline-primary,outline-secondary, etc.)<@button>→<@cBtn><@tform>→<@cForm><@formGroup>→<@cField>or<@cBlock><@select>/<@option>→<@cSelect>/<@cOption>
style attribute on macros
- Do not use
style='...'directly as a macro parameter — it is not a valid parameter of<@cCol>,<@cTitle>,<@cTd>, etc. - Use
params='style="..."'if absolutely necessary, or prefer a CSS class:<#-- INCORRECT --> <@cTitle level=2 style='margin-bottom:30px'> <@cTd style='vertical-align: middle'> <#-- CORRECT --> <@cTitle level=2 class='mb-4'> <@cTd class='align-middle'>
FreeMarker conditions - Empty if branch
- Never leave an empty
<#if>branch with all the content in<#else>— invert the condition:<#-- INCORRECT — empty if branch --> <#if modifDateAppointment?? && modifDateAppointment> <#else> ...content... </#if> <#-- CORRECT — inverted condition --> <#if !(modifDateAppointment?? && modifDateAppointment)> ...content... </#if>
FreeMarker - Modern syntax (?? vs ?exists)
- Always use
??instead of?exists—?existsis obsolete in FreeMarker 2.3+<#-- INCORRECT --> <#if entry.helpMessage?exists && entry.helpMessage != ''> <#-- CORRECT --> <#if entry.helpMessage?? && entry.helpMessage != ''> - Applies everywhere: variables, object properties, optional parameters
??tests presence, not content. On an XMLNodeModel(portlet templates fed byNodeModel,${quicklinks.entry}-style paths) a missing child is an empty node list, present and non-null:node.child??is true andnode.child!is not the default. Only?has_contenttells an empty node list from a filled one; use it for XML-backed values
Dynamic classes (conditional concatenation)
- Always pre-build the
classstring with<#assign>rather than inline FreeMarker in theclassparameter<#-- INCORRECT — inline FreeMarker in class --> <@cBlock class='bl-body<#if !blog.displayToc> bl-body-one-col</#if>'> <#-- CORRECT — assign before the macro --> <#assign bodyClass = 'bl-body'> <#if !blog.displayToc><#assign bodyClass = bodyClass + ' bl-body-one-col'></#if> <@cBlock class=bodyClass> - The
?then(a, b)pattern is also acceptable for only 1 or 2 classes:<#assign cardClass = 'bl-card' + isActive?then(' is-active', '')>
Dead / duplicated code
- During a migration, always re-read the result to detect any buggy copy-paste (e.g. a duplicated
<#assign breadcrumbItems...>in another container without use) - Remove commented-out HTML blocks (
<!-- ... -->) that are not genuinely useful as documentation - Remove
<!-- TOC -->,<!-- BODY -->etc. comments whose intent is obvious in the structured FreeMarker code
What NOT to do
- Mistakes not to copy:
imgTitle=oncCard(not a parameter, svg dropped),@parisIcon(undefined in the core),cBtn class='btn btn-primary'(rendersbtn btn-btn btn-primary),cCol class='12 col-sm-5', stray" />text after an icon,name='back'oncBtn,arrow-rightfor a back button, French copy inhome=/title=,<@cIcon name='#i18n{...}'> - Do not flip the line endings of a file (CRLF stays CRLF) and do not overwrite a plugin's templates with wholesale copies of the theme's: both widen the diff
- Do not add JavaScript unless requested or required by a macro
- Do not use deprecated macro parameters
- Do not wrap a
<@cAlert>in an unnecessary<@cBlock>or<@cCard> - Do not duplicate the
btn btn-prefix in the class of<@cBtn> - Do not leave orphan
<li>without a parent<@chList> - Do not wrap each
<@chItem>in a<@cRow>/<@cCol>— list items go directly inside<@chList> - Do not leave raw HTML tags (
<br>,<hr>,<b>,<i>, etc.) when a macro exists or when they are unnecessary — remove formatting<br> - Do not use
<@cCol cols='xs-12'>— simply use<@cCol>(full-width column by default) - Do not use
— replace with a normal space or remove if unnecessary; a requiredlabelwith no visible title keeps its real text withlabelClass='visually-hidden' - Do not use
style='...'on macros — useclasswith Bootstrap utilities orparams='style="..."'as a last resort - Do not mix BO and FO macros — check that all the macros used exist in the skin/FO context
- Do not use
>/<in FreeMarker conditions — usegt/lt - Do not self-close
<@cInline>— always</@cInline>, even when the content is empty - Do not inline FreeMarker in the
classparameter of a macro — pre-build the string with<#assign>(also applies tohref,id, etc.) - Do not inline
?string('yyyy-MM-dd')directly inparams='datetime="..."'— nested quotes break the FreeMarker parser. Pre-build with<#assign>. - Do not keep a separate
<figcaption>— use thecaptionparameter of<@cFigure> - Do not use
<@cBtn>for clickable cards — use<@cLink class='ma-card' label=''>when it is a clickable area not styled as a button - Do not keep duplicated/dead code during the migration — re-read the result to spot buggy copy-paste and unnecessary
<!-- ... -->comments - NEVER keep jQuery in a migrated template (
$(...),jQuery(...),.on(),.addClass(),.animate(),$(document).ready(), etc.) — the theme does not load jQuery, the code would crash at runtime. Always rewrite in vanilla JS (see the dedicated section)
Lutece v8 review
Read-only compliance review of the current Lutece 8 project. The full procedure lives in ${LUTECEPOWERS_ROOT}/agents/lutece-v8-reviewer.md. This skill only decides how to run it on your harness.
Steps
- Resolve the plugin root (
LUTECEPOWERS_ROOTfrom the session context, or the fallback inusing-lutecepowers). - Read
${LUTECEPOWERS_ROOT}/agents/lutece-v8-reviewer.md. - Run it:
- Harness with a native agent named
lutece-v8-reviewer(Claude Code, Cursor, Grok): invoke that agent on the current directory. - Harness with a generic subagent tool (Codex
spawn_agent, OpenCodetask): dispatch one subagent whose prompt starts withLUTECEPOWERS_ROOT=<literal absolute path>(the subagent does not see your session context), then the whole file content, then: "Review the project in . Do NOT modify any files. Reference implementations: ~/.lutece-references/." - No dispatch: follow the file yourself, step by step, without modifying any source file.
- Harness with a native agent named
- Return the report in the format defined at the end of that file. Never fix anything unless the user asks after reading the report.
Lutece 8 Workflow Module Development
Complete guide for creating and modifying Lutece 8 workflow modules.
Before writing workflow code, consult
~/.lutece-references/lutece-wf-module-workflow-forms/(the reference module) (search the references).
Workflow Architecture
plugin-workflow (core)
├── library-workflow-core # Base interfaces and classes
│ ├── ITask, Task, SimpleTask
│ ├── ITaskType, TaskType
│ ├── ITaskConfigService, TaskConfigService
│ └── ITaskConfigDAO
│
└── module-workflow-{xxx} # Custom module
├── business/ # Config + DAO
├── service/ # Task + Producers
└── web/ # TaskComponent
Workflow Module Structure
module-workflow-{pluginName}/
├── pom.xml
├── src/
│ ├── java/fr/paris/lutece/plugins/workflow/modules/{pluginName}/
│ │ ├── business/
│ │ │ ├── Task{Name}Config.java
│ │ │ └── Task{Name}ConfigDAO.java
│ │ ├── service/
│ │ │ ├── Task{Name}.java
│ │ │ ├── TaskType{Name}Producer.java
│ │ │ ├── Task{Name}ConfigProducer.java
│ │ │ └── Task{Name}ConfigServiceProducer.java
│ │ ├── web/
│ │ │ └── {Name}TaskComponent.java
│ │ └── resources/
│ │ └── workflow-{pluginName}_messages.properties
│ ├── sql/plugins/workflow/modules/{pluginName}/plugin/
│ │ └── create_db_workflow-{pluginName}.sql
│ └── main/resources/META-INF/
│ └── beans.xml
└── webapp/WEB-INF/
├── conf/plugins/
│ └── workflow-{pluginName}.properties
├── plugins/
│ └── workflow-{pluginName}.xml
└── templates/admin/plugins/workflow/modules/{pluginName}/
├── task_{name}_config.html
├── task_{name}_form.html
└── task_{name}_information.html
Build order
Thirteen files, in this order. Steps 1 to 7 and 10 are full class and template models, kept apart because they are long; open the file when you reach them.
| # | Produces | Where |
|---|---|---|
| 1 | the ITask implementation — what the task does when the action fires | reference/task-classes.md |
| 2 | the config entity holding the task's settings | idem |
| 3 | the config DAO | idem |
| 4 | the TaskType CDI producer that registers the task | idem |
| 5 | the config producer | idem |
| 6 | the config service producer | idem |
| 7 | the TaskComponent — back-office display and validation | reference/task-component.md |
| 10 | the FreeMarker templates for the config and information views | idem |
| 8, 9, 11, 12, 13 | properties, plugin descriptor, SQL, i18n, pom — below | this file |
8. Configuration Properties
webapp/WEB-INF/conf/plugins/workflow-{pluginName}.properties
# Task {Name} Configuration
workflow-{pluginName}.task{Name}.key=task{Name}
workflow-{pluginName}.task{Name}.titleI18nKey=module.workflow.{pluginName}.task.{name}.title
workflow-{pluginName}.task{Name}.beanName=workflow-{pluginName}.task{Name}
workflow-{pluginName}.task{Name}.configBeanName=workflow-{pluginName}.task{Name}Config
workflow-{pluginName}.task{Name}.configRequired=true
workflow-{pluginName}.task{Name}.formTaskRequired=false
workflow-{pluginName}.task{Name}.taskForAutomaticAction=true
9. Plugin Descriptor
webapp/WEB-INF/plugins/workflow-{pluginName}.xml
<?xml version="1.0" encoding="UTF-8"?>
<plug-in>
<name>workflow-{pluginName}</name>
<class>fr.paris.lutece.portal.service.plugin.PluginDefaultImplementation</class>
<version>1.0.0-SNAPSHOT</version>
<description>module.workflow.{pluginName}.plugin.description</description>
<provider>module.workflow.{pluginName}.plugin.provider</provider>
<provider-url>http://lutece.paris.fr</provider-url>
<icon-url>themes/admin/shared/images/apps.svg</icon-url>
<copyright>Copyright (c) {currentYear}</copyright>
<db-pool-required>1</db-pool-required>
<core-version-dependency>
<min-core-version>8.0.0</min-core-version>
<max-core-version/>
</core-version-dependency>
</plug-in>
11. SQL
src/sql/plugins/workflow/modules/{pluginName}/plugin/create_db_workflow-{pluginName}.sql — Liquibase header required (rules/sql-liquibase.md; reference create_db_workflow-forms.sql:1-3):
-- liquibase formatted sql
-- changeset workflow-{pluginName}:create_db_workflow-{pluginName}.sql
-- preconditions onFail:MARK_RAN onError:WARN
DROP TABLE IF EXISTS workflow_task_{name}_config;
CREATE TABLE workflow_task_{name}_config (
id_task INT NOT NULL,
title VARCHAR(255) DEFAULT NULL,
target_state VARCHAR(255) DEFAULT NULL,
notify_user SMALLINT DEFAULT 0,
PRIMARY KEY (id_task)
);
12. i18n
workflow-{pluginName}_messages.properties
# Plugin
plugin.description=Workflow module for {pluginName}
plugin.provider=City of Paris
# Task {Name}
task.{name}.title={Name} Task
task.{name}.config.title=Title
task.{name}.config.targetState=Target State
task.{name}.config.notifyUser=Notify User
task.{name}.form.info=This action will change the state to:
task.{name}.info.targetState=Target State
task.{name}.info.noConfig=No configuration found
13. pom.xml Dependencies
library-workflow-core comes transitively through plugin-workflow; do not declare it (reference: module-workflow-forms/pom.xml).
<dependencies>
<dependency>
<groupId>fr.paris.lutece</groupId>
<artifactId>lutece-core</artifactId>
<version>[8.0.0,)</version>
<type>lutece-core</type>
</dependency>
<dependency>
<groupId>fr.paris.lutece.plugins</groupId>
<artifactId>plugin-workflow</artifactId>
<version>[7.0.0,)</version>
<type>lutece-plugin</type>
</dependency>
<!-- Business plugin if needed -->
<dependency>
<groupId>fr.paris.lutece.plugins</groupId>
<artifactId>plugin-{pluginName}</artifactId>
<version>[1.0.0,)</version>
<type>lutece-plugin</type>
</dependency>
</dependencies>
Naming Conventions
| Element | Pattern | Example |
|---|---|---|
| Module | module-workflow-{plugin} | module-workflow-forms |
| Package | fr.paris.lutece.plugins.workflow.modules.{plugin} | |
| Task class | Task{Name} | TaskEditFormResponse |
| Config class | Task{Name}Config | TaskEditFormResponseConfig |
| DAO class | Task{Name}ConfigDAO | TaskEditFormResponseConfigDAO |
| TaskType producer | TaskType{Name}Producer | TaskTypeProducer (forms groups them) |
| Config producer | Task{Name}ConfigProducer | EditFormResponseConfigProducer |
| Component | {Name}TaskComponent | EditFormResponseTaskComponent |
| Bean names | workflow-{plugin}.task{Name} | workflow-forms.taskEditFormResponse |
| Properties prefix | workflow-{plugin}.task{Name}. | |
| Templates | task_{name}_*.html | task_edit_form_response_config.html |
| SQL table | workflow_task_{name}_config | workflow_task_edit_form_response_config |
| i18n prefix | module.workflow.{plugin}.task.{name} |
Reference Sources
| Need | Repo to consult | Key files |
|---|---|---|
| Workflow core architecture | lutece-wf-library-workflow-core | src/java/**/service/task/, src/java/**/business/ |
| Workflow plugin (engine) | lutece-wf-plugin-workflow | src/java/**/web/, src/java/**/service/ |
| Complete workflow module (main example) | lutece-wf-module-workflow-forms | Task, Producer, Component, DAO, templates |
| Module with assignment | lutece-wf-module-workflow-forms-automatic-assignment | Automatic assignment pattern |
| Module with upload | lutece-wf-module-workflow-upload | File handling in workflow |
| PDF module | lutece-wf-module-workflow-formstopdf | Document generation |
New Task Checklist
-
Task{Name}Config.java- Config entity -
Task{Name}ConfigDAO.java- DAO with @Named -
Task{Name}.java- Task with @Dependent @Named -
TaskType{Name}Producer.java- Producer @Produces ITaskType -
Task{Name}ConfigProducer.java- Producer @Produces @Dependent @Named config (theconfigBeanName) -
Task{Name}ConfigServiceProducer.java- Producer ITaskConfigService -
{Name}TaskComponent.java- UI with @ApplicationScoped @Named, ctor injectingITaskType+ITaskConfigService -
workflow-{plugin}.properties- TaskType config -
task_{name}_config.html- Config template -
task_{name}_form.html- Form template -
task_{name}_information.html- Info template - SQL table
workflow_task_{name}_config - i18n keys
Using Lutecepowers
Lutecepowers is a set of skills, path-scoped rules, reference sources and scripts for Lutece 8 development. The content is the same on every harness. Only the way you invoke a skill or dispatch a subagent changes, see Harness adaptation.
Scope
- Do the task the user asked and what it needs to pass (a build or a test it is about), nothing wider.
- The user asks to migrate or update the whole project: load
lutece-update-plugin(a site:lutece-update-site). - Lutece 8 debt the task does not need (a project below Lutece 8, code the checks already reject): leave it unless the
user asks, never fix it piece by piece on your own. End your answer by asking, in the user's language, whether to run
lutece-update-plugin(a site:lutece-update-site) on the whole project; load it only when the user says yes. - A project's Lutece version is the one its poms declare (Lutece parent, lutece-core), never what its imports suggest. Below 8 and not being updated, work in its own version: the reads, rules and checks below describe Lutece 8.
Mandatory reads
On a Lutece 8 project, and during an update to it:
- Before writing any Lutece code (bean, service, DAO, XPage, daemon, template): load the
lutece-patternsskill. - Before editing a file matching a rule glob (table below): read that rule file. On Claude Code the rules are also loaded automatically from
.claude/rules/. - Before writing any non-trivial pattern: search
~/.lutece-references/for an existing implementation. The references are the living truth. They are cloned and updated in the background at session start from thedevelopbranch (where v8 lives), and each one also carries the v7 branches that exist upstream (develop_core7,master_core7;develop7.xandmaster7.xfor lutece-core), listed bygit branch -r, to compare a pattern before and after migration. Repositories born in v8 have none. The list of repositories is theREPOSarray of${LUTECEPOWERS_ROOT}/hooks/sync-references.
Plugin root
Skills, agents and scripts refer to the installed plugin directory as ${LUTECEPOWERS_ROOT}.
- The session-start hook prints the absolute value at the top of the context it injects and substitutes it in this text. On Claude Code it is also exported to your shell.
- If the variable is not set in your shell, substitute the literal path from the injected context.
- Every script also resolves the root from its own location, so
bash "${LUTECEPOWERS_ROOT}/tools/<script>.sh"works as soon as the path is right. - Fallback when nothing is injected:
find ~ -maxdepth 7 -path '*/skills/using-lutecepowers/SKILL.md' 2>/dev/null | head -1, then take the directory containingskills/. - When you dispatch a subagent or teammate, write the literal path into its prompt. A subagent does not see this context.
Toolkit
One command checks any Lutece project, a v7 one to migrate as a v8 one:
bash ${LUTECEPOWERS_ROOT}/tools/lutece-check.sh <project>runs every check and prints only the findings of this project, each with what to do;--explain CODEsays what a check proves and how to fix it.bash ${LUTECEPOWERS_ROOT}/tools/doctor.sh <project>checks the machine (Linux or WSL 2, the project outside/mnt/c, the Linux java and Maven 3.9, git line endings, Docker): run it when the user asks for the doctor, and before any work when a build or a bench fails for a reason outside the project.
On Claude Code, every edit of a Lutece file is checked at once: what the edit breaks comes back to you, fix it; what the file or the project already broke comes as a note (see Scope). What a script reports is not repeated in the skills.
Skills
| Skill | Use when |
|---|---|
lutece-brainstorming | Use before any creative Lutece work: a new plugin, a new feature, a new screen, or a behaviour change. Explores intent, requirements and design with the user before any implementation. Triggers on 'I want to build', 'add a feature', 'new plugin', 'how should we design'. |
lutece-cache | Use when adding, fixing or reviewing a cache in a Lutece 8 plugin: AbstractCacheableService, CDI initialization, cache keys, invalidation through CDI events. Triggers on 'cache', 'cacheable', 'invalidate', 'CacheService'. |
lutece-checkup | Use when the user wants the mechanical state of a Lutece 8 project (core, plugin, module, site) without changing it: runs every check script of the toolkit in one pass (verify-migration, template scanner, i18n keys, template parse), summarises the blocking and the warning findings, then asks the user what to do. Triggers on 'checkup', 'bilan', 'état du plugin', 'lance les contrôles', 'vérifie le projet', 'mechanical check'. |
lutece-e2e | Use to give a Lutece 8 plugin, module or site an e2e bench run with one command (lpe2e) on the machine's shared e2e server: the latest Lutece 8 snapshots, Open Liberty and MariaDB kept warm, static + dynamic inventory of every back-office screen and action, Playwright suites (screens, YAML scenarios, forms) with a clean-console rule on warm browsers, server timings, SQL digests, JFR, a compact report, a hot loop (lpe2e watch) that applies a template or Java change in the running application and replays the tests it can break in seconds, and the database upgrade (lpe2e upgrade) lived as an environment lives it. Triggers on 'e2e', 'tests de bout en bout', 'Playwright', 'tester tous les écrans', 'banc de test', 'non-régression BO', 'prouver la migration'. |
lutece-elasticdata | Use when creating or modifying an Elasticsearch DataSource module for Lutece 8: DataSource and DataObject interfaces, CDI auto-discovery, @ConfigProperty injection, batch processing, two-daemon indexing, incremental updates through CDI events. Triggers on 'elasticdata', 'Elasticsearch', 'DataSource module'. |
lutece-lucene-indexer | Use when adding plugin-internal Lucene search to a Lutece 8 plugin: custom index, indexing daemon, CDI events, batch processing. Triggers on 'Lucene', 'full-text search inside the plugin', 'indexer'. |
lutece-patterns | Use before writing or reviewing any Lutece 8 code (CRUD, JspBean, XPage, service, DAO, daemon, template) and when answering questions about Lutece 8 architecture, layered design or coding conventions. Canonical patterns extracted from lutece-core. |
lutece-rbac | Use when adding or reviewing permissions in a Lutece 8 plugin: RBAC entity permissions, ResourceIdService, plugin.xml declaration, JspBean authorization checks. Triggers on 'RBAC', 'permission', 'right', 'authorization', 'ResourceIdService'. |
lutece-scalability-v8 | Use after a migration to v8 to make a Lutece plugin horizontally scalable and prove it: scans scalability anti-patterns, fixes them, deploys a real 3-instance cluster (Liberty, MariaDB, nginx, Hazelcast) and verifies through UI end-to-end tests. Plugin code only: configuring and deploying a site with several replicas is lutece-site-multi-instance. Triggers on 'scalability', 'cluster', 'multi-instance', 'horizontal scaling' for a plugin. |
lutece-site-multi-instance | Use when a Lutece 8 site (packaging lutece-site, OpenLiberty container image) must run as several replicas behind a load balancer, on Kubernetes or elsewhere: shared HTTP session and Lutece cache (Hazelcast, the tested setup, or another store), clustered Quartz daemons, plugins.dat, Liquibase from one replica, shared Forms index, probes, rolling updates. Site configuration and deployment only; the code of a plugin belongs to lutece-scalability-v8. Triggers on 'site multi-instance', 'plusieurs réplicas', 'plusieurs instances du site', 'site en cluster', 'session partagée', 'Hazelcast', 'déployer le site sur Kubernetes', 'replicas'. |
lutece-solr-indexer | Use when creating or modifying a Solr search module for Lutece 8: SolrIndexer interface, CDI auto-discovery, SolrItem dynamic fields, batch indexing, incremental updates through CDI events. Triggers on 'Solr', 'search module', 'SolrIndexer'. |
lutece-update-plugin | Use when bringing a Lutece plugin, module or library to the Lutece level lutecepowers supports, whatever its starting point: migrating from v7 or older (Spring to CDI, javax to jakarta, XML context, templates, tests), or updating a v8 project to the current level (parent, deprecated API, checks, bench). The scripts report every checkable finding with what to do, one agent makes every change, a read-only reviewer and the e2e bench prove the result. Triggers when the user asks to migrate or update the whole plugin, module or library: 'migrate to v8', 'upgrade to Lutece 8', 'migration v7 v8', 'CDI migration', 'passer en v8', 'montée de version', 'mise à niveau v8', 'migrer le plugin', 'mettre à jour le plugin'. |
lutece-update-site | Use when bringing a Lutece site (packaging lutece-site: a site, a pack or a theme) to the Lutece 8 level lutecepowers supports, whatever its starting point: migrating a v7 or older site, or updating a v8 site (parent, BOM, starter, pack). Checks first that every artefact the site ships has a Lutece 8 version and hands the missing ones to lutece-update-plugin; then proves that nothing the site configured, shipped or overrode is lost, by comparing the assembled site before and after and by running it. Triggers when the user asks to migrate or update the whole site: 'migrer un site', 'passer le site en v8', 'mettre à jour le site', 'montée de version du site', 'monter le pack', 'site v8', 'migrate site', 'update site'. |
lutece-update-template-bo | Converts a Lutece Back Office (admin) template to the BO FreeMarker macros of lutece-core (Tabler theme). Discovers the macros from the core sources rather than from a fixed list, so it never goes stale, and applies the house rules that are not readable from the macro files: manageFeature versus table, the mandatory empty state, the page hierarchy, no offcanvas (a modal or a plain link), no inline form, and the e-mail templates that must never be converted. Takes the template path as argument. Triggers on 'migrer un template BO', 'convertir un template admin', 'macros BO', 'thème tabler', 'update back office template'. |
lutece-update-template-fo | Converts a Lutece Front Office (skin) template to the FO FreeMarker macros of lutece-core. Discovers the macros from the core sources rather than from a fixed list, so it never goes stale, and applies the rules that are not readable from the macro files: the FO macros are never the Back Office ones, the FreeMarker syntax to use, Bootstrap 5 classes, and the jQuery that must become vanilla JS. Takes the template path as argument. Triggers on 'migrer un template FO', 'convertir un template skin', 'macros FO', 'front office template', 'update skin template'. |
lutece-v8-review | Use when the user asks to review, audit, check or verify a Lutece plugin, module or library for v8 compliance or conformity, or after a migration to v8 before delivering. Read-only. Dispatches the lutece-v8-reviewer instructions as a subagent, or follows them inline on a harness without dispatch. |
lutece-workflow | Use when creating or modifying a Lutece 8 workflow module: tasks, CDI producers, task components, templates, configuration DAOs. Triggers on 'workflow', 'task', 'workflow module', 'TaskComponent'. |
The reviewer procedure itself is ${LUTECEPOWERS_ROOT}/agents/lutece-v8-reviewer.md, also registered as a native agent where the harness loads agents/.
Rules
Rules are short constraints that apply to files matching a glob. Source files live in ${LUTECEPOWERS_ROOT}/rules/. Tables below are generated from the skill and rule frontmatter (scripts/build-tables.sh).
| Rule | Applies to | Constraint |
|---|---|---|
dao-patterns | **/business/**/*.java | Lutece 8 DAO/Home constraints: DAOUtil lifecycle, generated keys, SQL constants, Home facade, CDI lookup |
dependency-convergence | pom.xml | Lutece 8 dependency convergence: latest released global-pom 8.x as parent, Jakarta EE 10 pins, which test artifacts the parent manages, enforcer rules |
dependency-references | always | When a task involves a dependency (Lutece or external), ensure its source/docs are available for exploration |
java-conventions | **/*.java | Lutece 8 global Java conventions: Jakarta EE, CDI, forbidden patterns |
jsp-admin | **/*.jsp | Lutece 8 JSP constraints: admin feature JSP boilerplate, bean naming, errorPage, no init() for MVC beans |
messages-properties | always | Lutece 8 i18n constraints: no prefix in .properties, prefix in Java/templates, key naming |
plugin-descriptor | **/plugins/*.xml | Lutece 8 plugin.xml constraints: structure, icon-url, core-version-dependency, admin-feature and application declaration |
rest-resource | **/rs/**/*.java, **/rest/**/*.java | Lutece 8 JAX-RS resources: application path, securing endpoints per resource, and how a bench tests them |
service-layer | **/service/**/*.java | Lutece 8 service layer constraints: CDI scopes, injection, getInstance removal, events, configuration |
sql-liquibase | **/sql/**/*.sql | Lutece 8 SQL: every plugin .sql (create_db, init_db, init_core, upgrade) MUST carry the Liquibase formatted-sql header, otherwise the schema silently fails to deploy in v8 |
sql-rename | **/sql/**/*.sql, **/WEB-INF/plugins/*.xml | Renaming a SQL directory or a plugin: logicalFilePath goes on the changeset line (not the file header), or existing sites replay their creation scripts and lose data |
template-back-office | **/templates/admin/**/*.html | Lutece 8 Freemarker constraints: layout macros, list layout (@manageFeature / @table), form components, messages, i18n, vanilla JS |
template-front-office | **/templates/skin/**/*.html | Lutece 8 front-office (skin/site) templates: FO macros (c*), Bootstrap 5, vanilla JS, messages null-safety |
testing | **/test/**/*.java, pom.xml | Lutece 8 build and test commands, JUnit 5 conventions, test base classes |
web-bean | **/web/**/*.java | Lutece 8 JspBean/XPage constraints: CDI annotations, @Controller attributes, CRUD lifecycle, CSRF policy, Models, pagination |
Delivery by harness:
- Claude Code: the hook copies the rules into
.claude/rules/of the Lutece project. They load automatically by path (Grok reads that directory too, but does not run the hook). - Cursor: shipped as native
.mdcrules withglobs. - Other harnesses: nothing is automatic. Read the rule before touching a matching file.
Build and test
# Compile only
mvn clean install -Dmaven.test.skip=true
# Full build with tests (exploded webapp + HSQL are required)
mvn clean lutece:exploded antrun:run -Dlutece-test-hsql test -q
Never run plain mvn test. Lutece tests need the lutece:exploded antrun:run goals first.
Long-running commands
Never wait on a command. Anything that may take more than about 30 seconds (a build, the e2e bench, a test suite, a series of measurements) starts in the background and is followed by events: one line per result as soon as it exists, one per failure signature (error, stack trace, unhealthy, a server start that fails), and a silence detector that reports a hang after a few seconds without output. Meanwhile, work on something else that does not touch what is running. Never poll with sleeps, never block the session on a foreground wait.
- Split a series so each result streams on its own (one event per run), and stop the job at the first event that shows it is lost, instead of letting it run to its timeout.
- Stop a background job by its id or its pid, never by a name pattern (
pkill -f): the pattern also matches the command that runs it. - Prefer a tool that reports its outcome itself (the bench's
watch-boot.shends on READY, FAIL or HANG) over a fixed timeout.
Subagents and teams
lutece-update-plugin runs in one agent and dispatches two read-only or self-contained subagents, one after the other (the reviewer, the e2e bench). lutece-scalability-v8 is written as a lead orchestrating teammates described in teammates/*.md files.
- Harness with a team or subagent tool: dispatch one subagent per teammate with the spawn template given in the skill. On Claude Code, Agent Teams is experimental and needs
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1; without it, use regular subagents. - Harness without dispatch: run the subagent or teammate instructions yourself, sequentially, in the order the skill gives. Read each file, execute it fully, then move to the next. Never invent a tool call.
Rules shared by every skill: a project has one writer at a time; no skill ever creates a git commit.
Harness adaptation
Skills name actions (read a file, run a command, invoke a skill, dispatch a subagent). Map them to your tools with the reference for your harness:
- Codex:
references/codex-tools.md - Cursor:
references/cursor-tools.md - OpenCode:
references/opencode-tools.md - Claude Code, Grok Build: native tool surface, no mapping needed.
User instructions (CLAUDE.md, AGENTS.md, direct requests) take precedence over skills, which override default behaviour.
Agents 1
You audit a Lutece plugin, module or library against Lutece 8 and produce a conformity report. You never modify a
file. The references are the truth: for any non-trivial pattern (producer, listener, cache, REST), compare with the
same pattern in ~/.lutece-references/ (core, lutece-form-plugin-forms, gru-plugin-appointment, each with its v7
branches) and flag a divergence even when it compiles.
Step 0 — Plugin root
LUTECEPOWERS_ROOT comes from your prompt. If absent:
LUTECEPOWERS_ROOT="${LUTECEPOWERS_ROOT:-${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT:-}}}"
[ -f "$LUTECEPOWERS_ROOT/tools/lutece-check.sh" ] || LUTECEPOWERS_ROOT="$(dirname "$(dirname "$(find ~ -maxdepth 7 -path '*/tools/lutece-check.sh' 2>/dev/null | head -1)")")"
Phase A — Scripts
bash "$LUTECEPOWERS_ROOT/tools/lutece-check.sh" .
bash "$LUTECEPOWERS_ROOT/tools/render-template.sh" .
lutece-check.sh runs every mechanical check (verify-migration, template design scan, i18n keys, template parse) and
prints the findings to act on; --explain CODE gives the meaning of one. render-template.sh renders every template
with the real macros: errors do not render (500s), wrongArguments are arguments a macro ignored, missingI18nKeys
labels that render empty. Everything these scripts check is theirs: do not re-grep it.
Phase B — Judgement (what no script decides)
- CDI scope. A class the plugin descriptor instantiates by reflection (
<content-service-class>,<search-indexer-class>,<rbac-resource-type-class>, filters, servlets, listeners, page includes, dashboard components, daemons:Plugin.javaof the core) and a static facade carry no scope (WARN if they do). Any other service:@ApplicationScoped(WARN if missing). A JspBean or XPage with state held across requests is@SessionScoped, else@RequestScoped; pagination state does not count (@Inject @Pager IPagerholds it). - Singletons. A plugin's own
getInstance( )is removed and the bean injected (FAIL), except a portlet home, whosegetInstance( )returnsCDI.current( ).select( X.class ).get( )(HM01).SecurityService.getInstance( )andAdminAuthenticationService.getInstance( )are not deprecated. - Injection.
CDI.current( ).select( … )in a CDI bean: WARN, prefer@Inject; in a static context (Home, utility): PASS. - Producers. A producer of a class of
src/that could simply be scoped: WARN. A pluggable implementation (IFileStoreService,IFileDownloadUrlService,IFileRBACService) resolved by a literal@Named: WARN, resolve the name from@ConfigPropertylike the core'sDefaultFileStoreServiceProviderProducer; a module-internal bean by literal name (workflowITaskConfigDAO): PASS. - Configuration.
@ConfigPropertyin a non-CDI class: FAIL (never injected);AppPropertiesServicein a CDI bean where@ConfigPropertyfits: WARN. A key shipped empty now readsnull: its callers must cope. - Deprecated API the compiler warnings name and no script rewrote: WARN each, with its replacement
(
patterns/deprecation-fixes.md);@Deprecated(forRemoval = true): FAIL. - JavaScript. jQuery with a pom that declares
library-theme-jquery: WARN unless a widget with no v8 equivalent justifies it (the others are TM02 / VL01, script checks). - JPA (
persistence.hasJpa):equals/hashCodeover a collection, a new object reachable through a relation withoutcascade = PERSISTbefore a flush,EntityManagerandDAOUtilmixed outside@Transactional, JPQL calling a database function withoutFUNCTION( )(persistence-patterns.md§5–§7).
Phase C — Build and tests
bash "$LUTECEPOWERS_ROOT/tools/final-gate.sh" . --no-e2e
One build with the compiler warnings and the unit tests read from surefire (BUILD SUCCESS alone means nothing), then the checks. Report its lines; do not fix anything.
Report
# Lutece v8 Compliance Report
**Project:** <artifactId> | **Type:** <plugin/module/library> | **Version:** <version>
## Scripts
<lutece-check.sh verdict per tool, FAIL/WARN counts; render-template counts>
## Judgement
| # | Check | Status | Issues |
|---|---|---|---|
| 1–8 | … | PASS/WARN/FAIL/N/A | n |
## Build & tests
<final-gate.sh --no-e2e lines: build, warnings, tests run / failures / errors>
## Findings
### <Category> — <STATUS>
| Severity | File | Line | Finding | Expected |
|---|---|---|---|---|
Templates get their own section: does not render (parse, render errors), silently wrong (wrongArguments, icons that
render nothing, a back-office macro in a skin template), not polished (WARN per code), judgement calls (INFO).
FAIL breaks the build or the runtime; WARN is a practice to fix; N/A when a category does not apply. Every finding
names its file and line, and a fix it proposes compiles: an @Override only on a method a supertype declares
(grep the supertype), an API only if the reference code calls it. Return the report as is: the caller decides with the
user what gets fixed.
Hooks 3
Sponsors
Details
- Marketplace
- lutece-platform/lutece-dev-plugin-claude
- Category
- Development
- Keywords
- lutece, java, jakarta, cdi, migration