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.

Current product update — 9 November 2026. App Chat is now an implemented optional App Shell feature configured in the App Shell's Designer properties. It is separate from generic screen-language fields and Studio Ask Inflow. References below to a “planned” floating App Chat are historical; they do not describe current availability. App Chat still is not a page-level screen-language field. For current setup, approved sources/actions and user-facing limits, use the App Shell and App Chat lesson. This update does not claim that a specific published app or user session has been runtime-verified.

Inflow Screen Language (ISL) — Manual

Read, validate, save and publish as separate steps

A complete ISL document and an API request containing that document are different objects. Business-function ownership belongs to the native authoring command/context; do not add obsolete root fields to a closed ISL schema merely because an old fixture contained them. The examples below include two whole documents checked against the current Draft2020-12 schema and one explicitly partial event fragment. Schema qualification is static: native semantic validation, object access, publication impact and actual rendering remain separate.

Use current colon namespaces, preferably ri:input and locals:name. A form has a structural Form root, even though that structural type is not a standalone Toolbox palette choice. App Shell pages bound by screenKey follow the latest published target; the deprecated binding.version is ignored. Rules, task forms and embedded interfaces retain their own distinct version contracts.

Example UIAI-SCREEN_LANGUAGE-01 — Author a complete leave-input form

Scenario and inputs. Nadia creates a Form in the authorized people-ops workspace. The teaching record uses14–18December2026 and an annual-leave reason. The fields below capture values only; there is deliberately no business mutation or automatic leave approval in this first document.

Procedure. Start with the native wizard so the owning workspace/business function is set outside the ISL body. In Code, inspect the complete document below. The Form root owns three typed answer controls; bind targets refer to declared inputs, and field-level required validation concerns user entry. Save through the native revision-aware flow, then provide synthetic values in Preview.

Complete current-schema ISL, statically validated with Draft2020-12; external application/runtime validation is still required:

{
  "id": "leave-request",
  "version": 1,
  "screenKind": "form",
  "title": "Leave request",
  "inputs": {
    "reason": {
      "type": "Text"
    },
    "startDate": {
      "type": "Date"
    },
    "endDate": {
      "type": "Date"
    }
  },
  "body": [
    {
      "id": "leave-fields",
      "type": "Form",
      "children": [
        {
          "id": "leave-start",
          "type": "Date",
          "label": "First day",
          "bind": "ri:startDate",
          "required": true
        },
        {
          "id": "leave-end",
          "type": "Date",
          "label": "Last day",
          "bind": "ri:endDate",
          "required": true
        },
        {
          "id": "leave-reason",
          "type": "TextArea",
          "label": "Reason",
          "bind": "ri:reason",
          "required": true
        }
      ]
    }
  ]
}

Expected result. The document has a legal form/root shape, unique authored IDs and typed declared destinations. It can demonstrate value capture and required-field behavior; no row is persisted merely because an input changed or the JSON parsed.

Failure and recovery. A root Stack fails the Form-specific schema rule; wrap the answer controls in the required Form root. Unknown root fields or undeclared bindings require correcting the actual document contract. A semantic or permission failure must not be hidden by claiming that schema-only validation proved the full application.

Sources. Complete document schema, conditional save, binding targets.

Example UIAI-SCREEN_LANGUAGE-02 — Compose the current App Shell contract

Scenario and inputs. Nadia has published an actual permitted form with screenKey leave-request. She wants a Leave requests shell with an overview and a page opening that form. The sample is a complete shell document, but the external referenced screen must exist and be admitted in the reader's environment.

Procedure. Choose App Shell in the wizard. Inspect the six explicit region settings, page IDs/urlStubs and page modes below. A canvas page owns its body; a bind page names the actual published screen key. Use source:pages for supported shell navigation. Review permissions, required target inputs and the shell's native account/notification controls separately.

Complete current-schema ISL; it is not a self-contained application import with its external form dependency:

{
  "id": "leave-app",
  "version": 1,
  "screenKind": "app-shell",
  "title": "Leave requests",
  "appShell": {
    "schemaVersion": 1,
    "presetKey": "enterprise",
    "layout": {
      "attachment": "flush",
      "contentWidth": "fluid"
    },
    "regions": {
      "header": {
        "enabled": false,
        "body": []
      },
      "primaryNavigation": {
        "enabled": true,
        "placement": "start",
        "style": "sidebar",
        "source": "pages",
        "body": []
      },
      "secondaryNavigation": {
        "enabled": false,
        "placement": "start",
        "style": "sidebar",
        "source": "pages",
        "body": []
      },
      "utilityPanel": {
        "enabled": false,
        "placement": "end",
        "collapsible": true,
        "body": []
      },
      "footer": {
        "enabled": false,
        "body": []
      },
      "mobileNavigation": {
        "enabled": true,
        "style": "bottom",
        "source": "pages",
        "body": []
      }
    }
  },
  "pages": [
    {
      "id": "overview",
      "title": "Overview",
      "urlStub": "overview",
      "mode": "canvas",
      "body": [
        {
          "id": "overview-note",
          "type": "Prose",
          "value": "Leave requests demonstration"
        }
      ]
    },
    {
      "id": "request",
      "title": "New request",
      "urlStub": "request",
      "mode": "bind",
      "binding": {
        "screenKey": "leave-request"
      }
    }
  ]
}

Expected result. The shell schema is valid and the page intent is explicit. A bound page uses the latest published target for its screenKey; writing the deprecated binding.version would not pin it. This differs from contracts that genuinely require an exact version.

Failure and recovery. Repair missing region settings, invalid urlStubs or inaccessible target dependencies through their owners. Do not invent a page version pin, use visibility as authorization, or add the separately planned floating App Chat as if it were an implemented shell field.

Sources. Shell/page schema, wizard, screen publication/runtime boundary.

Example UIAI-SCREEN_LANGUAGE-03 — Wire a deliberate rule-backed submit

Scenario and inputs. A separate data tutorial has produced a real published rule and declared its inputs. Nadia wants a Form submission to call that known version, then retain the result locally. The following object is an event fragment, not a complete screen or proof that a rule with this key exists.

Procedure. Use the native Automations editor to choose Call a rule, select its actual published version and map the declared record argument. Retain a stable actionId and explicit local result target. Replace the illustrative key/version with the admitted rule coordinate. Inspect the generated fragment in Code and validate the whole enclosing form before publication.

{"onSubmit":{"do":[{"action":"runRule","actionId":"submitLeave","ruleKey":"create-new-leave-request","ruleVersion":1,"args":{"record":"${values}"},"into":"locals:result"}]}}

Expected result. The pipeline uses the actual runRule event contract with a declared action identity, version, argument map and result destination. Local result storage is not itself evidence of a successful business effect; read the actual rule result and any native completion/receipt behavior.

Failure and recovery. A missing rule/version, refused permission or incompatible argument shape must be corrected through that source. Do not replace the call with arbitrary client code, fabricate a success toast or retry a consequential request solely because its acknowledgement was lost.

Sources. Event/action schema, automation action catalog, native run-rule typing.

Example UIAI-SCREEN_LANGUAGE-04 — Publish the revision that was reviewed

Scenario and inputs. Nadia saved a draft, read revision7 and reviewed its actual publication impact. The value7 is illustrative: the request must carry the revision returned by her environment. She retained the original publication intent and the native impact receipt where required.

Procedure. Save edits with the current expectedRevision, re-read the saved draft and review its exact impact candidate. Publish that saved revision with its original idempotencyKey and the applicable native X-Impact-Receipt. The JSON below is the actual publication body shape; the draft ID is the URL coordinate, not a guessed body field.

{"expectedRevision":7,"idempotencyKey":"leave-form-publish-014"}

Expected result. Conditional save prevents silent whole-document overwrites, and publication validates the reviewed revision plus stable intent. The returned published version, rather than the draft label or local Preview, establishes which release exists. A newly changed draft needs a new review of its actual content.

Failure and recovery. A stale revision requires re-reading/reconciling edits and reviewing the new candidate. After an unknown publish reply, inspect the original intent/receipt through the native reconciliation flow; do not mint another key to force a duplicate version. A denied publication remains unavailable and does not authorize a bypass.

Sources. Revision-required save, publish/impact controller, publication body validation.

Saving an existing draft also requires its current expectedRevision; publication requires the reviewed revision and original idempotencyKey. Follow native impact review and reconcile an unknown publication reply with that original intent rather than issuing a new one. These are screen-publication fields, not generic task completion fields. See the authoring API guide.

Human + agent reference for authoring screens. The canonical, machine-checked contract is conf/screen-language/screen.schema.json (JSON Schema 2020-12). This manual explains it and teaches the language through worked examples.

1. What a screen is

A screen is one JSON tree that describes a form, App Shell, or dashboard. The renderer reads the tree verbatim; no imperative logic lives in it. Logic is by reference: expressions use InflowEL through declared authored-value positions and their syntax version, and behavior calls named functions, rules, and data-model operations that the backend resolves and permission-checks.

Three screen kinds share a vocabulary but have distinct structural and semantic requirements:

screenKind Typical nodes
form Form, Section, inputs, submit onSubmit action list
app-shell AppHeader, NavMenu, ContentOutlet (App Shell-only), pages and shell regions
dashboard Dashboard, Grid, Metric, Chart (read-only)

AppHeader, NavMenu and ContentOutlet are valid only in app-shell documents ($defs.appShellOnlyType); validation reports CONTROL_REQUIRES_APP_SHELL for any of them in a form or dashboard, at any depth, and publication and rollback of such a version are refused. EmbeddedInterface is valid in every kind (SCRUM-1908).

A Form Designer document is a valid ISL document with screenKind: "form" (ISL is a superset).

2. Document shape

Use the complete Form example and complete App Shell example above as current-schema starting points. They are deliberately different: a Form has a structural Form root in body; an App Shell declares appShell regions and pages. Their external rules/screens/data sources still need real admitted publications.

Root member Meaning
id / version / screenKind Document identity and declared kind; not the API's draft revision.
title / direction / locale Human title and supported presentation context.
inputs Typed declared interface values; bindings must match their actual types.
body Authored node tree where the selected kind requires it.
appShell / pages App Shell-specific region/page contract.
settings / theme / data Structured optional contracts whose exact allowed shape comes from the current schema/native editor.

Do not paste a conceptual theme/source sketch as an executable declaration. Use the relevant native builder, inspect its actual saved shape and validate the whole document. Business-function ownership is supplied through the authoring API/context rather than an obsolete arbitrary ISL root property.

3. Nodes

Every node has the uniform shape { id, type, ...props, children? }.

Base props (all nodes): id (required), type (required, from the closed enum), name?, style? (width, align, labelPosition), visibleWhen? (InflowEL boolean), dataAgentId?, children? (containers only).

Input props (adds): bind (required — inputs.x | data.<src>.<field> | item.<field>), label?, required?, readOnly?, disabled?, placeholder?, help?, defaultValue?, options?/optionsSource?, validate? (rule or builtin references). required/readOnly/disabled may be a boolean or an expression.

Action props (Button/Link): label (required), variant? (primary|secondary|danger|quiet) and an optional typed onClick event handler. The handler owns its optional expression guard and ordered do array. A task submit Button also has its explicit submit/outcome/reason contract, not a guessed generic workflow call.

3.1 Authorable controls and the wire vocabulary

The current node reference derives the actual palette/control contract and separately lists the closed schema vocabulary. A structural Form root, a contextual semantic item and a legacy wire member are not interchangeable with a standalone Toolbox choice. Use the native wizard for kind-specific roots and opaque controls' own composition rules; a ContentOutlet or TaskViewer does not accept arbitrary authored child content.

3.2 Choose an input by its declared value contract

Use Text/TextArea for text, a typed numeric editor for numeric values, Checkbox/Toggle for Boolean values and Date/Time/DateTime for the corresponding temporal type. Choice controls need stable values and a compatible single/collection destination. A record Lookup needs the admitted record identity/label contract; a file control needs the actual governed document/file contract. A superficially similar label is insufficient to convert one type into another.

4. Data sources

The following is a conceptual property sketch: get|list|search denotes alternatives, not one operation string. It is not an executable source declaration. Use the native source builder for the actual type/version/operation and allowed fields.

"data": {
  "customer":   { "source": "DataModel.Customer", "op": "get|list|search", "args": { }, "writable": true },
  "salesByMonth": { "source": "Report.salesByMonth", "op": "run", "args": { "range": "${inputs.range}" } }
}

DataModel.* reads/writes go through DataModelService and are permission-checked — a field the actor cannot read is not resolvable in a binding (fail closed). Report.* / Fabric sources are read-only.

Caller-supplied live preview also checks the publication target connector against the same object visibility policy used by the authoring source catalog. Hidden or unprovable published-record sources show the existing safe unavailable outcome before business rows or aggregates are read. This covers legacy and exact source identities without choosing a different visible destination. A distinct bound source connector retains its existing policy. Published screens, server-loaded children and saved expression contexts keep their established runtime authorization (N-034); independent rule functions and metadata validation retain their own guards.

Exact form-data sources

For a DataModel.* declaration, a present sourceRef claims one exact source identity. It must have the supported DataModel identity shape and match the record type in source. Explicit JSON null is present and invalid. Ordinary preview and saved rendering reject an invalid identity before any provider read or argument evaluation in that form-data block; they do not substitute the latest logical model. A valid identity uses the existing pinned or governed-plan read, whose authorization and publication checks still apply. Only a missing sourceRef key retains the existing workspace-scoped legacy read.

Publish and rollback already validate and attest these sources. If preview reports that the governed source could not be loaded, correct the source identity and validate again; deleting a pin changes its meaning. Earlier independent input relationship hydration and metadata attestation are separate boundaries.

5. Typed events and actions

A handler is an object with an optional guard and an ordered do list. This is a node-property fragment, not a complete screen or record mutation:

{
  "onClick": {
    "do": [
      {"action":"setValue","target":"ri:reason","value":"Annual leave"}
    ]
  }
}

The current action union/schema owns the exact fields for runRule, admitted record actions, integrations, lifecycle start, navigation and other supported effects. For example, a rule call has its actual key/version/action identity/argument contract, while startLifecycle has lifecycle/version/args and its own optional idempotency/correlation behavior. Do not replace these with invented objects such as workflow:start or record:save. An event list is not arbitrary JavaScript. Native services still authorize every protected read and effect. See event types and handlers and the schema action union.

6. Expressions (InflowEL)

Expression interpretation belongs to a declared property/event position and the document's syntax version. Use the native expression editor to persist the supported marker: current syntax-version1 authored expressions use =; older wrapped ${…} values retain their compatibility contract. A text string inside arbitrary structured data is not automatically executable code. A bind destination is a path, not an expression wrapper.

Scalar editors generally enable expression mode unless expr:false/read-only says otherwise. Composite source/profile/options editors own their own evaluated positions and mappings. Server-backed saved rendering and the event runtime have distinct context/effect boundaries; a cheap client evaluation is not authority for a protected source, saved condition or business mutation. See the authored value codec, current property modes and event contracts.

: is the one separator an author ever types, for every namespace alike (inputs:, data:, locals:, rules:, constants:, ...) -- there is no second syntax for "how do I reference a value." The designer still accepts legacy bang-separated ri! reads while an existing expression is edited, but normalizes them to inputs:<name> when the expression is saved. Quoted text that contains the retired separator is never rewritten. A writable control's bind and event-target paths use this same colon syntax for inputs: and locals:. data: is the one exception: a bind path into a declared data source is written data.<sourceKey>.<field> (dot) -- a narrower, storage-only grammar, distinct from the expression read data:<sourceKey>.<field> (colon) used everywhere above.

locals: represents browser-session state — specifically, the result of a client action such as Call a rule stored via into: "locals:x" — and is therefore not valid in an expression that can be evaluated by /render or a published interface. Draft validation reports SCREEN_EXPRESSION_NAMESPACE_UNSUPPORTED and requires the author to use inputs:*, data:*, an item-scoped value, or a published rule. It is not a general-purpose way to reference another field on the same screen; for that, bind both fields to inputs: or a shared data: source and reference them from there. Likewise, item.* is valid only inside a collection row/template context such as a DataGrid, Table, or Repeater.

When an expression on a control, an App Shell region, a container header or a computed value cannot produce a value at runtime, the person sees a plain sentence, never the code: Some values here are not available yet. Save your changes, then reload the page. when the saved expression source is not available (for example in a Preview of an unsaved draft), and Some values here could not be calculated. for any other failure (Arabic: بعض القيم هنا غير متاحة بعد. احفظ تغييراتك ثم أعد تحميل الصفحة. and تعذّر حساب بعض القيم هنا.). Agents and tests read the codes from the alert's data-expression-error attribute (space separated, for example SCREEN_EXPRESSION_SOURCE_REQUIRED), the family from data-expression-error-reason (context or calculation) and the failing properties from data-expression-error-path (for example /value or second/title). A value in a code slot that is not code-shaped (^[A-Z][A-Z0-9_]+$) is recorded as SCREEN_EXPRESSION_FAILED, so free evaluator text never reaches an attribute. A tree grid that cannot build its tree keeps its sentence and carries the reason code in the error row's data-agent-error (INVALID_TREE_PLAN, TREEGRID_MAPPING_REQUIRED, ...). (SCRUM-3859)

The same failure, when a person presses Submit, appears in the form's error summary and on the field's own error line with that same sentence after the field name, for example Total: Some values here could not be calculated., never /value: SCREEN_.... The summary item (li) and the field's error line (.isl-field-error) carry the same data-expression-error, data-expression-error-reason and data-expression-error-path attributes. In a published subform the sentence is in the subform's language. (SCRUM-3864)

A published subform that is still loading, or failed to load, says so in words too: the summary reads Wait for this part of the form to finish loading. while it loads and Unable to load the child interface. when it failed, and the subform's body reads the same failure sentence. A refused child (not signed in, no access, or not found) reads This is not available to you (ar هذا غير متاح لك) instead, unless the author set an unauthorized message. The load code (for example SCREEN_EMBED_LOAD_FAILED) is only in data-embed-error. A summary item whose field is not known reads A field (ar حقل); its path is only in data-error-path. Only data-* attributes with text values reach a summary item or a field's error line. (SCRUM-3871)

7. Validation & self-repair

POST /api/screens/drafts/{id}/validate returns ValidationIssue[]: { severity, code, path (JSON-pointer), humanMessage, suggestion }. It is the server publication-preflight, not a Studio-only lint: the same structural checks and ScreenPublicationPolicy consumer gates that POST .../publish runs. Structural ERROR findings still short-circuit the publication policy; WARNING findings (for example the rule-reference lint) are returned and do not block publish. Only ERROR severity refuses publication. Static checks include: every type is in the enum; every bind resolves; current declared action/source references resolve at their required boundary; authored expression positions parse; permission references are valid. The JSON-pointer path lets an agent fix the exact node and re-validate. Studio Validate/Publish calls this endpoint so a consumer-policy failure appears before the publish write, but the server still re-runs the same gates on publish and remains authoritative.

A screen key has at most one working draft. Creating a second draft is refused with SCREEN_DRAFT_EXISTS (HTTP 409). GET /api/screens/{key}/draft returns that draft when the caller may SCREEN_MANAGE the screen, or 204 when the screen is manageable but currently has no draft. Unknown keys stay 403 from the object ACL. The New-interface wizard uses this lookup to Open the existing draft, or Replace a draft-only interface (GET /latest 204) by deleting it (DELETE /api/screens/{key}) and then creating. Published interfaces cannot be replaced from the wizard; open the working draft instead. The one-draft-per-key guard is not weakened.

8. Learn it through representative examples

Full, schema-valid documents live in src/test/resources/screen/ and double as golden fixtures:

  • form.customer-onboarding.json — a Form with Sections, mixed inputs (Text, Email, Select, RecordPicker, Date, TextArea), a visibleWhen, a validate rule reference, and a submit action list (record: save → workflow: start → toast).
  • dashboard.customer-list.json — a Table over DataModel.Customer with columns, filter, pagination, and rowActions (navigate + guarded delete), plus a RecordPicker filter.
  • dashboard.sales-overview.json — a Dashboard/Grid of Metrics and a Chart over Report.* sources with a shared DateRange filter.
  • golden.app-shell-workspace.json — an app-shell with a materialized region map, persistent navigation, multiple pages, and an exact-version embedded-interface binding.

The golden suite parses, validates, publishes, and renders these documents through their kind-specific contracts.

9. Agent code-authoring API (designer)

The full-browser Interface Designer exposes a programmatic editor surface so an agent writes the document in one shot instead of simulating keystrokes (spec §A6). Both paths share the same islTree structural ops the WYSIWYG uses, so the Code ⇄ WYSIWYG round-trip guarantee (§8.3) holds for agent edits too.

Two ways to call it (both gated on ?agentMode=true):

  • Command bridge — window.__agent.run('<id>', <args>):
    • interface.code.set { json } — replace the whole ISL document (validated; [data-agent-id="interface.code"]'s data-agent-state becomes ok/invalid).
    • interface.code.applyPatch { patch } — an ordered op list against the tree.
    • interface.node.add { path, node, index? } — path is the PARENT path.
    • interface.node.update { path, patch } / interface.node.remove { path }.
    • interface.validate / interface.publish / interface.doc.get.
  • Imperative handle — window.__inflowDesigner (methods that RETURN values; the command bridge is fire-and-forget): codeSet, applyPatch, nodeAdd, nodeUpdate, nodeRemove, docGet, validate, publish.

A node path is an array of child indices: [] is the root body list, [2] is body[2], [2,0] is body[2].children[0]. Every op is total — an invalid path is a no-op.

applyPatch op shape (a small documented shape, not RFC-6902): { op: 'add'|'update'|'remove'|'move', path?, parentPath?, node?, patch?, index?, from?, toParentPath? }.

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