Hanami ext folder

The ext folder contains configuration files and resources that define the behavior of the Hanami application. It has the following structure:

boot/: Contains Trig files (.trig) to be loaded into the internal triple store. Those are loaded only the first time Hanami is booted, unless backups are disabled (see hanami.backup.enabled in config/customer.yml) below.
collections/: Contains configuration for the various collections (see detailed section here).
collections/<collection‑id>/actions/: Contains YAML hook actions executed on item lifecycle events (detailed section here).
config/: Contains application‑wide YAML files → customer.yml, security.yml, profile overrides and the workflow actions configuration (see Workflow actions).
environment-changes/: Contains SPARQL queries (.sparql) to be run on the data in the boot folder before loading. These are mainly used to correctly configure the external RDF store for different environments. The hanami.customer.template-arguments property in customer.yml defines values to be templated in these queries.
operations/: Contains operations.json5 that defines the possible operations that are checked before allowing CRUD operations. This implements a role-based access control system and is only used for admin access in environments using WAC. This should not be edited.
config.json5: Contains configurations mostly related to access control.

`config/` folder

This folder centralises application‑wide YAML plus additional documentation:

File / pattern	Purpose
`customer.yml`	Customer‑specific settings (auth provider, language, Elasticsearch, etc.).
`security.yml`	User/role definitions and auth‑method (`basic`, `saml`, oauth – planned).
`application-<profile>.yml`	Spring profile overrides for dev/test/prod (merged at runtime).
`*-workflow.yml`	Recommended Workflow‑action bundles – see Workflow actions.

All files are merged by Spring’s property loader, so larger installations often split per domain such as for example customer-workflow.yml

`customer.yml`

This file contains customer-specific configuration.

hanami.authorization.provider: Specifies the authorization provider, either operations or wac.
hanami.elasticsearch.url: URL for Elasticsearch, typically referenced from environment variables.
hanami.lang.app: Application language settings:
- default-lang: Default language for the application UI (e.g., en).
- available-langs: List of available languages for the application UI (e.g., ['en', 'fr']).
- locale-mapping: Maps language codes to locale codes (e.g., fr → fr-BE).
hanami.lang.data: Data language settings:
- available-langs: List of available languages for data (e.g., ['en', 'fr']). This is used to give default possible languages for the hanami:LangStringEditor widget if no sh:languageIn is given. It is also used as the lits of languages used to try to match on labels when doing full text search.
hanami.prefixes: Namespace prefixes used throughout the application for RDF data, defining shorthand references to URIs (legacy config, will be removed in the future).
hanami.sync: Settings that allow Hanami to send synchronization events to a paired catalogue application.
- eventTransmission.enabled: When true, Hanami emits create/update/delete event payloads so the paired application can stay in sync.
- catalogue.baseUrl: Base URL of the REST endpoint exposed by the paired catalogue application.
- catalogue.username: Username used for HTTP Basic authentication when invoking the catalogue endpoint.
- catalogue.password: Password for HTTP Basic authentication. Prefix {noop} keeps it in plain text (suitable only for development); in production you should encode the password (e.g., {bcrypt}…) or store it in a secrets manager.
local.assets.folder: path to set a deep override of the UI asset folder. More on this here.

Example of a customer.yml file:

hanami:
  authorization:
    provider: operations # alternative: wac
  elasticsearch:
    url: ${env.hanami.elasticsearch.url}

  lang:
    app:
      default-lang: en
      available-langs:
        - en
        - fr
      locale-mapping:
        en: en-UK
        fr: fr-BE
    data:
      available-langs:
        - en
        - fr

  prefixes:
    dct: http://purl.org/dc/terms/
    hanami: https://hanami.app/ontology#
    owl: http://www.w3.org/2002/07/owl#
    prov: http://www.w3.org/ns/prov#
    rdf: http://www.w3.org/1999/02/22-rdf-syntax-ns#
    rdfs: http://www.w3.org/2000/01/rdf-schema#
    schema: http://schema.org/
    sh: http://www.w3.org/ns/shacl#
    skos: http://www.w3.org/2004/02/skos/core#
    vcard: http://www.w3.org/2006/vcard/ns#
    xsd: http://www.w3.org/2001/XMLSchema#

  sync:
    eventTransmission:
      enabled: true
    catalogue:
      baseUrl: "<ctalogue application hostname>"
      username: "<catalogue sync api user name>"
      password: "<catalogue sync api password>"

local:
  assets:
    folder: /opt/hanami/ext

`security.yml`

This file contains the security-related configuration and can have the given properties:

cognizone.security.auth-method: Authentication method, basic or saml. # TODO I suppose that oauth will come here?
cognizone.security.basic-auth: Basic authentication configuration:
- realm: Authentication realm message.
  - users: User definitions with:
    - password: Encrypted password (typically BCrypt format).
    - roles: List of roles assigned to the user (e.g., 'ADMIN', 'EDITOR').

Example of a security.yml file:

cognizone:
  security:
    auth-method: basic
    basic-auth:
      realm: Hanami is asking who you are
      users:
        admin:
          password: "{bcrypt} encrypted password"
          roles:
            - ADMIN
        editor:
          password: "{bcrypt} encrypted password"
          roles:
            - EDITOR

Profile-specific files

Profile-specific YAML files can also be included in the config/ folder, which may override settings in the base configuration files for different deployment environments. These files follow the naming convention application-{profile}.yml and are loaded based on the active Spring profile.

Profile-specific files can:

Override settings from base configuration files
Provide environment-specific configurations
Split configuration into logical sections for better maintainability

Common configurations in profile-specific files include:

env: Environment-specific variables and settings, used to be references in other files to make references to. Can contain anything.
hanami.index: Indexing configuration
- full-node-indexing.enabled: Whether full node indexing is enabled or not (should be true for newer installations)
- startup.workspaces: Whether to index workspaces at startup
- startup.collections: Whether to index collections at startup
hanami.features: Feature toggles for the environment
- validation.enabled: Whether validation features are enabled
- actions.enabled: Whether action features are enabled
hanami.backup: Backup configuration
- enabled: Whether backups are enabled
- backup-rate-ms: Backup frequency in milliseconds
- backup-delay-ms: Delay before first backup in milliseconds
- clean-rate-ms: Cleanup frequency in milliseconds
- clean-delay-ms: Delay before first cleanup in milliseconds
hanami.customer.template-arguments: Environment-specific template arguments. Typically a map of strings for variable to be used in templated sparql queries.
info.app.environmentName: Human-readable name for the environment, displayed in the top-right part of the UI.

Example of a profile-specific file structure:

env: # can contain anything
  cognizone:
    security:
      auth-method: basic
  hanami:
    id: hanami-dev
    elasticsearch:
      url: http://elasticsearch-dev-exmple:9200/

hanami:
  index:
    full-node-indexing:
      enabled: true
    startup:
      workspaces: true
      collections: true
  features:
    validation:
      enabled: true
    actions:
      enabled: true
  customer:
    template-arguments:
      rdfStore: http://rdf-store-dev-example:8890/sparql
      rdfStoreUser: <trplestore user>
      rdfStorePassword: <triplestore password>
      serviceAHost: http://localhost:8080
      serviceAAuthHeaders: Basic <base 64 encoded credentials>

info:
  app:
    environmentName: Development Environment

For better maintainability, profile-specific configurations can be split across multiple files (e.g., application-profile1.yml, application-profile2.yml, application-profile3.yml), which will be combined when the corresponding profiles are active.

`config.json5`

This file contains configurations that should eventually move to RDF in the admin workspace. It primarily defines security-related settings and access control for different parts of the application. In details:

security.collections: Maps CRUD keywords in the application to their corresponding operations to be checked for authorization.
security.endpoints: Defines role-based access control for specific API endpoints.
security.workspaces: Defines which workspaces are accessible to users with specific roles.
security.isDefaultAllowed: A boolean flag that determines whether users can access collections that are not explicitly configured in the access control settings.

Hanami ext folder

config/ folder​

customer.yml​

security.yml​

Profile-specific files​

config.json5​

`config/` folder

`customer.yml`

`security.yml`

Profile-specific files

`config.json5`