Inflow.aiDocs

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/templateVersion are 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 as arabic is not a constant: it reads inputs.arabic when the rule runs.
  • inputs declare named bindings into the execution context. kind is TEXT (default), DOCUMENT, or IMAGE. DOCUMENT inputs load the current document version's content through the governed document service (audited under the ambient actor when one is present, else the ai-task-rule system 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 with AI_TASK_DOCUMENT_UNSUPPORTED. IMAGE inputs travel as typed attachments the provider client sends in its native multimodal format (OpenAI-compatible image_url data-URL parts, Gemini inlineData parts, Anthropic base64 image blocks, Ollama message images) — 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 to image/png, image/jpeg, image/webp, image/gif and 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 with AI_TASK_ATTACHMENT_UNSUPPORTED. An IMAGE input also forces the IMAGE_UNDERSTANDING routing 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 with AI_TASK_ATTACHMENT_EXTERNAL_BLOCKED.
  • Each input is required by default: a required binding must declare a non-blank path and must resolve at execution time, otherwise the run fails with AI_TASK_INPUT_MISSING (or AI_TASK_INVALID_BODY at authoring time for a blank path). A binding with "required": false may leave path blank 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 with AI_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_VIEW is 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 = pinned and pinnedModelId = "<connectionKey>-chat". The body contract is unchanged.
  • A stored pinnedModelId that 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_format fails such a run with a provider error. It does not fall back to another model.
  • requiredCapabilities entries are validated against the platform capability allowlist and normalized to canonical case at body validation: a misspelled capability fails with AI_TASK_INVALID_BODY.
  • dataClass is one of standard, confidential, restricted. restricted is hard-enforced server-side: it runs on on-premise models only and fails with a governed error otherwise. confidential follows 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_UNREACHABLE and 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 an itemSchema validate 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_TRUNCATED instead (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.
  • recordMapping then 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 with AI_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 returnAs keeps 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_BODY at 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, auditId and latencyMs;
  • 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.category now reads rows.0.category.
  • An expression now reads rules:x(...).category instead of .output.category.
  • meta is now diagnostics.

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_MISMATCH and says to use an expression step.
  • Expressions in forms, gateways, conditions and automations: rules:triage(...) or rule('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/toJson functions.

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. is text). A record type named like a built-in type (Date, Number…) is declared OBJECT.
  • A root used both as a value and as an object, or used with different kinds, is ANY.
  • inputs sent 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) and AI_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-rule system actor.
  • renderedPrompt in diagnostics is 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 as maxTokens are sent as before.
  • dataClass is author-declared. restricted is hard-enforced by routing (on-premise required, governed failure otherwise); confidential follows 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.

Try “document generation”, “integrations” or “first form”.