# Process A Process performs a business action. It is implemented in a separate AIScript resource or as a composite that calls other Processes and maps their Inputs and Outputs. A Process has a name describing the action and documentation explaining its purpose, rules and result. For example, CreatePurchaseOrder, ApprovePurchaseOrder and ListSupplierOrders are actions with different contracts, even though they use related Collections. The produced file is `processes//process.json`; its folder uses the Process's exact `name`. It follows `Process.schema.json`. A coded Process also has `code.ais`, with a System-relative reference in `implementation.resource`. | Property | Meaning | | --- | --- | | `name` | Process name, unique among Processes in this System and used in references and its folder name. | | `audience` | Required exact name of the one Audience this Process belongs to. The Audience must exist in this System. | | `description` | Business purpose of the action. | | `tags` | Optional list of distinct, nonblank labels chosen by the author for grouping, filtering and discovery. | | `enabled` | Whether it is available for publication. | | `channels` | Optional allowed invocation channels. Omitted means all channels; an empty array means none. Distinct from Audiences. | | `authentication` | Incoming authentication method: `none`, `token` or `signature`, separate from invocation channels. | | `signature` | Verification configuration, required only when `authentication` is `signature`. | | `invocation` | Cron, timezone and supplied Inputs for a scheduled Process. | | `inputs`, `outputs` | Typed contract of the action. | | `dependencies` | Declared resources used by the action. | | `documentation` | Summary, operation, success, errors and realistic examples. | | `implementation.resource` | System-relative AIScript file path ending in `.ais`. | | `composition` | Child Processes, mappings and connections, instead of code. | | `presentation` | Optional App presentation of the Process. | | `primary` | Whether to present it as a primary business Process. | Tags are general-purpose labels, not predefined categories. For example, `"tags": ["Purchasing", "Approvals"]`. Omit `tags` or use an empty array when no labels are needed. Tags do not change execution, grant access or establish certification. ## JSON Example ```json { "name": "ReadSupplier", "audience": "Employees", "description": "Retrieve the active supplier selected by its record identity.", "tags": ["Purchasing", "Supplier Management"], "enabled": true, "channels": [ "http" ], "authentication": "token", "inputs": [ { "name": "supplierId", "type": "reference", "collection": "Supplier", "description": "Identity of the supplier to retrieve.", "required": true, "label": "Supplier ID" } ], "outputs": [ { "name": "supplier", "type": "object", "description": "The selected supplier's identity and business name.", "required": true, "schema": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "label": "Supplier" } ], "dependencies": { "dataCollections": [ "Supplier" ], "services": [ "database_default" ] }, "documentation": { "summary": "Read an active supplier", "operation": "Look up Supplier by supplierId with deleted=false and return its identity and name. Return not found when no active record matches.", "success": "The response contains the selected active supplier's identity and name.", "errors": [ { "status": 404, "condition": "No active Supplier record matches the supplied identity.", "message": "Supplier not found." } ], "examples": [ { "name": "Read an existing supplier", "description": "Retrieve a supplier whose active record already exists.", "request": { "supplierId": "aaaaaaaaaaaaaaaaaaaaaaaa" }, "response": { "supplier": { "id": "aaaaaaaaaaaaaaaaaaaaaaaa", "name": "Example Supplies" } } } ] }, "implementation": { "resource": "processes/ReadSupplier/code.ais" } } ``` The referenced Collection and Service must be declared separately using those exact names. The referenced AIScript file must implement this operation and contract; this JSON is not a replacement for that code. The sample `supplierId` is a stored record ID, not a resource name. ### Inputs And Outputs Inputs are values supplied to perform the action. Outputs are the values returned by the action. Each has a `name`, a readable `label`, a type and a description of its business meaning. The name is used in code and mappings; the label is display text. Their definitions include required values, limits, allowed values and related Collections where applicable. Use `values` for a fixed list of allowed values chosen by the System author, for both Inputs and Outputs. Each value follows the field's type. Omit `values` when there is no fixed list. The field's `label` is its display name, not a label for each choice. ```json { "name": "status", "label": "Status", "description": "Business state selected for this action.", "type": "string", "values": ["pending", "approved", "rejected"] } ``` Define the Inputs needed by the business action and use them in the implementation. System Access and Identity Management already exist and are managed separately by the runtime, outside this contract. Execution tracking and audit are runtime responsibilities, not additional business Processes to generate. An Input is required when the action cannot be performed without it. An optional Input has a documented meaning when omitted, such as not applying a particular search filter. Information obtained from a related record need not be requested again as an Input. ### Input And Output Types | Type | Meaning | | --- | --- | | `string` | Text, with length limits or allowed values where needed. | | `text` | Longer textual content. | | `integer` | A whole number, represented by AIScript's checked integer type. | | `long` | A larger whole number, represented by AIScript's checked integer type. | | `decimal` | A fractional numeric value, such as an amount or rate. Use AIScript decimal calculations and explicit rounding where the business rule requires it. | | `boolean` | A true or false value. | | `date` | A calendar date. | | `datetime` | A date and time. | | `object` | A structured value. Its `schema` describes properties, their types and required values. | | `array` | Several values. Its `schema` describes the array and its `items`, including nested structures where needed. | | `reference` | A record ID. `collection` names the related Data Collection; the value follows that Collection's ID type. | | `file` | A value describing a stored file: `id` (upload identifier), `name`, `contentType`, `extension` and `size` in bytes. It contains metadata, not file contents, a local path or a filesystem object. | Use the same lowercase type names as Data Collection fields and Event values. Use `decimal` for fractional numeric values, not a separate `number` resource type. Embedded JSON Schema uses its standard names, such as `number` for a numeric property; that is validation syntax, not another System field type. An array of file values uses `type: "array"` and a schema describing those metadata objects as its items, just as any array describes its elements. There is no separate multiple-file resource or Process type. Outputs describe the actual result, including the structure of returned records, totals or other values. Use the same name and type for Inputs with the same meaning throughout the System. The same applies to Outputs passed between Processes. A Collection reference field represents the related object; an Input that selects that object can carry its record identity. For a list operation, define the supported filters, ordering and paging Inputs and the corresponding Outputs. The returned array can have any meaningful declared name; there is no assumed `records` property. ### Dependencies Dependencies identify the Collections, Services, Secrets, Events and other Processes used by the action. They describe actual usage. A dependency declaration alone does not implement that usage. For example, CreatePurchaseOrder can depend on PurchaseOrder and Supplier, a database Service, and an email Service. Its implementation must store the declared order information, associate the selected supplier and handle any promised notification. ### Code Implementation Process code uses the System's declared Services and AIScript. It can also call other Processes and publish declared Events. Event consumption is defined in the Process/Event resources, not by writing a listener. The code is delivered in a separate `.ais` file, referenced by `implementation.resource`. It defines `execute(input)` and may define helper functions. The code reads the declared Inputs, performs the action and returns the declared Outputs. There are no file-level variables or endpoint specifications in code. Service interfaces, record operations, errors and code examples are defined in `languages/aiscript/AIScript.md`. The resource declares its authentication requirement, not a generated endpoint specification or a policy for managing Users, Roles or access grants. ### Composite Implementation A composite describes an action using child Processes rather than an AIScript implementation of its own. Its nodes identify child Processes. Input mappings provide each child's Inputs from the parent Inputs or earlier results; Output mappings make child results available to the composite. Each node's `process` is the exact name of a declared Process. A node's local `id` distinguishes steps inside this composition, including two steps that call the same Process. It is not a System resource identifier. Connections describe the flow between nodes, including conditions where the flow branches. Entry nodes identify where execution starts, and exit nodes identify where it finishes. Every required child Input must have a source, and the completed flow must provide the parent Outputs. A Process uses either a code implementation or a composite, not both. Calling a Process directly is distinct from emitting an asynchronous Event. ### Audience And Invocation Every Process declares one required `audience`, using the exact name of an Audience in this System. Internal, scheduled and message-driven Processes also name the Audience whose work they support. This does not expose them: channels and authentication remain separate. When two Audiences need similar actions, each has its own Process and contract; those Processes can call a common internal Process, which retains its own Audience reference. `channels` identifies how a Process can be invoked, not who its Audience is. It is optional: omit it to allow all channels, use `[]` to allow none, or list the allowed channels. An empty array does not mean all channels. | Channel | Meaning | | --- | --- | | `http` | Calls through the API endpoint. | | `internal` | Direct Process calls within the same API. | | `peer` | Calls from another API. | | `scheduler` | Scheduled invocation, using HTTP transport with the scheduler channel. | | `mom` | Message-driven invocation receiving Events. | A Process may allow several channels. Channels do not create jobs or Event subscriptions by themselves: scheduled execution needs `invocation`, and Event delivery needs an Event mapping. A scheduled Process requires `invocation`: the cron expression, timezone and Inputs supplied for each scheduled call. An Event-driven Process receives its Inputs through the Event mapping. Internal, scheduled and message-only Processes are not human Audiences. ### Authentication `authentication` defines how incoming calls are authenticated. It is separate from `channels`: a channel describes where a call comes from, while the authentication method describes the credential it must present. Allowing a channel does not bypass authentication. | Method | Meaning | Principal | | --- | --- | --- | | `none` | Authentication is not required. | Anonymous when no identity has been resolved. An already resolved identity is not removed. | | `token` | A valid token is required; the runtime checks the caller's access. | Contains the authenticated properties supplied by token resolution. | | `signature` | A valid request signature is required. | Signature verification alone does not populate a user identity. The principal can remain anonymous unless identity was resolved separately. | The principal represents the resolved caller. Its properties depend on the identity contract supplied by the runtime; declaring an authentication method does not invent user fields or business bindings. An anonymous principal has no resolved identity properties. Signature authentication verifies the signed request. It does not automatically populate the principal. Process code can use its Inputs and verified signed values to establish the business context it needs. Only values included in the signed content are protected by the signature. Do not create a principal in Process code; identity management belongs to the runtime. `none` and `token` need no Process-specific signing configuration. `signature` also needs a verification configuration describing the key identifier, where the signature arrives, the exact content signed and the verification options. Declare any required key material as Secrets. Signature verification proves possession of the signing key; it does not by itself grant user permissions. Authentication is enforced by the runtime, not implemented in the Process's business code. #### Signature Configuration ```json { "authentication": "signature", "signature": { "key": "H/X-Key", "signature": "B/proof.signature", "payload": "{{verb}}\n{{host}}\n{{path}}", "options": { "algorithm": "HmacSHA256" } } } ``` This is an excerpt of a Process. Header and body field names are chosen for the caller's contract; the names shown are examples, not reserved names. | Property | Meaning | | --- | --- | | `key` | Where the request supplies the provider key identifier. Declare the required signing material as a Secret; deployment supplies its actual identifier. | | `signature` | Where the request supplies the signature to verify. | | `payload` | Exact text template signed by the caller and verified by the runtime, encoded as UTF-8. Supported values are `verb`, `host`, `path` and `parameters` (including named parameter values). The path includes the deployed API's base path. | | `options` | Verification options described in `languages/aiscript/AIScript.md`, matching the caller's signing algorithm. | For `key` and `signature`, `H/name` reads a header, `P/name` reads a request parameter and `B/` reads a value at a JSON body path. For example, `B/a.b.c.d` resolves through `Object.get(body, 'a.b.c.d')`. A name without a prefix reads a header. `B/` requires a body with Content-Type `application/json` or an `application/` subtype ending in `+json`. Matching is case-insensitive and permits parameters such as `charset=UTF-8`. Missing bodies, unsupported content types, malformed JSON and missing required values are rejected; there is no fallback to another source. The default SecretsProvider is always used; do not declare `secretsProvider`. `B/` locates a value in the body; it does not add that body to the signed payload. The example protects the verb, host and path only. Automatic signature payload templates do not currently expose body bytes or arbitrary headers. Do not claim that other request values are signed when they are not. Timestamp validation is not included in this authoring contract. A named request parameter can be included explicitly, for example `"payload": "{{verb}}\n{{host}}\n{{path}}\n{{parameters.reference}}"`. The caller signs that exact UTF-8 text, including line breaks and the decoded parameter value. Require the named value, and agree its exact representation with the caller. This does not include a body property with the same name. These placeholders belong to the signature contract, not executable AIScript. ### Scheduling The existing scheduler uses five cron fields: minute, hour, day of month, month and day of week. Values support `*`, numbers, comma-separated lists, ranges and steps. Day of week uses 0 or 7 for Sunday. Use a valid timezone identifier, such as `UTC`. A six-field seconds expression is not supported. For example, a scheduled Process can declare: ```json { "channels": [ "scheduler" ], "invocation": { "cron": "*/5 * * * *", "timezone": "UTC", "inputs": {} } } ``` This excerpt runs every five minutes and assumes the Process requires no supplied Inputs. Otherwise, `invocation.inputs` must provide the required values. The scheduler sends an HTTP POST with those Inputs as JSON. A 2xx response records success; another status or a transport failure records failure. The current scheduler does not automatically retry a failed firing. Within one scheduler server, a job already executing causes another firing of that same job to be recorded as skipped. This is not a distributed lock across independently active scheduler servers. A client timeout can occur while the remote Process continues; it is not proof that execution stopped. The scheduler does not replay every missed firing after downtime. The author decides whether a recurring Process needs to find unfinished work or prevent overlapping business effects across executions. Those rules are separate from a cron expression. ### Service Callbacks And Browser Returns A Service interaction can continue after the initiating Process completes. Define a receiving Process for a later server callback, with Inputs describing the business values it receives. The interaction documentation identifies how those values arrive: JSON, form values, query parameters, headers or raw body bytes. The callable request interfaces are described in `languages/aiscript/AIScript.md`. A browser return URL sends the person back to the calling application. A callback URL tells the remote service where to send a server notification. They are different addresses and need not identify the same Process. Where the action needs these addresses, define them as Inputs or required configuration. The caller can supply an address it owns; do not invent deployment URLs. An initiating Process can return a URL as an ordinary `string` Output so the calling application can continue the interaction. A browser return alone does not establish the business outcome; the receiving Process validates the corresponding notification or uses the Service's result interface. Keep correlation values and any required progress in business records. Typed business Inputs do not by themselves define the transport mapping for an external callback. Document that mapping explicitly; do not assume the runtime converts every incoming format into the declared Inputs. Process App navigation currently targets Process presentations; it does not promise an automatic external redirect or an embedded third-party browser component. ### Availability `enabled` determines whether the Process is available for publication. A disabled Process cannot be treated as an available dependency by another published Process. ### Behavior And Documentation Document the operation's rules, information read or changed, successful outcome and failure conditions. Describe what happens when a record is absent, an action is not allowed by its current business state, or a called Service fails. Explain transaction boundaries and externally visible side effects where they matter. Examples contain realistic Inputs and the corresponding Outputs. They must agree with the implementation, declared types, constraints and related records. A title or description is not a substitute for implementing the action. A complete coded Process includes its definition and referenced code file. Its documentation describes the implemented behavior, actual failure conditions and realistic examples. The schema requires at least one documented error and one example; document meaningful behavior rather than filling these entries with generic text. Scheduling and presentation configure how the Process is used; neither replaces its implementation. Include comments in `code.ais` explaining the business operations and important decisions. Documentation in `process.json` does not replace code comments. Add applicable industry or security annotations beside the operations they describe; use verified references and do not claim certification. The Process specification is `Process.schema.json`. `Process.md` explains the Process contract; `languages/aiscript/AIScript.md` defines functions, values, utilities, Service calls and execution semantics. ## Process Apps A Process can have an App presentation. Forms collect its Inputs, actions invoke Processes and views display their Outputs. Lookups call Processes rather than accessing Collections directly. If a Process is intended to have an App, provide its presentation. Typed Inputs and Outputs alone do not create an App when presentation is absent. Processes not intended as Apps can omit presentation. The presentation's `process` is the Process's exact name. Lookup and resolver operations and actions targeting another Process also use exact Process names. Presentation components have local `id` values for the renderer; those do not identify System resources or stored records. The presentation describes a user interface, not another implementation of the business action. Validation and business rules remain in the Process. ### Forms And Layout Fields bind to the Process Inputs. Their controls can be text, multiline text, numbers, dates, switches, option selectors, record lookups, item selectors or file uploads. The control must match the Input type and constraints. For an Input of type `file`, an upload control can restrict accepted kinds and size. For an array of file values, it can allow multiple selections. The control supplies the declared metadata values after upload, not raw contents or local paths. Rows group related fields on the same line, with spans controlling their relative widths. Sections group related content. Tabs separate views, while wizard steps divide a longer interaction into stages. Use labels and help text to explain the information needed without repeating the same heading at every level. Conditional visibility shows content based on declared Input or Output values. It changes presentation, not the Process contract or its business rules. ### Lookups A lookup invokes a Process that searches or lists records. Its definition identifies the operation, arguments, search and paging Inputs, the returned array, and each item's identity and display label. A resolver Process can retrieve the labels for already selected identities. For example, a supplier lookup can call ListSuppliers and place the selected supplier identity into CreatePurchaseOrder's `supplierId` Input. It does not query Supplier directly. The lookup's paths must match the actual Outputs of ListSuppliers. ### Results And Dashboards Details show named Output values. Tables and cards show an Output array, with declared columns or card fields and a stable row identity. Search and paging controls bind to the listing Process's actual Inputs and Outputs. Metrics show individual values. Line, bar and donut charts use declared category and value paths in returned data. Timelines use time, title and detail values. Graphs use node and edge arrays with explicit identity and connection paths. A file viewer displays a `file` Output or an item from an array of file values. Images and videos use media views, PDFs use a PDF preview, and text or code uses a read-only editor. Other formats can be downloaded. File access is managed by the runtime. The presentation binds to the names and structure actually returned by the Process; it does not assume an array called `records` or invent missing totals. Calculations promised by a dashboard belong in its Processes. Refresh can be manual or interval-based; an interval refresh repeatedly invokes the Process, not an unrequested real-time subscription. ### Actions And Navigation Actions submit Inputs, reset a form, refresh results or navigate to another Process presentation. Navigation can map values from a selected record or current result into the destination Process's Inputs. The destination Process must exist and accept those values. Actions can require confirmation before an operation is submitted. Button, tab and title labels use readable, action-oriented text with the first letter of each word capitalized. ### Labels And Bindings Presentation labels and help text are supplied through its message entries. Bindings identify Input values, Output values or selected row values using a source and a path, as defined in `Process.schema.json`. A display format changes how a value is shown, not its stored type or business meaning. The presentation properties are part of `Process.schema.json`. They define the available components, bindings, actions and layout properties. The renderer supplies the UI components and branding; the author supplies the presentation that fits the Process.