bazis 0.131.0 → 0.132.0

package/core/workflow/definitions_module/http/Processes.controller.ts

@@ -1,10 +1,11 @@
 import { contextOnlyController } from "../../../http/Routing/contextOnlyControllers";
-import { can } from "../../../access";
+import { can, type AccessObject } from "../../../access";
+import type { LocalizedText } from "../../../../library/workflow";
 import { Authorize, Controller, Created, Get, Patch, Post, Put, type HttpContext } from "../../../http";
 import { buildListDocument } from "../../../../library/jsonapi";
-import { body, callerOf, filterOf, listQuery, optionalInteger, optionalString, pagingOfList, param, requiredString } from "../../internal/http";
+import { body, callerOf, defaultLanguage, filterOf, listQuery, optionalInteger, optionalString, optionalText, pagingOfList, param, requiredString, withTitleText } from "../../internal/http";
 import { WorkflowError } from "../../contracts/WorkflowError";
-import { IWorkflowDefinitions } from "../services/IWorkflowDefinitions.service";
+import { IWorkflowDefinitions, type ProcessSummary } from "../services/IWorkflowDefinitions.service";
 
 /** The process catalog over HTTP (WORKFLOW-001 §3); rights are `workflow.processes.*` (WORKFLOW-002 §6.2). */
 @Controller("workflow")
@@ -14,12 +15,19 @@ export class ProcessesController {
   @Get("processes")
   @Authorize(can("workflow.processes.read"))
   async list(ctx: HttpContext) {
-    const { access } = await callerOf(ctx);
-    const list = listQuery(ctx, { filter: { archived: ["eq"], search: ["eq"] }, sort: ["key", "title", "createdAt", "updatedAt"] });
+    const { access, language } = await callerOf(ctx);
+    const list = listQuery(ctx, { filter: { archived: ["eq"], search: ["eq"], folder: ["eq"], owner: ["eq"] }, sort: ["key", "title", "folder", "createdAt", "updatedAt"] });
     const archived = filterOf(list, "archived");
     if (archived !== undefined && archived !== "true" && archived !== "false") throw new WorkflowError("invalid_input", "archived must be true or false");
-    const page = await this.definitions.list({ ...pagingOfList(list), access: await access.filter("workflow.processes.read"), archived: archived === undefined ? undefined : archived === "true", search: filterOf(list, "search") });
-    return buildListDocument(page.items, list, page.total, { basePath: ctx.path });
+    const page = await this.definitions.list({
+      ...pagingOfList(list),
+      access: await access.filter("workflow.processes.read"),
+      archived: archived === undefined ? undefined : archived === "true",
+      search: filterOf(list, "search"),
+      folder: filterOf(list, "folder"),
+      owner: filterOf(list, "owner"),
+    });
+    return buildListDocument(this.localized(page.items, language, ctx), list, page.total, { basePath: ctx.path });
   }
 
   @Post("processes")
@@ -27,22 +35,25 @@ export class ProcessesController {
   async create(ctx: HttpContext) {
     const request = await body(ctx);
     const key = requiredString(request.key, "key", 64);
-    const { actor, request: from } = await callerOf(ctx, "workflow.processes.manage", { process: key });
+    const folder = optionalString(request.folder, "folder", 500) ?? null;
+    const { actor, request: from, language } = await callerOf(ctx, "workflow.processes.manage", { process: key, folder });
     const process = await this.definitions.create({
       key,
-      title: requiredString(request.title, "title"),
-      description: optionalString(request.description, "description", 2000) ?? null,
+      title: optionalText(request.title) as LocalizedText,
+      description: optionalText(request.description) ?? null,
+      folder,
+      owner: optionalString(request.owner, "owner") ?? null,
       retentionDays: optionalInteger(request.retentionDays, "retentionDays") ?? null,
     }, actor, { request: from });
-    return Created(`${ctx.path}/${process.key}`, process);
+    return Created(`${ctx.path}/${process.key}`, withTitleText(process, language, defaultLanguage(ctx)));
   }
 
   @Get("processes/:key")
   @Authorize(can("workflow.processes.read"))
   async get(ctx: HttpContext) {
     const key = param(ctx, "key");
-    await callerOf(ctx, "workflow.processes.read", { process: key });
-    return await this.definitions.get(key);
+    const { language } = await callerOf(ctx, "workflow.processes.read", await this.objectOf(key));
+    return withTitleText(await this.definitions.get(key), language, defaultLanguage(ctx));
   }
 
   @Patch("processes/:key")
@@ -50,14 +61,20 @@ export class ProcessesController {
   async update(ctx: HttpContext) {
     const key = param(ctx, "key");
     const request = await body(ctx);
-    const { actor, request: from } = await callerOf(ctx, "workflow.processes.manage", { process: key });
+    const { actor, request: from, language } = await callerOf(ctx, "workflow.processes.manage", await this.objectOf(key));
     if (request.archived !== undefined && typeof request.archived !== "boolean") throw new WorkflowError("invalid_input", "archived must be a boolean");
-    return await this.definitions.update(key, {
-      ...(request.title === undefined ? {} : { title: requiredString(request.title, "title") }),
-      ...(request.description === undefined ? {} : { description: optionalString(request.description, "description", 2000) ?? null }),
+    const folder = optionalString(request.folder, "folder", 500) ?? null;
+    // Moving a process needs the right in the folder it goes to as well.
+    if (request.folder !== undefined) await callerOf(ctx, "workflow.processes.manage", { process: key, folder });
+    const process = await this.definitions.update(key, {
+      ...(request.title === undefined ? {} : { title: optionalText(request.title) as LocalizedText }),
+      ...(request.description === undefined ? {} : { description: optionalText(request.description) ?? null }),
+      ...(request.folder === undefined ? {} : { folder }),
+      ...(request.owner === undefined ? {} : { owner: optionalString(request.owner, "owner") ?? null }),
       ...(request.retentionDays === undefined ? {} : { retentionDays: optionalInteger(request.retentionDays, "retentionDays") ?? null }),
       ...(request.archived === undefined ? {} : { archived: request.archived as boolean }),
     }, actor, { request: from });
+    return withTitleText(process, language, defaultLanguage(ctx));
   }
 
   @Put("processes/:key/draft")
@@ -65,19 +82,19 @@ export class ProcessesController {
   async saveDraft(ctx: HttpContext) {
     const key = param(ctx, "key");
     const request = await body(ctx);
-    const { actor, request: from } = await callerOf(ctx, "workflow.processes.manage", { process: key });
+    const { actor, request: from, language } = await callerOf(ctx, "workflow.processes.manage", await this.objectOf(key));
     const expected = optionalString(request.expected, "expected");
     const expectedAt = expected === undefined ? undefined : new Date(expected);
     if (expectedAt !== undefined && Number.isNaN(expectedAt.getTime())) throw new WorkflowError("invalid_input", "expected must be the draftUpdatedAt that was read");
-    return await this.definitions.saveDraft(key, request.document, actor, { request: from, ...(expectedAt === undefined ? {} : { expected: expectedAt }) });
+    return await this.definitions.saveDraft(key, request.document, actor, { request: from, language, ...(expectedAt === undefined ? {} : { expected: expectedAt }) });
   }
 
   @Post("processes/:key/publish")
   @Authorize(can("workflow.processes.publish"))
   async publish(ctx: HttpContext) {
     const key = param(ctx, "key");
-    const { actor, request } = await callerOf(ctx, "workflow.processes.publish", { process: key });
-    const version = await this.definitions.publish(key, actor, { request });
+    const { actor, request, language } = await callerOf(ctx, "workflow.processes.publish", await this.objectOf(key));
+    const version = await this.definitions.publish(key, actor, { request, language });
     return Created(`${ctx.path.replace(/\/publish$/, "")}/versions/${version.version}`, version);
   }
 
@@ -85,7 +102,7 @@ export class ProcessesController {
   @Authorize(can("workflow.processes.read"))
   async versions(ctx: HttpContext) {
     const key = param(ctx, "key");
-    await callerOf(ctx, "workflow.processes.read", { process: key });
+    await callerOf(ctx, "workflow.processes.read", await this.objectOf(key));
     return { data: await this.definitions.versions(key) };
   }
 
@@ -93,16 +110,41 @@ export class ProcessesController {
   @Authorize(can("workflow.processes.read"))
   async version(ctx: HttpContext) {
     const key = param(ctx, "key");
-    await callerOf(ctx, "workflow.processes.read", { process: key });
+    await callerOf(ctx, "workflow.processes.read", await this.objectOf(key));
     const version = optionalInteger(param(ctx, "version"), "version");
     if (version === undefined) throw new WorkflowError("invalid_input", "version must be an integer");
     return await this.definitions.version(key, version);
   }
 
+  /** Checks a document without storing it: every finding, as a save and a publication would give them. */
+  @Post("validate")
+  @Authorize(can("workflow.processes.read"))
+  async validate(ctx: HttpContext) {
+    const request = await body(ctx);
+    const { actor, language } = await callerOf(ctx);
+    return { issues: await this.definitions.validate(request.document, { actor, language }) };
+  }
+
+  /** What a designer builds its forms from (WORKFLOW-002 §4.2). */
+  @Get("palette")
+  @Authorize(can("workflow.processes.read"))
+  async palette() {
+    return this.definitions.palette();
+  }
+
   @Get("tools")
   @Authorize(can("workflow.processes.read"))
   async tools() {
     return { data: this.definitions.tools() };
   }
+
+  /** A process as the object of a permission. */
+  private async objectOf(key: string): Promise<AccessObject> {
+    return { process: key, folder: await this.definitions.folderOf(key) };
+  }
+
+  private localized(items: readonly ProcessSummary[], language: string, ctx: HttpContext) {
+    return items.map((item) => withTitleText(item, language, defaultLanguage(ctx)));
+  }
 }
 contextOnlyController(ProcessesController);

package/core/workflow/definitions_module/model/Definitions.dbContext.ts

@@ -10,7 +10,7 @@ export class DefinitionsDbContext extends DbContext {
 /** The tables of the Definitions part: bazis creates and checks them in the application database. */
 export const definitionsStore = defineOrmOwnedStoreV1({
   contract: "bazis.orm-owned-store/v1",
-  storeKey: "bazis.workflow.definitions",
+  storeKey: "bazis.workflow.definitions.v2",
   formatVersion: 1,
-  ownedScope: { schema: "public", tablePrefix: "bazis_wf_def_" },
+  ownedScope: { schema: "public", tablePrefix: "bazis_wf2_def_" },
 });

package/core/workflow/definitions_module/model/WfProcess.model.ts

@@ -1,11 +1,12 @@
 import { Column, Entity, Index, UUID } from "../../../orm";
+import type { LocalizedText } from "../../../../library/workflow";
 
 /**
- * A process in the catalog: the key it is started by, its names, the draft a
- * designer edits and the retention of finished instances. Changes; the
+ * A process in the catalog: the key it is started by, its card (names, folder,
+ * owner), the draft a designer edits and the retention of finished instances. Changes; the
  * published versions ({@link WfVersion}) do not.
  */
-@Entity({ table: "bazis_wf_def_processes" })
+@Entity({ table: "bazis_wf2_def_processes" })
 export class WfProcess {
   @UUID({ version: "v7" })
   id = "";
@@ -14,11 +15,24 @@ export class WfProcess {
   @Column({ type: "text" })
   key = "";
 
+  @Column({ type: "json" })
+  title: LocalizedText = "";
+
+  /** Every text of `title`, the default language first: what a list searches and sorts by. */
   @Column({ type: "text" })
-  title = "";
+  titleText = "";
+
+  @Column({ type: "json", nullable: true })
+  description: LocalizedText | null = null;
+
+  /** A path, `Sales/Orders`: there is no folder entity. */
+  @Index()
+  @Column({ type: "text", nullable: true })
+  folder: string | null = null;
 
+  /** Whose process it is: an opaque id of the application. */
   @Column({ type: "text", nullable: true })
-  description: string | null = null;
+  owner: string | null = null;
 
   /** The draft document; kept with validation errors too. */
   @Column({ type: "json", nullable: true })

package/core/workflow/definitions_module/model/WfVersion.model.ts

@@ -4,7 +4,7 @@ import { WfProcess } from "./WfProcess.model";
 /** A published version of a process: an immutable snapshot of its document. */
 @ForeignKey(() => WfProcess, { properties: ["processId"], onDelete: "cascade" })
 @Index(["processId", "version"], { unique: true })
-@Entity({ table: "bazis_wf_def_versions" })
+@Entity({ table: "bazis_wf2_def_versions" })
 export class WfVersion {
   @UUID({ version: "v7" })
   id = "";

package/core/workflow/definitions_module/services/IWorkflowDefinitions.service.ts

@@ -1,13 +1,17 @@
 import type { AccessFilter } from "../../../access";
 import type { AgentToolContract } from "../../../agent";
-import type { ProcessDocument, ProcessIssue } from "../../../../library/workflow";
+import type { LocalizedText, ProcessDocument, ProcessIssue, ProcessPalette } from "../../../../library/workflow";
 import type { WorkflowActor, WorkflowAuditOptions, WorkflowPage, WorkflowPaging } from "../../contracts/types";
 import type { OwnedCodeProcess } from "../code/codeProcesses";
 
 export interface ProcessSummary {
   readonly key: string;
-  readonly title: string;
-  readonly description: string | null;
+  readonly title: LocalizedText;
+  readonly description: LocalizedText | null;
+  /** A path, `Sales/Orders`. */
+  readonly folder: string | null;
+  /** Whose process it is: an opaque id. */
+  readonly owner: string | null;
   readonly latestVersion: number | null;
   readonly retentionDays: number | null;
   readonly archived: boolean;
@@ -41,14 +45,18 @@ export interface VersionDetails extends VersionSummary {
 
 export interface CreateProcess {
   readonly key: string;
-  readonly title: string;
-  readonly description?: string | null;
+  readonly title: LocalizedText;
+  readonly description?: LocalizedText | null;
+  readonly folder?: string | null;
+  readonly owner?: string | null;
   readonly retentionDays?: number | null;
 }
 
 export interface UpdateProcess {
-  readonly title?: string;
-  readonly description?: string | null;
+  readonly title?: LocalizedText;
+  readonly description?: LocalizedText | null;
+  readonly folder?: string | null;
+  readonly owner?: string | null;
   readonly retentionDays?: number | null;
   readonly archived?: boolean;
 }
@@ -57,11 +65,20 @@ export interface ProcessListQuery extends WorkflowPaging {
   /** Which processes the caller may see, from `IAccess`; without it the calling code has decided. */
   readonly access?: AccessFilter;
   readonly archived?: boolean;
-  /** Part of the key or title, case-insensitive. */
+  /** Part of the key or a title in any language, case-insensitive. */
   readonly search?: string;
+  /** This folder and those below it. */
+  readonly folder?: string;
+  readonly owner?: string;
 }
 
-export interface SaveDraftOptions extends WorkflowAuditOptions {
+/** Who asks for a validation: it goes to the application's `WorkflowExtensions`. */
+export interface ValidateOptions {
+  readonly language?: string;
+  readonly actor?: WorkflowActor;
+}
+
+export interface SaveDraftOptions extends WorkflowAuditOptions, Pick<ValidateOptions, "language"> {
   /** The `draftUpdatedAt` the caller read: another save since then is `conflict`. Without it the last save wins. */
   readonly expected?: Date;
 }
@@ -81,6 +98,12 @@ export interface SavedDraft {
 export abstract class IWorkflowDefinitions {
   abstract list(query?: ProcessListQuery): Promise<WorkflowPage<ProcessSummary>>;
   abstract get(key: string): Promise<ProcessDetails>;
+  /** The folder of a process, for a check of rights; `null` also for a process that does not exist. */
+  abstract folderOf(key: string): Promise<string | null>;
+  /** Every finding of a document, with the application's `extensions` checks; nothing is stored. */
+  abstract validate(document: unknown, options?: ValidateOptions): Promise<readonly ProcessIssue[]>;
+  /** What a designer builds its forms from: node kinds, functions, paths and Tools. */
+  abstract palette(): ProcessPalette;
   abstract create(process: CreateProcess, actor: WorkflowActor, options?: WorkflowAuditOptions): Promise<ProcessDetails>;
   /** A process declared in code takes only `archived`; other fields give `conflict`. */
   abstract update(key: string, changes: UpdateProcess, actor: WorkflowActor, options?: WorkflowAuditOptions): Promise<ProcessDetails>;
@@ -90,7 +113,7 @@ export abstract class IWorkflowDefinitions {
    * Validates the draft and stores it as the next version; the same document
    * again returns the latest version. `conflict` for a process declared in code.
    */
-  abstract publish(key: string, actor: WorkflowActor, options?: WorkflowAuditOptions): Promise<VersionDetails>;
+  abstract publish(key: string, actor: WorkflowActor, options?: WorkflowAuditOptions & Pick<ValidateOptions, "language">): Promise<VersionDetails>;
   abstract versions(key: string): Promise<readonly VersionSummary[]>;
   abstract version(key: string, version: number): Promise<VersionDetails>;
   /** The latest published version of a process that is not archived. */

package/core/workflow/definitions_module/services/WorkflowDefinitions.service.ts

@@ -2,11 +2,15 @@ import { grantsToWhere } from "../../../access";
 import { createHash } from "node:crypto";
 import { paginate, UniqueViolationError } from "../../../orm";
 import type { AgentToolContract } from "../../../agent";
-import { emptyProcess, hasErrors, validateProcess, type ProcessDocument, type ProcessIssue } from "../../../../library/workflow";
+import { allTexts, checkLocalizedText, emptyProcess, hasErrors, processPalette, validateProcess, type LocalizedText, type ProcessDocument, type ProcessIssue, type ProcessPalette } from "../../../../library/workflow";
+import type { ServiceProvider } from "../../../di";
 import { isUuid, pageQueryOf, type WorkflowActor, type WorkflowAuditOptions, type WorkflowPage } from "../../contracts/types";
 import type { WorkflowClock } from "../../contracts/WorkflowClock";
 import { WorkflowError } from "../../contracts/WorkflowError";
+import { WorkflowExtensions, type ExtensionTarget, type WorkflowPortContext } from "../../contracts/WorkflowExtensions";
+import { canonicalJson } from "../../internal/canonicalJson";
 import type { WorkflowEvents } from "../../internal/WorkflowEvents";
+import type { WorkflowLanguages } from "../../internal/WorkflowLanguages";
 import type { WorkflowTools } from "../../internal/WorkflowTools";
 import type { CodeProcessCatalog } from "../code/CodeProcessCatalog";
 import type { OwnedCodeProcess } from "../code/codeProcesses";
@@ -23,11 +27,14 @@ import {
   type SavedDraft,
   type SaveDraftOptions,
   type UpdateProcess,
+  type ValidateOptions,
   type VersionDetails,
   type VersionSummary,
 } from "./IWorkflowDefinitions.service";
 
 const KEY = /^[a-z][a-z0-9_.-]{0,63}$/;
+/** A path of segments without empty ones: `Sales/Orders`. */
+const FOLDER = /^[^/\s](?:[^/]*[^/\s])?(?:\/[^/\s](?:[^/]*[^/\s])?)*$/;
 /** Who publishes the processes declared in code. */
 const CODE_ACTOR: WorkflowActor = { kind: "system", id: "code" };
 
@@ -38,6 +45,9 @@ export class WorkflowDefinitions extends IWorkflowDefinitions {
     private readonly code: CodeProcessCatalog,
     private readonly clock: WorkflowClock,
     private readonly events: WorkflowEvents,
+    private readonly languages: WorkflowLanguages,
+    /** The scope: the port is asked here, so that the application's own registration replaces the default. */
+    private readonly services: ServiceProvider,
   ) {
     super();
   }
@@ -51,9 +61,16 @@ export class WorkflowDefinitions extends IWorkflowDefinitions {
     if (query.archived === false) source = source.where((p) => p.archivedAt.isNull());
     if (query.search !== undefined && query.search.trim() !== "") {
       const text = query.search.trim();
-      source = source.where((p) => p.key.contains(text, { ignoreCase: true }).or(p.title.contains(text, { ignoreCase: true })));
+      source = source.where((p) => p.key.contains(text, { ignoreCase: true }).or(p.titleText.contains(text, { ignoreCase: true })));
     }
-    const { items, total } = await paginate(source, pageQueryOf(query, { field: "key", dir: "asc" }));
+    if (query.folder !== undefined) {
+      const folder = query.folder;
+      source = source.where((p) => p.folder.eq(folder).or(p.folder.startsWith(`${folder}/`)));
+    }
+    if (query.owner !== undefined) source = source.where((p) => p.owner.eq(query.owner!));
+    // The list sorts by a title as `titleText`: `title` itself is JSON.
+    const sort = query.sort?.map((field) => (field.field === "title" ? { ...field, field: "titleText" } : field));
+    const { items, total } = await paginate(source, pageQueryOf({ ...query, ...(sort === undefined ? {} : { sort }) }, { field: "key", dir: "asc" }));
     return { items: items.map((row) => this.summaryOf(row)), total };
   }
 
@@ -61,12 +78,44 @@ export class WorkflowDefinitions extends IWorkflowDefinitions {
     return this.detailsOf(await this.process(key, false));
   }
 
+  async folderOf(key: string): Promise<string | null> {
+    const row = await this.db.processes.asNoTracking().firstOrDefault((p) => p.key.eq(key));
+    return row?.folder ?? null;
+  }
+
+  async validate(document: unknown, options: ValidateOptions = {}): Promise<readonly ProcessIssue[]> {
+    const port = this.services.resolve(WorkflowExtensions);
+    const namespaces = new Set(port.namespaces());
+    const issues = validateProcess(document, { tools: (name) => this.workflowTools.has(name), extensions: (namespace) => namespaces.has(namespace) });
+    if (namespaces.size === 0 || issues.some((issue) => issue.code === "too_large" || issue.code === "schema")) return issues;
+    const context: WorkflowPortContext = { partition: null, language: options.language ?? this.languages.default, actor: options.actor ?? null };
+    const found: ProcessIssue[] = [...issues];
+    const { extensions, variables, nodes } = document as ProcessDocument;
+    const checkAll = async (data: Readonly<Record<string, unknown>> | undefined, target: ExtensionTarget): Promise<void> => {
+      if (typeof data !== "object" || data === null) return;
+      for (const [namespace, value] of Object.entries(data)) {
+        if (!namespaces.has(namespace)) continue;
+        for (const message of await port.check(namespace, value, target, context)) found.push({ severity: "error", code: "extension_invalid", message: `${namespace}: ${message}`, ...target });
+      }
+    };
+    await checkAll(extensions, {});
+    if (Array.isArray(variables)) for (const variable of variables) await checkAll(variable?.extensions, { variable: variable?.name });
+    for (const [node, raw] of Object.entries(nodes)) await checkAll(raw?.extensions, { node });
+    return found;
+  }
+
+  palette(): ProcessPalette {
+    return processPalette(this.tools());
+  }
+
   async create(process: CreateProcess, actor: WorkflowActor, options: WorkflowAuditOptions = {}): Promise<ProcessDetails> {
     if (typeof process.key !== "string" || !KEY.test(process.key)) throw new WorkflowError("invalid_input", "key must match ^[a-z][a-z0-9_.-]{0,63}$");
     const row = Object.assign(new WfProcess(), {
       key: process.key,
-      title: title(process.title),
+      ...this.titled(process.title),
       description: description(process.description),
+      folder: folder(process.folder),
+      owner: owner(process.owner),
       retentionDays: retention(process.retentionDays),
       draft: emptyProcess(),
       draftUpdatedAt: this.clock.now(),
@@ -88,19 +137,22 @@ export class WorkflowDefinitions extends IWorkflowDefinitions {
     const row = await this.process(key, true);
     const { archived, ...fields } = changes;
     if (Object.values(fields).some((value) => value !== undefined)) this.assertNotCode(key);
-    const before = { title: row.title, description: row.description, retentionDays: row.retentionDays, archived: row.archivedAt !== null };
-    if (changes.title !== undefined) row.title = title(changes.title);
+    const card = (): string => canonicalJson({ title: row.title, description: row.description, folder: row.folder, owner: row.owner, retentionDays: row.retentionDays });
+    const before = { card: card(), archived: row.archivedAt !== null };
+    if (changes.title !== undefined) Object.assign(row, this.titled(changes.title));
     if (changes.description !== undefined) row.description = description(changes.description);
+    if (changes.folder !== undefined) row.folder = folder(changes.folder);
+    if (changes.owner !== undefined) row.owner = owner(changes.owner);
     if (changes.retentionDays !== undefined) row.retentionDays = retention(changes.retentionDays);
     if (archived !== undefined) row.archivedAt = archived ? row.archivedAt ?? this.clock.now() : null;
     await this.db.saveChanges();
-    if (row.title !== before.title || row.description !== before.description || row.retentionDays !== before.retentionDays) await this.changed("updated", key, actor, options);
+    if (card() !== before.card) await this.changed("updated", key, actor, options);
     if (archived !== undefined && archived !== before.archived) await this.changed(archived ? "archived" : "restored", key, actor, options);
     return this.detailsOf(row);
   }
 
   async saveDraft(key: string, document: unknown, actor: WorkflowActor, options: SaveDraftOptions = {}): Promise<SavedDraft> {
-    const issues = this.validate(document);
+    const issues = await this.validate(document, { actor, ...(options.language === undefined ? {} : { language: options.language }) });
     if (issues.some((issue) => issue.code === "too_large")) throw new WorkflowError("invalid_document", "The document is too large", issues);
     return await this.db.transactionScope(async (transaction) => {
       const row = await this.db.processes.where((p) => p.key.eq(key)).forUpdate().firstOrDefault();
@@ -120,13 +172,13 @@ export class WorkflowDefinitions extends IWorkflowDefinitions {
     });
   }
 
-  async publish(key: string, actor: WorkflowActor, options: WorkflowAuditOptions = {}): Promise<VersionDetails> {
+  async publish(key: string, actor: WorkflowActor, options: WorkflowAuditOptions & Pick<ValidateOptions, "language"> = {}): Promise<VersionDetails> {
     return await this.db.transactionScope(async (transaction) => {
       const row = await this.db.processes.where((p) => p.key.eq(key)).forUpdate().firstOrDefault();
       if (!row) throw notFound(key);
       this.assertNotCode(key);
       if (row.archivedAt !== null) throw new WorkflowError("archived", `Process ${key} is archived`);
-      const issues = this.validate(row.draft);
+      const issues = await this.validate(row.draft, { actor, ...(options.language === undefined ? {} : { language: options.language }) });
       if (hasErrors(issues)) throw new WorkflowError("invalid_document", `Process ${key} has errors and cannot be published`, issues);
       const { version, created } = await this.publishDraft(row, actor);
       if (created) transaction.afterCommit(() => this.changed("published", key, actor, options, version.version));
@@ -151,9 +203,13 @@ export class WorkflowDefinitions extends IWorkflowDefinitions {
           this.db.processes.add(row);
           transaction.afterCommit(() => this.changed("created", process.key, CODE_ACTOR));
         }
-        const fields = { title: title(process.title), description: description(process.description), retentionDays: retention(process.retentionDays) };
-        if (row.title !== fields.title) row.title = fields.title;
-        if (row.description !== fields.description) row.description = fields.description;
+        const named = this.titled(process.title);
+        const about = description(process.description);
+        if (canonicalJson(row.title) !== canonicalJson(named.title)) Object.assign(row, named);
+        if (canonicalJson(row.description) !== canonicalJson(about)) row.description = about;
+        const fields = { folder: folder(process.folder), owner: owner(process.owner), retentionDays: retention(process.retentionDays) };
+        if (row.folder !== fields.folder) row.folder = fields.folder;
+        if (row.owner !== fields.owner) row.owner = fields.owner;
         if (row.retentionDays !== fields.retentionDays) row.retentionDays = fields.retentionDays;
         if (row.draft === null || canonicalJson(row.draft) !== canonicalJson(process.document)) {
           row.draft = process.document;
@@ -260,6 +316,8 @@ export class WorkflowDefinitions extends IWorkflowDefinitions {
       key: row.key,
       title: row.title,
       description: row.description,
+      folder: row.folder,
+      owner: row.owner,
       latestVersion: row.latestVersion,
       retentionDays: row.retentionDays,
       archived: row.archivedAt !== null,
@@ -278,8 +336,11 @@ export class WorkflowDefinitions extends IWorkflowDefinitions {
     };
   }
 
-  private validate(document: unknown): ProcessIssue[] {
-    return validateProcess(document, { tools: (name) => this.workflowTools.has(name) });
+  /** A title with the column a list searches and sorts by. */
+  private titled(value: unknown): { readonly title: LocalizedText; readonly titleText: string } {
+    const problem = checkLocalizedText(value, 200);
+    if (problem) throw new WorkflowError("invalid_input", `title ${problem}`);
+    return { title: value as LocalizedText, titleText: allTexts(value as LocalizedText, this.languages.default) };
   }
 
   private async process(key: string, tracked: boolean): Promise<WfProcess> {
@@ -294,14 +355,22 @@ function notFound(key: string): WorkflowError {
   return new WorkflowError("not_found", `Process ${key} does not exist`);
 }
 
-function title(value: unknown): string {
-  if (typeof value !== "string" || value.trim() === "" || value.length > 200) throw new WorkflowError("invalid_input", "title must be 1–200 characters");
+function description(value: unknown): LocalizedText | null {
+  if (value === undefined || value === null) return null;
+  const problem = checkLocalizedText(value, 2000, 0);
+  if (problem) throw new WorkflowError("invalid_input", `description ${problem}`);
+  return value as LocalizedText;
+}
+
+function folder(value: unknown): string | null {
+  if (value === undefined || value === null) return null;
+  if (typeof value !== "string" || value.length > 500 || !FOLDER.test(value)) throw new WorkflowError("invalid_input", "folder must be a path like Sales/Orders");
   return value;
 }
 
-function description(value: unknown): string | null {
+function owner(value: unknown): string | null {
   if (value === undefined || value === null) return null;
-  if (typeof value !== "string" || value.length > 2000) throw new WorkflowError("invalid_input", "description must be up to 2000 characters");
+  if (typeof value !== "string" || value === "" || value.length > 200) throw new WorkflowError("invalid_input", "owner must be up to 200 characters");
   return value;
 }
 
@@ -321,12 +390,3 @@ function versionOf(key: string, row: WfVersion): VersionDetails {
     document: row.document as ProcessDocument,
   };
 }
-
-/** JSON with sorted keys: the same document gives the same hash whatever the key order. */
-function canonicalJson(value: unknown): string {
-  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
-  if (typeof value === "object" && value !== null) {
-    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson((value as Record<string, unknown>)[key])}`).join(",")}}`;
-  }
-  return JSON.stringify(value) ?? "null";
-}

package/core/workflow/generated/deps.ts

@@ -5,7 +5,10 @@ import { DbContextOptions } from "../../../library/orm/DbContextOptions";
 import { ServiceProvider } from "../../di/ServiceProvider";
 import { EventBus } from "../../kernel/events/EventBus";
 import { WorkflowClock } from "../contracts/WorkflowClock";
+import { FolderReferences } from "../definitions_module/access/Folder.references";
 import { ProcessReferences } from "../definitions_module/access/Process.references";
+import { ProcessFolderLookup } from "../definitions_module/access/ProcessFolder.lookup";
+import { CatalogImport } from "../definitions_module/code/CatalogImport";
 import { CodeProcessCatalog } from "../definitions_module/code/CodeProcessCatalog";
 import { CodeProcessPublisher } from "../definitions_module/code/CodeProcessPublisher";
 import { ProcessesController } from "../definitions_module/http/Processes.controller";
@@ -13,6 +16,7 @@ import { DefinitionsDbContext } from "../definitions_module/model/Definitions.db
 import { IWorkflowDefinitions } from "../definitions_module/services/IWorkflowDefinitions.service";
 import { WorkflowDefinitions } from "../definitions_module/services/WorkflowDefinitions.service";
 import { WorkflowEvents } from "../internal/WorkflowEvents";
+import { WorkflowLanguages } from "../internal/WorkflowLanguages";
 import { WorkflowTools } from "../internal/WorkflowTools";
 import { WorkflowRetention } from "../runtime_module/background/WorkflowRetention";
 import { WorkflowWorker } from "../runtime_module/background/WorkflowWorker";
@@ -33,12 +37,15 @@ import { IWorkflowTasks } from "../tasks_module/services/IWorkflowTasks.service"
 import { WorkflowTasks } from "../tasks_module/services/WorkflowTasks.service";
 
 registerFrameworkClassDeps([
+  [CatalogImport, [DefinitionsDbContext, WorkflowLanguages]],
   [CodeProcessCatalog, [ServiceProvider]],
   [CodeProcessPublisher, [ServiceProvider]],
   [DefinitionsDbContext, [DbContextOptions]],
   [EventsController, [IWorkflowRuntime]],
-  [InstancesController, [IWorkflowRuntime]],
+  [FolderReferences, [DefinitionsDbContext]],
+  [InstancesController, [IWorkflowRuntime, IWorkflowDefinitions]],
   [ProcessesController, [IWorkflowDefinitions]],
+  [ProcessFolderLookup, [DefinitionsDbContext]],
   [ProcessReferences, [DefinitionsDbContext]],
   [RuntimeDbContext, [DbContextOptions]],
   [Schedules, [RuntimeDbContext, WorkflowEngine, IWorkflowDefinitions]],
@@ -47,11 +54,12 @@ registerFrameworkClassDeps([
   [TasksDbContext, [DbContextOptions]],
   [TimerStep, [RuntimeDbContext, WorkflowEngine]],
   [ToolStep, [RuntimeDbContext, WorkflowEngine, WorkflowTools]],
-  [WorkflowDefinitions, [DefinitionsDbContext, WorkflowTools, CodeProcessCatalog, WorkflowClock, WorkflowEvents]],
+  [WorkflowDefinitions, [DefinitionsDbContext, WorkflowTools, CodeProcessCatalog, WorkflowClock, WorkflowEvents, WorkflowLanguages, ServiceProvider]],
   [WorkflowEngine, [RuntimeDbContext, IWorkflowDefinitions, GraphCache, WorkflowEvents, WorkflowClock]],
   [WorkflowEvents, [EventBus, ServiceProvider, "optional:Logger"]],
+  [WorkflowLanguages, ["Config:workflow"]],
   [WorkflowRetention, [ServiceProvider, "Config:workflow"]],
-  [WorkflowRuntime, [RuntimeDbContext, WorkflowEngine, IWorkflowDefinitions, ServiceProvider]],
+  [WorkflowRuntime, [RuntimeDbContext, WorkflowEngine, IWorkflowDefinitions, ServiceProvider, WorkflowLanguages]],
   [WorkflowTasks, [TasksDbContext, IWorkflowRuntime, WorkflowClock, WorkflowEvents]],
   [WorkflowTools, [ServiceProvider]],
   [WorkflowWorker, [ServiceProvider, "Config:workflow"]],

package/core/workflow/index.ts

@@ -1,5 +1,5 @@
 /**
- * Business processes without a UI (WORKFLOW-001): the composite `WorkflowModule`
+ * Business processes without a UI (WORKFLOW-001, WORKFLOW-002): the composite `WorkflowModule`
  * with the Definitions and Runtime parts, their services, HTTP, events and
  * extension points. The document format is `bazis/library/workflow`.
  */
@@ -26,6 +26,7 @@ export {
   type SavedDraft,
   type SaveDraftOptions,
   type UpdateProcess,
+  type ValidateOptions,
   type VersionDetails,
   type VersionSummary,
 } from "./definitions_module/services/IWorkflowDefinitions.service";
@@ -58,11 +59,12 @@ export {
   type WorkflowTaskRequested,
   type WorkflowTokenClosed,
 } from "./runtime_module/events/Runtime.events";
-export { workflowRuntimeConfig } from "./runtime_module/config/Runtime.config";
+export { workflowConfig, type WorkflowSettings } from "./contracts/Workflow.config";
 export type { HistoryType } from "./runtime_module/model/WfHistory.model";
 export type { InstanceStatus, StartedVia } from "./runtime_module/model/WfInstance.model";
 export type { TokenStatus } from "./runtime_module/model/WfToken.model";
 export { WorkflowInputValidator, DefaultWorkflowInputValidator, type WorkflowInputContext } from "./contracts/WorkflowInputValidator";
+export { WorkflowExtensions, DefaultWorkflowExtensions, type ExtensionTarget, type WorkflowPortContext } from "./contracts/WorkflowExtensions";
 export { WorkflowError, type WorkflowErrorCode } from "./contracts/WorkflowError";
 export type { WorkflowActor, WorkflowAuditOptions, WorkflowPage, WorkflowPaging, WorkflowRequest, WorkflowToolMetadata } from "./contracts/types";