Operations Guide¶

The operations guide describes how to look after a running Egeria deployment: checking that the OMAG Server Platforms and their OMAG Servers are healthy, starting and stopping servers, loading new content, and running and tuning the connectors that do Egeria's work in the background.

It assumes the servers are already configured. Watching the deployment over time, tuning the infrastructure Egeria depends on (Apache Kafka and PostgreSQL) and routine maintenance such as backups are covered in the Monitoring and Tuning Guide. When something has gone wrong, turn to the Diagnostic Guide.

Ways to operate Egeria¶

When Egeria was first released, its REST APIs were the only way to control it. There are now four, and they all end up calling the same services, so you can mix them freely - for example, watching connector status in the portal while scripting a bulk change in Python.

flowchart LR
    portal["`**Egeria Operations**
    portal`"] --> vs
    hey["`**hey_egeria**
    commands`"] --> py
    nb["`**Jupyter
    notebooks**`"] --> py
    py["`**pyegeria**`"] --> vs
    rest["`**Your own tools**
    REST calls`"] --> vs
    subgraph platform ["OMAG Server Platform(s)"]
    vs["`**View Server**
    Runtime Manager
    Automated Curation
    Asset Maker`"] --> mas["Metadata Access Store"]
    vs --> id["Integration Daemon"]
    vs --> eh["Engine Host"]
    end

All four routes go through a view server, which looks up the catalog entries for the platforms and servers and makes the calls on your behalf. This means operators only need access to the view server, not to every platform in the deployment, and every request is subject to the same security checks. The older platform services calls described in REST APIs go directly to a platform and are mainly useful in scripts that check whether a platform has started.

Egeria Operations in the portal¶

Egeria Operations is the runtime control panel on Egeria's portal. Open it from its tile on the portal home page, or go directly to /egeria-operations on the portal's address. It shows the state of the runtime itself rather than the metadata it holds; for the catalog entries describing the same servers, use the Open in The Catalog button on a server's detail panel.

Figure 1: Tabs of Egeria Operations

Each tab has a Refresh button and an auto setting that refreshes the view at a chosen interval. The Catalog link on a detail panel opens the catalog entry for the same server, connector, engine or action in The Catalog.

hey_egeria commands¶

hey_egeria is the command line interface installed with pyegeria. Operational commands live under hey_egeria_ops (also reachable as hey_egeria ops) and come in two groups: show commands display information, and tell commands make changes. Many of the show commands are monitors: they redraw in place every few seconds until you press Ctrl-C, so they can be left running in a terminal window as a simple dashboard.

pip install pyegeria

The commands find the platform, servers and user from environment variables (such as EGERIA_VIEW_SERVER, EGERIA_VIEW_SERVER_URL, EGERIA_INTEGRATION_DAEMON and EGERIA_USER) or from options on the command line - run any command with --help to see them. hey_egeria tui opens a menu-driven builder that is the easiest way to discover the commands.

Figure 2: Building an operations command with hey_egeria tui

The full command reference, with a screenshot of each display, is in the hey_egeria documentation .

pyegeria scripts and Jupyter notebooks¶

pyegeria wraps Egeria's REST APIs in Python classes. The ones used for operations are:

A short script can check a server and refresh a connector:

from pyegeria import RuntimeManager

rm = RuntimeManager("qs-view-server", "https://localhost:9443", user_id="garygeeke", user_pwd="secret")
rm.create_egeria_bearer_token()

# How is the integration daemon doing?
print(rm.get_server_report(server_name="qs-integration-daemon"))

# Refresh one connector (omit connector_name to refresh them all)
rm.refresh_integration_connector(connector_name="MSSQLServerCataloguer",
                                 display_name="qs-integration-daemon")

rm.close_session()

Servers can be identified by server_guid, display_name or qualified_name, so scripts do not need to look up GUIDs first. Most report methods take an output_format ("JSON", "DICT", "MD", "TABLE" and others) so the same call can feed another program or produce a readable report.

The same code runs in a Jupyter notebook, which is a good way to capture an operational procedure: each step is explained in a markdown cell, and its live result appears underneath. The egeria-workspaces deployments include a Jupyter server with sample notebooks.

REST APIs¶

Every operation above is available as a REST call.

• The Runtime Manager view service covers platforms, servers, cohorts, archives, integration connectors and governance engines. Calls go to the view server, which forwards them to the right platform. Sample requests are in Egeria-api-runtime-manager.http .
• Asset Maker maintains the catalog targets and integration group registrations that drive the integration daemons.
• Automated Curation lists, starts and cancels engine actions.
• The platform services go directly to one platform. They need no view server, which makes them the right choice for start-up scripts that wait for a platform to come up. See Server Platform Origin Service, Starting and Stopping an OMAG Server and Adding an Archive to a Running Server.

All calls carry a bearer token obtained from the platform's token service:

###
# @name Token
POST {{baseURL}}/api/token
Content-Type: application/json

{
  "userId" : "garygeeke",
  "password" : "secret"
}

For example, this call activates a server from its stored configuration:

###
# @name activateWithStoredConfig
POST {{baseURL}}/servers/{{viewServer}}/api/open-metadata/runtime-manager/omag-servers/{{serverGUID}}/instance
Authorization: Bearer {{token}}

Operating servers¶

Running and tuning integration connectors¶

An integration daemon runs integration connectors that keep open metadata in step with third party technologies. What a daemon runs is not in its configuration document: the document names one or more integration groups, and the integration groups, connectors and their settings are held as open metadata in the metadata access store. So most tuning is done by changing metadata, and the daemon picks the change up while it runs.

flowchart LR
    ID["`**Integration Daemon**
    configured with
    integration group names`"] -.->|reads| IG
    IG["`**IntegrationGroup**`"] -->|"`**RegisteredIntegrationConnector**
    connectorName, refreshTimeInterval,
    startDate, stopDate,
    permittedSynchronization ...`"| IC["`**IntegrationConnector**`"]
    IC -->|ConnectionToAsset| CN["`**Connection**
    connector type,
    configurationProperties`"]
    IC -->|"`**CatalogTarget**
    catalogTargetName,
    configurationProperties,
    templates ...`"| A1["`**Asset**
    e.g. a database server`"]
    IC -->|CatalogTarget| A2["`**Asset**
    another database server`"]

Figure 4: The open metadata that controls an integration connector

Connector status¶

The integration daemon reports a status for each connector. This is what the portal, show integrations status and the server report display:

Here is the report for one connector from qs-integration-daemon:

{
  "connectorId": "0e29b0a8-0535-4be0-8941-f8ef2af3dc3b",
  "connectorName": "MSSQLServerCataloguer",
  "connectorInstanceId": "18425ffc-804d-4846-89df-d9f65da2a949",
  "connectorStatus": "WAITING",
  "lastStatusChange": "2026-11-10T11:11:28.623+00:00",
  "lastRefreshTime": "2026-11-10T11:11:28.623+00:00",
  "minMinutesBetweenRefresh": 60
}

Refresh and restart¶

Refresh calls the connector's refresh() method now, without waiting for the next scheduled refresh. Use it when you know something has changed in the third party technology. Restart disconnects the connector, builds a new instance and starts it - use it to recover a FAILED connector or to pick up a corrected connection. Both can be issued for one connector or for every connector in the daemon, from the portal, hey_egeria_ops tell integration-daemon refresh|restart, RuntimeManager.refresh_integration_connector() / restart_connector(), or POST .../integration-daemons/{serverGUID}/integration-connectors/refresh|restart.

Tuning the refresh interval¶

The refreshTimeInterval property on the RegisteredIntegrationConnector relationship sets the number of minutes between refreshes. The daemon checks each connector every second and calls refresh() once the interval has passed since the last refresh finished.

• 0 (the default) means the connector is refreshed once when it starts, and after that only when asked to - by a refresh request, or by a change to its configuration. This suits connectors that are driven by events (such as the OpenLineage and Kafka-based connectors) or that should only run on demand.
• A positive value suits connectors that poll the third party technology. Choose it from how quickly changes need to appear in open metadata and how much load each refresh puts on the technology: a full survey of a large database server every 5 minutes may cost more than it is worth, while a daily refresh may leave the catalog a day out of date.

Because the interval belongs to the registration, not the connector, the same connector definition can be registered in two integration groups with different intervals - for example, a frequent refresh in a development daemon and a nightly one in production.

Tuning catalog targets¶

A catalog target attaches one piece of technology - typically the asset for a server, database or folder - to a connector. One connector can have many catalog targets, and each one carries its own settings on the CatalogTarget relationship:

The configuration properties a connector understands are listed on its page in the connector catalog. Here is a catalog target being added through Asset Maker:

###
# @name addCatalogTarget
POST {{baseURL}}/servers/{{viewServer}}/api/open-metadata/asset-maker/integration-connectors/{{integrationConnectorGUID}}/catalog-targets/{{metadataElementGUID}}
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "class" : "NewRelationshipRequestBody",
  "properties": {
    "class": "CatalogTargetProperties",
    "catalogTargetName" : "postgreSQLDatabaseServer",
    "configurationProperties" : {
      "includeDatabaseList" : ["sales", "finance"]
    },
    "permittedSynchronization" : "FROM_THIRD_PARTY"
  }
}

The same change can be made with hey_egeria_ops tell integration-daemon add-target, with AssetMaker.add_catalog_target() in pyegeria, or with Dr.Egeria. update-target / update_catalog_target() change an existing target, and remove-target / remove_catalog_target() remove one.

When changes take effect¶

sequenceDiagram
    participant Op as Operator
    participant MAS as Metadata Access Store
    participant ID as Integration Daemon
    participant C as Integration Connector
    Op->>MAS: add/update CatalogTarget or RegisteredIntegrationConnector
    MAS-->>ID: change event (via the event bus)
    ID->>MAS: re-read the connector's registration
    alt connection or blocking-calls setting changed
        ID->>C: disconnect, build a new instance, start
    else anything else
        ID->>C: refresh()
        C->>MAS: read current catalog targets
        C->>C: start processors for new targets,<br/>restart changed ones, stop removed ones
    end

Figure 5: How a change to a connector's open metadata reaches the running connector

When Egeria has an event bus, the daemon hears about a change to a catalog target or registration within moments and refreshes the connector straight away. If a refresh is already in progress, the change is held until it finishes, so two instances of the connector never work on the same metadata at once. Without an event bus, the daemon re-reads each integration group's configuration roughly every half hour; issue a refresh to pick a change up sooner.

Operating governance engines¶

An engine host runs governance engines, whose definitions - like integration groups - are held in open metadata. Engines do their work as engine actions, which are created by people, by governance action processes and by other services.

An engine host normally picks up changes to its engine definitions by itself. Reloading the configuration is useful after the metadata access store has been unavailable, particularly while the engine host was starting.

Further information¶

• Monitoring and Tuning Guide - the audit log, Kafka and PostgreSQL, backups and housekeeping.
• Diagnostic Guide - finding out why something is not working.
• OMAG Server Runtime - running a single server in its own process.
• Administration Guide - creating and changing server configuration.

Raise an issue or comment below