App Configuration Model

The h_app.yaml file defines the contents of a Hantera app. It specifies which resources are included in the package and how they are linked together.

An app manifest typically declares:

• A unique app identifier
• Portal extensions
• Components
• Ingress definitions
• App settings
• Registry entries
• Job definitions
• Declared dependencies (requires) on other apps' graph shape and Filtrera modules — see Declaring App Dependencies and the Requires section below

id: hantera-test-app
name: Hantera Test App
description: Minimal example app showing HTTP ingress → reactor component → actor command, plus settings, registry entries, and a job definition.
authors:
  - Hantera

extensions:
  portal: ./portal

components:
  # Reactor component used by the HTTP ingress
  - id: components/orders.hrc

  # Reactor component used as a scheduled job target
  - id: components/hantera-test-app-order-processing.hrc

  # Example rule component 
  # - id: rules/cart-to-order.hrl

  # Example discount component 
  # - id: discounts/order-discount.hrd

ingresses:
  - id: orders
    componentId: components/orders.hrc
    type: http
    acl:
      - actors/order:create
      # If the component reads app settings from registry, grant it explicitly
      - registry/apps/hantera-test-app/settings/webhookSecret:read
    properties:
      route: hantera-test-app/orders
      httpMethod: POST
      body:
        mode: structured
      isPublic: true

registryEntries:
  # Example: extend the graph model with a field definition
  - path: /graph/order/fields/externalReference
    value:
      type: text
      source: dynamic->'externalReference'


jobDefinitions:
  - id: hantera-test-app-order-processing
    componentId: components/hantera-test-app-order-processing.hrc

settings:
  webhookSecret:
    label:
      default: Webhook secret
    description:
      default: Shared secret used to authenticate incoming webhook requests.
    secret: true

Each top-level field corresponds to a resource declaration or app-level configuration.

App ID

The id uniquely identifies the app resource and scopes app settings in Hantera.

Example:

id: hantera-test-app

App settings are stored under:

apps/hantera-test-app/settings/`<settingName>`

Portal Extensions

The extensions.portal field references a directory that will be bundled into the app package.

extensions:
  portal: ./portal

If defined, the portal extension directory is bundled and registered when the app is installed. Portal extensions are optional. Without one, the app can still execute backend logic and modify system state.

See the Portal Extension documentation for implementation details.

Components

The components field references component files included in the app.

components:
  - id: components/webhooks/orders.hrc
  - id: rules/cart-to-order.hrl

Each entry points to a Filtrera component file that will be packaged and registered during installation

See:

• Reactor
• Rules
• Discounts

Ingresses

The ingresses field declares transport bindings for components. Example:

ingresses:
  - id: orders
    componentId: components/webhooks/orders.hrc
    type: http
    acl:
      - actors/order:create
    properties:
      route: hantera-test-app/orders
      httpMethod: POST
      body:
        mode: structured

Each ingress:

• References a component via componentId
• Declares transport type (http, etc.)
• Defines an ACL
• Specifies transport properties

See the Ingress documentation for full specification details.

Registry

The registryEntries field declares registry paths that will be created or updated at installation time.

registryEntries:
  - path: /graph/ticket.cart/fields/email
    value:
      type: text
      source: dynamic->'email'

Each entry defines:

• A registry path
• A value payload

Registry semantics are defined in the Registry documentation.

Jobs Definitions

Apps can include jobDefinitions fields that reference components and make them schedulable for execution.

jobDefinitions:
  - id: hantera-test-app-order-processing
    componentId: components/hantera-test-app-order-processing.hrc

Job definitions and their executions are managed through:

• /resources/job-definitions
• /resources/jobs

For the full model, examples, scheduling, retention, and monitoring, see the Job definitions and Jobs documentation.

App Settings

The settings field declares configurable values exposed in the Portal UI.

Example:

settings:
  webhookSecret:
    label:
      default: Webhook secret
    secret: true

When installed, this creates a configuration field in the Portal UI.

The value is stored in the registry under:

apps/`<appId>`/settings/`<settingName>`

Components may read these values if granted appropriate permissions.

registry->'apps/hantera-test-app/settings/webhookSecret'

If secret: true, users cannot read it from the UI, but components can access it if granted ACL permission.

Requires

The requires section declares the graph shape and Filtrera modules an app depends on from other apps. For conceptual guidance and workflow, see Declaring App Dependencies.

Top-level structure

requires:
  graph: <RequiresGraph>      # optional
  modules: <RequiresModules>  # optional

Field	Type	Required	Description
graph	RequiresGraph	No	Graph contract: nodes, fields, edges, and sets the app reads.
modules	RequiresModules	No	Module contract: Filtrera modules the app imports.

Omitting requires means the app depends only on base graph shape and modules shipped in its own package.

requires.graph

requires:
  graph:
    nodes:
      <nodeId>: <RequiresGraphNode>
    sets:
      <setName>: <RequiresGraphSet>

Field	Type	Required	Description
nodes	Map<string, RequiresGraphNode>	No	Keyed by node id (asset.product, order, etc)
sets	Map<string, RequiresGraphSet>	No	Keyed by top-level set names used in queries

RequiresGraphNode

<nodeId>:
  fields:
    <fieldName>: <RequiresGraphField>
  edges:
    <edgeName>: <RequiresGraphEdge>

Field	Type	Required	Description
fields	Map<string, RequiresGraphField>	No	Fields the app reads from the node
edges	Map<string, RequiresGraphEdge>	No	Edges the app traverses from the node

RequiresGraphField

<fieldName>:
  type: <GraphFieldType>
  dimension: <dimensionName>   # optional
  enumDefinition: <enumId>     # optional

Field	Type	Required	Description
type	Graph field type	Yes	One of: text, enum, number, instant, [text], [enum]
dimension	string	No	Required dimension, for example locale
enumDefinition	string	No	Enum definition id; valid only when type is enum or [enum]

RequiresGraphEdge

<edgeName>:
  cardinality: single | many
  relatedNode: <nodeId>

Field	Type	Required	Description
cardinality	single | many	Yes	Whether traversal yields one node or many
relatedNode	Node id	Yes	Target node id, resolvable in the composite context

RequiresGraphSet

<setName>:
  node: <nodeId>

Field	Type	Required	Description
node	Node id	Yes	Node bound to this top-level set name

requires.modules

requires:
  modules:
    <modulePath>: <RequiresModule>

The map key is the path portion of component:// URI. For component://apps/products/price-lookup.module.hrc, the key is /apps/products/price-lookup.module.hrc.

RequiresModule

<modulePath>:
  exports:
    <exportName>: <RequiresModuleExport>

Field	Type	Required	Description
exports	Map<string, RequiresModuleExport>	No	Exports the app references; unused exports omitted

RequiresModuleExport

<exportName>:
  type: <FiltreraTypeString>

Field	Type	Required	Description
type	Filtrera type string	Yes	Consumer-declared expected export type

Manifest-level validation

CLI and server reject invalid requires declarations, including:

• requires.modules key resolves to a local module in this same app.
• requires.graph field/edge overlaps with graph contributions this app already provides via registryEntries.
• requires.graph field type is outside the supported graph field type set.
• requires.modules export type strings are not parseable Filtrera types.
• relatedNode references a node not resolvable in the composite context.

At activation, consumer components compile against real producer source from active apps. If declared and real module export types diverge, standard Filtrera type diagnostics are produced.