This is an automated email from the ASF dual-hosted git repository.
sergehuber pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/unomi.git
The following commit(s) were added to refs/heads/master by this push:
new 6d7b83dc1 docs: finish Unomi 3.1→4.0 wording in the manual (#903)
6d7b83dc1 is described below
commit 6d7b83dc12c25891fe0f4848b2b6bef8453db92c
Author: Serge Huber <[email protected]>
AuthorDate: Fri Oct 2 17:06:08 2026 +0200
docs: finish Unomi 3.1→4.0 wording in the manual (#903)
---
.../main/asciidoc/how-profile-tracking-works.adoc | 2 +-
.../asciidoc/migrations/migrate-3.0-to-4.0.adoc | 38 +++++++++++-----------
.../asciidoc/migrations/v2-compatibility-mode.adoc | 4 +--
.../migrations/writing-migration-scripts.adoc | 10 +++---
manual/src/main/asciidoc/samples/login-sample.adoc | 2 +-
manual/src/main/asciidoc/web-tracker.adoc | 2 +-
6 files changed, 29 insertions(+), 29 deletions(-)
diff --git a/manual/src/main/asciidoc/how-profile-tracking-works.adoc
b/manual/src/main/asciidoc/how-profile-tracking-works.adoc
index 4301d246c..6108bc399 100644
--- a/manual/src/main/asciidoc/how-profile-tracking-works.adoc
+++ b/manual/src/main/asciidoc/how-profile-tracking-works.adoc
@@ -241,7 +241,7 @@ Apache Unomi attempts to identify the visitor's profile
through the following pr
* **Public callers** (public API key / unauthenticated context): the
profile cookie is the **only** profile bearer. A body or query `profileId` is
**ignored** (even when no cookie is present).
* **Trusted callers** (system administrator or tenant private-key /
`TENANT_ADMINISTRATOR`): an explicit body/query `profileId` is honored and may
differ from the cookie.
* Cookie name defaults to `context-profile-id` (configurable via
`org.apache.unomi.profile.cookie.name`).
- * Cookie values are validated against a JSON schema — invalid values (for
example containing script tags) cause a `400 Bad Request`. Since 3.1 the cookie
is read on every request, so this also applies when the request supplies an
explicit `profileId`; before, a malformed cookie went unnoticed on those
requests.
+ * Cookie values are validated against a JSON schema — invalid values (for
example containing script tags) cause a `400 Bad Request`. Since 4.0 the cookie
is read on every request, so this also applies when the request supplies an
explicit `profileId`; before, a malformed cookie went unnoticed on those
requests.
* The resolved profile ID is used to attempt loading the profile from the
database.
2. **Session Profile Override** (if session exists):
diff --git a/manual/src/main/asciidoc/migrations/migrate-3.0-to-4.0.adoc
b/manual/src/main/asciidoc/migrations/migrate-3.0-to-4.0.adoc
index 97f2bd811..e93cd6427 100644
--- a/manual/src/main/asciidoc/migrations/migrate-3.0-to-4.0.adoc
+++ b/manual/src/main/asciidoc/migrations/migrate-3.0-to-4.0.adoc
@@ -50,9 +50,9 @@ The main change in 4.0 is the introduction of tenant-based
authentication. The s
|System Administrator Authentication (configured `UNOMI_ROOT_PASSWORD`)
|===
-==== API Key Types (3.1 Only)
+==== API Key Types (4.0 Only)
-3.1 introduces two types of API keys per tenant:
+4.0 introduces two types of API keys per tenant:
- **Public Key**: Used for public endpoints (event collection via
`/context.json`)
- **Private Key**: Used with tenantId for tenant-specific administrative
operations
@@ -61,7 +61,7 @@ The main change in 4.0 is the introduction of tenant-based
authentication. The s
[cols="1,1,1", options="header"]
|===
-|Endpoint Category |3.0 Authentication |3.1 Authentication
+|Endpoint Category |3.0 Authentication |4.0 Authentication
|Event Collection (`/context.json`)
|None
@@ -76,7 +76,7 @@ The main change in 4.0 is the introduction of tenant-based
authentication. The s
|System Admin (`karaf:$UNOMI_ROOT_PASSWORD`)
|===
-==== Authentication Flow (3.1)
+==== Authentication Flow (4.0)
The AuthenticationFilter in 4.0 follows this resolution order:
@@ -104,7 +104,7 @@ RestAssured.given()
.post("/context.json");
----
-===== 3.1 Authentication
+===== 4.0 Authentication
[source,java]
----
@@ -145,10 +145,10 @@ given()
----
public class UnomiConfiguration {
public UnomiClient createClient(String baseUrl) {
- String version = System.getProperty("unomi.version", "3.1");
+ String version = System.getProperty("unomi.version", "4.0");
- if ("3.1".equals(version)) {
- return new UnomiV31Client(baseUrl);
+ if ("4.0".equals(version)) {
+ return new UnomiV40Client(baseUrl);
} else {
return new UnomiV30Client(baseUrl);
}
@@ -167,7 +167,7 @@ public void init() {
.basic("karaf", System.getenv("UNOMI_ROOT_PASSWORD"));
}
-// 3.1 Client
+// 4.0 Client
public void init() {
RestAssured.baseURI = baseUrl;
}
@@ -180,19 +180,19 @@ public void updateKeys(String publicKey, String
privateKey) {
==== No API Contract Changes
-All API endpoints remain the same between 3.0 and 3.1, and request/response
payloads are unchanged in shape. The differences are in the authentication
mechanism, tenant resolution, and which of the identity fields a public caller
sends to `/context.json` and `/eventcollector` the server acts on — see
<<_client_facing_hardening_4_0,Client-facing hardening (3.1)>> below.
+All API endpoints remain the same between 3.0 and 4.0, and request/response
payloads are unchanged in shape. The differences are in the authentication
mechanism, tenant resolution, and which of the identity fields a public caller
sends to `/context.json` and `/eventcollector` the server acts on — see
<<_client_facing_hardening_4_0,Client-facing hardening (4.0)>> below.
[#_client_facing_hardening_4_0]
-==== Client-facing hardening (3.1)
+==== Client-facing hardening (4.0)
-`/cxs/context.json` and `/cxs/eventcollector` are reachable without
authentication, or with a tenant *public* API key. In 3.1 the identity fields
those endpoints accept are treated as claims to be checked rather than as
instructions.
+`/cxs/context.json` and `/cxs/eventcollector` are reachable without
authentication, or with a tenant *public* API key. In 4.0 the identity fields
those endpoints accept are treated as claims to be checked rather than as
instructions.
A caller is **trusted** when it holds a tenant private key or authenticates as
a system administrator (`ROLE_UNOMI_ADMIN` or `ROLE_UNOMI_TENANT_ADMIN`). A
tenant *public* API key is **not** trusted: it identifies the tenant, not the
visitor.
.What changed for public callers
[cols="1,2,2", options="header"]
|===
-| Field | 3.0 | 3.1
+| Field | 3.0 | 4.0
| Body/query `profileId`
| Selected the profile.
@@ -225,9 +225,9 @@ Anonymous browsing, personas and profile overrides are
otherwise unchanged, and
* A client that supplied a session id it did not own now finds `sessionId`
absent from the response. Treat that as "start a new session" and generate a
fresh id rather than replaying the old one.
[#_search_conditions_state_a_type]
-==== A search condition states its type (3.1)
+==== A search condition states its type (4.0)
-A search body carries a `condition`, and 3.1 resolves that condition by its
`type` before it runs the query. A condition with no resolvable type answers an
empty list, and the server logs the reason:
+A search body carries a `condition`, and 4.0 resolves that condition by its
`type` before it runs the query. A condition with no resolvable type answers an
empty list, and the server logs the reason:
[source]
----
@@ -240,7 +240,7 @@ WARN ProfileServiceImpl | Cannot execute query: condition
type 'null' could not
.What changed
[cols="1,2,2", options="header"]
|===
-| Body | 3.0 | 3.1
+| Body | 3.0 | 4.0
| `"condition": {}`
| The condition was dropped, and the search returned every item.
@@ -310,7 +310,7 @@ accepted again. The "Profile import and export" chapter
describes the rule in fu
- Keep system administrator authentication as fallback for administrative
operations
- Continue using system administrator authentication for tenant
administration
-4. **Related client contract changes (3.1 hardening)**
+4. **Related client contract changes (4.0 hardening)**
- Public `/context.json` and `/eventcollector` no longer treat body/query
`profileId` as identity — see below
- Endpoint paths and most payload shapes remain the same; authentication
and public profile-binding rules change
@@ -427,7 +427,7 @@ unomi:migrate 3.0.0
+
Pass your actual origin version without qualifier (for example `3.0.0`).
Optional second argument skips the confirmation prompt. You can preconfigure
`etc/org.apache.unomi.migration.cfg` instead of answering interactive
questions; see <<_shell_commands,Shell commands>>.
+
-Scripts applied for the 3.1 line include (under
`tools/shell-commands/.../META-INF/cxs/migration/`):
+Scripts applied for the 4.0 line include (under
`tools/shell-commands/.../META-INF/cxs/migration/`):
+
* `migrate-4.0.0-00-fixProfileNbOfVisits`
* `migrate-4.0.0-01-tenantDocumentIds`
@@ -468,7 +468,7 @@ Once the migration has been completed, you will be able to
start Apache Unomi 4.
Remember that all data operations now require proper tenant context, either
through tenant authentication or system administrator authentication.
-The fundamental difference between Unomi 3.0 and 3.1 is the introduction of
**comprehensive multi-tenancy support**:
+The fundamental difference between Unomi 3.0 and 4.0 is the introduction of
**comprehensive multi-tenancy support**:
- **3.0**: Single-tenant architecture with system administrator authentication
for all operations
- **4.0**: Multi-tenant architecture with complete data isolation and
tenant-specific authentication
diff --git a/manual/src/main/asciidoc/migrations/v2-compatibility-mode.adoc
b/manual/src/main/asciidoc/migrations/v2-compatibility-mode.adoc
index 463481354..e97b359af 100644
--- a/manual/src/main/asciidoc/migrations/v2-compatibility-mode.adoc
+++ b/manual/src/main/asciidoc/migrations/v2-compatibility-mode.adoc
@@ -79,11 +79,11 @@ single-tenant compatibility mode is managed through
configuration files only. Th
First, migrate your data with Apache Unomi stopped using the single shell
command (bundled Groovy scripts under `META-INF/cxs/migration/` run
automatically for versions after the origin you pass):
```bash
-# From the Karaf shell (Unomi runtime stopped). Example when upgrading from
2.x through 3.1:
+# From the Karaf shell (Unomi runtime stopped). Example when upgrading from
2.x through 4.0:
unomi:migrate 2.0.0
```
-The `migrate-4.0.0-10-tenantInitialization` script (run as part of that chain
when migrating through 3.1) creates tenant `default`, which is the only tenant
this mode uses. If that tenant is missing when the mode is on, the first public
request creates it. See <<_migrate_from_3_0_to_4_0,Migrate from 3.0 to 4.0>>
and <<_shell_commands,Shell commands>>.
+The `migrate-4.0.0-10-tenantInitialization` script (run as part of that chain
when migrating through 4.0) creates tenant `default`, which is the only tenant
this mode uses. If that tenant is missing when the mode is on, the first public
request creates it. See <<_migrate_from_3_0_to_4_0,Migrate from 3.0 to 4.0>>
and <<_shell_commands,Shell commands>>.
===== Step 2: Enable V2 Compatibility Mode
diff --git a/manual/src/main/asciidoc/migrations/writing-migration-scripts.adoc
b/manual/src/main/asciidoc/migrations/writing-migration-scripts.adoc
index f2e76786b..0944692f0 100644
--- a/manual/src/main/asciidoc/migrations/writing-migration-scripts.adoc
+++ b/manual/src/main/asciidoc/migrations/writing-migration-scripts.adoc
@@ -37,7 +37,7 @@ Each file must match:
migrate-<version>-<priority>-<name>.groovy
----
-* `<version>` — three-part version the script belongs to (for example `3.1.0`)
+* `<version>` — three-part version the script belongs to (for example `4.0.0`)
* `<priority>` — two-digit order within that version (`00`, `01`, `05`, …)
* `<name>` — short camelCase label (for example `tenantDocumentIds`)
@@ -81,9 +81,9 @@ Real impact: rollover **write aliases** for event/session
indices were skipped a
[source,groovy]
----
-context.performMigrationStep("3.1.0-get-all-indices", () -> {
+context.performMigrationStep("4.0.0-get-all-indices", () -> {
// ... reindex each index ...
- context.performMigrationStep("3.1.0-configure-rollover-aliases", () -> {
+ context.performMigrationStep("4.0.0-configure-rollover-aliases", () -> {
// configure aliases — NEVER REACHED on resume if outer step completed
})
})
@@ -93,11 +93,11 @@ context.performMigrationStep("3.1.0-get-all-indices", () ->
{
[source,groovy]
----
-context.performMigrationStep("3.1.0-get-all-indices", () -> {
+context.performMigrationStep("4.0.0-get-all-indices", () -> {
// ... reindex each index ...
})
-context.performMigrationStep("3.1.0-configure-rollover-aliases", () -> {
+context.performMigrationStep("4.0.0-configure-rollover-aliases", () -> {
// configure aliases — runs independently on resume
})
----
diff --git a/manual/src/main/asciidoc/samples/login-sample.adoc
b/manual/src/main/asciidoc/samples/login-sample.adoc
index 000d37d15..0224d9b6c 100644
--- a/manual/src/main/asciidoc/samples/login-sample.adoc
+++ b/manual/src/main/asciidoc/samples/login-sample.adoc
@@ -218,6 +218,6 @@ yet — set `privateKey` as shown above and run
`config:update`.
==== Related
-* <<_client_facing_hardening_4_0,Client-facing hardening (3.1)>>
+* <<_client_facing_hardening_4_0,Client-facing hardening (4.0)>>
* <<_how_profile_tracking_works,How profile tracking works>>
* Rule JSON:
https://github.com/apache/unomi/blob/master/samples/login-integration/src/main/resources/META-INF/cxs/rules/exampleLogin.json
diff --git a/manual/src/main/asciidoc/web-tracker.adoc
b/manual/src/main/asciidoc/web-tracker.adoc
index 8daf2e663..807dbe7d5 100644
--- a/manual/src/main/asciidoc/web-tracker.adoc
+++ b/manual/src/main/asciidoc/web-tracker.adoc
@@ -20,7 +20,7 @@ In this section of the documentation, more details are
provided about the web tr
Public context and event endpoints require a tenant public API key
(`X-Unomi-Api-Key`) unless <<_v2_compatibility_mode,V2 compatibility mode>> is
enabled.
-The built-in WAB tracker sample does **not** currently attach that header. For
production 3.1 deployments:
+The built-in WAB tracker sample does **not** currently attach that header. For
production 4.0 deployments:
* Prefer the NPM package / custom integration that can set `X-Unomi-Api-Key`
(see <<_javascript_tracker_guide,JavaScript tracker guide>>), or
* Enable V2 compatibility mode only as a temporary migration aid.
