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.

First-Party Expression Functions

Find the descriptor before copying a function call

A first-party function is a supported extension point with a typed descriptor: stable key, signature, parameters/defaults, return type, examples, determinism, provenance and argument-only/host-capability behavior. The catalog is the appropriate starting point for an author; a list of familiar Excel-like names is not permission to assume every spreadsheet coercion or locale behavior.

Bundled executable packs run through the admitted isolated function path. Declaration-only people/system operations are performed by compiled host bindings and retain their own permissions/effect contracts. They do not become harmless local calculations because they appear next to text/math functions in autocomplete. Customer uploads have a separate review/approval lifecycle and cannot replace the exact bundled distribution through the dynamic inventory.

Need Inspect before using
Working-day calculation Weekend definition, inclusive bounds, explicit holiday input and maximum span.
Finance calculation Exact decimal versus DECIMAL64 policy, day-count method and rounding intent.
Text/collection conversion Input kinds, index base, empty/missing behavior and growth/work bounds.
Document/reference helper Pure construction/inspection versus actual secured document I/O.
People/native capability Actual trusted caller/workspace and operation authorization.
Missing function Exact pack artifact, catalog discovery and admission state before editing production controls.

The cases below teach a few realistic choices. The pack reference remains below for broader discovery; every new function result must be checked against its own descriptor and implementation, not inferred from a different pack.

Worked examples

Example DATA-FUNCTION-01 — Count explicit holiday-adjusted weekdays for a leave request

Scenario and inputs. Mohammad requests 2026-12-14 through 2026-12-18. The admitted calendar-finance pack is available and Nadia has an explicit holiday list for this policy. The function accepts dates/date-time/ISO text according to its descriptor; it does not automatically fetch a workspace business calendar or deduct a leave balance.

Procedure. 1. Inspect networkDays(startDate, endDate, holidays?) in the current function catalog. 2. Evaluate the date range without holidays and compare it with a calendar: Monday through Friday inclusively contains 5weekdays. 3. Supply 2026-12-16 in the explicit holiday list when that is the authored policy; the expected count becomes 4. 4. Test a duplicate holiday, a weekend holiday and reversed dates separately. 5. Pass the resulting quantity into the declared eligibility/approval workflow, keeping actual policy ownership and authorized mutations separate.

Expected result. The function counts Monday–Friday dates inclusively, deduplicates holidays and makes a reversed range negative under its source-defined contract. A weekend holiday does not subtract an additional weekday.

Failure and recovery. A missing required date, invalid date value or span beyond its published bounds must be corrected under the input contract. Do not assume Friday/Saturday weekends, a different organization calendar or a successful balance update from the numeric result; those require a separately designed admitted policy/action.

Sources. NetworkDaysFunction.java.

Example DATA-FUNCTION-02 — Choose a financial day-count method instead of relying on defaults

Scenario and inputs. An expense/finance variant prorates a period from 2026-02-28 to 2026-03-31. Nadia’s business policy distinguishes US/NASD from European 30/360. Both are legitimate conventions, but they do not answer this boundary case identically. The example is a calculation design, not a posting instruction or accounting advice.

Procedure. 1. Read the exact days360(startDate, endDate, method?) descriptor and the organization’s approved method. 2. Call days360("2026-02-28", "2026-03-31", "US/NASD") for that explicit convention and compare its source-defined adjustment to the end-of-February start. 3. Compare with an explicit European call only as a test of the policy choice, not as a fallback when the first answer is inconvenient. 4. Keep the chosen method visible in the published expression and test reversed ranges and end-of-month dates.

Expected result. The implementation’s US/NASD adjustments yield 30for this range, while European clamps 31to 30but leaves February 28, yielding 32. The difference explains why a named published method is more reviewable than an unexamined default.

Failure and recovery. An unknown method token is a governed invocation failure; correct it to a supported convention instead of swallowing the error. Do not change method or round intermediate values to force a desired payout, and keep any actual financial effect behind its own authorized workflow and exact decimal settlement policy.

Sources. Days360Function.java.

Example DATA-FUNCTION-03 — Distinguish pure arguments from a host-owned people operation

Scenario and inputs. Nadia sees calendar, text and people/system entries in the function catalog. She wants to reuse one in an application rule, but only some are argument-only calculations. An operation that depends on current identity, workspace or a native effect must not be treated as a free computation over a user-supplied ID.

Procedure. 1. Inspect the actual descriptor’s canonical key, parameters, return type, provider/version and argument-only/capability metadata. 2. For a pure function, pass only values admitted by its declared input contract and respect work/output limits. 3. For a host-bound declaration, follow the actual native permission and trusted-context requirements before offering it to an author or consumer. 4. Validate the containing rule’s purpose and caller path. 5. Test denied and ordinary-user cases through the authorized product validation plan when such runtime execution is separately admitted.

Expected result. Descriptor provenance and the native binding make the boundary explicit. A JSON user/workspace ID does not grant authority, and shipping a declaration-only pack does not load arbitrary customer plugin bytecode into the API JVM.

Failure and recovery. If the intended caller lacks the required native capability, keep the operation unavailable or redesign the allowed business flow. Do not turn a host declaration into a runner function, remove its guard, use a model response as an access grant or borrow an administrator credential just to obtain a sample result.

Sources. FunctionDescriptor.java, README.md.

Example DATA-FUNCTION-04 — Diagnose missing or incompatible descriptors before changing controls

Scenario and inputs. The same expression works in one admitted environment but reports an unknown function or wrong signature in another. Nadia wants to know whether the error is in authored input, catalog discovery, packaged distribution or dynamic plugin admission. A passing pack unit test from a different build cannot resolve that question by itself.

Procedure. 1. Record the exact nonsecret function key and expected descriptor/version from the source application artifact. 2. Inspect the running environment’s authorized function catalog and actual pack provenance. 3. Compare parameter kinds, optional defaults and return shape before changing the expression. 4. If the bundled artifact or startup discovery is missing, ask the accountable release/operator owner to reconcile that distribution. 5. If this is a customer plugin, follow its separate administrator review/approval/enable flow and preserve validation failures.

Expected result. The diagnosis identifies the specific missing boundary instead of treating every unknown function as permission to install an ad hoc JAR. Correct argument errors and missing artifacts lead to different supported recoveries.

Failure and recovery. Do not disable strict verification, choose process mode for untrusted code, add an invented XML function catalog or replace a bundled pack through customer administration. Source/static examples remain unexecuted in a live environment until the actual admitted build and caller path are tested with the relevant evidence.

Sources. FunctionDescriptor.java, build-first-party-function-plugins.ps1, AdminPluginController.java.

Detailed reference

Inflow ships additional no-code expression functions as separately versioned first-party plugin JARs (including the icon() UI pack). They extend the expression language without loading plugin bytecode into the API JVM.

Build

From the repository root:

.\scripts\build-first-party-function-plugins.ps1

The command installs the standalone SDK and test kit, verifies every executable pack, and writes one deployable JAR per pack — seven today: calendar-finance, conversion-serialization, documents, icons, math-statistics, text, and validation-collections — to target/first-party-expression-functions. The expected count is derived from the inflow-functions-* modules under first-party-plugins, so a new pack module is picked up without editing the script. The declaration-only inflow-functions-people pack is not built here: its functions are performed by the host, and it ships only inside the application.

Distribution

The eight Inflow-maintained function packs — the seven deployable packs above plus the declaration-only inflow-functions-people pack — are bundled in the versioned application artifact and registered automatically after archive, manifest, provider, and content checks. They do not create administrator approval records and cannot be disabled or replaced through the customer-plugin administration surface.

Customer and third-party plugins still follow the explicit upload, fingerprint review, approval, and enablement flow. Executable plugin bytecode uses the isolated filesystem sidecar. The bundled declaration-only people functions and first-party system capability declarations use compiled host bindings/dispatch; they do not load customer plugin classes into the API JVM. Those host operations retain their own permission, trusted-context and effect checks.

Discovery In Studio

Enabled descriptors are added to GET /api/rules/functions. The shared catalog drives function search and autocomplete in expression rules, query rules, and interface expressions. A function therefore becomes available to all supported expression editors after enablement without a frontend release.

Each catalog entry provides a display name, searchable category, signature, plain-language summary, typed parameters, return type, examples, icon, determinism marker, plugin identity, provider, and plugin version.

Function Packs

Validation And Collections

isNull, isBlank, isPresent, isEmpty, isNotEmpty, isNumber, isEmail, index, length, append, insert, remove, updateArray, reverse, flatten, where, and whereContains.

Named index operations use 1-based positions. index supports nested object paths and an optional default. Collection operations return new values and do not mutate their inputs. Flattening is bounded to prevent unbounded nesting.

Text

like, find, search, replace, padLeft, padRight, repeat, proper, clean, exact, stripHtml, and stripWith.

find is case-sensitive, search is case-insensitive, and both return a 1-based position or zero. like is case-sensitive and treats * as any sequence and ? as one character. stripHtml removes markup for display and conversion workflows; it is not an HTML sanitizer and must not be used as a security boundary. Text growth and pattern work are bounded.

Calendar And Finance

networkDays, workday, days360, yearFrac, weekNum, second, time, and addDateTime.

Calendar functions use ISO values at the plugin boundary. time returns a real Time value, not formatted text. Week and financial basis methods are explicit arguments where their meaning can differ. Working-day functions use Monday through Friday plus the caller's explicit holiday list; they do not yet read a workspace calendar. weekNum defaults to Sunday-start numbering and accepts an explicit ISO method. yearFrac basis 1 uses ISDA Actual/Actual.

Math And Statistics

The math pack1.0.1 adds decimalSum(numbers) and decimalDivide(numerator, denominator, scale, roundingMode) for exact financial calculations. Ordinary arithmetic operators and the existing sum/average functions retain their16-significant-digit DECIMAL64 policy.

decimalSum adds1–10,000 finite Numbers without significant-digit rounding. It rejects an empty list or missing/non-number element; use [0] for an explicit known zero. product already multiplies exactly. decimalDivide requires an integral scale0–1000 and an explicit uppercase rounding mode, offered by the catalog: UP, DOWN, CEILING, FLOOR, HALF_UP, HALF_DOWN, HALF_EVEN or UNNECESSARY. UNNECESSARY refuses a result that needs rounding; division by zero is always refused. Scale chooses decimal places, not significant digits. Trailing-zero removal affects representation, not numerical value.

For example, decimalDivide(number("9999999999999999.000499"), 1, 10, "UNNECESSARY") preserves the fraction, whereas ordinary / follows DECIMAL64. For a prorated element, use exact product and explicit decimalDivide, sum raw segments with decimalSum, then settle the element once with roundTo according to the published currency policy. Do not round each display segment separately.

All these functions retain bounded inputs/results; they do not bypass native rule authorization, execute financial postings or select a payroll policy. Use exact decimal inputs: text can be converted natively with number; a value already rounded by an external floating-point client cannot be repaired.

product, median, mode, stdev, variance, int, mod, quotient, log, ln, and exp.

Invalid numeric domains and zero divisors fail with governed invocation errors. variance and stdev are sample statistics and divide by n - 1. mode returns the lowest value when frequencies tie and rejects input with no repeated value. Statistical functions define their empty and minimum-sample behavior in their catalog descriptions.

Conversion And Serialization

toJson, fromJson, typeOf, cast, bin2dec, bin2hex, bin2oct, dec2bin, dec2hex, dec2oct, hex2dec, hex2bin, hex2oct, oct2dec, oct2bin, and oct2hex.

JSON is limited to 256 KiB, nesting depth 32, collection width 1,000, and 10,000 aggregate nodes. Base conversion accepts signed integers up to a 4,096-bit magnitude. JSON object keys are emitted in canonical sorted order. Base-conversion negatives use signed-magnitude text such as -FF, not a fixed-width two's-complement representation. cast is intentionally dynamic and therefore advertises return type Any; date and time values use ISO text at the plugin boundary. These limits and representations are part of the function contract.

For an object assembled from expression values, use a direct list of pairs: cast([["status", "READY"], ["data", rows]], "Object"). Each pair has exactly two elements and a Text key. Keys are kept verbatim and duplicates are refused, including a duplicate whose first value was null. The result is deeply immutable and uses the existing shared depth, collection and aggregate-value limits. Nested lists remain data. Existing Map and JSON-object text casts keep their behavior; JSON text containing an array remains refused. This constructs the object in one ordinary sandboxed function invocation, without a JSON conversion for each field.

Documents

is_document_ref, document_ref, document_ref_id, document_ref_name, document_ref_version, document_ref_mime, document_ref_size, document_download_name, document_open_label, document_content_path, document_link, and document_ref_link.

These deterministic helpers construct and inspect document attachment references and download links. They perform no secured document I/O; operations that require document permissions remain in the platform service boundary.

Icons (UI)

icon.

Resolves a stable platform icon id from the self-contained catalog at icons/catalog.json inside the inflow-functions-icons JAR. Returns a platform-icon object for Studio to render (optional inline svg, otherwise the platform Lucide business-icon map). Full catalog and usage: docs/manuals/icon-expression.md.

Release Verification

The root certification test loads the same first-party JARs packaged for release, not their implementation classes. It verifies unique canonical keys, supported metadata types, no built-in collisions, catalog visibility, and external-runner execution. A release is not certified solely because the pack unit tests pass; frontend build, bundled startup discovery and immutability, autocomplete and runtime evidence, the full backend suite, and a fresh-checkout build are also required.

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