Ontoz Platform

Ontologica

Ontologica is the business domain-specific language behind Ontoz. It gives humans, systems and AI agents a shared, declarative vocabulary for describing work — not only what happens, but what is allowed to happen.

Who this is for

This reference is written for the people who author Ontologica configuration — solution engineers, business analysts, integration developers — and for anyone building tooling that generates Ontoz configuration. It describes what valid configuration looks like and what it means. It is not a guide to any particular deployment.

What a definition looks like

Ontologica is expressed in three complementary artifact languages:

UI forms, integration bindings and tenant patches are configured in the same declarative spirit. Everything is versioned, inheritable and hot-reloadable.

Conventions used in this document

Property names are given in their JSON/YAML form — that is what appears in configuration files. Types are shown as declared in the platform's construct definitions.

The mental model#

Ontologica organises every construct into six families. Understanding which family a construct belongs to tells you what it is allowed to do.

A seventh family — AI constructs — layers copilots and autonomous agents on top of the others. Critically, AI does not add a parallel execution path: everything an agent does flows back through actions, mutations, integrations and rules, so audit, inheritance and hot-reload semantics stay uniform across human, automated and AI work.

Two invariants worth internalising

Anatomy of a flow#

The process hierarchy is strict and has five levels.

A running Flow is a flow instance — one per application, or "case" in business-facing language. It holds the JSONB data payload plus flow state: current stage, open activities, live tasks.

Flow (process)
  └── Stage → Activity → Task (process)
        ├── references → Form Definition            (UI)
        ├── references → Mutation in GraphQL Schema (data)
        ├── references → Rule Sets                  (logic)
        ├── references → Integration API + Mapper   (integration)
        └── governed by → Stage Role Definition     (access)
All wrapped in a Base / Variant configuration chain (config).

Quickstart#

Six artifacts take a business process from nothing to running. The example below sketches an insurance claims flow; the same six steps apply to any domain.

1 · Declare the flow

# flow_definitions.yaml
- definitionKey: insurance-claims
  label: "Insurance Claims Processing"
  prefix: "CLM"
  initialStatus: IN_PROGRESS
  stages:                       # ordered — the flow walks this list by index
    - filing
    - triage
    - investigation
    - adjudication
    - settlement
  initiateFlowMutation: createClaim
  applicationDataScreenId: claims-overview

2 · Declare stages, activities and tasks

# stage_definitions.yaml
- definitionKey: triage
  label: "Triage"
  mandatoryActivities: [initialReview, policyVerification]
  possibleActivities:  [fraudScreening]
  activityOrchestrationRuleSet:
    name: TriageActivityOrchestration
    ruleType: ACTIVITY_ORCHESTRATION
  stageCompletionRuleSet:
    name: TriageMilestone
    ruleType: MILESTONE_ACHIEVED

# activity_definitions.yaml
- definitionKey: initialReview
  label: "Initial Review"
  startTasks: [reviewClaimForm]
  activityCompletionRuleSet:
    name: InitialReviewComplete
    ruleType: COMPLETE_ACTIVITY
  tasks:
    - definitionKey: reviewClaimForm
      taskType: HUMAN
      screenId: claim-review-screen
      clarificationsEnabled: true
      allocationStrategy:
        assignment:
          - allocationStrategyIdentifier: ROLE_BRANCH_CLAIM
            data: { roles: [claims_reviewer] }
      taskActions:
        primaryReadActionName: readClaimDetails
        allowedActionNames:   [readClaimDetails, updateReviewNotes, approveTriage]
        mandatoryActionNames: [approveTriage]
      taskMovement:
        nextTask: [assignAdjuster]

3 · Declare the data model

# claims-schema.graphqls
extend type CustomerApplicationData {
  claimNumber:     String
  policyNumber:    String
  claimType:       String
  incidentDate:    String
  claimAmount:     Float
  claimantDetails: ClaimantDetails
}

type ClaimantDetails {
  name:          String
  contactNumber: String
  address:       String
}

input UpdateClaimDetailsInput {
  claimType:   String @MappedTo(field: "$.customerApplicationData.claimType")
  claimAmount: Float  @MappedTo(field: "$.customerApplicationData.claimAmount")
              @Min(value: 0, message: "Claim amount cannot be negative")
  reviewNotes: String @MappedTo(field: "$.applicationDecisioningData.reviewNotes")
  reviewedBy:  String @ValueFrom(fromContext: "user.userId")
  reviewedAt:  String @CurrentTimestamp
}

4 · Write the business rules

// TriageActivityOrchestration.groovy
class TriageActivityOrchestration implements ActivityOrchestrationRuleExecutionTrait {

    boolean validateInput() { return ruleInput.applicationData != null }

    void ruleImplementation() {
        def amount = ruleInput.applicationData?.claimAmount ?: 0

        if (amount > 50000) {
            ruleOutput.nextActivities.add("detailedInvestigation")
        } else {
            ruleOutput.nextActivities.add("fastTrackAdjudication")
        }
    }
}

5 · Configure the UI

// action config for the reviewClaimForm task
export const reviewClaimActions = [
  {
    label: "Approve Triage",
    actionType: "popup",
    endpoint: "/api/actions/{flow}/{applicationId}/task/{taskId}/approveTriage",
    form: [
      { name: "reviewNotes", type: "textarea", label: "Review Notes", required: true }
    ],
    successMessage: "Triage approved successfully"
  }
]

6 · Register the flow and its access

# flow-uam-mapping.yaml — registers the flow with the platform catalog
- flowKey: insurance-claims
  productName: motor-insurance
  organizationName: insurer-realm
  host:
    dataLayer:   http://data-layer-service
    workflow:    http://workflow-service
    ruleService: http://rule-service

# stage_role_definitions.yaml — what each role may do, per stage
- stage: triage
  role:  claims_reviewer
  visibleTasks: [reviewClaimForm]
  topLevelActions:
    - { name: cancelClaim,   type: global }
    - { name: approveTriage, type: task, taskKey: reviewClaimForm }
  readAction:  readClaimDetails
  writeAction: updateClaimDetails

Process constructs#

Process constructs describe structure. They are loaded from the workflow configuration domain and validated at load time. Each carries a definitionKey that is unique within its type and is how every other construct refers to it.

BaseDefinition#

Base type for FlowDefinition, StageDefinition, ActivityDefinition, TaskDefinition, StageRoleDefinition, StatusDefinition

FlowDefinition#

extends BaseDefinition · flow_definitions.yaml

The root of a business process. Owns the ordered stage list, the initiation mutation, and flow-wide defaults.

StageDefinition#

extends BaseDefinition · stage_definitions.yaml

A major lifecycle phase. A stage is entered in the order given by FlowDefinition.stages, gated by its start rule, and closes when its completion rule signals the milestone is achieved.

ActivityDefinition#

extends BaseDefinition · activity_definitions.yaml

A logical group of related tasks. Activities are started by activity orchestration, never by a hard-coded list on the stage.

TaskDefinition#

extends BaseDefinition · declared inline on an activity or in task_definitions.yaml

A single unit of work. Everything about how a piece of work is performed — who does it, what they may do, what happens next, whether it calls an external system — hangs off the task.

Task sub-constructs#

TaskType (enum)

TaskActionsDefinition

TaskMovementDefinition

BusinessRuleSet

The registration record for a rule inside a definition. Wherever a construct says "rule set", this is the shape.

AutomatedTaskRuleSet

Extends BusinessRuleSet with no additional fields — it exists as a distinct type so an AUTOMATED task's rule binding is unambiguous. All five properties above apply; ruleType is typically AUTOMATED, TASK_ORCHESTRATION or SCRIPT.

ActivityTaskReference

StatusDefinition#

extends BaseDefinition

Declares an application status a case can hold, and whether reaching it ends the case.

Control flow#

This is the authoritative model for what starts what. Control flow happens at three levels — stage progression, activity orchestration and task orchestration — plus a set of triggers that can start work out-of-band.

Flow initiation#

Nothing runs until a flow is initiated. A flow instance is created by calling the initiate API with an initiation body:

On success the engine persists the initial application (applying initiateFlowMutation and setting initialStatus) and starts the first stage — the first entry in the flow's ordered stages list. That stage's own startStageRuleSet still applies. Starting the first stage is what kicks off the entire lifecycle.

Stage progression#

Stage order is static: it is the index order of FlowDefinition.stages. Rules cannot reorder stages; they can only decide whether a stage runs.

• When the engine advances, it takes the next key from stages.
• The stage starts only if its startStageRuleSet returns startStage: true.
• A stage with no start rule set always starts. A stage with one is conditional and therefore skippable — if it returns false, the engine cascades to the next stage in the list.

Stages listed in FlowDefinition.sideStages run alongside the main sequence in parallel and do not block it.

Activity orchestration#

An activity is started only by an activity-orchestration rule set. There is no hard-coded "next activity" list anywhere in the model. The rule decides which activity or activities start next.

Precedence: the stage-level rule always wins. mandatoryActivities and possibleActivities on the stage describe what may run and what must complete for the stage to close — they do not themselves start anything.

Task orchestration#

Entering an activity

When an activity starts, its entry-point tasks begin. An activity declares them one of two ways:

• startTasks — the explicit list of tasks entered when the activity starts.
• activityStartRuleSet — a START_ACTIVITY rule that computes the task set at runtime, returning tasksToStart.

Task-to-task progression

When a task completes and the activity is not yet complete, the next task inside the same activity is chosen. Three mechanisms are consulted in strict priority order — the first one configured wins:

The completion cascade#

Every time a task completes, the engine walks up the hierarchy before deciding what runs next.

task completes
  │
  ├─▶ 1. Evaluate Activity.activityCompletionRuleSet
  │        false → activity still running
  │                → start the NEXT TASK (priority order in §Task orchestration)
  │        true  → activity complete, continue ↓
  │
  ├─▶ 2. Evaluate StageDefinition.stageCompletionRuleSet
  │        false → stage still running
  │                → ACTIVITY ORCHESTRATION picks the next activity
  │                  (stage-level rule takes precedence over flow-level)
  │        true  → stage complete, continue ↓
  │
  └─▶ 3. Advance to the next stage in FlowDefinition.stages
           → gated by that stage's startStageRuleSet
           → false: skip it and cascade to the stage after it

In one sentence: activity-completion check → (if complete) stage-completion check → (if stage complete) next stage from the ordered list, gated by its start rule → (else) next activity via orchestration → (else) next task.

Out-of-band triggers#

Beyond the cascade, work can be started by three families of triggers.

Field cheat sheet#

Referenced-but-undefined targets

If a construct references a task or activity that is not defined in the flow — for example a MOVE_ACTIVITY action pointing at a non-existent activity — the target is still recorded in the flow graph as a thin node marked referencedOnly, and the referencing edge is kept. These are genuine configuration defects and are surfaced by flow analysis tooling rather than silently dropped.

The Action model#

An Action is an operation performed in the context of a task or a stage. Actions are the platform's only data boundary: reading, writing, calling an external system, moving the workflow and touching documents are all actions, dispatched polymorphically by actionType.

Action (base)

ActionType#

WorkflowActionType#

Applies to actions of type WORKFLOW.

Action subtypes#

Each subtype fixes its actionType and adds its own payload on top of the base fields.

ActionContext

Every action executes inside a context that rides along to rules, mutations and the audit trail.

Rules#

Business logic in Ontologica lives in rule sets — Groovy classes grouped by rule type. The rule type is the contract: it fixes when the engine invokes the rule and which response object the rule must return. Rules are hot-reloadable; they can be updated at runtime without restarting the platform.

The 16 rule types#

Execution contract#

Every rule follows the same template-method lifecycle. The engine owns the lifecycle; the script supplies exactly one decision.

1. A rule set is a Groovy class implementing the trait for its type — ScriptExecutionTrait, AssignmentExecutionTrait, ActivityOrchestrationRuleExecutionTrait, and so on.
2. BusinessRuleSet.ruleType selects the executor. Each type resolves to a rule executor and a rules subfolder — SCRIPT → script, START_STAGE → stage, and so forth.
3. Execution: load the pre-compiled class → instantiate → inject ruleInput, ruleOutput, uamService and masterService → call execute() → return the mutated ruleOutput as the response.
4. Rule files resolve to {rules.path}/{flowKey}/{subfolder}/{ruleName}.groovy. Rules may extend other rules, which is how a tenant variant overrides a base rule.

The execution context — ruleInput

Every rule type receives the same uniform context, so logic is portable across flows.

Injected services

Script rules#

The SCRIPT type is the general-purpose rule. It is what runs behind allocation scripts, and anywhere a flow needs to compute values, call platform services, or start tasks imperatively.

A script rule implements ScriptExecutionTrait and defines two methods:

• ruleImplementation() — the body, containing the actual logic.
• boolean validateInput() — a precondition. Returning false causes execute() to throw IllegalArgumentException("Invalid input").

class UpdateRiskLimit implements ScriptExecutionTrait {

    boolean validateInput() {
        return ruleInput.applicationData?.loan?.amount != null
    }

    void ruleImplementation() {
        def amount = ruleInput.applicationData.loan.amount as BigDecimal
        def band   = masterService.fetchMastersDataBySlug("risk-bands")

        def match = band.find { amount >= it.min && amount <= it.max }
        if (!match) {
            ruleOutput.success      = false
            ruleOutput.errorMessage = "No risk band configured for amount ${amount}"
            return
        }

        ruleOutput.applicationDataMap = [ riskBand: match.code, riskLimit: match.limit ]
        if (match.code == "HIGH") {
            ruleOutput.tasksToStart = ["seniorRiskReview"]
        }
        ruleOutput.success = true
    }
}

// A tenant variant simply extends the baseline rule:
class UpdateRiskLimitMg extends UpdateRiskLimit { /* overrides */ }

Boundaries

A script rule can read all request, flow and application data, call the injected UAM and master services, mutate applicationDataMap, request tasksToStart, and set success / errorMessage. It cannot call arbitrary external services beyond those two injected clients, and there is no direct transactional or database write surface exposed to the script other than what those services provide. External calls belong in integrations.

Response reference#

Each rule type returns a strongly-typed response. The engine validates the shape; fields you do not set retain their initialised defaults.

AutomationRuleResponse AUTOMATED

ActivityOrchestrationRuleResponse ACTIVITY_ORCHESTRATION

ActivityStartRuleResponse START_ACTIVITY

ActivityCompletionRuleResponse COMPLETE_ACTIVITY

TaskOrchestrationRuleResponse TASK_ORCHESTRATION

StartStageRuleResponse START_STAGE

MilestoneAchievedRuleResponse MILESTONE_ACHIEVED

ActionPreConditionRuleResponse PRE_ACTION BUTTON_STATUS_CHECK

AssignmentRuleResponse ASSIGNMENT

StageRoleConfigRuleResponse STAGE_ROLE_CONFIG

IntegrationMapperRuleResponse INTEGRATION_MAPPER

AsyncInboundCallRuleResponse ASYNC_INBOUND_CALL_MAPPER

AllDocumentsViewRuleResponse ALL_DOCUMENTS_VIEW

ObjectTransformerRuleResponse OBJECT_TRANSFORMER

ScriptRuleResponse SCRIPT

Role access model#

There is no separate permission object in Ontologica. A role's access is exactly the set of Actions it may invoke in the current (stage, role) context, and every Action is the only way data moves.

role  ──►  action  (allowed for this stage+role, or on an assigned task)
                │
                ├─ ReadAction.queryString  ──►  data-layer query    ──►  data point (read)
                └─ WriteAction.mutations[] ──►  data-layer mutation ──►  data point (write)

A role acquires actions through exactly two mechanisms:

StageRoleDefinition#

extends BaseDefinition · stage_role_definitions.yaml · keyed by (stage, role)

TopLevelAction

At load time the platform validates that every task-typed top-level action names a real taskKey and that the action appears in that task's taskActions.allowedActionNames. Multi-complete actions are validated to be global-only.

How the effective configuration is resolved

1. Read the current user's roles from the identity service, scoped by organisation and product.
2. Select every StageRoleDefinition matching (currentStage, anyOfUserRoles).
3. Statically union their visibleTasks and topLevelActions, deduped by action name (first wins), and take the first non-null readAction, writeAction and overviewScreenId.
4. Dynamically, for each matched definition carrying a ruleSet, execute the STAGE_ROLE_CONFIG rule and union its returned lists into the effective configuration.

Global-action access is therefore the union of static and rule-returned top-level actions. The rule path is how a role gains an action conditionally — for example only when application data meets some threshold.

How access is enforced

Worked example

# stage_role_definitions.yaml
- stage: "Application"
  role:  "PM"
  visibleTasks: [ "applicationTask" ]
  topLevelActions:
    - { name: "cancelApplication",       type: "global" }
    - { name: "rejectApplication",       type: "global" }
    - { name: "getLegalAdvice",          type: "global" }
    - { name: "completeApplicationTask", type: "task", taskKey: "applicationTask" }
  readAction:  "readApplicationData"
  writeAction: "updateApplicationData"

A user holding role PM on stage Application:

• May invoke the three global actions — the validator finds each name in the effective topLevelActions.
• Gets their data through GlobalStageRoleRead, which runs readApplicationData; that ReadAction's queryString fetches the data point.
• May invoke completeApplicationTask only if the live applicationTask instance is assigned to them.

Allocation strategies#

Allocation decides who receives a task, and — separately — which users are offered when a task is reassigned.

Configuration#

TaskDefinition.allocationStrategy → AllocationStrategyDefinition

AssignmentAllocationDetails

ReassignmentAllocationDetails

Extends AssignmentAllocationDetails and adds one field:

Strategy identifiers#

Each identifier maps to a strategy implementation and a dispatch mode. There are exactly two modes: AUTO_ASSIGN (the system assigns a single user directly) and CLAIM (a pool of eligible users, one of whom claims the task).

Resolution order#

Assignment — a priority-ordered fallback chain

1. Try assignment[0]. If it returns a non-empty user list, use it and stop.
2. Only if it returns no user, try assignment[1], and so on.
3. Once a non-empty list is chosen: one user → assigned directly; many users → a claimable pool, unless roundRobin is set, in which case one user is picked round-robin per (flow, taskDefinitionKey, branch).

assignment is a fallback chain, not a union. Configuring three strategies does not pool their results together.

Reassignment

When someone reassigns a task from the support UI, the reassignment strategy (or assignment[0] when null) computes the candidate list. The current assignee is stripped out, and the remainder is what the reassigning user may pick from. The open flag then controls whether the chosen target must be in that list.

Allocation scripts

After the assignee is set — on both assignment and reassignment — each rule set named in scripts runs in order as an ordinary SCRIPT rule. It may read flow and application data, call the UAM and master services, write back to application data, and request tasks to start.

allocationStrategy:
  assignment:
    # 1st choice: the officer recorded on the case
    - allocationStrategyIdentifier: "SINGLE_VARIABLE_USER"
      data:
        action:   "getApplicationTaskUser"
        variable: "applicationDecisioningData.assignedVariableUsers.applicationTaskUser"
    # fallback: anyone with the CO role at the case's branch may claim it
    - allocationStrategyIdentifier: "ROLE_BRANCH_CLAIM"
      data:
        role: "CO"
  reassignment:
    allocationStrategyIdentifier: "ROLE_BRANCH_CLAIM"
    data: { roles: [ "CO", "BM" ] }
    open: false
  roundRobin: true
  scripts: [ "NotifyAssigneeScript" ]

Data layer#

Ontologica has no fixed business schema. Each flow declares its own data model in GraphQL; every instance is stored as JSONB in a small set of generic tables. Adding a field is a schema edit, not a code change.

The three data categories

These three appear together at runtime in an ApplicationDataHolder:

Directives#

Directives are schema annotations that drive storage, population, validation and encryption behaviour without code. This is what replaces a hand-written persistence layer.

Structural directives

Validation directives

The EncryptedString scalar

A custom scalar providing transparent field-level encryption. It encrypts on the way in and decrypts on the way out, so encryption never appears in flow or rule logic.

Because encryption is a scalar concern, validating the underlying plaintext requires @ValidatePlaintext rather than @Pattern.

GraphQL type and field shape

A directive itself declares name, the applicableOn locations it is valid in (FIELD_DEFINITION, INPUT_FIELD_DEFINITION, INPUT_OBJECT, ARGUMENT_DEFINITION, SCALAR), and its named arguments.

Queries and mutations#

Query

Mutation

Mutations are the only way application data changes, and they always travel with who / where / why metadata.

Mutation (shared model)

A WriteAction references mutations by this two-field record:

MutationContext

The context is what makes @ValueFrom(fromContext: …) and the audit trail possible without per-flow code.

UpdateResult

Storage models#

Three generic JSONB tables back every flow on the platform. Each is versioned for optimistic concurrency.

CustomerApplicationData

ApplicationDecisioningData

InternalActivityData

The write pipeline#

Directives apply in a fixed order on every write. Understanding this order is essential when a value appears to be validated before it is populated, or encrypted before it is validated.

Action (WriteAction) ─ invokes ─▶ Mutation(name, inputType)
   │
   ▼ GraphQL mutation on the per-flow schema
Directives apply, in order:
   1. populate   @ValueFrom · @CurrentTimestamp · @GenerateRandomId
   2. validate   @NotBlank · @Pattern · @Min · @Max
                 @DateTimeFormatter · @ValidatePlaintext
   3. encrypt    EncryptedString.parseValue
   4. place      @MappedTo · @Symmetric   (into the JSONPath location)
   │
   ▼ persisted to one of
CustomerApplicationData │ ApplicationDecisioningData │ InternalActivityData
                                                        (JSONB, version++)
   │
   ▼ emits
AuditLogValue  (full snapshot, version, modifiedBy, updateActivity, updateAction)
   │
   ▼ returns
UpdateResult   (status + new version numbers)

The mutation context — user, activity, task, role — rides along the entire way. That is what makes @ValueFrom(fromContext: …) and a complete audit trail possible without per-flow code.

Audit and runtime records#

AuditLogKey

AuditLogValue

The audit log is append-only and immutable, and is archived to object storage for compliance retention.

Runtime timeline records

The platform records processing metrics used by reporting and SLA tracking.

Reference data

Versioned lookup datasets — dropdown options, rate tables, configuration values — are managed centrally and consumed by forms (through @EnumData), by rules (through masterService) and by reports.

Lifecycle: a definition or dataset is edited as a draft, then published — which freezes a numbered version into the history tables and flips activeVersion. Datasets are identified by slug and resolved per language and region, with default as the neutral variant.

Identity and access constructs

Access is modelled as (user × role × territory) tuples, extended ad hoc through validated JSON attribute bags rather than schema changes.

Integrations#

External systems are reached through the Integration Broker — a configured, not coded, bridge. Supported transports are REST, SOAP, direct database queries, custom scripts, and asynchronous queues.

Configuring an integration is four steps: register the external system, define the API, write the input and output mapper rules, then reference the integration from a task or an EXTERNAL_API action.

Synchronous integration#

TaskDefinition.integrationDefinition → IntegrationDefinition

Asynchronous integration#

TaskDefinition.asyncIntegrationDefinition → AsyncIntegrationDefinition

An async integration makes an outbound call and then waits. The task stays live; a correlated callback resumes it.

InboundCallRuleSet

The inbound rule returns an AsyncInboundCallRuleResponse: the mapped data to write, optionally an actionName to invoke, and completeTask to decide whether the waiting task should now finish.

- definitionKey: creditBureauCheck
  taskType: ASYNC_INTEGRATION
  asyncIntegrationDefinition:
    outboundCallDefinition:
      integrationName: credit-bureau
      apiName:         soft-pull
      method:          POST
      sendAuth:        true
      inputMapperRule:  CreditBureauRequestMapper
      preIntegrationWriteAction: markBureauPullInProgress
    inboundCallRuleSet:
      ruleName:   CreditBureauCallbackMapper
      readAction: readApplicationData
    timeoutAutomatedTaskDefinitionKey: creditBureauTimeoutHandler
    allowedActionNames: [ cancelBureauPull ]

Documents#

A document in Ontologica is not a first-class column. It is a DocumentFolder object stored inside the application-data JSON at a configured path.

The data model

type DocumentFolder

type Document

The corresponding DocumentInput and DocumentFolderInput types carry relative @MappedTo paths ($.folderId, $.documents, $.fileName, …). They place fields within the folder object; the folder itself is anchored under application data at the document type's path.

How a document path resolves

A document is identified by its documentType, which is a dot-separated path into application data — pointing not at a scalar but at a folder container. On read the platform walks the path segment by segment; on write it reconstructs the nested object graph so the folder lands at exactly that path.

documentType: customerApplicationData.documents.kycDocuments.photoOfCustomer
                                │
                                ▼
resolves to a DocumentFolder data point at
$.customerApplicationData.documents.kycDocuments.photoOfCustomer

By convention the path is rooted under one of the three data categories. When a file is uploaded, the document-store webhook writes a folder object — folderId plus a list of {documentId, fileName, fileType} — back through the standard document-details write action.

Document actions#

DocEvalAction

Per-document configuration

AllDocumentsViewAction and the document tree

Each tree node:

labelPath — data-driven labels

labelPath points at a second data point whose value becomes the node's label. A folder node keyed mortgage_1 can carry labelPath: customerApplicationData.collateralDetails.mortgage.mortgage_1.collateralLabel, so the user sees the real collateral description rather than a generic "Mortgage 1". dataPath works the same way but populates the node's data instead of its label.

Scopes#

There is no EVAL scope. "Evaluation" is an action type (DOC_EVAL), not a permission.

Wiring documents into a flow

# View action — renders the tree
- name: "allDocumentsView"
  actionType: "DOCUMENT_MANAGEMENT_VIEW"
  readAction: "readApplicationData"
  ruleSet:    "AllDocumentsView"
  config:
    - label: "{{workflowconfig.CUSTOMER}}"
      type: "FOLDER"
      children:
        - label: "{{workflowconfig.PHOTO_OF_CUSTOMER}}"
          type: "DOCUMENT"
          dataPath: "customerApplicationData.documents.kycDocuments.photoOfCustomer"
          metadata:
            singleFileUpload: true
            uploadConfig: { pathVariable: { uploadEndpoint: uploadDocument } }

# Eval action — referenced by uploadEndpoint, owns the scopes
- name: "uploadDocument"
  actionType: "DOC_EVAL"
  defaultScope: [ "VIEW", "UPLOAD", "UPDATE", "DELETE", "DOWNLOAD" ]
  documents:
    - documentType: "customerApplicationData.documents.kycDocuments.photoOfCustomer"
      singleFileUpload: true
    - documentType: "customerApplicationData.collateralDetails.mortgage.mortgage_1.collateralPicture"
      singleFileUpload: false
      documentDataPath: "customerApplicationData.customerNumber"
      relevantDataPath: "customerApplicationData.collateralDetails.mortgage.mortgage_1.collateralIdentifier"

AI constructs#

Ontologica lets configurators attach language-model behaviour to a flow in two shapes: a Copilot that assists a human inside a human task, and an AI Agent Task that replaces the human entirely. Both share the same configuration surface; the agent adds objective-driven autonomy.

Copilot

A Copilot is bound to a single human task (HUMAN or EXTERNAL_USER_HUMAN). It shares that task's data context — flow instance, current form draft, attached documents — and operates on the user's behalf within explicit limits.

AI Agent Task

An agent task is a Task of type AGENTIC, a peer to AUTOMATED and INTEGRATION. It is fully autonomous: no human is allocated, no form is rendered. Its configuration is the Copilot surface plus four objective-driven fields.

Tools#

Tools are the verbs available to the model. Each is a typed function with a schema; the runtime validates arguments before dispatch and writes an audit entry per call. Every tool also carries its own per-binding permission configuration — two copilots can share a tool definition with completely different blast radii.

tools:
  - read_data:
      fields: ["applicant.*", "loan.amount", "loan.purpose"]
  - call_action:
      actions: ["request-clarification", "flag-for-review"]
  - call_integration:
      apis: ["credit-bureau-soft-pull"]
      rateLimit: "10/min"
  - run_automated_activity:
      activities: ["fraud-screen-v3", "sanctions-screen-v2"]
  - run_subflow:
      flowKeys: ["customer-onboarding-mini"]
      maxConcurrent: 1

Skills and hooks#

Skills — capability contracts

A Skill is a reusable bundle giving a copilot a named competency without re-specifying it each time. A skill packages a prompt fragment, a required tool set, an action subset it expects to drive, optional few-shot examples, and skill-specific hooks. Skills compose: a copilot lists the skills it has, and the runtime stitches their prompt fragments and tool grants into the final session. Skills are versioned and live in the same configuration chain as every other construct.

Hooks — lifecycle interceptors

Hooks are the AI analogue of action pre-conditions. Each is a function attached at a named extension point, running inside the deterministic runtime — which makes hooks the right place to enforce hard policy. Prompt guardrails live in the model's head; hooks live in the platform's hands.

Layered enforcement#

Three permission layers stack. The narrowest wins, and a capability is permitted only when all three layers allow it.

A binding can never widen what the construct flags or catalog defaults deny.

Human Task ──┬── Form Definition          (existing)
             └── Copilot
                   ├── prompt + promptGuardrails
                   ├── allowedActions  ── references → Actions
                   ├── tools           ── bind to →   Mutations / Integrations / Subflows / Sandbox
                   ├── skills          ── references → Capability contracts
                   └── hooks           ── reuse →     Rules engine

AI Agent Task = Task(type=AGENTIC) + the same Copilot surface
              + mainObjective, successCriteria, terminationPolicy, escalation

Multi-tenancy and inheritance#

Constructs are organised into configuration domains — flow, data, rules, integration, UI and access. For multi-tenant deployments those configurations form an inheritance chain.

Product Baseline  (e.g. "loan-product")
    ├── Variant A  ("loan-product-nigeria")     — extends base, patches local rules
    ├── Variant B  ("loan-product-madagascar")  — extends base, patches local forms
    └── Variant C  ("loan-product-senegal")     — extends base, patches local workflows

Resolution at runtime follows a prototype-chain pattern: a variant's value wins, falling back to its baseline, recursively. At the flow-definition level this is expressed with $extends; rules inherit the same way, and a variant rule can literally extend the baseline rule class.

The practical consequence: define the base process once, create variants with minimal configuration, modify one variant without affecting others, and share improvements across all variants by updating the baseline.

Events#

Every action emits events that downstream systems consume. This is what makes the worklist, audit archive, analytics and notifications derived rather than bolted on.

User or agent action  (e.g. "Approve")
    ↓
Flow management  (executes the action, updates state)
    ↓ emits
Event stream
    ├──▶ Worklist        (updates the task list for all users)
    ├──▶ Audit archive   (long-term compliance storage)
    ├──▶ Reporting       (updates analytics dashboards)
    └──▶ Notifications   (email / SMS)

ActionEvent

Built-in capabilities#

Every flow gets these without configuration. Knowing what is already provided prevents rebuilding it in rules.

Naming conventions#

Ontologica deliberately reuses industry-standard vocabulary where it exists — Flow, Stage, Activity, Task, Action, Mutation, Field, Directive, Rule Set, Hook, Tool, Skill, Copilot — because a shared vocabulary is worth more than a bespoke one.

Principles

1. Prefer concrete user-facing terms over implementation terms. Case beats Flow Instance; Draft beats Partial Save Snapshot.
2. Avoid jargon that dates. Agentic is fashion; AI Agent positions the product without committing to the buzzword. Master data is dated; reference data is current.
3. Drop noise suffixes. Every construct is a definition, so Form Definition is just Form.
4. Do not reinvent industry-standard names. They come from elsewhere and the shared vocabulary is the benefit.
5. Names must describe the current job, not the historical one. Rename when purpose drifts.
6. Acronyms must earn their place.

Presentation names vs. configuration names

The following renames apply to user-facing surfaces only — UI labels, business documentation, support tooling. Internal and persistence names, YAML keys and code identifiers are unchanged, which is why both forms appear in this reference.

Key conventions

• Definition keys are the identity of every construct. They are referenced verbatim from other constructs and from rule code, so they should be stable, lowercase-camel, and meaningful without context — loanApprovalActivity, not activity3.
• Flow keys identify a specific flow variant, typically {product}-{market}.
• Rule names resolve to file paths. A rule named TriageMilestone of type MILESTONE_ACHIEVED lives under the flow's stage rules folder.
• Action names are the unit of access. Because they appear in allowedActionNames and topLevelActions, they should read as operations: approveTriage, rejectApplication, readClaimDetails.

Deprecations#

These fields still exist and still function. New configuration should use the replacement.

Corrections to earlier documentation

Construct index#

Glossary#