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

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.