Process Catalog

Required Access Level

Admin, Modeler 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 Process design → 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 Process design → 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 — while the version is saving, Close is disabled, so a refusal from the server shows up with the drawing still open

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 Process design → 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. A common reason in XML written outside the modeler is a step field holding text declared as an expression — see Java Delegates → What the platform refuses.

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.

The BPMN and CMMN properties panels follow the interface language. What stays the same in every language is what the engine reads as-is: the element ID, the listener events (start, end, take), the DMN result formats (singleEntry, resultList…) and the technical examples in the fields, such as P30D, groovy or com.example.MyDelegate.

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

Draft of what has not been published

While you edit, the modeler keeps a draft in this browser after each pause in editing, and also when you click Close or reload the page. If you close without publishing — or the publish is refused and you leave — the next time you open Edit / New version for the same definition the modeler shows the Unpublished draft notice, with the time it was saved:

• Restore draft loads the draft's diagram, and that is what New version publishes;
• Discard deletes the draft and keeps the deployed version.

If you start editing while the notice is open, that counts as your answer: the notice closes and a note says the previous draft was set aside and that what you edit now becomes the new draft. Changed your mind? The note's Restore the previous draft button brings it back. In the BPMN modeler, undoing every edit back to the deployed diagram also deletes the draft; in the DMN and CMMN modelers the draft goes away when you discard or publish it, or when the diagram becomes identical to the deployed one again.

If someone published another version after the draft was written, the notice turns yellow and says which version it started from (v3 → v4): restoring it publishes on top of changes the draft does not contain, so check the diagram first. The draft is deleted when the publish succeeds. It stays in this browser only, kept apart per organisation, per person and per process — it does not go to the server and no one else using the same browser sees it. Clicking Log out deletes every draft in this browser. If the session merely expires, your draft stays and comes back when you sign in again; when someone else signs in on this browser, the drafts that are not theirs are deleted. They also disappear if you clear the site's data. Creating a new definition from the catalog does not keep a draft yet.

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.

What publishing checks on agent steps

On publish, the platform checks what each agent step declares it writes and consults (see Agents → What the step writes). An error refuses the publish and the message names the step; a warning publishes and goes to the log. The modeler's AI assistant gets the same errors at the end of each turn.

Code	When	Effect
AGENT_WRITES_UNDECLARED	the step can write with Set Variables and does not declare what it writes	error (warning when the agent is chosen by expression)
AGENT_WRITES_RESERVED	the declaration includes aiDecision, escalateToHuman, a configuration field or ai_*	error
AGENT_WRITES_INVALID	the declaration is unreadable, repeats a name or uses a type the agent does not write (file, lookup, password)	error
AGENT_WRITES_TYPE_MISMATCH	a form of the process has the field with another type	error
AGENT_WRITES_TOOL_MISSING	declared, but the write tool is not on the step	warning
AGENT_WRITES_UNREAD	no form and no expression reads the variable	warning
AGENT_WRITES_OPTIONS_DIVERGE	two forms have different options for the same field	warning
PATTERN_TASK_UNKNOWN	the pattern task is not a human task of the model	error
PATTERN_TOOL_MISSING	pattern fields declared without the pattern tool	error
PATTERN_FIELD_NOT_IN_FORM	the field is not on the task's form	warning
PATTERN_FIELD_NEVER_LEARNED	the field is of a type learning does not mine	warning
PATTERN_SCOPE_UNDECLARED	the pattern tool is on the step without a declared task and fields	warning

Migrating an old step. A version already published keeps running as it was. To bring it to the new rule: open the version with Edit / New, select the agent step, fill in Variables the step writes with the variables it actually writes (the platform log records legacy undeclared write with the keys of each write of a step without a declaration) and publish the new 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.

Before configuring an automated step it checks what the tenant has: the agent tool catalogue, so each step gets only the tools it needs, and the connector list — decision tables, Java delegates and e-mail inboxes that start processes. With that it can wire a service task to a decision table (dmn, the table key) or to a Java delegate (delegateClass, the class) instead of an agent, using only keys and classes that appear on the list. Robots show up on the list as scheduled: they do not become a diagram 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. The proposal talks about steps and forms by name: where the model wrote a technical id (Task_…, Gateway_…, a form key), the proposal shows the element's name, and an id with no known name is removed. A key that is an ordinary word (review, reembolso) is only replaced where it appears as an identifier — in backticks or right after "formulário"; written as a word in a sentence, it stays as it is. The process's own key is never changed. What is saved on accept is exactly what the proposal showed.

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.

Completion target and escalation

In the definition's Settings tab, the Completion target and escalation section has two fields, both optional and written as an ISO-8601 duration (PT8H = 8 hours, P3D = 3 days, P2W = 2 weeks, P1M = 1 month):

Field	What it does
Completion target	How long, from the start, an instance should take to finish. Past that, whoever started it and whoever holds its open tasks get Instance over target. Empty = no target
Escalate after	How long after a missed deadline — of a task or of the target — Managers and Administrators are told, in the bell and by e-mail. Empty = no escalation

Each task's due date still comes from the modeler (the task's Due date field); the escalate after of this section applies to them too.

• The minimum is 1 minute. A value out of format is refused and nothing is saved.
• Changing the target applies to running instances: each one's deadline is recomputed as start + new target. Clearing the target takes the instances off the watch. When the new target (or escalation) leaves an instance already late, it moves silently to late or escalated — counted on the Monitor, with no notification and no e-mail.
• Test runs never count and never raise a notice.
• Deadlines are wall-clock hours — no business-day calendar.

Who edits it: Admin and Modeler. The result shows on the Monitor.

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. The Super Admin can redo the count right away, without waiting for the next day.

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.
• Hide below: The minimum confidence for a value to be suggested at all (default: 0.80). Below it, nothing appears. It is the former "Confidence threshold".
• Pre-fill when the task opens: Off by default. When on, it asks for the Pre-fill from threshold (the form suggests 0.95), and fields with a pattern at least that strong arrive filled when the task opens, tagged, with a banner asking the person to check them. The threshold cannot sit below Hide below — both the screen and the server refuse it.
• Fields that decide the path: The platform reads the published version and lists the fields used in gateway conditions and in the inputs of decision tables. They are never pre-filled, only offered on Autofill, unless you tick the field here.
• Per-step thresholds: The same two thresholds for each human step; blank means the process value. The same rule applies: a step's effective pre-fill threshold cannot sit below its effective hide threshold.
• 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. The When column says in which situation the pattern holds, with the field and option labels as the form shows them ("Categoria is Tecnologia and the requester is Ana Souza") — never the internal key nor a user code. Acceptance counts only what Autofill showed a person; what an AI agent consulted or wrote does not enter it.

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.

Precision per band and threshold simulation

Right below the holdout summary sit two tables, computed over the tasks completed inside the time window:

• Precision per band — one row per band (pre-filled, offered, hidden). Shown and Kept (incl. inertia) come from tasks that saw the suggestion: a pre-filled value nobody looked at counts as kept, which is why the column says "inertia". Holdout precision comes from the tasks of the draw, which saw nothing — it is the unbiased number. Coverage is the share of holdout decisions that fall in that band.
• Threshold simulation (holdout) — for every threshold between Hide below and 1.00, how many holdout decisions it would have covered and how often the value would have been right. The row of the current pre-fill threshold is tagged current. It is the table for deciding where to put the threshold before switching pre-fill on: holdout tasks also record the best pattern below the floor, so the simulation sees what would stay hidden.

As in the health table, any rate with fewer than ten samples reads "not enough data".