Optional technical reference. This material is for developers, integration specialists and platform administrators. For the consultant lesson, read the practical guide.
Preserved from source baseline
d4587c7c0e073e58c2d430342f65ac55dd701bf4; source/static examples retain their stated scope. They are not new runtime verification or required consultant setup steps.
AI Task Rules
Build a reusable task, not an untracked prompt
An AI Task rule connects a goal, named input bindings, instructions, an explicit result contract and an admitted model route. The six-step wizard is the normal consulting path. The saved body is self-contained: later template-catalog changes do not silently alter an already published rule's prompt/schema. Its output is still model-generated and must be validated and treated according to the business use.
| Step | Concrete decision |
|---|---|
| Goal | Select the actual supported task template/purpose. |
| Inputs | Decide caller input, record path or fixed Text value; mark required values. |
| Instructions | Insert actual {{input.name}} bindings and keep source content within disclosure policy. |
| Result | Choose Text or typed JSON fields and any deliberate mapping. |
| Model | Use a real currently admitted connection model or administrator default. |
| Try & publish | Supply admitted examples, inspect results, retain failures, then publish the reviewed rule version. |
The fictional leave fixture is request leave-2026-014, five days from2026-12-14 through2026-12-18. Sample model wording below is not an observed provider response. A request fragment is never a complete imported application or permission to read a live personnel record.
Example UIAI-AI_TASK_RULES-01 — Create a Text summary task
Scenario and inputs. Nadia wants a short factual summary of the synthetic leave request for Sara. The model is admitted for this nonconfidential demonstration, and Nadia has the actual rule authoring/execution permissions. The rule will not decide whether leave is approved.
Procedure. Choose Summarize Text, connect its required text input to a caller-provided field, and write instructions limiting the answer to the supplied facts and unresolved questions. Choose Return as Text and the actual enabled model/default. On Try & publish, supply the synthetic text, inspect the typed result and safe diagnostics, then publish the reviewed task version only when its intended contract is satisfied.
Illustrative caller-input object, not an execution envelope:
{"text":"Fictional request leave-2026-014: Mohammad requests five working days, 14–18 December2026. Manager review is pending."}
Expected result. A successful run's business value is Text. Its exact wording is nondeterministic; a saved expectation must reflect the actual evaluated contract rather than pretend the sample prose was executed here. The published rule retains its own instructions/input/output body.
Failure and recovery. Missing required text, no enabled model or an unavailable runtime are governed failures, not successful blank summaries. Correct the specific prerequisite. Do not change business data, suppress a failure or publish a task simply because a plausible answer appeared in a design sample.
Sources. Actual summarization template, wizard, Text/JSON public result distinction.
Example UIAI-AI_TASK_RULES-02 — Extract typed fields from an admitted document
Scenario and inputs. An administrator supplied a synthetic leave-policy memo in the document library. Nadia is authorized to read it and to disclose its relevant content to the chosen model. The document ID must come from that actual library response; a display name or local file path is not the document reference.
Procedure. Choose an extraction goal, bind a DOCUMENT input and define explicit JSON fields such as requestId(Text), requestedDays(Number) and needsManagerReview(Yes/No). Keep recordMapping separate from the source field keys. Supply an admitted library document on Try & publish and inspect field types/required values before using the result. Publishing a rule does not itself persist its JSON fields as a business approval.
Result-schema fragment:
{"schema":{"fields":[{"key":"requestId","type":"TEXT","required":true},{"key":"requestedDays","type":"NUMBER","required":true},{"key":"needsManagerReview","type":"BOOLEAN","required":true}]}}
Expected result. The typed output obeys the saved field contract, or the runtime refuses it. DOCUMENT input uses governed extracted text, not arbitrary PDF/DOCX binary decoding. An optional mapping changes the exposed output key intentionally, as described by the owning rule contract.
Failure and recovery. A binary document without supported extracted text fails rather than inventing content. Resolve extraction or choose an actually supported admitted source. Do not paste private bytes into a Text field to avoid document access or disclosure controls; retain output validation failures as evidence for correcting the task.
Sources. Input/output contract, governed document adapter, mapped result schema test.
Example UIAI-AI_TASK_RULES-03 — Fix the translation language in the task
Scenario and inputs. The demonstration app translates a short synthetic employee notice into Arabic. The author intends Arabic to be part of the task definition, not a variable callers must provide. The source text remains a caller input and follows its normal disclosure rules.
Procedure. In Inputs, select Fixed value for the target language and enter Arabic. Connect the content to a named caller path. Insert both named bindings in the instructions. Inspect How to call this rule and the generated Web API input contract: the caller should send the content root, not a fictional language field that the task no longer reads.
Binding fragment:
{"inputs":{"text":{"source":"input","path":"text","kind":"TEXT","required":true},"language":{"source":"value","value":"Arabic"}}}
Expected result. The fixed value is rendered into the prompt from the saved body every run and is omitted from the declared caller inputs. A path named arabic would instead read caller data; a path is not a constant. The actual output shape remains whichever Text/JSON contract the author selected.
Failure and recovery. A required fixed Text value must not be blank. Fix unknown prompt chips or missing required caller data in the wizard rather than adding undeclared arguments. After changing a fixed instruction, save/review/publish the intended new version; do not assume an older published task's behavior changed with the draft.
Sources. Fixed binding semantics, declared caller inputs.
Example UIAI-AI_TASK_RULES-04 — Save and recheck a meaningful example
Scenario and inputs. Nadia has an admitted successful synthetic run and wants a regression example before publishing changes to the instructions. A saved example records chosen inputs and expected mapped output; it is not an assertion that all possible model answers or all future providers are equivalent.
Procedure. Save the successful run as a named example. Inspect its input object and expected result against the task's current Text/JSON/mapping contract. After editing and saving the draft, use the native re-check action and read the field-by-field comparison. A Text result is compared in its actual mapped representation; a runtime that did not reach a model must not be scored as an ordinary returned object.
Expected result. Re-check distinguishes matching fields, genuine output differences and a refused/unavailable runtime. The saved example is tied to its declared sample and reviewed contract, not a newly certified production workload. Confidential/restricted sample handling retains its native storage limitations.
Failure and recovery. A failed model/runtime request is unavailable evidence, not a new expected answer. Correct missing inputs, model preparation or output schema as appropriate, and deliberately review expectation changes rather than copying whatever an erroneous engine printed. Do not hide a failure by deleting inconvenient examples or publish an unreviewed draft while a save is still pending.
Sources. Mapped-output refusal and comparison, wizard sample behavior.
AI Task rules (RuleKind.AI_TASK) package a governed AI operation — summarize,
extract, classify, OCR, translate, answer — as a first-class rule. A wizard in
Studio authors the rule from a template catalog; the published rule body is
self-contained JSON and executes through the
AI Gateway with full routing, redaction, metering, and audit.
Building an AI task in Studio
The wizard has six steps (SCRUM-4199). Each step is deep-linkable with
?step=<id>:
| Step | ?step= |
What the consultant does |
|---|---|---|
| Goal | template |
Picks "what should the AI do" from the goal gallery: a category rail on the left, goals grouped by intent, and a detail pane that says what the focused or chosen goal reads and returns, its data class, and whether it needs an image model. Enter on the chosen goal goes on to Inputs. ?goal=<category> opens the rail on that category on the first visit to the step; the wizard then drops it from the address, so going back to Goal later shows every goal (the New rule dialog's AI shortcuts use it). |
| Inputs | inputs |
Says where each input comes from: Provided when the rule runs (the default, under the input's own name), From a record field (record type and field pickers, document-type fields first for documents), or Custom path (advanced). "How to call this rule" shows the input object a caller sends. |
| Instructions | instructions |
Edits the text the AI receives and inserts inputs as {{input.<name>}} chips. Unknown references and unused inputs are named on the step. Optional system instructions are under Advanced. |
| Result | output |
Chooses Return as: Text (the result is the reply) or JSON (the result is an object of typed fields — Text, Number, Yes/No, Date, List, with item fields for a List — each optionally saved to a record field). A JSON task can create a data model type from its fields (see Result type). |
| Model | model |
Uses the AI model your administrator enabled in AI providers. With one enabled model the step only names it. With several, one list offers exactly the enabled models, or "Use the administrator's default". With none, AI Tasks are unavailable (see Model routing). Answer length, creativity and data class are under Advanced. |
| Try & publish | test |
Runs the task on real values, choosing documents from the library or pasting an id. Shows the typed answer first and the request and raw answer under Technical details. Saves good runs as examples, and shows the publish checklist. |
The wizard reads as one column beside a Your setup panel. The panel lists the task's goal, inputs, result, model, Web API state and saved examples, each with a Change link to its step, and it holds the publish checklist. A document or picture input on Try & publish shows the chosen item's name; its id is one copy away, and a pasted id is turned into the name.
A new task opens with no errors. Choosing a goal connects every input, so the task can be tried straight away. A step's blocker shows as the Next button's explanation, and every blocker appears in the publish checklist with a link to its step.
Publishing. Publish publishes the task and closes the wizard to the rule
page, which shows the published version and offers Open the AI task and
Web API. Closing the wizard also leads there. An AI task is published only
from its wizard; the rule page shows no separate Publish button for it. The Publish menu also offers Publish & expose as Web API: after a
confirmation, Rule API keys for this workspace can run the task from outside
Studio (POST /api/rules/<key>/execute). The Web API panel and its OpenAPI
document list the task's inputs as the request expects them (the first part of
each input's path; a document or picture is its library id) and the result as
text or the JSON fields. When the saved task already is the latest published
version, Publish says so instead of publishing again. A failed publish stays in
the wizard with its reason.
Stopping a run. Stop ends the wait in the browser straight away. The provider may still finish the request on its side; that request is recorded in the AI usage log like any other. Try again repeats the run.
Failures. A failed run shows a plain title, the cause and what to do next. The governed error code and the server detail are under Technical details.
Custom paths. A leading $. is not part of the path grammar. Studio
removes it as you type. For a rule saved earlier with a $.name path, the
runtime first looks for the literal {"$": {"name": …}} input and then for
name at the root, so both caller shapes work. Paths are names separated by
dots, using letters, digits, _ and -.
Record-field paths (spec 4317). From a record field saves the path under
the record type's key, not its display name. For example, choosing "Support
ticket" (key support_ticket) and its description field saves
support_ticket.description, and a caller passes the record as support_ticket
(for example rules:triage(support_ticket: ticket)). The picker still shows the
name.
- When several data models have a record type with the same key, the key is
prefixed with its model key, for example
help_desk__support_ticket. The saved path then still identifies the type when the rule is opened again. - A path saved earlier under a bare key that is now shared asks which type you mean. It does not block the step, because the path still works.
- Record types without a key a caller can pass, such as a query result named "Open orders", are not listed. The step says so.
- A path saved earlier under a display name keeps working, and stays under that name when you change only its field.
- A saved name that no caller can pass (one with a space or a non-ASCII letter) shows an error on the record type until you choose the type again. If the type has no usable key, the error says to ask the data model owner.
- A reader sees the saved type.
- Whenever Next is blocked on the Inputs step, the input shows the reason itself. An unconnected required input says so once, under the source choice.
Access. If a test run or example re-check is refused, the step shows the neutral "Not available" state and sends no further request.
Rule body — inflow.ai-task-rule v1
{
"contract": "inflow.ai-task-rule",
"version": 1,
"templateKey": "extract-by-schema",
"templateVersion": 1,
"inputs": {
"source": { "source": "input", "path": "ticketDocument", "kind": "DOCUMENT" }
},
"model": {
"mode": "automatic",
"pinnedModelId": null,
"requiredCapabilities": ["STRUCTURED_OUTPUT"],
"dataClass": "standard",
"maxTokens": 2048,
"temperature": 0.1
},
"output": {
"schema": {
"fields": [
{ "key": "customerName", "type": "TEXT", "required": true },
{ "key": "priority", "type": "TEXT", "required": true },
{ "key": "refundAmount", "type": "NUMBER", "required": false },
{ "key": "products", "type": "LIST", "required": false,
"itemSchema": [ { "key": "name", "type": "TEXT" },
{ "key": "quantity", "type": "NUMBER" } ] }
]
},
"recordMapping": { "customerName": "customer", "priority": "ticketPriority" }
},
"prompt": {
"systemOverride": null,
"userTemplate": "Extract the requested fields from the following content.\n\n{{input.source}}"
}
}
Rules:
- The body is self-contained: the prompt scaffold and output schema are
copied in at authoring time.
templateKey/templateVersionare provenance only — the runtime never consults the template catalog, so later catalog edits never change published behavior. - An input can instead be a fixed value (spec 4798):
{ "source": "value", "value": "Arabic" }. It is text only, a required one may not be blank, and its text is written into the prompt every run. In Studio choose Fixed value on the Inputs step (for example Translate's target language). A fixed input is not asked for in Try it, is not sent as a run input, and is not a declared Web API input. A custom path such asarabicis not a constant: it readsinputs.arabicwhen the rule runs. inputsdeclare named bindings into the execution context.kindisTEXT(default),DOCUMENT, orIMAGE. DOCUMENT inputs load the current document version's content through the governed document service (audited under the ambient actor when one is present, else theai-task-rulesystem actor) and resolve to governed extracted text: the text the DMS extraction pipeline (Tika at upload / extraction worker) stored on the version, or a direct UTF-8 decode for text-bearing mime types — raw PDF/DOCX bytes are never decoded into the prompt. A binary document with no extracted text fails withAI_TASK_DOCUMENT_UNSUPPORTED. IMAGE inputs travel as typed attachments the provider client sends in its native multimodal format (OpenAI-compatibleimage_urldata-URL parts, GeminiinlineDataparts, Anthropic base64imageblocks, Ollama messageimages) — never as base64 text in the prompt. The resolved input keeps only a{fileName, mimeType}marker so{{input.<name>}}placeholders still render the file name. Image mime types are restricted toimage/png,image/jpeg,image/webp,image/gifand the decoded size to 10 MB, and the decoded bytes are checked against the declared mime type's magic-number signature (stored metadata alone is never trusted); any violation fails withAI_TASK_ATTACHMENT_UNSUPPORTED. An IMAGE input also forces theIMAGE_UNDERSTANDINGrouting capability, so pixels can never be routed to a text-only model — including pinned models, whose capabilities are validated against the request before any provider call (AI_MODEL_CAPABILITY_NOT_FOUND). Because binary content cannot be scanned by the text redaction policy, attachments may only be sent to on-premise models: automatic routing filters to on-premise candidates, and a pinned or otherwise resolved external model is refused before provider invocation withAI_TASK_ATTACHMENT_EXTERNAL_BLOCKED.- Each input is required by default: a required binding must declare a
non-blank
pathand must resolve at execution time, otherwise the run fails withAI_TASK_INPUT_MISSING(orAI_TASK_INVALID_BODYat authoring time for a blank path). A binding with"required": falsemay leavepathblank or resolve to null; its{{input.<name>}}placeholder then renders as an empty string instead of failing. - Every declared input must be referenced by the prompt template; an
unreferenced binding is rejected at body validation with
AI_TASK_INVALID_BODY. The gateway request carries only the rendered prompt (plus typed image attachments) — there is no separate input map on the wire, so referenced content is sent exactly once and a binding the template never uses can never leak document text or pixels to a provider. - DOCUMENT/IMAGE inputs resolve through the permission-gated document
service, so they require an ambient actor/workspace at execution time
(HTTP-scoped). Headless executions without a workspace context fail
closed with
AI_TASK_DOCUMENT_NOT_FOUND. - Prompt placeholders use the
{{input.<name>}}syntax and resolve against the declared inputs. An unknown placeholder fails closed withAI_TASK_INPUT_MISSING— it is never left as a silent literal.
Model routing
Owner decisions of 2026-10-25 (Mohammad): AI Task rules use the enabled
model — the model an administrator selected with Use this model on an
enabled AI provider connection (Studio → AI providers). The model catalog
(GET /api/ai-gateway/model-catalog) lists it as the <connectionKey>-chat
entry of that connection. Studio never offers any other catalog model to an
AI Task.
- No enabled model: the AI Task feature is unavailable. The New rule
dialog does not offer AI Task: its "Let AI do the work" band and the AI
shortcuts ("Summarize a document", "Extract fields", "Classify text") are
absent. An existing AI Task's Model step says "AI
Tasks are unavailable until an administrator enables an AI model in AI
providers", and Publish and Run test are disabled with that reason. If the
catalog cannot be read (a person without
AI_GATEWAY_VIEWis never sent to read it), the dialog keeps offering AI Task. The other AI controls are absent too: rule Assist, "Write it for me", "Apply change", Fix, "Build it for me", "Explain with AI", "Draft from a description" and the workspace wizard's "Suggest with AI" (spec 4253). Ask Inflow is also hidden (spec 4252). - One enabled model: it is used. The Model step names it and asks nothing.
- Several enabled models: the author may choose one of them in a single
list, or keep Use the administrator's default.
- The default stores
model.mode = automatic. - A choice stores
model.mode = pinnedandpinnedModelId = "<connectionKey>-chat". The body contract is unchanged.
- The default stores
- A stored
pinnedModelIdthat is no longer an enabled model shows the warning "The chosen model is no longer enabled; this rule uses another enabled model". It does not block publishing. - A chosen enabled model that cannot run the task (a cloud model for an image task, a model without a required capability, or a not-ready model) blocks publishing with that reason.
- An enabled model from Gemini, Ollama, OpenAI, Azure OpenAI, Mistral, Groq,
Together AI, DeepSeek, OpenRouter or vLLM also returns structured answers
(
STRUCTURED_OUTPUT), because their clients ask the model for JSON (specs 4258, 4259). Other providers' enabled models do not claim it.- Standard and confidential goals that need structured answers (Classify Text, Extract by Schema) run on it.
- PII Detect & Redact is restricted, so it still runs only on an on-premise (Ollama) enabled model. On Gemini or OpenAI it stays blocked with "restricted data stays on-premise".
- The same applies to process steps that ask for structured answers
(
service.ai.extract,service.ai.classify,service.ai.generate.email). They now use the enabled model, as every other AI feature does (spec 4252), and an AI Task pin to another model is ignored. - An OpenAI-type connection whose endpoint rejects
response_formatfails such a run with a provider error. It does not fall back to another model.
requiredCapabilitiesentries are validated against the platform capability allowlist and normalized to canonical case at body validation: a misspelled capability fails withAI_TASK_INVALID_BODY.dataClassis one ofstandard,confidential,restricted.restrictedis hard-enforced server-side: it runs on on-premise models only and fails with a governed error otherwise.confidentialfollows the enabled model; Studio applies no on-premise gate to it.
Model step guidance and an unreachable provider (spec 4798)
- The Model step lists every enabled model and says whether it can run this task, or why not (for example "Cannot read images", or "Runs in the cloud, and restricted data stays on-premise"). Refresh reads the list again without reloading the page.
- An image task whose only possible models run in the cloud, while the workspace has not approved external AI image processing, says so in one message: "Your workspace has not approved sending images to cloud AI models". The message links to the workspace security settings for someone who may change them. Refresh reads the approval again.
- When no enabled model can run the task, Next is disabled and its reason names what is missing (a capability, the data class, the workspace image approval, or a model switched off). The step also says who can enable one. A model whose AI service is not ready reads "Its AI service is not ready right now". That is a warning only: Next stays available, because the server still routes the task.
- A restricted goal says on its card that it needs an on-premise model. On the Model step it explains that restricted data only goes to AI models that run on premise, and that an administrator approves one by connecting an on-premise provider (such as Ollama) in AI providers and enabling its model. The Open AI providers button is shown only to a person who may manage AI providers; anyone else is told to ask that administrator.
- With automatic model choice, a provider that cannot be reached (no answer: unknown host, refused connection, I/O error or the attempt deadline) is retried once on the next eligible administrator-enabled model (never an unconfigured catalog model). An answer the client could not read is not "unreachable" and is not retried. The retry keeps every data-class, capability and approval rule, so restricted data never moves to a cloud model. A pinned model, or a purpose default, never falls back.
- When no model answers, the run fails with
AI_PROVIDER_UNREACHABLEand the plain sentence "<Provider> could not be reached." Studio shows "The AI model couldn't be reached", with Try again and, when several enabled models exist, Choose model. The provider address and the transport error are written to the server log only.
Output enforcement
The model response is validated platform-side before anything consumes it:
- Structured output wins when the provider returns it; otherwise the response
text must parse as a JSON object. An answer that wraps exactly one JSON
object in a Markdown code fence, or in a short sentence, is read too. Text
with no object, or with more than one, still fails with
AI_TASK_OUTPUT_INVALID. - Every declared field is type-checked (
TEXT,NUMBER,BOOLEAN,DATE,DATETIME,LIST,OBJECT) with narrow scalar coercions; LIST fields with anitemSchemavalidate each item recursively. - A missing required field or a type mismatch fails with
AI_TASK_OUTPUT_INVALID, carrying a short whitespace-normalized excerpt of the raw response (never credentials). Studio never shows that excerpt. - An answer cut off at the task's answer length fails with
AI_TASK_OUTPUT_TRUNCATEDinstead (spec 4798): the provider reported that it stopped at the output limit (length,max_tokens,MAX_TOKENS), or the text is an unfinished JSON object. Studio says "The answer was too long" and Change answer length opens Answer length under Advanced on the Model step (model.maxTokens). Answer Question from Document and Summarize Document start at 2048 tokens; existing drafts keep their saved value. recordMappingthen renames output keys onto record field names; unmapped keys pass through unchanged. A mapping source that names no declared output field is rejected at body validation withAI_TASK_INVALID_BODY(a typo would otherwise be silently ignored, returning the unmapped key). Two fields mapping to the same destination are also rejected (a collision would silently overwrite one value).
Return as (spec 4261)
output.returnAs decides what the rule's result is:
returnAs |
Result value |
Fields |
|---|---|---|
TEXT |
The trimmed reply string. An empty reply fails with AI_TASK_OUTPUT_INVALID. |
None allowed. The prompt asks for no JSON, and the task needs a CHAT model, not STRUCTURED_OUTPUT. |
JSON |
The checked, mapped object of the fields itself, read as result.category. There is no wrapper and no output rows. |
At least one. The model must answer with a JSON object of them (see above). |
- A stored body without
returnAskeeps working: with fields it is JSON, without fields it is Text. - Text with fields, JSON without fields, or any other value is rejected with
AI_TASK_INVALID_BODYat save, publish and run. - In a lifecycle Expression step, a JSON result's fields land in case variables of the same names. A Text result lands in the step's result variable. The mapped fields are also declared as the rule's outputs (key and type) for API-authored output mappings.
How the answer was produced travels beside the result, never inside it. The execute and dry-run responses carry diagnostics:
resolvedModelId,providerId,usage,auditIdandlatencyMs;renderedPrompt, on the authoring dry-run (/api/rules/evaluate) only. Published executions never include it.
diagnostics is omitted for rule kinds that have none.
Changed in spec 4261: the result used to be { "output": {…}, "meta": {…} }.
- A form that read
rows.0.output.categorynow readsrows.0.category. - An expression now reads
rules:x(...).categoryinstead of.output.category. metais nowdiagnostics.
Calling an AI task
While you type, rules:<key>(…). suggests a JSON task's result fields (spec 4262). These are the names the result
carries, after any record mapping.
An AI task is callable wherever a rule is:
- Lifecycle Expression step. The step's rule reference may be an AI task.
- A JSON result's fields land in case variables, as with any rule that returns an object.
- A Text result lands in the step's result variable.
- Restarting or undoing a case counts an Expression step that references an AI task (or any rule that is not a constant, expression, decision table or query) as work that contacts outside systems, so its preview warns that the AI provider is called again.
- Limit: an AI task called inside an expression (an inline formula, a gateway condition, an activity binding) is not detected. Restarting before such a step calls the provider again without that warning. Reference the AI task from an Expression step when the restart warning matters.
- Lifecycle Decision step. Decision tables only. Publishing a decision step that references an AI task fails with
PROCESS_DESIGNER_RULE_KIND_MISMATCHand says to use an expression step. - Expressions in forms, gateways, conditions and automations:
rules:triage(...)orrule('triage'). - Form buttons (run rule).
- From another rule. Calls from one rule to another keep their existing kind restrictions, which do not include AI tasks on every path. Call the AI task from the step, form or condition directly.
- JSON text can be converted with the
fromJson/toJsonfunctions.
Declared inputs (spec 4315)
The server derives a published version's declared inputs from the body, on every draft save and on publish. A caller passes one value per path root:
| Binding path | Declared input | Type |
|---|---|---|
text (provided when the rule runs) |
text |
TEXT; for a DOCUMENT or IMAGE input, the document id as text |
payload.text (custom path) |
payload |
OBJECT |
Invoice.summary (record field) |
Invoice |
the record type Invoice |
- A root is required when any input under it is required. An unbound optional input (blank path) declares nothing; the wizard's test run and "How to call this rule" leave it out.
- A trailing dot is ignored (
text.istext). A record type named like a built-in type (Date,Number…) is declaredOBJECT. - A root used both as a value and as an object, or used with different kinds, is
ANY. inputssent with an AI task draft are ignored: the body decides.- If a root cannot be a rule input name (a reserved word such as
data, or a name with-), the version declares no inputs and keeps the open input object. - Outputs are unchanged. A JSON task declares its result fields; a Text task declares none, and its value is the reply.
Form buttons (Call a rule), lifecycle bindings and the Web API OpenAPI document all read these declared inputs.
Execution checks them as it does for every rule with declared inputs. An unknown top-level input fails with
RULE_INPUT_UNKNOWN. A TEXT input takes text only: a number or boolean fails with RULE_INPUT_TYPE_MISMATCH. The
wizard's Test checks the inputs against the body being tested, even before it is saved.
Versions published before spec 4315 keep their empty signature; publish the task again to declare its inputs. Callers that do not pin a version pick up the stricter contract when you republish:
- lifecycle steps without a pinned version, including running cases that reach the step afterwards;
- Call a rule steps without a pinned version;
- Web API callers, once a declaring version is exposed.
A lifecycle step pinned to a declaring version must bind each required input (activity.input.<name>); otherwise the
process fails validation with PROCESS_BINDING_REQUIRED_INPUT, as for any rule with declared inputs.
Each call is a metered AI Gateway call. Whether to call a model is the designer's decision.
Suggested fields (spec 4263)
On a JSON task, Suggest fields asks the AI model to propose result fields. It reads the task's goal, instructions, input names and existing fields, never input values or documents.
- Placement and cost: the button sits beside Add result field and is the main action while there are no fields yet. Its hint says the request is counted as AI usage, like a test run.
- Review: the suggestions appear in a table with name, type, required and a one-line reason. New fields are pre-selected. Fields already in the result are shown disabled ("Already in the result").
- Add and Undo: Add {n} fields appends the chosen ones as ordinary result fields. Undo removes them again until the next change to the result fields.
- Other actions: Suggest again replaces only suggestions not yet added. Discard closes the list. Stop stops waiting; the provider may still finish the request, which is recorded in the AI usage log.
- When it is absent: for readers, when no AI model is enabled, and for a Text task. A refusal shows the neutral "Not available" state.
- How the server runs it: as an internal AI task (
POST /api/rules/ai-task/suggest-result-fields) on the task's own model choice and data class, through the AI Gateway (routing, redaction, metering, audit). It needs the rule-authoring permission, like a test run. - Clean-up: names become identifiers, unknown types are dropped, duplicates are removed, and at most 20 come back.
- Failure codes:
AI_TASK_SUGGESTION_UNREADABLE(the model's answer could not be turned into fields) andAI_TASK_SUGGESTION_NEEDS_INSTRUCTIONS(the task has no instructions yet).
Suggestions you have not added or discarded are kept while you visit other steps (spec 4798). The Result step's footer says how many are not added yet, and every other step shows "N suggested fields are not added yet" with Review suggested fields.
Result type
On a JSON task, a designer with DATA_MODEL_MANAGE and DATA_MODEL_PUBLISH sees Create a type from these fields on the Result step. It creates a data model, by default <rule key>_result (the next free _2, _3, … when that key is taken), with one record type of the same key. Field types map as follows:
| Result field | Data model type |
|---|---|
| Text | TEXT |
| Number | DECIMAL (precision 38, scale 10) |
| Yes/No | BOOLEAN |
| Date | DATE |
| Date and time | TIMESTAMP |
| List of plain items | LIST of TEXT |
| List with item fields, or Object | JSON (a list of records has no portable type) |
Data model field keys are lowercase ([a-z][a-z0-9_]*), so a result field such as redactedText becomes the type field redacted_text. The field keeps resultKey: "redactedText" in its metadata, which is what the type describes. Two result fields that would become the same type field (for example aB and a_b) are refused before anything is created.
The model and record type are marked as made by this task (aiTaskResult: <rule key> in their metadata). Update type changes only a type this task made. A link to any other model offers Open the data model instead.
If a later step fails, the draft is still linked to the task, so trying again updates that draft instead of creating another model.
The draft is validated, reviewed with the same publication impact review as the data model editor, and published as a version. It is published from here only when the review finds nothing. Any finding, even a warning, is reviewed in the data model editor. So is a draft that holds other unpublished changes.
- It is never made live, so no table is created.
- The task stores the link as
output.resultType {modelKey, recordTypeKey}. - When the review needs a decision, the step says so and offers Open the data model to review and publish there.
When the fields later differ from the published type (names, types or required flags), the step offers Update type, after a confirmation that names the fields it removes.
- It changes only that record type. Each field the result still has keeps its data model settings (name, PII flag, classification, AI exposure, uniqueness, default and metadata). Only its type and required flag follow the result.
- It then publishes a new version.
- If the data model holds other unpublished changes, including edits to this record type, nothing is changed. The step asks you to publish or discard them in the data model first.
- A model never published may hold only this task's own record type, exactly as this task last wrote it, under the name it was given. A deleted type, a rename or another change means someone else's unpublished work.
- A link to a model that is no longer available shows only "This is not available to you" and Remove type link. Removing the link lets you create a new type.
The ownership marker is the rule key, so anyone who can edit the model could set it. The server still authorizes every change. When they match, it says the type is up to date.
The controls are absent:
- without both permissions;
- for a read-only task;
- after the server refuses, in which case the step says only "This is not available to you".
The server authorizes every call.
Template catalog
The wizard's step 1 gallery is served from an open XML catalog:
conf/ai-task-templates/*.xml
GET /api/rules/ai-task-templates
Nine templates ship with the platform: Summarize Document, Summarize Text,
Understand Image, OCR Document Image, Extract by Schema, Classify Text,
Translate, PII Detect & Redact, and Answer Question from Document. The
former Extract Invoice Details preset was removed at the owner's request
(SCRUM-4200). Each declares its category, required
capabilities, default data class, input schema (including DOCUMENT and IMAGE
inputs), default output schema, prompt scaffold with {{input.<name>}}
placeholders, and default token/temperature constraints.
Adding a template is a content change: add a <template> entry (or another
*.xml file) under conf/ai-task-templates/. Capabilities must be AI Gateway
capability names; unknown categories, data classes, capabilities, or malformed
XML are rejected at load time with AI_TASK_TEMPLATE_CATALOG_INVALID.
Removing a template is also a content change. Because the runtime never consults the catalog, rules already made from a removed template keep executing as saved. Studio opens them with a neutral notice ("built from a template that is no longer offered"), derives their inputs, output fields and prompt from the saved body, and keeps them editable and testable. A removed template is never offered again for new rules.
Testing a draft
The wizard test step runs the real runtime against the unsaved draft body through the standard authoring dry-run endpoint — what you test is what executes:
POST /api/rules/evaluate
{ "kind": "AI_TASK", "body": "<rule body JSON>", "inputs": { … } }
The dry-run result's value is the same result as a published execution (the
reply text or the object of the fields), and its diagnostics add
renderedPrompt (design-time only). Because a dry-run executes an arbitrary, unsaved body — including real,
metered AI gateway calls — the endpoint requires the rule-authoring permission
(RULE_DEFINITION_MANAGE) whether or not a ruleKey is supplied; actors
without it receive ACCESS_DENIED before anything executes. Environments
without a configured AI gateway return a governed AI_TASK_RUNTIME_UNAVAILABLE
result instead of executing.
Try it asks only for inputs given when the rule runs; fixed values are shown as facts. While a required value is missing, the text beside Run test names it ("Fill in Text first"). The last sample values are kept for this browser tab per signed-in person, workspace and rule, so leaving the step or reopening the wizard keeps them (spec 4798). They are kept only for standard data: a confidential or restricted task never stores its samples, and samples are never written into the rule. Save as example beside Run test keeps a run with the task.
Baseline test cases (saved examples)
A draft body can carry a sidecar array of named regression cases. Studio calls them saved examples:
The following is an object fragment containing the saved-example property:
{ "testCases": [
{ "name": "happy-path",
"inputs": { "ticketDocument": "<document id>" },
"expected": { "customerName": "ACME OFFICE SUPPLIES LTD.", "priority": "high" } }
] }
The wizard saves any successful test run as an example. Re-checking an example
executes the saved draft (Studio waits for the draft to save first) through
the same real runtime and scores the mapped output against
expected field-by-field (nested objects compare recursively, numbers compare
numerically):
POST /api/rules/{ruleKey}/test-cases/{name}/run
→ { "name": "happy-path", "passed": true, "accuracy": 1.0,
"diff": [ { "field": "vendor", "expected": "…", "actual": "…", "match": true } ] }
accuracy is matched/expected fields and passed requires
accuracy == 1.0. An empty expected: {} therefore scores accuracy 1.0 /
passed by definition. A nested expected object whose actual field is
missing scores as a single field mismatch (the nested fields are not
expanded into separate diff rows). Unknown rule or case name returns 404
(RULE_TEST_CASE_NOT_FOUND); a non-AI_TASK rule returns 400. The sidecar is
part of the rule body, so baselines version with the rule.
Governed error codes
| Code | Meaning |
|---|---|
AI_TASK_INVALID_BODY |
Body JSON, inputs, model, output, or prompt section invalid |
AI_TASK_INVALID_CONTRACT |
contract is not inflow.ai-task-rule |
AI_TASK_INVALID_VERSION |
version is not 1 |
AI_TASK_INPUT_MISSING |
Declared input or {{input.<name>}} placeholder did not resolve |
AI_TASK_DOCUMENT_UNAVAILABLE |
DOCUMENT/IMAGE input but no document service wired |
AI_TASK_DOCUMENT_NOT_FOUND |
Document id resolved to no readable document |
AI_TASK_DOCUMENT_UNSUPPORTED |
DOCUMENT input resolved to a binary document with no extracted text |
AI_TASK_ATTACHMENT_UNSUPPORTED |
IMAGE input mime type not in the allowed set, decoded size over 10 MB, or bytes not matching the declared mime's signature |
AI_TASK_ATTACHMENT_EXTERNAL_BLOCKED |
Request carries attachments but the resolved model is not on-premise (binary content cannot be redaction-scanned) |
AI_TASK_RUNTIME_UNAVAILABLE |
No AI gateway port available in this environment |
AI_TASK_EXECUTION_UNAVAILABLE |
Direct compiled-rule execution attempted (use the rule service) |
AI_TASK_CAPABILITY_UNKNOWN |
Rule body names a capability the gateway does not know |
AI_TASK_OUTPUT_INVALID |
Model response failed output-schema validation |
AI_TASK_OUTPUT_TRUNCATED |
The answer was cut off at the answer length (model.maxTokens) before it was complete |
AI_PROVIDER_UNREACHABLE |
The AI provider gave no answer at all (I/O, unknown host, refused, attempt deadline); the detail names no address |
AI_TASK_TEMPLATE_CATALOG_INVALID |
Template catalog XML malformed or values out of vocabulary |
Security and audit notes
- Execution is a normal AI Gateway call: purpose-scoped routing, redaction
policy, metering, and audit all apply; the gateway audit id travels with the
response (
diagnostics.auditId). - Document content is read through the governed document service, never
through raw storage, and the read is audited under the ambient actor when
one is present, else the
ai-task-rulesystem actor. renderedPromptindiagnosticsis built rule-side before the gateway call, so provider-side redaction has not been applied to it. It is exposed only on the design-time authoring dry-run path (Studio's test step), never in published-execution diagnostics. It contains document text the caller already had governed access to (DOCUMENT inputs load through the permission-gated document service), and it never contains provider credentials.- Routing-only constraints (
workspaceId,dataClass) steer the gateway's routing and approval checks but are not written into the text sent to the provider. Model-facing limits such asmaxTokensare sent as before. dataClassis author-declared.restrictedis hard-enforced by routing (on-premise required, governed failure otherwise);confidentialfollows the enabled model — see Model routing.
Current-source update — native result-type publication
The current implementation validates an AI Task result type and submits it directly to the native model publisher as a new version. Dependency warnings, restricted dependents, or unavailable dependency advice do not block submission; the publisher still checks permission, schema, source integrity, and conflicts. If the model has other unpublished changes, review them in the data-model editor first. A successful result confirms publication of this model version only; it does not confirm that every dependent has updated. Native failures remain visible, and uncertain outcomes are not retried automatically. The result type is not made live and creates no table.