Configuring an integration daemon¶
An Integration Daemon is configured by creating a configuration document. Below is the outline structure of the integration daemon's configuration document.
Configuring the basic properties
Configure the basic properties¶
The basic properties 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 that are set up when you first create the configuration document:
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. The default value is Open Metadata and Governance Server
.
If you have no specific value to set the server type name to, we recommend that you set the server type name to null. This will cause the server start up process will derive a standard server type name based on the rest of the configuration for the server.
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 userId, so it is possible to restrict the resources that each server has access to and identify the origin of updates to the metadata elements.
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}}
Configuring the audit log
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.
Each audit log record has a severity that can be used to route it to one or more specific destinations. Therefore, when an audit log destination is configured, it is optionally supplied with a list of severities to filter audit log records it should receive.
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 default audit log destination is the console audit log destination. This writes selected parts of each audit log record to "standard out" (stdout). It is configured to receive log records of all severities except Trace
and PerfMon
.
The default audit log destination is added automatically to Cohort Member servers when a repository, or cohort connection is configured.
For View Servers and Governance Servers, it is only added when other audit log destinations are configured. Therefore, is it necessary to issue at least one of the following configuration commands for the audit log for these types of servers.
Add audit log destinations¶
If the server is a development or test server, then the default audit log configuration is probably sufficient, and you should use the following command:
POST - set default audit log destination
{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/audit-log-destinations/default
Note: Using this command overrides all previous audit log destinations configured for the server.
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 receive different severities of audit log records.
There are various destinations that can be configured for the audit log:
Since the default audit log destination is also a console audit log destination, only use this option to add the Trace
and PerfMon
severities.
POST - add console audit log destination
{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/audit-log-destinations/console
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.
This destination writes JSON files in a shared directory. One file for each audit log record.
POST - add JSON file-based audit log destination
{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/audit-log-destinations/files
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.
This destination writes each log record as an event on the supplied event topic. It assumes that the event bus is set up first.
POST - add event-based audit log destination
{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/audit-log-destinations/event-topic
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.
This writes full log records to the slf4j ecosystem. When configuring slf4j as destination you also need to specify audit log logger category via the application properties of the OMAG Server Platform. This is described in Connecting the OMAG Audit Log Framework section of the developer logging guide.
The configuration of the slf4j ecosystem determines it ultimate destination(s).
POST - add slf4j audit log destination
{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/audit-log-destinations/slf4j
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.
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 are supplied in the connection's configuration properties.
POST - add connection-based audit log destination
{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/audit-log-destinations/connection
It is also possible to set up all the audit log destinations in one command as a list of connections. Using this option overrides all previous audit log destinations and so can be used as the update command. The list of connections is passed in the request body and the supported severities are supplied in each connection's configuration properties.
POST - add a list of connection-based audit log destinations
{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/audit-log-destinations
Retrieving audit log destinations¶
The configured list of audit log destinations can be retrieved using this command:
GET - the list of configured audit log destinations
{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/audit-log-destinations
Updating audit log destinations¶
Audit log destinations can be updated individually, by qualified name using the following command:
POST - update connection-based audit log destination
{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/audit-log-destinations/connection/{{qualifiedName}}
If you are not sure what the audit log connection is called, retrieve the list of configured audit log connections and the resulting list of audit log connections will include the qualified names.
Remove audit log destinations¶
The following will remove all audit log destinations, enabling you to add a new set of audit log destinations.
DELETE - clear all audit log destinations
{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/audit-log-destinations
It is also possible to remove a single audit log destination using its connection's qualified name.
DELETE - clear then named audit log destination
{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/audit-log-destinations/{{qualifiedName}}
Configuring the server security connector
Configure the server security connector¶
Metadata that is being aggregated from different sources is likely to need comprehensive access controls.
Egeria provides fine-grained security control for metadata access. It is implemented in a server metadata security connector that is called whenever requests are made for to the server.
Security is configured for a specific OMAG Server by adding a connection for this connector to the server's configuration documentusing the following command.
POST - configure security connector
{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/security/connection
This passes in a connection used to create the server security connector in the request body.
{
"class": "Connection",
"connectorType": {
"class": "ConnectorType",
"connectorProviderClassName": "{fullyQualifiedJavaClassName}"
}
}
Example: set up the sample server security connector
For example, this is the connection that would set up the sample server security connector provided for the Coco Pharmaceuticals case study:
{
"class": "Connection",
"connectorType": {
"class": "ConnectorType",
"connectorProviderClassName": "org.odpi.openmetadata.metadatasecurity.samples.OpenMetadataServerSecurityProvider"
}
}
Determine configured security¶
GET - query the server security connector setting
{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/security/connection
Response indicating no security
{
"class": "ConnectionResponse",
"relatedHTTPCode": 200
}
Response indicating a specific security connector
If the response looks more like the JSON below, a connector is configured. The connectorProviderClassName
tells you which connector is being used.
{
"class": "ConnectionResponse",
"relatedHTTPCode": 200,
"connection": {
"class": "Connection",
"connectorType": {
"class": "ConnectorType",
"connectorProviderClassName": "{fullyQualifiedJavaClassName}"
}
}
}
Remove configured security¶
DELETE - remove configured security connector
{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/security/connection
This removes all authorization checking from the server.
Configuring the integration connectors
Configuring the integration connectors¶
The integration connectors that are to run in the integration daemon can be configured one of two ways:
- Statically in the integration daemon's configuration document using integration service definitions
- Dynamically using integration groups
Both approaches can be used in the same integration daemon instance. However, each integration connector to run should only be configured by
Configuring integration services
Configure the integration services¶
The integration services (or Open Metadata Integration Services (OMIS) to give them their full name) run in an integration daemon.
Each integration service hosts one or more integration connectors. An integration connector is responsible for the exchange of metadata with a specific deployment of a third party technology. For example, the database integrator integration service supports integration connectors that work with relational databases (RDBMS). A deployment of this integration service in an integration daemon may host, say, two integration connectors each loading metadata from their own relational database server.
The descriptive information and operational status are filled out automatically by the administration services based on the integrationServiceURLMarker
value that you supply. The other values are supplied on the configuration call.
List integration services¶
It is possible to get a description of each of the registered integration services using the following command:
GET - list integration services
{{platformURLRoot}}/open-metadata/platform-services/users/{{adminUserId}}/server-platform/registered-services/integration-services
Note the integrationServiceURLMarker
for the integration service that you want to configure.
Configure an integration service¶
Each integration service is configured with the network location of the metadata access point / metadata access store running the appropriate OMAS. There are a set of options that the integration service supports along with the list of configuration properties for the integration connectors that will be run in the integration service. The integration connector's configuration properties defines which connector implementation to use and how it should be operated.
POST - configure an integration service
{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/integration-services/{{integrationServiceURLMarker}}
With a request body like the following:
{
"class": "IntegrationServiceRequestBody",
"omagserverPlatformRootURL": "{MDServerURLRoot}",
"omagserverName": "{MDServerName}",
"integrationConnectorConfigs":
[
{
"class": "IntegrationConnectorConfig",
"connectorName": " ... ",
"connectorUserId": " ... ",
"connection":
{
"class": "Connection",
"connectorType":
{
"class": "ConnectorType",
"connectorProviderClassName": "{connector provider class name}"
},
"endpoint":
{
"class": "Endpoint",
"address" : "..."
}
},
"metadataSourceQualifiedName": " ... ",
"refreshTimeInterval": "60",
"usesBlockingCalls": "false",
"permittedSynchronization": " ... "
}
]
}
Detailed description of the properties:
connectorName
sets up the name of the connector. This name is used for routing refresh calls to the connector as well as being used for diagnostics. Ideally it should be unique amongst the connectors for the integration service.connectorUserId
sets up the user id for the connector - if this is null, the integration daemon's userId is used on requests to the Open Metadata Access Service (OMAS).connection
sets up the connection for the integration connector.metadataSourceQualifiedName
sets up the qualified name of the metadata source for this integration connector. This is the qualified name of an appropriate software capability element stored in open metadata. This software capability is accessed via the partner OMAS and is used to control the origin information - known as metadata provenance in any metadata elements created by the integration connector. The default value is null, which means all metadata elements created by the integration connector will have local cohort provenance values and can be updated by other process in the open metadata ecosystem. If it is set up with a valid qualified name, the metadata elements will have external source provenance values and only the integration connector is able to update the values.refreshTimeInterval
sets up the number of minutes between each call to the connector to refresh the metadata. Zero means that refresh is only called at server start up and whenever the refresh REST API request is made to the integration daemon. If the refresh time interval is greater than 0 then additional calls to refresh are added spaced out by the refresh time interval.usesBlockingCalls
sets up whether the connector should be started in its own thread to allow it to block on a listening call.permittedSynchronization
is an optional property that defines the permitted directions of metadata flow between the third party technology and open metadata. If the integration connector attempts to flow metadata in a direction that is not permitted, it receives theUserNotAuthorizedException
. The default for this value is set up automatically in the integration service's descriptive information so this value only needs to be set if it is necessary to restrict the behavior of the connector. These are the different values for this property and their effect:TO_THIRD_PARTY
- The third party technology is logically downstream of open metadata. This means the open metadata ecosystem is the originator and owner of the metadata being synchronized. Any updates detected in the third technology are overridden by the latest open metadata values.FROM_THIRD_PARTY
- The third party technology is logically upstream (the originator and owner of the metadata). Any updates made in open metadata are not passed to the third party technology and the third party technology is requested to refresh the open metadata version.BOTH_DIRECTIONS
- Metadata exchange is permitted in both directions. Synchronization is halted on a specific element if potentially clashing updates have occurred both in the third party technology and open metadata. Such conflicts are logged on the audit log and resolved through manual stewardship.
Configuring integration groups
Configure dynamic integration groups¶
Each integration group hosts one or more integration connectors. An integration connector is responsible for the exchange of metadata with a specific deployment of a third party technology. For example, the database integrator integration service supports integration connectors that work with relational databases (RDBMS).
Configure an integration group¶
Each integration group is configured with the network location of the metadata access point / metadata access store running the appropriate OMAS along with the qualified name of the IntegrationGroup entity that represents the integration group.
POST - configure an integration group
{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/integration-groups/configuration
With a request body like the following:
{
"class": "IntegrationGroupConfig",
"omagserverPlatformRootURL": "{MDServerURLRoot}",
"omagserverName": "{MDServerName}",
"integrationGroupQualifiedName": {qualifiedName}
}
Configure all integration groups in one command¶
POST - configure all integration groups
{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/integration-groups/configuration/all
With a request body like the following:
[
{
"class": "IntegrationGroupConfig",
"omagserverPlatformRootURL": "{MDServerURLRoot}",
"omagserverName": "{MDServerName}",
"integrationGroupQualifiedName": {qualifiedName}
},
{
"class": "IntegrationGroupConfig",
"omagserverPlatformRootURL": "{MDServerURLRoot}",
"omagserverName": "{MDServerName}",
"integrationGroupQualifiedName": {qualifiedName}
},
]
Retrieve configured integration groups¶
GET - all configured integration groups
{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/integration-groups/configuration
Remove all configured integration groups¶
DELETE - all configured integration groups
{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/integration-groups
Remove a specific configured integration group¶
DELETE - a configured integration group
{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/integration-groups/{{qualifiedName}}
Further information
- For help in fixing any error you find using the integration daemon, visit the integration daemon diagnostic guide.
- Link to the Egeria solutions to see the integration daemon in action.
- Link to the integration daemon services to understand how the integration daemon is implemented.
Raise an issue or comment below