Lutece 8 development toolkit for coding agents: skills, path-scoped rules, reference sources, migration and review workflows.

Install

/plugin install lutecepowers-v8@lutece-plugins

Run it inside Claude Code after adding the marketplace with /plugin marketplace add lutece-platform/lutece-dev-plugin-claude.

Contents

Discovered from source

Skills 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

SituationTool
Yes/No, pick one, pick manyAsk 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:

  1. Read project structure — pom.xml, webapp/WEB-INF/conf/plugins/, existing Java packages
  2. Check recent commits — git log --oneline -10 to understand current momentum
  3. Scan existing features — plugin descriptor XML, existing XPages, JspBeans, services
  4. 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

  1. What — What does this feature do? What problem does it solve?
  2. Who — Back-office users? Front-office visitors? Both? API consumers?
  3. Where — New plugin? Existing plugin extension? Module?
  4. Scope — What is explicitly OUT of scope? (Apply YAGNI ruthlessly)
  5. Constraints — Must integrate with existing workflows? RBAC requirements? Performance targets?
  6. 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

SourceWhat to look forHow
Lutece Platform GitHubOfficial plugins and modulesSearch the web for site:github.com/lutece-platform [feature keywords]
Lutece Secteur Public GitHubPublic-sector-specific modulesSearch the web for site:github.com/lutece-secteur-public [feature keywords]
Local referencesAlready-cloned v8 reposSearch the references in ~/.lutece-references/
Lutece dev wikiArchitecture notes, existing module docsSearch the web for site:dev.lutece.paris.fr [feature keywords]
Maven artifactsPublished Lutece modulesSearch for fr.paris.lutece.plugins + keywords

Search strategy

  1. Identify keywords from the Discovery phase (e.g. "notification", "workflow", "form", "directory", "appointment")
  2. Search GitHub orgs — search the web in both lutece-platform and lutece-secteur-public:
    site:github.com/lutece-platform [keyword] plugin OR module
    site:github.com/lutece-secteur-public [keyword] module
    
  3. Check local references — scan ~/.lutece-references/ for related code
  4. 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 — @ApplicationScoped vs @Dependent vs @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

  1. Architecture overview — layers, components, data flow diagram
  2. Business objects — entities, fields, relationships
  3. DAO / Home layer — persistence strategy, SQL queries
  4. Service layer — business logic, CDI beans, scopes
  5. Web layer — JspBeans (back-office) and/or XPages (front-office)
  6. Templates — admin HTML templates, front-office Freemarker
  7. Plugin descriptor — XML entries needed
  8. Error handling & validation — user input validation, error messages
  9. i18n — messages.properties keys
  10. 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:

  1. Create the design document:

    docs/plans/YYYY-MM-DD-<topic>-design.md
    

    Structure:

    # 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]
    
  2. 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:

  1. Relevant skills — point to the skills needed for implementation:
    • rules/dao-patterns.md for the DAO/Home layer
    • /lutece-patterns for architecture patterns
    • /lutece-workflow if workflow integration is needed
    • /lutece-rbac if RBAC is needed
    • /lutece-cache if caching is needed
  2. Create a task list — use your task-tracking tool to break the design into implementation tasks

Key Principles

PrincipleRule
One question at a timeNever overwhelm with multiple questions in one message
Multiple choice preferredEasier to answer than open-ended when possible
YAGNI ruthlesslyRemove unnecessary features from all designs
Explore alternativesAlways propose 2-3 approaches before settling
Incremental validationPresent design in sections, validate each one
Be flexibleGo back and clarify when something doesn't make sense
Reuse-firstSearch lutece-platform and lutece-secteur-public for existing modules before building
Lutece-firstAlways check ~/.lutece-references/ for existing patterns before inventing
Context before questionsRead the project state silently before asking anything

Lutece 8 Cache Implementation

Before implementing cache, consult ~/.lutece-references/lutece-form-plugin-forms/ — specifically FormsCacheService.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
  • @PostConstruct calls initCache( name, keyClass, valueClass ) — registers the cache with CacheService
  • 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/remove to 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)

ContextPatternExample
CDI-managed bean (@ApplicationScoped, @RequestScoped, etc.)@InjectService class
Static context (Home class, static utility)CDI.current().select() direct field initHome 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

MethodUsage
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

FileWhat to add
EntityCacheService.javaNew class in service/cache/, @ApplicationScoped, extends AbstractCacheableService, key builders
EntityService.java@Inject EntityCacheService, cache-through logic (get → miss → load → put)
beans.xmlAlready present (required for CDI)

No changes needed in plugin.xml or messages.properties — cache is infrastructure, not UI.

Reference Sources

NeedFile 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 of seed7-*.sql asserted with the v7_witness step: exactly 1 on a database born in v7 (the core changeset 7.9.9-8.0.0 in DATABASECHANGELOG), 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.

CommandWhat it doesWhen
(none), allbuild if needed, start, inventory, crawl, smoke, suites, perf, report, visual review, stopfirst and last run
watchthe 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 suitewhile fixing
selftestproves 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 1after changing the hot loop, or before trusting it on a new project
buildpackages the artefact and lays out the bench site (the assembled site is cached)after a source change, to work step by step
upbuilds when the sources changed, starts the bench on a fresh database, waits for the application, seedsto work step by step
inventoryreads the sources: every screen, action, right and REST endpointto see what there is to cover
discovercrawls the running site and completes the inventoryafter up
testevery suite against the running benchafter up
test <pytest args>one pytest call, e.g. test /bench/tests/test_scenarios.py -k <id> (seconds)while writing a scenario
perfserver timings, SQL digests; E2E_JFR=1 adds the JFR hot methodsafter the suites
reportrebuilds summary.md and report.html from the artefacts already therefree, anytime
reviewthe screen-by-screen visual gatebefore handing over
keythe 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, pythe application log, the containers, the host port, a shell, a script in the runnerwhile diagnosing
upgradethe 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
downremoves the bench's containers and database; the shared server stays for the other bencheswhen 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_PLUGINS extra 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_ENABLE plugin names to mark installed in plugins.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 params rule in scenarios/screens.yaml, or a seed row;
  • a form needs a value the generic filler cannot guess → values: in a fill_form step;
  • 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 in report.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 @manageFeature is cards, not a table: its oracle is .row-cards li (rows) and .empty (no row), never table tbody tr, which silently counts zero after a list migration.
  • Confirmation screens: expect_message: confirmation then confirm:; 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: and shots: lines review-todo.md prints at the top of artifacts/review.md, then one line per group: - [x] G012 ok or - [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 report copies the aria snapshots when it is empty and E2E_SCOPE is not all), 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 of summary.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/ without page= or page_id= (a JSON endpoint, a Do… 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 in scenarios/screens.yaml or from a scenario's versions, 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 @Inject one: @ApplicationScoped beans are proxied by their concrete class (reference FormsDataSource.java:116)
  • @ConfigProperty injects values from properties file (MicroProfile Config)
  • getIdDataObjects() returns ALL IDs — the framework handles batching via BatchDataObjectsIterator
  • getDataObjects(List) fetches a batch of entities — keep this efficient (single SQL query for the batch)
  • AbstractDataSource provides getDataObjectsIterator() implementation using BatchDataObjectsIterator

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:

  • AbstractDataObject provides getTimestamp() with day/week/month extraction for analytics
  • @JsonIgnore on getId() — the ID is used for ES document routing, not stored as a field
  • getDocumentTypeName() — 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.

EventSent byObserver
FormResponseEventfireAsync (lutece-form-plugin-forms/src/java/**/service/FormService.java)@ObservesAsync (lutece-form-module-elasticdata-forms/src/java/**/FormResponseIndexerEventListener.java)
ResourceEvent of the workflowfire (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 update
  • IndexerAction.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), in service/event/;
  • @Inject Event<MyEntityEvent> in the @ApplicationScoped service, select( new TypeQualifier( action ) ).fireAsync( … ) after the write, CREATE / UPDATE / REMOVE;
  • fireAsync throws RejectedExecutionException while the server stops: catch it and fire again with NotificationOptions.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 only
  • TIMESTAMP_AND_LOCATION_MAPPINGS — timestamp + geo_point for 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

ModeDaemonIntervalTriggerWhat happens
FullFullIndexingDaemondaemon.fullIndexingDaemon.interval (shipped: 86400 s)Admin button or daemon scheduleDelete index → recreate with mappings → bulk index all DataObjects
IncrementalIncrementalIndexingDaemondaemon.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):

  1. do the write through the screens;
  2. read the queue: jsp/admin/plugins/elasticdata/ManageElasticData.jsp?view=manageIndexerActions lists one task per resource (1 create, 3 delete);
  3. run "Indexation incrémentale" on ManageElasticData.jsp, then read the document back: curl localhost:9200/<targetIndexName>/_doc/<lutece.name>_<dataSourceId>_<id> (the id is DataSourceService.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

FileWhat to create
pom.xmlMaven module with plugin-elasticdata dependency
MyEntityDataSource.java@ApplicationScoped extending AbstractDataSource, @ConfigProperty constructor
MyEntityDataObject.javaExtends AbstractDataObject, typed fields + Map<String,Object>
MyEntityIndexerEventListener.javaCDI 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.xmlplugin.xml descriptor
src/main/resources/META-INF/beans.xmlCDI descriptor (empty <beans> tag)

No daemon, no DAO, no SQL table needed — plugin-elasticdata provides all infrastructure.

Reference Sources

NeedFile 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, absolute indexPath). FormsPlugin.warnIfIndexPathIsNodeLocal() logs an error when the path is under the webapp or java.io.tmpdir.
  • Full and incremental indexing run under a database lease lock with heartbeat (forms LuceneLockManagerDB + LockDAO, table forms_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

TypeForExample
StringFieldExact match, stored IDsUIDs, type codes
TextFieldFull-text searchTitle, description, content
IntPointInteger range queriesIntPoint.newExactQuery(field, value)
LongPointLong/date range queriesTimestamps
NumericDocValuesFieldSorting on numbersSort by ID, date
SortedDocValuesFieldSorting on stringsSort by title
StoredFieldStore-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

FileWhat to create
IEntitySearchIndexer.javaInterface in service/search/
LuceneEntitySearchIndexer.javaImplementation @ApplicationScoped
LuceneEntitySearchFactory.javaIndex lifecycle (open, close, swap)
EntitySearchDaemon.javaDaemon extending Daemon (reflection-instantiated, no CDI scope)
EntityIndexerEventListener.javaCDI @ObservesAsync listener
IndexerAction.java + DAO + HomeQueue entity in business/search/
ILuceneLockManager.java + LuceneLockManagerDB.java + LockDAO.javaDB lease lock, copied from forms service/lock/ and business/form/lock/
create_db_myplugin.sqlLiquibase header + myplugin_indexer_action + myplugin_lucene_lock
plugin.xml<daemon> declaration (<daemon-class>, no interval)
myplugin.propertiesIndex path outside the webapp, lock TTL, daemon.<id>.interval

Reference Sources

NeedFile 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 reads null.
  • 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

  1. @Controller( right = … ): processController checks it (never init( ) in the bean or the JSP).
  2. securityTokenEnabled = true: the core puts the token in every form and validates every @Action POST.
  3. securityTokenAction on confirmation views, so the confirm button carries the token of the action.
  4. RBACService.getAuthorizedCollection( ) when RBAC is on; AdminWorkgroupService.getAuthorizedCollection( ) for workgroups.

Lutece 8 RBAC Implementation

Before implementing RBAC, consult ~/.lutece-references/lutece-form-plugin-forms/ — specifically FormsResourceIdService.java, AbstractJspBean.java, and FormJspBean.java. Caveat: FormJspBean still uses the deprecated getModel(), manual LocalizedPaginator pagination and manual MARK_TOKEN puts although its @Controller has securityTokenEnabled=true; copy its RBAC logic only, and follow rules/web-bean.md for 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_TYPE is a unique constant — use PLUGINNAME_ENTITYNAME in uppercase
  • getResourceId() 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 ResourceIdService per 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 with I18nService
  • register() creates the ResourceType, registers all permissions, and calls ResourceTypeManager.registerResourceType()
  • getResourceIdList() returns all resources for the admin RBAC configuration UI
  • getTitle() 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

ConstantMeaningUsage
RBAC.WILDCARD_RESOURCES_ID ("*")All resources of a typeisAuthorized(type, RBAC.WILDCARD_RESOURCES_ID, perm, user)
RBAC.WILDCARD_PERMISSIONS_KEY ("*")All permissionsGranted when configuring a role in admin

Common Permissions

PermissionConstantWhen to check
CREATEPERMISSION_CREATEBefore showing create form / processing create action
MODIFYPERMISSION_MODIFYBefore showing modify form / processing modify action
DELETEPERMISSION_DELETEBefore delete confirmation / processing delete action
VIEWPERMISSION_VIEWBefore listing or viewing details
PUBLISHPERMISSION_PUBLISHBefore changing visibility/status

File Checklist

FileWhat to add
Entity.javaimplements RBACResource, RESOURCE_TYPE constant, getResourceTypeCode(), getResourceId()
EntityResourceIdService.javaNew class extending ResourceIdService, permission constants, register()
plugin.xml<rbac-resource-type> with <rbac-resource-type-class>
messages.propertiespermission.resourceType.entity.label + one key per permission
EntityJspBean.javaRBACService.isAuthorized() calls, AccessDeniedException throws, permission flags in model
Templates<#if canXxx> conditionals around protected buttons/links

Reference Sources

Forms plugin (RBAC + workgroups)

NeedFile 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

NeedFile 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/Timer in session.
  • 2-sessionscoped — stateful @SessionScoped/@ConversationScoped beans: whole graph Serializable + passivation test, and the cluster MUST run Liberty writeContents="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:

AxisLooks likeWhy it is usually a FALSE POSITIVE
3-singletongetInstance() callsCalls 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-singletonprivate static X _dao = CDI.current().select(...).get()The Home pattern — an effectively-immutable reference resolved once at class-load. Not divergent state.
4-cachenew 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-cachea service extending AbstractCacheableServiceAlready 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-sessionList<String> / other Serializable light values in sessionFine. Only non-Serializable or heavy/Future/Timer/Thread session state is a defect.
1-idSELECT 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.post that 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:

TeammateInstructionsAxes
Locks & Concurrencyteammates/locks-concurrency.md1-locks, 1-id
CDI scopes & singletonsteammates/cdi-scopes.md3-singleton, 3-cdi-static, 4-cache
Serialization & sessionteammates/serialization-session.md2-session, 2-sessionscoped, 2-nonserial
Config & robustnessteammates/config-robustness.md5-config, 6-streams, 6-threadlocal
Verifierteammates/verifier.mdbuilds + 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 Liberty logs/messages.log and FFDC incidents (logs/ffdc/, cluster-verify.sh section 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

  1. 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.
  2. Present the summary: scan deltas, triage verdicts (false positives dropped + reason), RED→GREEN reproduction results, build result, cluster-verify.sh PASS/FAIL, files modified.
  3. 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, the e2e/ 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 --out target); 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 to e2e/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

  1. Run after migration — the plugin must already be v8-compliant and compile.
  2. 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.
  3. 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.
  4. After Phase B the Lead orchestrates only and never edits files.
  5. Reference-first — copy the real mechanics from ~/.lutece-references/ (forms LockDAO/forms_lucene_lock, core CDI/serialization), never invent. Match the primitive to the lifetime: a short critical section (a few statements) → transactional SELECT … FOR UPDATE (auto-released on commit/crash, no orphan); a long single-writer lease (daemon/indexer) → the forms TTL LockDAO. Don't copy the TTL lease onto a short section.
  6. File ownership — one file, one teammate.
  7. 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).
  8. getInstance() is removed, never bridged — delete it and migrate callers (rules/service-layer.md).
  9. Keep all artifacts — never auto-delete .scalability/, e2e/ scripts, or the generated cluster. Tear down only running containers.
  10. NEVER commit.

Script Locations

All in ${LUTECEPOWERS_ROOT}/skills/lutece-scalability-v8/scripts/:

ScriptPurposeUsed by
scan-scalability.shScan 6-axis anti-patterns → JSONLead (A)
verify-file.shPer-file residual anti-pattern checkFixer teammates
gen-test-site.shGenerate a disposable 3-node Docker cluster for the pluginVerifier (F)
cluster-verify.shEmpirical scalability proofs against the running clusterVerifier (F)

Pattern Locations

All in ${LUTECEPOWERS_ROOT}/skills/lutece-scalability-v8/patterns/:

FileAxis
distributed-lock.md1 — concurrency, contended resources, ID generation
cdi-scopes.md3 — static singletons → CDI beans
serialization-session.md2 — Serializable session/cache, session state
cache-distributed.md4 — JSR-107 / Hazelcast distributed cache
config-and-robustness.md5 & 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.0 over 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

  1. Read the site: pom.xml, src/main/liberty/config/*, Dockerfile, webapp/WEB-INF/conf/override/*.properties, webapp/WEB-INF/plugins/plugins.dat.
  2. Note the site code (<site> in the templates: cluster name, Kubernetes names), the database, the plugins.
  3. Check reference/platform-versions.md: lutece-platform BOM and starter 8.0.0-beta-04 or later, nothing pinned below them.
  4. 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.

FileTemplateContent
pom.xml (merge)pom-profiles.xmlHazelcast 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.xmlcluster.xml include, persistTimeout, remoteIp, bounded executor, maxPoolSize on the existing data source
src/main/liberty/config/cluster.xmlsame namesessionCache-1.0, session library, httpSessionCache, Lutece cache provider
src/main/liberty/config/hazelcast-config-api-mode.yamlsame nameMember: cluster name, graceful shutdown, JVM hook off, immediate invalidations, fixed port, Kubernetes discovery
src/main/liberty/config/hazelcast-client-config-api-mode.yamlsame nameClient of the Lutece cache: member of its own pod, near cache
src/main/liberty/config/jvm.options (merge)jvm.optionsMember provider type, Hazelcast service name, --add-opens
webapp/WEB-INF/conf/override/quartz-daemons.propertiessame namequartzscheduler.cluster.enable=true, exclusive daemons, Forms lock lease
webapp/WEB-INF/plugins/plugins.datsite_check.py plugins-dat <war>Plugins installed on a fresh database
Dockerfilesame nameConfiguration, war, configure.sh (expanded war)
Kuberneteskubernetes-rbac.yamlService account, Service on 5701, Role/RoleBinding for the discovery
Kuberneteskubernetes-service.yamlService of the site, ReadWriteMany volume of the Forms index
Kuberneteskubernetes-migration.yamlOne-replica Liquibase run, before the replicas
Kuberneteskubernetes-deployment.yamlReplicas, sizes, probes, preStop, grace period, Liquibase off, Forms index path
Kuberneteskubernetes-ingress.yamlReplay 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 @SessionScoped beans modified in place are lost on a node switch.
  • -Dhazelcast.jcache.provider.type=member in jvm.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, BINARY for formsCacheService (Forms modifies the objects it reads from its cache).
  • Quartz: quartzscheduler.cluster.enable=true (the plugin ships false) and every daemon acting on shared state declared exclusive; the core indexer and threadLauncherDaemon stay local (table in reference/rules.md).
  • Liquibase from one replica only: -Dliquibase.enabled.at.startup=false on the replicas, kubernetes-migration.yaml before them on a fresh database and before each new war.
  • plugins.dat shipped 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 (indexPath in JVM_ARGS, fsGroup: 0) and lock lease forms.index.writer.ms.timeout.lock=120000.
  • Liberty: persistTimeout above 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), maxPoolSize 12; the database user limit covers (replicas + surge + migration run) x maxPoolSize.
  • 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-hazelcast in the cluster profile. Enabling or disabling a cache from the back office reaches the other replicas within lutece.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

MethodSuffixSolr typeUse for
addDynamicField(name, String)_textAnalyzed textFull-text searchable strings
addDynamicFieldNotAnalysed(name, String)_stringKeywordExact match, facets, filters
addDynamicField(name, Long)_longLongNumbers, counts
addDynamicField(name, Date)_dateDateDates, timestamps
addDynamicField(name, Float)_floatFloatDecimal numbers
addDynamicField(name, List<String>)_listMulti-valuedCheckboxes, tags
addDynamicFieldListDate(name, List<Date>)_list_dateMulti-valued dateMultiple dates
addDynamicFieldGeoloc(name, addr, lon, lat, type)_geoloc + _geojson + _address_textGeoMap 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

FileWhat to create
pom.xmlMaven module with plugin-solr + plugin-myentity dependencies
SolrMyEntityIndexer.java@ApplicationScoped implementing SolrIndexer
MyEntitySolrPlugin.javaPlugin class (only if dynamic resource types needed)
module-myentity-solr.propertiesIndexer name, description, enable flag
WEB-INF/plugins/myentity-solr.xmlplugin.xml descriptor
src/main/resources/META-INF/beans.xmlCDI descriptor (empty <beans> tag)

No daemon, no DAO, no SQL table needed — plugin-solr provides all infrastructure.

Reference Sources

NeedFile 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

StepFile (steps/)ScopeCodes it answers
11-config.mdpom, beans.xml, descriptors, web.xml, Spring context files, SQL, propertiesV8FLOOR, PM*, PV*, WB*, SP03, SQ*, PT*, XT*, I18N*
22-java.mdsrc/java: the Spring context to CDI, what the checks name, the designs a script cannot chooseJX*, SP*, DL*, EV*, CA*, DP*, DA*, JP*, CD*, MV*, ST*, HM*, XS*, CS*, TL*, LG*, GI*, PI*, RL*, PD*, WG*, JS04
33-templates.mdJSP, admin and skin templates, JavaScriptTM*, TD*, JS*, VL*
44-tests.mdsrc/testTS*, 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 of lutece-check.sh in their scope, in this order; a step with none is skipped. A V8FLOOR refusal 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:

SymptomFix
cannot find symbol on a Spring or javax typethe Java of step 2
final class cannot be proxieddrop final on that class only; legal when the bean is resolved by its interface
UnsatisfiedResolutionException in a Home static initializerbeans.xml missing from the archive, or excluded by .gitignore (ST05)
@Inject field null in a testthe 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/hashCode over a collection, a new object attached to a relation without cascade = PERSIST before a flush: fine with Hibernate, broken with EclipseLink (persistence-patterns.md §6).
  • ShutdownService implementations: a @PreDestroy method on the bean when process() does real cleanup; drop the interface when it does nothing. Case by case: getName() may be used elsewhere.

Patterns (patterns/, load on demand)

FileWhen
cdi-patterns.mdscopes, injection, producers, Models, Pager (Java, always)
deprecation-fixes.md, core-8x-moves.mdwhat replaces a deprecated or moved API
mvc-patterns.mdJspBean, XPage, portlet (HTML port §10, CSRF §11)
events-patterns.md, cache-patterns.md, rest-patterns.md, json-patterns.md, fileupload-patterns.md, persistence-patterns.mdwhen 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
  1. Identify the parent (lutece-site-pom version), 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).
  2. 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.
  3. 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 --profile and no --as-profile: a v8 war already holds every profile). Ask the user when it is not certain. check later reports every commit of another branch after the ref (SI86).
  4. 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:

StatusMeaningWhat to do
BOMmanaged by the target BOMnothing: the site declares it without version
STARTERa starterthe version of the target BOM
PUBLISHEDa release with a Lutece 8 parent, outside the BOMthe site pins that version
LOCALa 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
SNAPSHOTa Lutece 8 snapshot only, or the snapshot the target BOM managestell the user: a site released on it changes under its feet; pin the last release when there is one
NO-V8no published version with a Lutece 8 parentblocker
DRIFTa Lutece jar of the v7 before war built for Java 17the 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

StepFile (steps/)Scope
11-pom.mdparent, BOM import, starter or pack, versions, types, profiles
22-configuration.mdoverrides, per-environment conf to MicroProfile profiles, Spring contexts, database, secrets
33-webapp.mdplugins.dat, template and JSP overrides, web.xml, static files
44-database.mdSQL of the site, an existing database, the settings the takeover changes
55-runtime.mdLiberty 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 check proves 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: envconf leaves 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

  1. Read the target template.
  2. For each block of raw HTML, find the domain that covers it (step 0) and read the signatures.
  3. Rewrite using only macros.
  4. 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 inline style="...", comments <!--[if mso]> or <!--[if gte mso 9]>
  • Presence of a <meta name="x-apple-disable-message-reformatting">, of classes like email-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 via MailService.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 email
  • send_my_mail.html — sent email body
  • templates/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 via boxTools=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-workflow manage_workflow.html); on 8.0.2-beta-04 the parameter is dropped (TD16)
  • Main column (name/title): <@manageFeatureItemColumn auto=true flex=false> (with flex=false for 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, @manageFeatureItem generates its own cards

@tform boxed=true - Replacing @box

  • When a <@box> / <@boxBody> only contains a <@tform> or a <@manageFeature>, remove the <@box> and add boxed=true to 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 iconName relevant to the business context (e.g.: calendar-off for appointments, users-minus for users, inbox-off by 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=true when the form replaces a <@box> wrapper (see convention above)
  • Use <@formGroup> to group label + input with labelKey, 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 with title) 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 simple title is enough — prefer the self-closing form
  • color: 'danger', 'warning', 'info', 'success'
  • iconTitle to add an icon: <@alert color='warning' iconTitle='exclamation-circle'>
  • dismissible=true to 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 labelFor parameter on <@checkBox> when an id is already present (redundant)

@button / @aButton - Buttons

  • <@button> for form actions (submit)
  • <@aButton> for links styled as buttons (navigation)
  • buttonIcon uses the Tabler icons (without prefix): 'edit', 'trash', 'plus', 'check', 'times'
  • hideTitle=['all'] for icon-only buttons in lists
  • hideTitle=['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'. Never cancel=true (TD51) nor a cancel without colour (TD56)
  • color: 'primary', 'light', 'success', 'danger', 'warning', 'info'. The neutral button is color='light': aButton.ftl/button.ftl turn color='secondary' and cancel=true into the class btn-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=1 to 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
  • offsetMd for 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 @table for 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 → use boxed=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

  1. Read the target template.
  2. For each block of raw HTML, find the domain that covers it (step 0) and read the signatures.
  3. Rewrite using only macros.
  4. 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 core skin/site/*.html (examples.md § Page skeleton). Only a fragment included by another template (portlet body, component) skips cTpl and cContainer
  • Titles: level=2 for the page title (the h1 belongs to the frameset), level=3 below
  • 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/*.html and skin/search/search_results.html
  • The theme ships component CSS under webapp/themes/skin/lutece/css/{components,layout} and themes/skin/shared/css (bl-*, search-*, tile*, lutece-ds-empty): target those classes through class=, 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 no xs breakpoint)
  • has-error → is-invalid (validation)
  • btn-default → btn-secondary

FreeMarker HTML entities

  • Replace &gt; with gt in FreeMarker conditions: <#if list?size gt 0> (not &gt;)
  • Replace &lt; with lt in FreeMarker conditions: <#if value lt 10> (not &lt;)

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.xml freemarker-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 the c* macros but drops cTpl, cContainer and cForm. The first two are the page-override hooks of a site page and a fragment is not a page; cForm injects the front-office validation modules, which an admin page does not load. Every other c* 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>
      
      infos and warnings are Set<String> (${info.message} throws), errors are MVCMessage/ParamError objects: 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 — ?exists is 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 XML NodeModel (portlet templates fed by NodeModel, ${quicklinks.entry}-style paths) a missing child is an empty node list, present and non-null: node.child?? is true and node.child! is not the default. Only ?has_content tells an empty node list from a filled one; use it for XML-backed values

Dynamic classes (conditional concatenation)

  • Always pre-build the class string with <#assign> rather than inline FreeMarker in the class parameter
    <#-- 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= on cCard (not a parameter, svg dropped), @parisIcon (undefined in the core), cBtn class='btn btn-primary' (renders btn btn-btn btn-primary), cCol class='12 col-sm-5', stray " /> text after an icon, name='back' on cBtn, arrow-right for a back button, French copy in home=/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 &nbsp; — replace with a normal space or remove if unnecessary; a required label with no visible title keeps its real text with labelClass='visually-hidden'
  • Do not use style='...' on macros — use class with Bootstrap utilities or params='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 &gt; / &lt; in FreeMarker conditions — use gt / lt
  • Do not self-close <@cInline> — always </@cInline>, even when the content is empty
  • Do not inline FreeMarker in the class parameter of a macro — pre-build the string with <#assign> (also applies to href, id, etc.)
  • Do not inline ?string('yyyy-MM-dd') directly in params='datetime="..."' — nested quotes break the FreeMarker parser. Pre-build with <#assign>.
  • Do not keep a separate <figcaption> — use the caption parameter 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

  1. Resolve the plugin root (LUTECEPOWERS_ROOT from the session context, or the fallback in using-lutecepowers).
  2. Read ${LUTECEPOWERS_ROOT}/agents/lutece-v8-reviewer.md.
  3. 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, OpenCode task): dispatch one subagent whose prompt starts with LUTECEPOWERS_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.
  4. 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.

#ProducesWhere
1the ITask implementation — what the task does when the action firesreference/task-classes.md
2the config entity holding the task's settingsidem
3the config DAOidem
4the TaskType CDI producer that registers the taskidem
5the config produceridem
6the config service produceridem
7the TaskComponent — back-office display and validationreference/task-component.md
10the FreeMarker templates for the config and information viewsidem
8, 9, 11, 12, 13properties, plugin descriptor, SQL, i18n, pom — belowthis 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

ElementPatternExample
Modulemodule-workflow-{plugin}module-workflow-forms
Packagefr.paris.lutece.plugins.workflow.modules.{plugin}
Task classTask{Name}TaskEditFormResponse
Config classTask{Name}ConfigTaskEditFormResponseConfig
DAO classTask{Name}ConfigDAOTaskEditFormResponseConfigDAO
TaskType producerTaskType{Name}ProducerTaskTypeProducer (forms groups them)
Config producerTask{Name}ConfigProducerEditFormResponseConfigProducer
Component{Name}TaskComponentEditFormResponseTaskComponent
Bean namesworkflow-{plugin}.task{Name}workflow-forms.taskEditFormResponse
Properties prefixworkflow-{plugin}.task{Name}.
Templatestask_{name}_*.htmltask_edit_form_response_config.html
SQL tableworkflow_task_{name}_configworkflow_task_edit_form_response_config
i18n prefixmodule.workflow.{plugin}.task.{name}

Reference Sources

NeedRepo to consultKey files
Workflow core architecturelutece-wf-library-workflow-coresrc/java/**/service/task/, src/java/**/business/
Workflow plugin (engine)lutece-wf-plugin-workflowsrc/java/**/web/, src/java/**/service/
Complete workflow module (main example)lutece-wf-module-workflow-formsTask, Producer, Component, DAO, templates
Module with assignmentlutece-wf-module-workflow-forms-automatic-assignmentAutomatic assignment pattern
Module with uploadlutece-wf-module-workflow-uploadFile handling in workflow
PDF modulelutece-wf-module-workflow-formstopdfDocument 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 (the configBeanName)
  • Task{Name}ConfigServiceProducer.java - Producer ITaskConfigService
  • {Name}TaskComponent.java - UI with @ApplicationScoped @Named, ctor injecting ITaskType + 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:

  1. Before writing any Lutece code (bean, service, DAO, XPage, daemon, template): load the lutece-patterns skill.
  2. 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/.
  3. 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 the develop branch (where v8 lives), and each one also carries the v7 branches that exist upstream (develop_core7, master_core7; develop7.x and master7.x for lutece-core), listed by git branch -r, to compare a pattern before and after migration. Repositories born in v8 have none. The list of repositories is the REPOS array 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 containing skills/.
  • 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 CODE says 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

SkillUse when
lutece-brainstormingUse 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-cacheUse 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-checkupUse 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-e2eUse 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-elasticdataUse 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-indexerUse 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-patternsUse 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-rbacUse 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-v8Use 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-instanceUse 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-indexerUse 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-pluginUse 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-siteUse 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-boConverts 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-foConverts 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-reviewUse 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-workflowUse 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).

RuleApplies toConstraint
dao-patterns**/business/**/*.javaLutece 8 DAO/Home constraints: DAOUtil lifecycle, generated keys, SQL constants, Home facade, CDI lookup
dependency-convergencepom.xmlLutece 8 dependency convergence: latest released global-pom 8.x as parent, Jakarta EE 10 pins, which test artifacts the parent manages, enforcer rules
dependency-referencesalwaysWhen a task involves a dependency (Lutece or external), ensure its source/docs are available for exploration
java-conventions**/*.javaLutece 8 global Java conventions: Jakarta EE, CDI, forbidden patterns
jsp-admin**/*.jspLutece 8 JSP constraints: admin feature JSP boilerplate, bean naming, errorPage, no init() for MVC beans
messages-propertiesalwaysLutece 8 i18n constraints: no prefix in .properties, prefix in Java/templates, key naming
plugin-descriptor**/plugins/*.xmlLutece 8 plugin.xml constraints: structure, icon-url, core-version-dependency, admin-feature and application declaration
rest-resource**/rs/**/*.java, **/rest/**/*.javaLutece 8 JAX-RS resources: application path, securing endpoints per resource, and how a bench tests them
service-layer**/service/**/*.javaLutece 8 service layer constraints: CDI scopes, injection, getInstance removal, events, configuration
sql-liquibase**/sql/**/*.sqlLutece 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/*.xmlRenaming 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/**/*.htmlLutece 8 Freemarker constraints: layout macros, list layout (@manageFeature / @table), form components, messages, i18n, vanilla JS
template-front-office**/templates/skin/**/*.htmlLutece 8 front-office (skin/site) templates: FO macros (c*), Bootstrap 5, vanilla JS, messages null-safety
testing**/test/**/*.java, pom.xmlLutece 8 build and test commands, JUnit 5 conventions, test base classes
web-bean**/web/**/*.javaLutece 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 .mdc rules with globs.
  • 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.sh ends 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)

  1. 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.java of 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 IPager holds it).
  2. Singletons. A plugin's own getInstance( ) is removed and the bean injected (FAIL), except a portlet home, whose getInstance( ) returns CDI.current( ).select( X.class ).get( ) (HM01). SecurityService.getInstance( ) and AdminAuthenticationService.getInstance( ) are not deprecated.
  3. Injection. CDI.current( ).select( … ) in a CDI bean: WARN, prefer @Inject; in a static context (Home, utility): PASS.
  4. 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 @ConfigProperty like the core's DefaultFileStoreServiceProviderProducer; a module-internal bean by literal name (workflow ITaskConfigDAO): PASS.
  5. Configuration. @ConfigProperty in a non-CDI class: FAIL (never injected); AppPropertiesService in a CDI bean where @ConfigProperty fits: WARN. A key shipped empty now reads null: its callers must cope.
  6. Deprecated API the compiler warnings name and no script rewrote: WARN each, with its replacement (patterns/deprecation-fixes.md); @Deprecated(forRemoval = true): FAIL.
  7. 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).
  8. JPA (persistence.hasJpa): equals/hashCode over a collection, a new object reachable through a relation without cascade = PERSIST before a flush, EntityManager and DAOUtil mixed outside @Transactional, JPQL calling a database function without FUNCTION( ) (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.

Sponsors

Details

Marketplace
lutece-platform/lutece-dev-plugin-claude
Category
Development
Keywords
lutece, java, jakarta, cdi, migration