Skip to content

Configuring a Data Engine Proxy Server

Overview

Each type of OMAG Server is configured by creating a configuration document.

For data engine proxy server, followng can be configured:

Configuration for an data engine proxy server

What are the required configuration elements for this server type?
  • Audit Log Destination
  • Local In-Memory Repository
  • Data Engine Proxy Config

Set the server URL root

Configure the local server URL root with the value of the OMAG Server Platform where the service will run: in particular if the configuration document will be deployed to a different OMAG Server Platform from the one used to maintain the configuration document.

POST - set server URL root

{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/server-url-root?url={{targetPlatformURLRoot}}
Detailed explanation

The {{targetPlatformURLRoot}} gives the location of the OMAG Server Platform on which this configured service is intended to run, while the {{platformURLRoot}} gives the location of the OMAG Server Platform in which this configuration document is maintained.

They could be, but do not need to be, the same location.

Configure the basic properties

The basic properties of the OMAG Server are used in logging and events originating from the server. They help to document the purpose of the server (which helps with problem determination) and enable performance improvements by allowing the server to ignore activity or metadata that is not relevant to its operation.

The basic properties include two unique identifiers:

Property Description
localServerId Unique identifier for this server. By default, this is initialized to a randomly generated Universal Unique identifier (UUID).
localServerName Meaningful name for the server for use in messages and UIs. Ideally this value is unique to aid administrators in understanding the source of messages and events from the server. This value is set to the server name assigned when the configuration is created.

The other basic properties have values that can be changed through the admin services API:

Property Description
localServerType Descriptive type name for the server. Again this is useful information for the administrator to understand the role of the server. The default value is Open Metadata and Governance Server.
organizationName Descriptive name for the organization that owns the local server/repository. This is useful when the open metadata repository cluster consists of metadata servers from different organizations, or different departments of an enterprise. The default value is null.
localServerUserId UserId to use for server-initiated REST calls. The default is OMAGServer.
localServerPassword Password to use for server-initiated REST calls. The default is null. This means that only the userId is sent in the HTTP header.
maxPageSize The maximum page size that can be set on requests to the server. The default value is 1000. A value of zero means unlimited page size. Although supported, the zero value is not recommended because it provides no protection from a large request denial of service attack.

The sections that follow cover how to set up these values.

Set server type name

The server type name should be set to something that describes the OMAG Server's role. It may be the name of a specific product that it is enabling, or a role in the metadata and governance landscape.

POST - set server type

{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/server-type?typeName="{{serverTypeName}}"

Set organization name

The organization name may be the owning organization or department or team supported by the server.

POST - set organization name

{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/organization-name?name="{{organizationName}}"

Set the server's userId and optional password

The server's userId is used when processing requests that do not have an end user, such as receiving an event from a topic. The default value is OMAGServer. Ideally each server should have its own user ID so it is possible to restrict the resources that each server has access to.

If the password is specified as well, the userId and password combination are used to provide authentication information on each REST call made by the server.

POST - set server's userId

{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/server-user-id?id="{{serverUserId}}"

POST - set server's password

{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/server-user-password?password="{{serverUserPassword}}"

Set the maximum page size for REST API requests

The maximum page size value sets an upper limit on the number of results that a caller can request on any paging REST API to this server. Setting maximum page size helps to prevent a denial of service attack that uses very large requests to overwhelm the server. A value of 0 means no limit, and leaves the server open to such attacks.

POST - set maximum page size

{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/max-page-size?limit={{maxPageSize}}

Configure the audit log

Egeria's audit log provides a configurable set of destinations for audit records and other diagnostic logging for an OMAG Server. Some destinations also support a query interface to allow an administrator to understand how the server is running.

If the server is a development or test server, then the default audit log configuration is probably sufficient: the console audit log destination.

POST - set default audit log destination

{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/audit-log-destinations/default

Using this option overrides all previous audit log destinations.

If this server is a production server then you will probably want to set up the audit log destinations explicitly. You can add multiple destinations and each one can be set up to process specific severities of log records. The audit log severities are as follows:

Severity Description
Information The server is providing information about its normal operation.
Event An event was received from another member of the open metadata repository cohort.
Decision A decision has been made related to the interaction of the local metadata repository and the rest of the cohort.
Action An Action is required by the administrator. At a minimum, the situation needs to be investigated and if necessary, corrective action taken.
Error An error occurred, possibly caused by an incompatibility between the local metadata repository and one of the remote repositories. The local repository may restrict some of the metadata interchange functions as a result.
Exception An unexpected exception occurred. This means that the server needs some administration attention to correct configuration or fix a logic error because it is not operating as a proper peer in the open metadata repository cohort.
Security Unauthorized access to a service or metadata instance has been attempted.
Startup A new component is starting up.
Shutdown An existing component is shutting down.
Asset An auditable action relating to an asset has been taken.
Types Activity is occurring that relates to the open metadata types in use by this server.
Cohort The server is exchanging registration information about an open metadata repository cohort that it is connecting to.
Trace This is additional information on the operation of the server that may be of assistance in debugging a problem. It is not normally logged to any destination, but can be added when needed.
PerfMon This log record contains performance monitoring timing information for specific types of processing. It is not normally logged to any destination, but can be added when needed.
<Unknown> Uninitialized Severity

The body of the request should be a list of severities

If an empty list is passed as the request body then all severities are supported by the destination.

Add audit log destinations

There are various destinations that can be configured for the audit log:

POST - add console audit log destination

This writes selected parts of each audit log record to stdout.

{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/audit-log-destinations/console

POST - add slf4j audit log destination

This writes full log records to the slf4j ecosystem.

{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/audit-log-destinations/slf4j

When configuring slf4j as destination you also need to specify auditlog logger category via the application properties. This is described in Connecting the OMAG Audit Log Framework section of the developer logging guide.

POST - add JSON file-based audit log destination

This writes JSON files in a shared directory.

{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/audit-log-destinations/files

POST - add event-based audit log destination

This writes each log record as an event on the supplied event topic. It assumes that the event bus is set up first.

{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/audit-log-destinations/event-topic

POST - add connection-based audit log destination

This sets up an audit log destination that is described though a connection. In this case, the connection is passed in the request body and the supported severities can be supplied in the connection's configuration properties.

{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/audit-log-destinations/connection

POST - add a list of connection-based audit log destinations

It is also possible to set up the audit log destinations as a list of connections. Using this option overrides all previous audit log destinations.

{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/audit-log-destinations

Remove audit logs

The following will remove all audit log destinations:

POST - clear all audit log destinations

Clears the list of audit log destinations from the configuration enabling you to add a new set of audit log destinations.

{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/audit-log-destinations/none

For the next step it is important to configure in-memory repository type

Since Data Engine Proxy is a stateless service, it only relies on in-memory repository to operate. The sync state (last sync date) is stored in the external system and managed by the connector.

Configure the local repository

A metadata server supports a local metadata repository that has native support for the Open Metadata Repository Services (OMRS) types and instances.

Choose a repository

Egeria provides a number of implementations of such a repository -- only one of these options can be configured for a given metadata server at a time.

This command enables a XTDB-based metadata repository, which itself has a number of pluggable back-end options for persistence and other configuration options.

This plugin repository is currently the highest-performing, most fully-functional repository for Egeria, supporting all metadata operations including historical metadata as well as being highly-available through clustered deployment.

POST - enable the bi-temporal graph repository

{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/local-repository/mode/plugin-repository/connection
{
  "class": "Connection",
  "connectorType": {
    "class": "ConnectorType",
    "connectorProviderClassName": "org.odpi.egeria.connectors.juxt.xtdb.repositoryconnector.XtdbOMRSRepositoryConnectorProvider"
  }
}

May require additional driver libraries

Note that depending on the persistence you configure, you may need to obtain additional driver libraries for your back-end service, as not every driver is embedded in the XTDB connector itself.

This command enables a JanusGraph-based metadata repository that is embedded in the metadata server and uses the local disk to store the metadata, but does not manage any historical metadata.

POST - enable the graph repository

{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/local-repository/mode/local-graph-repository

The in-memory repository maintains an in-memory store of metadata. It is useful for demos and testing. No metadata is kept if the open metadata services are deactivated, or the server is shutdown. It should nto be used in a production environment.

POST - enable the in-memory repository

{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/local-repository/mode/in-memory-repository

The read-only repository connector provides a compliant implementation of a local repository that can be configured into a metadata server. It does not support the interfaces for create, update, delete. However, it does support the search interfaces and is able to cache metadata.

This means it can be loaded with metadata from an open metadata archive and connected to a cohort. The content from the archive will be shared with other members of the cohort.

POST - enable the read-only repository

{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/local-repository/mode/read-only-repository

Remove the local repository

This command removes all configuration for the local repository. This includes the local metadata collection id. If a new local repository is added, it will have a new local metadata collection id and will not be able to automatically re-register with its cohort(s).

DELETE - remove the local repository

{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/local-repository

Configuring Date Engine Proxy Services

POST - Configure Date Engine Proxy Services

{{serverURLRoot}}/open-metadata/admin-services/users/{{userId}}/servers/{{serverName}}/data-engine-proxy-service/configuration
{
    "class": "DataEngineProxyConfig",
    "accessServiceRootURL": "{{{metadata-server-platform-url}}}",
    "accessServiceServerName": "{{metadata-server-name}}",
    "dataEngineConnection": {
        "class": "Connection",
        "connectorType": {
            "class": "ConnectorType",
            "connectorProviderClassName": "org.odpi.egeria.connectors.ibm.datastage.dataengineconnector.DataStageConnectorProvider"
        },
        "endpoint": {
            "class": "Endpoint",
            "address": "{{data-engine-endpoint}}",
            "protocol": "https"
        },
        "userId": "{{data-engine-user}}",
        "clearPassword": "{{data-engine-password}}"
    },
    "pollIntervalInSeconds": 60
}

Configuration Reference

Property Description Is mandatory
dataEngineConnection OCF connection configuration object that defines the connector type and its properties. Refer to specific connector for detailed reference. Example provided for IBM Data Stage connector. Yes
pollIntervalInSeconds The polling interval in seconds to call the sequence extracting metadata. Yes

Removing the Data Engine Services from the server configuration

DELETE - Remove Data Engine Configuration from the server

{{serverURLRoot}}/open-metadata/admin-services/users/{{userId}}/servers/{{serverName}}/data-engine-proxy-service/configuration
Back to top