Skip to content
Agile Defense

Curriculum / Application Developer & Ontology Engineering

ADVANCEDUnit 5unit-05

Function-backed Actions: edit the Ontology safely

not started~300 min
Publish an Ontology-edit function and a function-backed Action (triageDisruption) that sets owner and status on a DisruptionEvent.

Introduction

Scenario: Your supply-chain command-center app can now read risk and run analysis, but operators still cannot act: when a DisruptionEvent fires, no one can assign an owner or escalate its status from inside the app. This unit gives them a governed write path — an Ontology-edit function wrapped in a function-backed Action (triageDisruption) that safely sets owner and status on a DisruptionEvent.

Up to now every Function you published for the command center has been read-only. Query functions are the read-only subset of Foundry Functions exposed through the API gateway; by design they cannot have side effects such as modifying the Ontology — the docs are explicit that to change data you use an Action, not a query. That separation is the whole point of this unit: operators need to triage disruptions (assign an owner, move status to assigned or resolved), and that is a write, so it must flow through an Action type rather than through anything callable as a query.

The mechanism is the function-backed Action. A function-backed Action is an action type that calls an Ontology-edit function to define how objects are modified: you author the edit function with the Ontology edits API (declaring its edits via the Edits type / createEditBatch over imported object types), publish it so action types can read it, and then configure an action type to use that function as its backing. This unlocks edits more complex than rule-based actions — branching logic, multi-object edits, computed values — while keeping a single governed entry point. Function-backed actions are supported across TypeScript v1, TypeScript v2, and Python; for this app the edit function is authored against DisruptionEvent and the action is named triageDisruption.

A crucial honesty thread runs through this unit: the edit function is not a query and will never show up where queries do. It will not be enumerable in List Query Types and cannot be run via Execute Query — attempting either is a category error. Because of that, you confirm the edit function only indirectly: the action type that wraps it appears in List Action Types, and once an operator applies the action the resulting object state (a DisruptionEvent that now has an owner and a triaged status) proves the edit actually landed. Apply itself is a write API; only the state it leaves behind is read-confirmable. You will close the unit by documenting permissions, parameters, and submission criteria, which are configuration the read APIs do not expose and so must be self-attested.

Capability focus: Ontology-edit functions; function-backed Action types; applied-action effects proven via object state (edit functions are NOT queries). · Artifact: A published Ontology-edit function and a function-backed Action (triageDisruption).

Key concepts

  • Query function vs edit function: A query function is the read-only subset of Functions exposed through the API gateway (annotated @Query, lowerCamelCase apiName); it cannot have side effects such as modifying the Ontology. An Ontology-edit function is the opposite — it exists to mutate object state and is consumed by an Action, never enumerated in List Query Types nor invoked via Execute Query.
  • Ontology-edit function: A Function authored with the Ontology edits API that declares the edits it performs (e.g., via the Edits type / createEditBatch) over imported object types. Per the docs it is built from the functions-on-objects template, imports the relevant object types, and must be published so action types can read it as their backing logic.
  • Function-backed Action type: An action type whose behavior is defined by an Ontology-edit function rather than by rule-based edits. You publish the edit function, then configure the action type to use it as its backing — enabling edits more complex than rule-based actions. Supported in TS v1, TS v2, and Python.
  • Applied action and object state: Applying (running) an action is a write operation; it is not itself read-introspectable. The proof that an action executed is the object state it leaves behind — here, a DisruptionEvent with a non-empty owner and a status in {assigned, resolved} — which is observable via List Objects.
  • Action configuration that is not read-API-exposed: List Action Types returns an action's apiName and parameter names, but submission criteria, validation rules, and permissions are configuration that no read API surfaces. These must be documented and self-attested rather than machine-checked.
  • Read-API surface for this unit: The relevant v2 read endpoints are List Action Types / Get Action Type (to confirm the action exists) and List Objects (to confirm post-edit object state). Notably absent from any useful result for an edit function are List Query Types and Execute Query — by design.

Companion video

Function-backed Actions walkthrough (placeholder) · open on YouTube

Hands-on activity

each step validates · the unit completes when all steps pass
  1. 1

    Write and publish the Ontology-edit function

    Author the Ontology-edit function that triage will call. Using the Ontology edits API (the functions-on-objects template), import the DisruptionEvent object type and write a function that declares its edits — setting owner and moving status to a triaged value such as assigned or resolved — batching them via the Edits type / createEditBatch, then publish it (Tag version / commit) so action types can read it. Confirm to yourself in the Functions Live Preview that the edit logic runs. The grader cannot inspect this function directly and it is intentionally treated as self-attested: an edit function is NOT a query, so it will never appear in List Query Types and cannot be run through Execute Query — its real proof comes in the next two steps via the action it backs and the object state that action produces.

    not startedself-attested

    Self-attested: an edit function declaring its edits is published (edit functions are NOT queries — they will not appear in List Query Types).

  2. 2

    Configure the function-backed Action type

    Wire the published edit function as the backing of a function-backed Action type and name the action triageDisruption. In the action-type configuration, select the edit function as the backing logic and expose the parameters operators will supply (the target DisruptionEvent, the owner to assign, and the target status). Once configured, the action type becomes enumerable: the grader calls List Action Types and confirms that an action with apiName triageDisruption is present in the Ontology. This is the first machine-confirmable evidence that your edit function exists at all — not as a query, but as the logic behind a registered action type.

    not startedinstance check

    Confirms the triageDisruption action type exists after the edit function is wired as a function-backed action.

  3. 3

    Apply the action and confirm its effect on object state

    Apply the triageDisruption action against a seeded DisruptionEvent so its edit actually lands, then verify the result. Applying an action is a write through the apply API and is not itself read-introspectable, so the check looks at what the apply left behind: via List Objects, the grader confirms that at least one DisruptionEvent now carries a non-empty owner and a status in {assigned, resolved}. That post-edit object state is the definitive proof that the Ontology-edit function ran end to end — the read side cannot watch the edit happen, only the triaged object it produces.

    not startedinstance check

    Confirms an applied action: a DisruptionEvent now has an owner and a triaged status (proving the EDIT landed).

  4. 4

    Document permissions and submission criteria

    Document the action's governance so a reviewer can reason about it without re-running it. Record the action's parameters (target DisruptionEvent, owner, target status), the submission criteria and validation rules that gate when triage may be applied, and the permissions that determine who may run it. This step is self-attested by design: List Action Types returns only the action's apiName and parameter names, while submission criteria, validation, and permission bindings are action configuration that no read API exposes. State these honestly in the note rather than implying the grader verified them.

    not startedself-attested

    Self-attested: a note records the action's permissions, parameters, and submission criteria.