- Get Started
- Functionality
- Learning
- Extension
- Dev Tooling
- APIs
- Releases
Changed on:
9 Nov 2026
`module.json`. Deploy modules, not individual workflows or JARs. One module install keeps the rules and the workflows that call them in step.| In the module | Outside the module |
| Rule plugin JARs | Credentials and secrets |
| Workflows | Retailer IDs and other account-specific identifiers |
| Settings whose value is the same in every environment | Settings whose value differs per environment (supply them through module config) |
`module.json`, `module.config.json`, README, CHANGELOG | Test data and reference data loads |
`module.json` so an install into an account that lacks them fails early:`module.json` and the rule plugin JAR.`major.minor` in one place: the `<revision>` property of the plugin reactor `pom.xml`. The committed `resources/module.json` carries the same value.`1.0.412`.`dist/` copy is stamped. The build writes the full version into the `module.json` inside `dist/` and passes it to Maven as `-Drevision`. Committed files never change during a build.`module.json`. If the two disagree, the CLI skips the JAR upload without failing: the deploy looks green but ships no rules. Have the build fail on a mismatch before it zips anything.`build-module.sh` (abridged)`module.config.json` declares what a module needs from the environment. Commit one filled-in config per retailer per module under `cicd/configs/`, named `module.config.<RETAILER>.<module>.json`, and have the install step apply it with `fluent module config` before `fluent module install`.`cicd/configs/` also serves as the list of modules each retailer expects. A preflight step can use it to confirm that the reference modules the implementation builds on (order, inventory and so on) are already installed before it installs anything (see profile.sh).`fluent blueprint validate`) and download for offline or pinned installs (`fluent blueprint download`). A single extension module, as in the samples here, does not need one.1{
2 "_schema": "1.0.0",
3 "name": "ACME",
4 "version": "1.0",
5 "title": "Acme - OMS Extension Module",
6 "dependencies": [
7 { "name": "fluent-commerce/core", "type": "module", "version": "2.2.1" }
8 ],
9 "rules": [
10 "com.acme.rule.order.DetermineFulfilmentType"
11 ]
12}1#!/bin/bash
2# Builds the rule plugins and assembles dist/<module>-<version>.zip.
3# Usage: build-module.sh [-v <build-id>] (CI passes the build number or tag)
4set -eo pipefail
5
6VERSION_SUFFIX=""
7while getopts "v:" opt; do
8 case $opt in v) VERSION_SUFFIX=$OPTARG ;; *) exit 1 ;; esac
9done
10
11SCRIPT_DIR=$(dirname "$(realpath "$0")")
12MODULE_DIR="$SCRIPT_DIR/.."
13PLUGIN_DIR="$MODULE_DIR/plugins"
14RESOURCES_DIR="$MODULE_DIR/resources"
15DIST_DIR="$MODULE_DIR/dist"
16
17authored=$(sed -n 's|.*<revision>\([^<]*\)</revision>.*|\1|p' "$PLUGIN_DIR/pom.xml" | head -n 1)
18[ -n "$authored" ] || { echo "No <revision> in pom.xml" >&2; exit 1; }
19
20# With no -v, a tag on HEAD names the build, so a local build of a tagged commit matches CI.
21# --points-at, not `git describe`, which would reuse an ancestor's tag.
22suffix=${VERSION_SUFFIX:-$(git tag --points-at HEAD 2>/dev/null | head -n 1)}
23suffix=$(printf '%s' "$suffix" | tr -c 'A-Za-z0-9_-' '_')
24version=${suffix:+$authored.$suffix}
25version=${version:-$authored}
26
27(cd "$PLUGIN_DIR" && mvn clean package -Drevision="$version")
28
29# The CLI silently skips a rules JAR whose version differs from module.json.
30for jar in "$PLUGIN_DIR"/rules/*/target/*.jar; do
31 case $(basename "$jar") in
32 *-"$version".jar) ;;
33 *) echo "Error: $(basename "$jar") does not carry version $version" >&2; exit 1 ;;
34 esac
35done
36
37name=$(sed -n 's/.*"name": *"\([^"]*\)".*/\1/p' "$RESOURCES_DIR/module.json" | head -n 1 | tr '/' '-')
38out="$DIST_DIR/$name-$version"
39rm -rf "$DIST_DIR" && mkdir -p "$out/assets/rules"
40
41cp "$RESOURCES_DIR/module.json" "$RESOURCES_DIR/module.config.json" "$out/"
42cp "$MODULE_DIR"/{README,CHANGELOG}.md "$out/" 2>/dev/null || true
43find "$RESOURCES_DIR" -mindepth 1 -maxdepth 1 -type d -exec cp -r {} "$out/assets/" \;
44cp "$PLUGIN_DIR"/rules/*/target/*.jar "$out/assets/rules/"
45
46# Stamp the dist copy only: the first "version" key, leaving dependency versions alone.
47awk -v v="$version" '!d && /"version"[[:space:]]*:/ { sub(/"version"[[:space:]]*:[[:space:]]*"[^"]*"/, "\"version\": \"" v "\""); d=1 } 1' \
48 "$out/module.json" > "$out/module.json.tmp" && mv "$out/module.json.tmp" "$out/module.json"
49
50(cd "$out" && zip -qr "../$name-$version.zip" .)
51echo "Built $DIST_DIR/$name-$version.zip"