Configuring a view server ¶

A View Server is configured by creating a configuration document. Below is the outline structure of the server's configuration document.

Configuration for a view server

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:

consolefileeventslf4jconnectionlist

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 view services

Configure the view services¶

The Open Metadata View Services (OMVS's) run in a view server.

View services provide task-oriented, domain-specific services for user interfaces that integrate with open metadata. View services are part of a multi-tier architecture for the provision of multi-tenant user interfaces. The front tier consists of web components that are rendered in a web browser and served by a web application called the presentation server . The presentation server in turn delegates requests to a set of view services that form a second tier running in the view server. Each view service exposes a REST API that supports the domain-specific operations relevant to the service and issues queries and commands to other OMAG Servers.

To get a description of each of the registered view services, and each service's viewServiceURLMarker, see list view services instructions below.

To activate a specific view service in a view server, it is necessary to add an entry for the view service to the view server's configuration document.

Configuration document contents for a view service

The descriptive information and operational status are filled out automatically by the administration services based on the viewServiceURLMarker value that you supply. The other values are supplied on the configuration call.

There are two types of view services, each with a different type of view service configuration object:

Solution view services¶

A solution view service supports operations needed by a solution-oriented user interface. These are typically geared toward a specific Open Metadata Access Service (OMAS). For example, the Glossary Author view service supports a user interface for creation and management of glossaries using the Subject Area OMAS.

A solution view service is configured using a SolutionViewServiceConfig object which has the following properties:

Property	Use
`viewServiceId`	required property, set to a unique numeric identifier
`viewServiceAdminClass`	required property, set to the admin class of the view service
`viewServiceName`	required property, set to the name of the view service being configured
`viewServiceFullName`	required property, set to the full name of view service
`viewServiceURLMarker`	required property, set to the serviceURL Marker of the service - this can be discovered by listing the registered view services
`viewServiceDescription`	optional property that describes the view service
`viewServiceWiki`	optional property specifying the location of the view service documentation
`viewServiceOperationalStatus`	required property, set to ENABLED or DISABLED
`viewServiceOptions`	optional property that specifies options needed by a specific view service (refer to the documentation for the specific service for details)
`omagServerPlatformRootURL`	required property (see below)
`omagServerName`	required property (see below)

A solution view service configuration must include omagServerPlatformRootURL and omagServerName properties(defined in OMAGServerClientConfig). These properties specify the OMAG Server to which to send downstream REST calls to an OMAG Server that is running the OMAS needed by the view service.

Example solution view service configuration

Below is an example of a configuration object for a solution view service. In this example, the view service is Glossary Author View Service . It would be similar for the other solution view services.

The configuration contains the name and status of the view service and contains the name and rootURL of the OMAG Server to which 'downstream' requests will be sent. In this example the 'downstream' server is the server running the Subject Area OMAS, required by the Glossary Author view service.

{
    "class":"SolutionViewServiceConfig",
    "viewServiceAdminClass":"org.odpi.openmetadata.viewservices.glossaryauthor.admin.GlossaryAuthorViewAdmin",
    "viewServiceFullName":"Glossary Author",
    "viewServiceOperationalStatus":"ENABLED",
    "omagserverName":"Subject_Area_Server",
    "omagserverPlatformRootURL":"https://localhost:8083"
}

Integration view services¶

An integration view service supports operations needed by an integration-oriented user interface. Examples include the Repository Explorer View Service , Type Explorer View Service or Dino View Service for operational management.

It additionally has the following configuration properties:

Property	Use
`viewServiceId`	required property, set to a unique numeric identifier
`viewServiceAdminClass`	required property, set to the admin class of the view service
`viewServiceName`	required property, set to the name of the view service being configured
`viewServiceFullName`	required property, set to the full name of view service
`viewServiceURLMarker`	required property, set to the serviceURL marker of the service - this can be discovered by listing the registered view services
`viewServiceDescription`	optional property that describes the view service
`viewServiceWiki`	optional property specifying the location of the view service documentation
`viewServiceOperationalStatus`	required property, set to ENABLED or DISABLED
`viewServiceOptions`	optional property that specifies options needed by a specific view service (refer to the documentation for the specific service for details)
`resourceEndpoints`	required property that lists the platform and server endpoints of the OMAG Platforms or Servers to which to send downstream REST calls, for example to query metadata repositories (see below)

An integration view service configuration does not need the omagServerPlatformRootURL and omagServerName properties that are required for a solution view service configuration. This is because an integration view service will generally need to perform operations routed to a variety of open metadata servers, selected by the user at runtime. The set of platforms and servers that the user can select are configured by the resourceEndpoints configuration property.

The resourceEndpoints property is a list of ResourceEndpointConfig objects, which each have the following properties:

Property	Use
`resourceCategory`	required property, set to either "Platform" or "Server"
`platformName`	required property, a unique name given to a "Platform" resource, or a reference to a named "Platform" resource endpoint from a "Server" resource
`serverName`	required property for a "Server" resource, set to the name of the OMAG Server. Not used for a "Platform" resource.
`serverInstanceName`	required property for a "Server" resource, a unique name for the combination of server and platform.
`description`	optional property that is displayed by some integration view services

In an Egeria deployment, a server may be deployed to multiple platforms; this is typically used for clustering. A "Server" ResourceEndpointConfig must possess a serverInstanceName property which contains a unique name that refers to the specific instance of the server identified by the serverName property hosted by the platform identified by the platformName property. For example, you could configure a pair of server resource endpoints called Server1@PlatformA and Server1@PlatformB: both are Server1, but hosted on different platforms (PlatformA and PlatformB). The serverInstanceName is used to display the resource in the user interface selector lists.

Example integration view service configuration

Below is an example of a configuration object for an Integration View Service. In this example, the view service is Dino View Service . It would be similar for the other integration view services.

The configuration contains the name and status of the view service and contains a list of the resources that will appear in the platform and server selectors in the user interface. All requests to the view service REST API are based on these configured named resources. When a user selects a platform name or server name from the selector lists, the interface sends the resource name to the view service, which resolves the platform or server name to a resource endpoint to identify the URL needed to send a request to the platform or server.

In the example configuration, the list of ResourceEndpointConfig objects represents two platforms and two servers. Every ResourceEndpointConfig has a resourceCategory, set to either "Platform" or "Server". Each platform ResourceEndpointConfig has a unique platformName and platformRootURL and an optional description property. Each server ResourceEndpointConfig has a serverInstanceName, serverName and the platformName of one of the configured platform resource endpoints. Each server also has an optional description property.

You would need to replace the <hostname> and <port> variables with your own values:

{
    "class":"IntegrationViewServiceConfig",
    "viewServiceAdminClass":"org.odpi.openmetadata.viewservices.rex.admin.RexViewAdmin",
    "viewServiceFullName":"RepositoryExplorer",
    "viewServiceOperationalStatus":"ENABLED",
    "resourceEndpoints" : [
        {
            "class"              : "ResourceEndpointConfig",
            "resourceCategory"   : "Platform",
            "platformName"       : "Platform1",
            "platformRootURL"    : "https://<hostname>:<port>",
            "description"        : "This platform is running in the development cloud"
        },
        {
            "class"              : "ResourceEndpointConfig",
            "resourceCategory"   : "Platform",
            "platformName"       : "Platform2",
            "platformRootURL"    : "https://<hostname>:<port>",
            "description"        : "This platform is running in the departmental test cluster"               
        },
        {
            "class"              : "ResourceEndpointConfig",
            "resourceCategory"   : "Server",
            "serverInstanceName" : "Central Metadata Server",
            "serverName"         : "Metadata_Server1",
            "platformName"       : "Platform1",
            "description"        : "Metadata server with home reopsitory for schema artefacts"
        },
        {
            "class"              : "ResourceEndpointConfig",
            "resourceCategory"   : "Server",
            "serverInstanceName" : "Supplementary Metadata Server",
            "serverName"         : "Metadata_Server2",
            "platformName"       : "Platform2",
            "description"        : "Metadata server with home repository for review artefacts"
        }
    ]
}

Administrative operations¶

List view services¶

It is possible to list the registered view services for an OMAG Server Platform using the following command:

GET - list view services

{{platformURLRoot}}/open-metadata/platform-services/users/{{adminUserId}}/server-platform/registered-services/view-services

Response from listing view services

{
    "class": "RegisteredOMAGServicesResponse",
    "relatedHTTPCode": 200,
    "services": [
        {
            "serviceName": "Glossary Author",
            "serviceURLMarker": "glossary-author",
            "serviceDescription": "View Service for glossary authoring.",
            "serviceWiki": "https://odpi.github.io/egeria/open-metadata-implementation/access-services/subject-area/"
        },
        {
            "serviceName": "Repository Explorer",
            "serviceURLMarker": "rex",
            "serviceDescription": "Explore open metadata instances.",
            "serviceWiki": "https://odpi.github.io/egeria/open-metadata-implementation/view-services/rex-view/"
        },
        {
            "serviceName": "Type Explorer",
            "serviceURLMarker": "tex",
            "serviceDescription": "Explore the open metadata types.",
            "serviceWiki": "https://odpi.github.io/egeria/open-metadata-implementation/view-services/tex-view/"
        },
        {
            "serviceName": "Dino",
            "serviceURLMarker": "dino",
            "serviceDescription": "Operate an open metadata topology.",
            "serviceWiki": "https://odpi.github.io/egeria/open-metadata-implementation/view-services/dino-view/"
        }
    ]
}

These view services are available to configure either together or individually.

This operation is a good way to discover the serviceURLMarker property for each view service, which is needed for various operations described below.

List configured view services¶

It is possible to list the configured view services for an OMAG Server using the following command:

GET - list configured view services

{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/view-services/configuration

Response from listing configured view services

The response will be a RegisteredOMAGServicesResponse which contains a list of RegisteredOMAGService objects, that will look something like the following:

{
    "class": "RegisteredOMAGServicesResponse",
    "relatedHTTPCode": 200,
    "services": [
        {
            "serviceName": "Glossary Author",
            "serviceURLMarker": "glossary-author",
            "serviceDescription": "View Service for glossary authoring.",
            "serviceWiki": "https://odpi.github.io/egeria/open-metadata-implementation/access-services/subject-area/"
        },
        {
            "serviceName": "Repository Explorer",
            "serviceURLMarker": "rex",
            "serviceDescription": "Explore open metadata instances.",
            "serviceWiki": "https://odpi.github.io/egeria/open-metadata-implementation/view-services/rex-view/"
        },
        {
            "serviceName": "Type Explorer",
            "serviceURLMarker": "tex",
            "serviceDescription": "Explore the open metadata types.",
            "serviceWiki": "https://odpi.github.io/egeria/open-metadata-implementation/view-services/tex-view/"
        }
    ]
}

These view services are available to configure either together or individually.

Retrieve view service configuration¶

individuallymultiple

Retrieve a specific view service's configuration:

GET - retrieve a specific view service's configuration

{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/view-services/{{serviceURLMarker}}

The response will be a ViewServiceConfigResponse containing a ViewServiceConfig object.

It is also possible to retrieve the current configuration for all configured view services:

GET - retrieve current configuration for all configured view services

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

This will return a ViewServicesResponse which will contain a list of ViewServiceConfig objects.

Configure view services¶

individuallymultiple

A specific view service can be individually configured with the following command:

POST - configure a specific view service

{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/view-services/{{serviceURLMarker}}

The request body must contain a ViewServiceConfig object, while the serviceURLMarker can be found by listing the configured view services.

It is also possible to configurate a set of view services at the same time, using the following command:

POST - configure multiple view services

{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/view-services/configuration

The request body must contain a list of ViewServiceConfig objects.

Remove view services¶

individuallymultiple

A specific view service can be individually cleared with the following command. This will remove the view service's configuration from the server.

DELETE - remove configuration for a specific view service

{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/view-services/{{serviceURLMarker}}

The serviceURLMarker can be found by listing the configured view services.

All the view services configured on a server can be cleared with the following command:

DELETE - remove configured view services

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

Raise an issue or comment below

Configuring a view server¶

Configure the basic properties¶

Set server type name¶

Set organization name¶

Set the server's userId and optional password¶

Set the maximum page size for REST API requests¶

Configure the audit log¶

Add audit log destinations¶

Retrieving audit log destinations¶

Updating audit log destinations¶

Remove audit log destinations¶

Configure the server security connector¶

Determine configured security¶

Remove configured security¶

Configure the view services¶

Solution view services¶

Integration view services¶

Administrative operations¶

List view services¶

List configured view services¶

Retrieve view service configuration¶

Configure view services¶

Remove view services¶

Configuring a view server ¶