Process Catalog

Required Access Level

Admin or Super Admin

What is a definition?

A definition is the process model (BPMN) or case model (CMMN) published on the platform. The platform divides them between Global and Local scopes.

Local Definitions (Tenant Processes): The Tenant Admin views and manages that process's configuration inside their company, under Modeling → Process Catalog. Opening a process gives access to the Diagram, Documentation, Versions, Settings, Variables, Knowledge Base, AI Agents, Forms and Auto-Learning tabs.

Global Processes Catalog: The Tenant Admin also sees, in the same list, the global processes available on the platform:

• They cannot create, edit models, or view the internal development configurations of global templates.
• They can activate or deactivate (using the toggle switch) any global process for their own environment. A deactivated process will not appear for users to start instances in the portal or via API in that specific tenant.
• Drafts: Global processes that have not yet been officially published will appear with the toggle disabled. The Admin will not be able to use them until the Super Admin finishes publishing.

Publishing a new definition

Creating a definition and drawing it are two steps, in this order.

Step 1 — Create the empty definition

1. Go to Modeling → Process Catalog
2. Click New Definition and choose the type — BPMN, DMN Template or CMMN
3. Enter the key and the name, and confirm

The definition is deployed right away, with the minimum drawing for its type: a start event for BPMN, an empty case plan for CMMN. No modeler opens at this point — the first version shows up on the Versions tab as Available, and publishing is a separate step.

Step 2 — Draw it in the modeler

1. Open the definition from the list
2. Click Edit / New version — the modeler opens with the current version's XML loaded
3. Model, then click New version to publish

For BPMN, the modeler also offers Review with AI, which analyses the drawing before you publish.

Alternative path — sending a ready-made XML

If you already have the file drawn, you do not need the two steps above.

1. Go to Modeling → Process Catalog
2. Click Import XML, at the top of the screen, next to New Definition
3. Pick the file — .bpmn, .bpmn20.xml, .cmmn, .cmmn.xml and .dmn are accepted

The file is deployed as soon as you confirm the choice; there is no confirmation dialog. If the XML is rejected, the server's message appears in the red alert just below the header.

The same upload remains available through the API, at POST /api/a/definitions/deploy with the file in the file field — see API Reference.

In the CMMN modeler the properties panel changes with what you select:

Selected	What the panel offers
Case plan (the outer rectangle)	Auto-complete and the case's start form
Human task	Form, assignee, candidate users, candidate roles, due date and priority
Inner stage	Auto-complete
Service task	Implementation (class, delegate, expression or ✨ AI agent), result variable, background execution and the delegate's parameters
Service task with an AI agent	Agent, instruction, result variable, this step's tools and this step's knowledge bases — the same controls the BPMN modeler offers

Assignee and candidates take either a person from the list or an expression such as ${gestor} — in that case the start form is what fills the value in.

What the panel does not edit, the modeler no longer deletes

A case can call a process or another case and pass variables into it — the <flowable:in> / <flowable:out> block written by hand in the XML. The panel still has no field for it: whoever wants that wiring writes it in the file and uploads it. What changed is that opening and saving the same case in the modeler now keeps that block — it used to disappear silently, and the case went back to running with no variables passed in at all.

The DMN Template option does different things per role

For the Super Admin it creates a global DMN template — the baseline each tenant deploys its own decision table from. For the tenant Admin it deploys a decision table straight into the tenant, which then shows up under DMN Decisions.

Editing an existing definition

To create a new version of an already published definition:

1. Open the definition and go to the Versions tab
2. Click Edit / New on the row of the version you want to start from
3. The modeler opens with that version's XML pre-loaded
4. Make your changes and click New version to publish

On the same tab, each row shows the version's state — Published, Available or Suspended — and a version that is not published yet carries a Publish button.

Versioning

When publishing a file with the same process key, a new version is created automatically. Ongoing instances continue on the previous version; new instances use the latest version.

AI assistant in the modeler

The modeler has an assistant that works on the open process. Beyond drawing the diagram, it configures what surrounds it: it can create and change forms, create knowledge bases and link them to the process, create CMS collections, create AI agents and attach them to a step.

Four things are worth knowing before using it:

• It says what it did. Every form, knowledge base or agent it creates is listed back in the conversation, named and linked. When an instruction could not be applied — a connection whose elements do not exist, for instance — it reports it instead of moving on silently.
• It does not publish. Nothing the assistant creates reaches a running process: publishing the definition is your action, and it is where you check the result by running an instance.
• It does not edit an existing agent. An agent already used by a published process would take effect on the next run with no publish and no test in between. To change behaviour, create another agent and attach the step to it.
• The conversation survives a reload. The history is kept per process, in this browser. It never reaches the server, is not shared with anyone else and disappears if you clear the site data — it is the reasoning you just had, not an audit record.

The assistant reads the process description before proposing anything, and may propose a new description at the end of the conversation. The proposal is shown beside the current text — the description only changes when you accept it, because it has no version history to undo.

Scope

The assistant works in the scope you are in. Editing a Global Template it reads and writes global data; inside a tenant, the tenant's. It never mixes the two in one conversation.

Reading a version's XML

In the Process Catalog list, every row carries Export XML, next to Details. The file is downloaded with the definition key in its name and the extension of its type — .bpmn, .cmmn or .dmn. It is the same content the modeler loads when you open the version under Edit / New, and it is the version the list is showing.

The button requires the same role as the rest of the screen: tenant Admin or Super Admin. Through the API, the address is GET /api/a/definitions/{key}/versions/{id}/xml.

Export and Import XML are the pair that moves a process between environments: export it in the staging tenant, import it into the production one.

Process documentation

The Documentation tab, right after Diagram, holds a Markdown text written for people: what the process is for, who the actors are, what triggers each path, what to do when something goes wrong.

The diagram shows the shape of the flow and says nothing about intent. Without this text, a new analyst inherits a picture without its rationale.

The editor has two tabs, Write and Preview. The text is saved immediately and takes effect at once — it does not depend on publishing a new version or on a deploy. Documentation changes more often than diagrams, and forcing a deploy to fix a sentence would be the wrong trade.

Not to be confused with a Knowledge Base

This documentation is read by people. It is not sent to the AI, not split into chunks and not retrieved by vector search. What feeds the agent are Knowledge Bases — see Knowledge Bases (RAG) below.

Processes that come from a global template

If the process comes from a global template, its documentation is written by the Super Admin in the Global Templates panel and appears here read-only, with a banner naming the source. There is no editor, and that is deliberate: a global process has no tenant-editable diagram, agents or forms either. A local text that diverged would describe a flow nobody here can change.

If the template carries no documentation yet, the tab says so — rather than inviting you to write something that would not be saved.

Who may write

Only a tenant Admin or Manager. Everyone else reads. Someone who cannot write does not see a disabled editor: they see no editor at all.

Process Roles

Each process can declare specific roles (e.g., Requester, Approver). After publishing the definition, you can view the roles automatically extracted from the BPMN/CMMN file.

These roles are used to assign tasks to the right people in each execution. Tenant members with the corresponding process role will receive the tasks automatically.

Business Key template

The business key is the instance's identifier in business terms — the invoice number, the order code, whatever ties the execution to the document that started it. On the definition's Settings tab you define a template using process variables, for example ${tipoDoc}-${emissao}-${cnpjEmissor}.

A missing variable does not make a key

If the template's variables are not sent when the instance starts, the instance is not created: the platform answers 422 naming the template variables that were missing.

Refusing at the door is deliberate. An instance born without a key would run to completion and produce its result, and only much later would anyone find there is no way to refer to it — or to answer whether that document had already been processed. One immediate, readable error costs less than weeks of orphaned instances.

The refusal covers any template variable that does not resolve, not only the case where all of them are missing. A key like NFSE--, with only the document type filled in, is identical for every invoice of that type — it collides by construction, and a key that collides is not a key.

Two ways out when a variable may legitimately be absent:

• give it a default in the template itself: ${cnpjEmissor:-SEM-CNPJ};
• or send businessKey directly on creation, which bypasses the template.

A definition without a template still gets a key. The platform applies a built-in default, DOC-${date:yyyyMMdd}-${random:4}, so every instance started without an explicit businessKey is born with something like DOC-20260813-A7K2. There is no such thing as a keyless instance by omission.

That default never trips the refusal above, because a date and a random suffix always resolve. It simply means nothing to the business: if you want a key that identifies the document, declare the template; otherwise the platform guarantees at least a dated identifier.

Attachment policy

In the definition's Settings tab, below the Business Key template, you define how that process's attachments behave.

How attachments arrive

Mode	What happens
Ad hoc (default)	Besides the form, anyone with permission can attach directly from the task's attachment panel.
Form only	The file arrives exclusively through a file field on the form. The panel becomes read-only.

Form only requires a file field

In this mode, a process whose form has no file field accepts no attachment at all. And since the instance screen has no form, it stops offering any upload path — files then only enter while a task is being filled in.

Who can do what

Three lists, all filled with process roles:

• Roles that may preview — who can open the preview and download.
• Roles that may replace — who can swap a file for a new version.
• Roles that may attach from the panel — only appears in Ad hoc mode.

An empty list means "anyone holding a role in this process" — not "everyone". Someone with no role in the definition does not reach its attachments. Administrators always pass every check.

Deleting is not an option

There is no attachment deletion for a process, for any role, administrators included. Correcting a file means replacing it: the previous one leaves the list and remains as history.

Knowledge Bases (RAG)

On the details page of a process, you will have access to the Knowledge Base tab. In it, you can view all the knowledge bases created by the administrators (Global KBs or restricted to the Tenant) and enable them for this specific process.

By making this explicit link (Toggling), any AI agent that acts in this process will have its System Prompt fed back with the rules from the enabled bases. This prevents the AI from applying financial sector rules in an HR process, for example.

The base belongs to the process; the step chooses within it

The link belongs to the process, not to the agent: swapping the agent on a step does not change which bases are within its reach.

What the link defines is the available set. Each Service Task picks inside it through the aiKnowledgeBases field, and picks its own tools too — two steps of the same process can see different bases. See What belongs to the agent and what belongs to the step and, on splitting the prompt across more than one agent, One agent per domain.

A step that calls a Java Delegate

Not every step needs AI. When the rule is deterministic — reading a known layout, computing a check digit, normalising a document with a fixed format — a Java Delegate does the work exactly, with no token cost and no risk of the model inventing a value.

In the modeler, select the Service Task and pick the delegate in the delegateExpression field. The list carries the delegates the platform currently has loaded, with the class name beside each one to tell similar names apart.

When the delegate exists in the target environment but not in this one, use Type manually and write the expression by hand. The list is the default path, not a cage.

Picking from a list is not just convenience

A delegate's name is not always obvious: it comes from @Component("name") when the class carries the annotation, and from the simple class name with a lowercase initial when it does not. Typing it wrong would publish a process that accepts work and then stalls at the step. That is why the platform also refuses to deploy a process referencing a delegate that does not exist, even when the XML came from outside the modeler.

Parameters

A delegate may declare parameters. When it does, the fields appear right below the selection, already filled with the default value its author defined.

The value can be literal (nfse-v2) or come from a process variable — write it as ${myVariable} and the platform recognises the form and stores it correctly in the XML.

A parameter marked as required and left empty blocks the definition from being saved, naming the parameter that is missing. The check happens in the modeler, where it can still be fixed on the spot.

A parameter holds no secret: passwords, tokens and API keys belong in tenant variables, for the reason given in Java Delegates.

Inside a case the delegate is a different type

The case engine does not run JavaDelegate. A service task inside a CMMN needs a class implementing PlanItemJavaDelegate (or PlanItemFutureJavaDelegate); pointing at a JavaDelegate publishes a case that stalls on the step, with no error in the modeler.

That is why the CMMN modeler's list shows only the delegates the case engine can run, and the panel warns in red when the case already points at one only the process engine executes — the normal outcome of a file written by hand or copied from a process.

The panel's Service task section writes flowable:type="java" along with the implementation you pick. Without that attribute Flowable ignores the whole task, which is exactly what happened to whoever edited the XML by hand and forgot it.

The platform ships a case delegate of its own: the AI step. Pick ✨ AI agent as the implementation and the panel starts asking for the agent, the instruction, the result variable, the tools and the knowledge bases — the same fields the BPMN modeler offers. It does not appear in the delegate list because that list shows what this tenant uploaded, and the AI step belongs to the platform. See AI Agents.

When the delegate changes

If you swap the selected delegate, parameters with matching names are preserved and the rest are marked unknown rather than disappearing. The same holds for an expression pointing at a delegate not loaded in this environment: it stays, flagged — deleting it would silently discard a decision somebody made on purpose.

Self-learning

A published process learns from its own history: the platform counts what was decided in each field, in comparable situations, and uses that count to suggest values on the next tasks. It is configured on the definition's Self-Learning tab.

How It Works

Once a day the platform walks the history of completed tasks and counts, field by field, what was decided in comparable situations. That is where suggestions with a confidence score and the "34 of 38 cases" explanation come from. No AI is involved: these are counts over real decisions. The details are in Smart autocomplete.

When a user asks for suggestions on a task, fields with a qualifying pattern are filled from the counts, calling no AI at all. Tier 2 is offered with a button to apply, badged Past case.

A suggestion is built from two tiers, and each is only reached when the one above has nothing for that field:

1. Counting — choice fields (select, radio, checkbox, boolean, lookup, rating) and also textareas that repeat. A long-text field with few distinct values over the period is a template, not prose, and is counted like any category. Costs nothing.
2. Past case — for a text field with no qualifying pattern, the platform returns the most frequent past value for that same context, verbatim, for you to edit. Also costs nothing, and it is traceable: it can say how many past cases it came from. Counting frequencies only means something over categories — an opinion written afresh for every document occurs exactly once, so its confidence could never be high enough to become a suggestion.

Autofill calls no AI at all

Both tiers are counts over real decisions, so Autofill consumes no AI quota. If a genuinely unique text field has no similar past case, it simply gets no suggestion rather than a generated one.

The following stay out of both paths, always:

• Personal fields by declared type — CPF, CNPJ, postal code, e-mail and phone. What counts is the type picked in the form builder, not the field name: a field named requester declared as text is protected once you declare it correctly, and a productName declared as a select is learned normally.
• Attachments and layout elements — file, heading, separator and markdown viewer carry no suggestible value.
• Platform-internal variables — those starting with _ or ai_, plus tenantId.

Number, currency and date fields never become suggestions, but still serve as conditions ("when the document type is X..."). Variables the process creates outside the form follow the same rule: never suggested, because they are not on the user's screen, but they may condition.

None of this reaches the AI either: an excluded field is removed from what the model sees, not masked.

There is no screen where you pick what to learn: the type you chose when building the form decides.

Field type	Enters learning
Select, radio, checkbox, boolean, lookup, rating	Always
Single-line text	While the value stays within 512 characters
Textarea	Only with up to 20 distinct values over the period; above that it is prose
Date, number, currency	Never become a suggestion; only condition with up to 20 distinct values
CPF, CNPJ, postal code, e-mail, phone, password	Never — removed from what the model sees
File, heading, separator, markdown viewer	Never — they carry no suggestible value

If a field should be learned and is not, the likely cause is that it is declared as free text where it should have been a select.

A person's name and an address are not protected by type

The protection on the last row works by declared type, and there is no "person name" or "address" type in the form builder — a fullName or deliveryAddress field declared as text is learned like any other.

For those, use Fields excluded from learning. It is the only protection that works.

There is a partial exception that must not be mistaken for a guarantee: fields the form does not declare — the variables a process creates outside the screen — are checked by name (nome, endereco, nascimento, rg, idade and others). That catches some cases and errs in both directions, and the check is never consulted for a field the form does declare.

To exclude a specific field, list its name under Fields excluded from learning, comma-separated. It is a denylist: everything else keeps being learned, and a new field on the form starts being learned on its own. It does not re-enable what is already excluded by type — a CPF field stays out whether or not you list it.

There is no batch trigger. The micro-analysis does not fire once N completions have accumulated: counting completions skips or double-fires when two people finish at the same moment, and the counter has no reliable point to reset at. Everything happens in the daily run.

The fields on the tab

The Self-Learning tab sits on the process definition itself, alongside the others. The AI Agent form carries no learning field at all — looking for it there is looking where it does not exist.

The practical consequence is worth stating: a process running several agents has one learning configuration, shared by all of them. Swapping the agent on a step does not change what that process learns, nor does it split learning by specialty.

The fields on the screen:

• Auto-Learning Enabled: Toggles task learning on/off. Switched off, the pattern counts are not refreshed and no new suggestion appears.
• Time Window (Months): How many months of recent history the counts consider (default: 3). It is what lets a process forget obsolete decisions when a business rule changes.
• Fields excluded from learning: A comma-separated list of field names this process must neither learn from nor send to the AI. It is a denylist: everything else keeps being learned, and a field added to the form later is learned on its own. It cannot re-enable what is already excluded by type — a CPF field stays out whether or not you list it.

Every published process has its own configuration, and it applies to that process alone. Switching learning off on one process does not affect the others.

Learning health

Below the configuration, on the same tab, sits the Learning health table: every pattern in use, with the confidence it claims and the rate at which users actually accepted it, side by side.

Reading the two columns together is the point. Confidence is what the history says; acceptance is what people did when they saw the suggestion. While the two track each other, the pattern still holds. When acceptance collapses and confidence stays high, the business rule has usually changed and the history has not caught up — those rows are highlighted and sorted to the top.

A row only gets a verdict after ten exposures. Below that it reads "not enough data", because a pattern refused twice is not a bad pattern.

The footer says how many suggestions were withheld on purpose (the draw explained in Smart Autofill). That withholding is what keeps the confidence column trustworthy: without people deciding unaided, there would be nothing to compare against.