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 read-compatibility note — 10 November 2026. Existing varchar values for typed reference fields may use the same validated identity shorthand as the writer. For example, a stored USER value root is returned as the canonical user identity object {kind: "user", userId: "root"}. Valid stored JSON keeps its existing representation. This shorthand applies only to typed reference fields: a JSON field containing the text root is not reinterpreted as a USER reference, and a raw RECORD_REF identity is still refused because it requires structured schema and record identity. Malformed JSON, control characters and invalid reference identifiers remain errors. Bounded record reads charge the original text against their existing budget before conversion. This compatibility path does not grant access to the referenced object.

Platform Value Types and Multiplicity

Choosing a type is choosing behavior

Use the canonical value vocabulary when defining a platform contract, and the owning surface’s vocabulary when filling a data-model field or a rule input. These vocabularies overlap but are not interchangeable: a data model’s FieldTypeRef has PORTABLE/NATIVE facets, a reusable rule input uses typeName plus multiple, and a collection plan uses its own smaller ValueType enum. Do not copy a spelling from one table into every other surface.

For the leave example, dates describe calendar days, requested days are whole numbers, a status is a deliberately constrained enumeration, and request IDs are stable text. For an expense extension, DECIMAL describes amounts, while a potentially long numeric identity must survive serialization without losing digits. A user, document or record reference is a typed identity object, not permission to fetch or mutate the referenced object.

Question Choose deliberately Common mistake to avoid
Quantity, identifier or display label? Numeric kind for arithmetic; text/key grammar for identity Turning a long identifier into a browser float.
Calendar value or point in time? DATE/TIME/LOCAL_DATETIME/INSTANT according to meaning Calling every date-time value UTC.
One or many? Cardinality independently of value kind Assuming a one-item list is a scalar.
Missing allowed? Required/nullability contract Treating null, empty text and empty list as identical.
Local object or governed reference? Actual record/reference shape and optional version pin Using a label as an object ID or treating a reference as an access grant.

The following cases explain these choices without claiming that arbitrary JSON is a valid complete model or workflow definition. Follow the owning schema/API for the final containing document.

Worked examples

Example DATA-TYPES-01 — Keep quantities, amounts and identifiers separate

Scenario and inputs. Nadia adds requestedDays, expenseAmount and externalEmployeeNumber to an application design. A request asks for 5days, an expense is 125.50, and the employee number may contain leading zeros. This is a type-selection worksheet, not a complete API request. The reader must apply the corresponding field facets in the actual model editor.

Procedure. 1. Define requestedDays as an INTEGER when the business policy permits only whole days. 2. Use DECIMAL with an explicit precision/scale policy for the expense amount and preserve exact input before any browser arithmetic. 3. Keep the external employee number as text so leading zeros and nonnumeric identity grammar survive. 4. Declare requiredness independently and validate boundary values before publishing. 5. Where a true LONG identity is returned to a browser, retain its canonical wire string rather than converting it to Number.

Expected result. The model communicates arithmetic and identity intentions separately. A display formatter can show 125.50 without changing the canonical amount, and employee 000123 remains a different textual identity from 123 if the domain says so.

Failure and recovery. A value rounded by an external floating-point client cannot be repaired by choosing DECIMAL later. Re-read or re-enter the original exact value through a permitted source, correct the client serialization, and rerun the relevant validation; never invent the missing digits.

Sources. ValueKind.java, FieldTypeRef.java.

Example DATA-TYPES-02 — Distinguish vacation dates from meetings and audit instants

Scenario and inputs. Mohammad’s leave runs from 2026-12-14 through 2026-12-18. A separate optional interview is scheduled for 09:30 in local wall-clock terms, and an audit event has a precise timestamp. These values represent different concepts; a business date is not a midnight UTC instant with an implied timezone conversion.

Procedure. 1. Model leave start/end as DATE and document whether business intervals include both end dates. 2. Use TIME for a time-of-day value with no date, and LOCAL_DATETIME for a date plus wall time when the owning contract intentionally has no offset. 3. Use INSTANT for an actual absolute audit event and preserve its offset/UTC semantics. 4. Inspect the owning surface’s aliases before entering a type name: reusable rule DateTime resolves to local date-time, while Timestamp resolves to an instant in its input contract.

Expected result. The four canonical kinds remain distinct. Display conversion is an explicit application concern rather than an undocumented coercion in a shared type table; a user in another timezone does not accidentally see a different leave calendar date.

Failure and recovery. If a source supplies a local date-time without the timezone needed to determine an instant, the missing fact must be resolved by the application’s declared policy or user input. Appending Z to make a payload parse fabricates information and is not a supported recovery.

Sources. ValueKind.java, RuleInputDefinition.java.

Example DATA-TYPES-03 — Pass a pinned document identity without granting document access

Scenario and inputs. A leave request may attach a supporting document already stored in the permitted document system. Nadia wants the workflow to refer to the reviewed version rather than whatever might later become latest. The specific reference is obtained from the actual document picker or secured response, not assembled from a visible filename.

Procedure. 1. Select the actual document under the acting user’s document permissions. 2. Read the canonical reference fields from that surface and choose the supported version-pinned option where the consumer requires immutability. 3. Declare the containing field/input as DOCUMENT rather than arbitrary text or a copied download URL. 4. Carry the reference unchanged into the specific admitted task/service action. 5. Reauthorize content use at that consumer; a human-readable attachment or a client reference does not itself authorize AI/provider disclosure.

Expected result. The reference preserves an object’s identity and any supported pinned version. Renaming the display file does not change that identity, and a later document version does not silently replace the reviewed bytes when an exact version is required.

Failure and recovery. An inaccessible or deleted document, missing required version, or incompatible reference kind must be handled through the owning document service. Ask for a permitted replacement or fix the declared contract; do not use a guessed URL, copied token or broader actor to make the reference resolve.

Sources. ValueKind.java, ValueTypeDescriptor.java.

Example DATA-TYPES-04 — Reject list-to-scalar mistakes before publication

Scenario and inputs. A reusable policy rule expects one employee record but a query returns a list of records. Even if the list currently contains one row, its declared contract remains MANY. Nadia also has an optional single record that may be null, which is a different shape from an empty list.

Procedure. 1. Read the producer’s declared result kind, schema reference, cardinality and nullability. 2. Match the consumer’s typeName, multiple and required properties deliberately. 3. If the business needs one row, choose an explicit single-record query/result policy and define the no-match and multiple-match behavior; otherwise make the consumer accept a list and iterate using supported expressions. 4. Validate with zero, one and several rows so accidental first-row assumptions are exposed. 5. Preserve required-value validation independently from collection width.

Expected result. The producer and consumer agree on meaning instead of relying on a temporary fixture size. A MANY record input stays a collection, and a nullable ONE input can represent absence without pretending it is a collection.

Failure and recovery. A cardinality/type error should lead to a deliberate contract or mapping correction. Silently taking the first element can lose data and change business decisions; casting an arbitrary object to a reference also cannot create the source identity or authorization it lacks.

Sources. RuleInputDefinition.java, Cardinality.java.

Detailed reference

Overview

Inflow provides a unified canonical type contract across all execution environments:

  • Interface Designer (Screens, Inputs, and Locals)
  • Lifecycle Engine (BPMN Process Variables and Task Payloads)
  • Decision Engine (Rule Inputs and Decision Tables)
  • Integration Layer (Service Task and Agent Reference Parameters)
  • Data Model (Record Attributes and Persistent Collections)

Value Kinds and Cardinality

The platform defines 23 portable value kinds. Cardinality is orthogonal to value kinds: any kind can be declared as Single (scalar) or Multiple (collection).

Value Kind Wire Format / JSON Representation Description
TEXT string Text string; some surface grammars also accept a String alias
INTEGER number (32-bit signed) Whole number between -2^31 and 2^31 - 1
LONG number / string (64-bit signed) High-magnitude integer
DECIMAL string / number Arbitrary precision decimal
BOOLEAN boolean true or false
DATE string (ISO 8601 YYYY-MM-DD) Calendar date without time
TIME string (ISO 8601 HH:mm:ss[.SSS]) Wall clock time
LOCAL_DATETIME string (ISO 8601 local date-time) Date and time without a UTC offset
INSTANT string (ISO 8601 instant) Absolute point in time
UUID string (RFC 4122) 128-bit unique identifier
JSON object / array / scalar Arbitrary JSON structure
ENUM string Enumerated token
BINARY string (base64) Binary payload
AUTO_NUMBER number / string System-assigned monotonic number
DOCUMENT object (Canonical Document Reference) Document reference with version and metadata
USER object (Canonical User Reference) User reference {kind: "user", userId: "..."}
GROUP object (Canonical Group Reference) Group reference {kind: "group", groupId: "..."}
FOLDER object (Canonical Folder Reference) DMS Folder reference
CABINET object (Canonical Cabinet Reference) DMS Cabinet reference
LIFECYCLE_REF object (Lifecycle Reference) Reference to lifecycle case
FUNCTION_REF object (Function Reference) Governed function reference
RECORD object Key-value record instance
RECORD_REF object Pointer to stored record

This table follows the closed ValueKind enum in platform-foundation. Expression/process grammars have their own aliases and dynamic Any handling; ANYTHING is not a member of that enum. A surface's DateTime alias must be interpreted through that surface's type contract, not by merging local date-time and instant semantics.

Canonical Document References

Documents are represented as structured references rather than raw identifiers:

{
  "kind": "document",
  "documentId": "doc-a1b2c3d4",
  "versionNumber": 2,
  "name": "Vendor-Proposal.docx",
  "size": 3670016
}

Version Pinning vs Latest

  • Pinned Version: When versionNumber is specified, process execution and task retrieval pin to that exact immutable document version.
  • Current / Follow Latest: When versionNumber is omitted, dereferencing retrieves the latest active version.
  • Shorthand Normalization: Submitting a raw document ID string (e.g. "doc-a1b2c3d4") is accepted as shorthand and automatically normalized into the canonical reference { "kind": "document", "documentId": "doc-a1b2c3d4" }.

Multiplicity and Process Variables

In BPMN Process Definitions, variables are declared with multiplicity via List<T> grammar:

  • Document: Holds one document reference.
  • List<Document>: Holds an ordered collection of document references, preserving duplicates and versions.
  • In the Studio Process Variable modal, multiplicity is selected via the Single / Multiple toggle.

Exact Decimal values and local defaults

Declared process Decimal values use the canonical limit of 1,000 digits of precision in plain decimal text and 1,000 fractional places. Tiny values such as 1e-400 remain exact in scalar and collection defaults and writes. Integral zeros implied by an exponent count toward precision. Fractional scale is retained, including trailing zeros such as 120.50, through expression responses.

In the interface designer, an invalid local default stays visible with its validation error after leaving the field or switching inspector tabs. Correct the value, clear it, remove the local, or explicitly discard the pending edit before saving or publishing; the previous valid default is not silently substituted.

Removing a reference from a Multiple local also matches shorthand defaults. For example, removing "doc-1" from ["doc-1", "doc-2"] removes the first matching reference. Document version pinning still participates in identity.

Saved screen expressions also retain exact Decimal/Long arithmetic inside declared record fields and record collections. For example, a Decimal invoice.total of 9007199254740993.01 plus 1 yields 9007199254740994.01. Numeric functions retain that policy: roundTo(value, 2) + 1 preserves cents even when rounding changes scale. Expressions reading these fields use the saved server evaluator in the browser. Event action expressions and handler/step guards use the same routing for inline fields and published record types. Decimal collection addItem, addItems and setValue accept canonical values longer than 128 characters, up to the same 1,000-digit precision and scale bounds, without rounding or dropping trailing zeros.

AI task Document and Image bindings accept both raw document IDs and canonical document references through the public rule service, including pinned versions. Screen User, Group, Folder, Cabinet and Function inputs normalize shorthand IDs to the same canonical objects as explicit references, for both Single and Multiple values. Expressions such as inputs.owner.userId therefore work with either spelling.

Run 23: modeled references and saved local guards

Modeled User and other reference fields expose their canonical properties to expression checking. For a User field, customer.owner.userId and customer.owners[0].userId are valid; collections must be indexed or traversed before accessing properties. Unknown reference properties remain publication errors. Collection-plan fields retain reference cardinality and are opaque where the plan vocabulary has no reference schema.

A synthetic local draft coordinate ($local:<name>) retains the eligibility of its saved bound controls and their parents. Hidden, disabled and read-only controls cannot be bypassed by changing the coordinate; whole-record edits also preserve guards on bound members. Unbound locals remain editable, and row-local controls govern their own row scope.

Decimal and legacy Number validation reject numeric inputs whose exponent would exceed the 1,000-digit precision or scale limit before expanding them into plain text. Ordinary values retain their exact digits and fractional scale. Collection removal by index leaves the collection unchanged when the selection is absent, blank, boolean, nonnumeric, fractional or outside the collection. In-range integer numbers and numeric strings (including zero) still select the corresponding item.

Human-task input bindings retain exact Long and Decimal values, including lists, through origin tracking and task snapshots. Public values remain readable without losing digits or decimal scale; sensitive and credential restrictions still apply. Folder, Cabinet and Document reference pickers display canonical local defaults as selected references. Mounting or reconfirming the same document retains its version pin; choosing a different document does not transfer the old pin.

Process references and exact reciprocal powers

Typed process-variable writes normalize reference IDs and alias objects to canonical maps, including every typed list element. For example, {kind: "document", id: "doc-1", version: 1} becomes {kind: "document", documentId: "doc-1", versionNumber: 1}, so doc.documentId works after storage and reload. User, Group, Folder, Cabinet, LifecycleRef, FunctionRef and RecordRef follow their shared reference contracts. RecordRef requires a schema and record identity; a raw ID alone is insufficient. Legacy lifecycle {key, version} maps remain supported.

Negative integer powers of declared exact Decimal values retain finite reciprocal results within the existing precision/scale limits: power(2, -60) produces 8.67361737988403547205962240695953369140625E-19. Recurring reciprocals and ordinary Number values retain their existing rounding policy.

Reference assignment and expression properties

Human-task participant variables and assignment expressions accept canonical User values ({"kind":"user","userId":"alice"}) and userId maps. The directory still determines the actor and task workspace eligibility. A present userId takes precedence over legacy id; blank, invalid or unknown canonical identities do not fall back to another user.

Declared local collections (MULTIPLE, List, RecordList) reject null members in defaults and draft edits, matching rule collection inputs. An optional collection may itself be null; an empty list remains valid subject to its size constraints.

Reference expressions support canonical keys and the existing aliases, case-insensitively: id selects documentId, userId, groupId, folderId or cabinetId; Document version selects versionNumber. Lifecycle/Function id and lifecycleKey/functionKey select key; RecordRef id selects recordId and recordType selects schemaRef. These rules apply to interpreted and compiled property/index access. Missing optional reference metadata evaluates to null. Ordinary map keys remain exact and unknown properties remain errors.

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