Skip to content
Stable

This component is complete and can be used. The interfaces will be supported until the function is removed from the project via the deprecation process. There will be ongoing extensions to this function, but it will be done to ensure backward compatibility as far as possible. If there is a need to break backward compatibility, this will be discussed and reviewed in the community, with a documented timeline.

Administration services

The administration services support the commands to:

  • Configure an OMAG Server Platform.
  • Configure different types of OMAG Servers
  • List the configured OMAG Servers
  • Deploy the configuration document for an OMAG Server to a different OMAG Server Platform.
  • Start and stop OMAG Servers
  • Retrieve the status of an OMAG Server along with the status of each of its active subsystems and services.

The Java clients for the administration services are located in its admin-services-client module.

Each Java client has multiple constructors. The constructors set up the connection to the OMAG Server Platform. The parameters are passed in different combinations to control security and logging.

  • platformName - the descriptive name of the OMAG Server Platform for error logging.
  • platformURLRoot - the platform url root of the OMAG Server Platform.
  • auditLog - logging destination for audit log messages.
  • userId - this is the optional userId that is embedded in all REST calls. Think of it as the client's user Id rather than the userId of the end user.
  • password - this is the password that goes with the client's userId. The userId and password should both be supplied or neither.
  • maxPageSize - controls the maximum number of results that can be returned on any call. If this is not set, the max page size is controlled platform-side.
  • restClient - inside the java client is a REST API connector that manages the marshalling and de-marshalling of the requests into the HTTP protocol used by REST. Normally this connector is created by the client, but this parameter enables an externally created connector to be used instead.

The constructor may throw InvalidParameterException if there is an issue setting up the client-side components based on the supplied parameters. Pick the constructor that matches the parameters you have. For example, if you call the constructor that supports the client's userId and password and you pass null in these parameters, the exception is thrown.

Configuring the OMAG Server Platform

The OMAG Server Platform has two connectors that are configured though the OMAGServerPlatformConfigurationClient.

OMAGServerPlatformConfigurationClient

The OMAGServerPlatformConfigurationClient is responsible for setting up the connectors for the OMAG Server Platform. This configuration needs to be re-applied each time the platform start up,

The client supports retrieving the connection for either of these connectors, updating it and deleting it. The example below shows how to retrieve the connections for the platform's two connectors.

Example: retrieving all available configuration documents
1
2
3
4
OMAGServerPlatformConfigurationClient platformConfigurationClient = new OMAGServerPlatformConfigurationClient(clientUserId, platformURLRoot);

Connection configurationStoreConnection = platformConfigurationClient.getConfigurationStoreConnection();
Connection platformSecurityConnection   = platformConfigurationClient.getPlatformSecurityConnection();

The platform's configuration is not stored. Instead it needs to be added/updated each time the platform starts.

Configuring an OMAG Server

The Administration Services clients that support the configuration of OMAG Servers are specialized to configure the specific services that each type of OMAG Server supports. For example, MetadataAccessStoreConfigurationClient has all of the methods necessary to configure a Metadata Access Store. Similarly, the IntegrationDaemonConfigurationClient has all of the methods necessary to configure an Integration Daemon. Since there are some common services, the clients make use of inheritance to share configuration methods that are common. The diagram below how they are related.

OMAG Server configuration client hierarchy

The configuration clients for OMAG servers are organized in an inheritance hierarchy to allow them to share common methods. However, each has all of the method needed to configure its services.

Java Client Type of OMAG Server it configures Javadoc Link
MetadataAccessPointConfigurationClient Metadata Access Point Javadoc
MetadataAccessStoreConfigurationClient Metadata Access Store Javadoc
RepositoryProxyConfigurationClient Repository Proxy Javadoc
ConformanceTestServerConfigurationClient Conformance Test Server Javadoc
EngineHostConfigurationClient Engine Host Javadoc
IntegrationDaemonConfigurationClient Integration Daemon Javadoc
ViewServerConfigurationClient View Server Javadoc

The configuration for each server is stored in a configuration document. The Java class that holds the configuration document is called OMAGServerConfig. It is a JavaBean and it can be used directly to set up the configuration for a server, or it can be set up by calling the configuration client APIs.

The sample code below shows a series of calls to the MetadataAccessStoreConfigurationClient to set up a Metadata Access Store that is using the in-memory repository and is activating the following access services.

Example: Methods used to configure a Metadata Access Store
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
/**
 * Set up the defaults that are used whenever a topic is configured for a server.
 * Check that the eventBusURLRoot is correct for your Kafka installation.
 *
 * @param client client responsible for the server configuration
 *
 * @throws OMAGNotAuthorizedException the supplied userId is not authorized to issue this command.
 * @throws OMAGInvalidParameterException invalid parameter.
 * @throws OMAGConfigurationErrorException unusual state in the admin server.
 */
private void setEventBus(OMAGServerConfigurationClient client) throws OMAGNotAuthorizedException,
                                                                      OMAGInvalidParameterException,
                                                                      OMAGConfigurationErrorException
{
    if (eventBusURLRoot != null)
    {
        Map<String, Object> configurationProperties = new HashMap<>();
        Map<String, Object> producerProperties      = new HashMap<>();
        Map<String, Object> consumerProperties      = new HashMap<>();

        producerProperties.put("bootstrap.servers", eventBusURLRoot);
        consumerProperties.put("bootstrap.servers", eventBusURLRoot);
        consumerProperties.put("auto.commit.interval.ms", "1");

        configurationProperties.put("producer", producerProperties);
        configurationProperties.put("consumer", consumerProperties);

        client.setEventBus(null, // use default - kafka
                           null, // use default - egeria.omag
                           configurationProperties);
    }
}


/**
 * Configure a security connector.  The default connector uses the Coco Pharmaceutical users and rules.
 * Change the serverSecurityConnectorProviderClassName to null to turn off security in new servers.
 * Alternatively change the class name for a different connector.
 *
 * @param client client responsible for the server configuration
 *
 * @throws OMAGNotAuthorizedException the supplied userId is not authorized to issue this command.
 * @throws OMAGInvalidParameterException invalid parameter.
 * @throws OMAGConfigurationErrorException unusual state in the admin server.
 */
private void setSecuritySecurityConnector(OMAGServerConfigurationClient client) throws OMAGNotAuthorizedException,
                                                                                       OMAGInvalidParameterException,
                                                                                       OMAGConfigurationErrorException
{
    if (serverSecurityConnectorProviderClassName != null)
    {
        Connection    connection    = new Connection();
        ConnectorType connectorType = new ConnectorType();

        connectorType.setConnectorProviderClassName(serverSecurityConnectorProviderClassName);
        connection.setConnectorType(connectorType);

        client.setServerSecurityConnection(connection);
    }
}


/**
 * Create a new metadata access store OMAG server with an in-memory repository.
 * If the event bus is not set up, the access services are configured without in and out topics.
 *
 * @param serverName name of the new server
 */
private void createMetadataStore(String serverName)
{
    try
    {
        System.out.println("Configuring metadata store: " + serverName);

        MetadataAccessStoreConfigurationClient client = new MetadataAccessStoreConfigurationClient(clientUserId, serverName, platformURLRoot);

        client.setServerDescription("Metadata Access Store called " + serverName + " running on platform " + platformURLRoot);
        client.setServerUserId(serverName + "npa");
        client.setServerType(null); // Let the admin service set up the server types
        client.setOrganizationName(organizationName);
        client.setMaxPageSize(maxPageSize);

        this.setSecuritySecurityConnector(client);
        client.setDefaultAuditLog();

        client.setServerURLRoot(platformURLRoot);
        this.setEventBus(client);

        client.setInMemLocalRepository();
        client.setLocalMetadataCollectionName(serverName + "'s metadata collection");

        List<String> assetLookupZones = new ArrayList<>();

        assetLookupZones.add("data-lake");
        assetLookupZones.add("personal-files");

        List<String> personalFilesZone = new ArrayList<>();

        assetLookupZones.add("personal-files");

        List<String> maintenanceZones = new ArrayList<>();

        maintenanceZones.add("quarantine");
        maintenanceZones.add("trash-can");
        maintenanceZones.add("data-lake");

        List<String> newDataZone = new ArrayList<>();

        newDataZone.add("quarantine");

        Map<String, Object> accessServiceOptions = new HashMap<>();


        if (eventBusURLRoot != null)
        {
            accessServiceOptions.put("SupportedZones", assetLookupZones);
            accessServiceOptions.put("DefaultZones", personalFilesZone);

            client.configureAccessService("asset-consumer", accessServiceOptions);

            accessServiceOptions.put("KarmaPointPlateau", 10);

            client.configureAccessService("community-profile", accessServiceOptions);

            accessServiceOptions = new HashMap<>();
            accessServiceOptions.put("SupportedZones", maintenanceZones);
            accessServiceOptions.put("DefaultZones", newDataZone);
            accessServiceOptions.put("PublishZones", assetLookupZones);

            client.configureAccessService("asset-owner", accessServiceOptions);
            client.configureAccessService("data-manager", accessServiceOptions);
            client.configureAccessService("asset-manager", accessServiceOptions);
            client.configureAccessService("governance-program", accessServiceOptions);
            client.configureAccessService("digital-architecture", accessServiceOptions);
        }
        else // configure the access services without in and out topics
        {
            accessServiceOptions.put("SupportedZones", assetLookupZones);
            accessServiceOptions.put("DefaultZones", personalFilesZone);

            client.configureAccessServiceNoTopics("asset-consumer", accessServiceOptions);

            accessServiceOptions.put("KarmaPointPlateau", 10);

            client.configureAccessServiceNoTopics("community-profile", accessServiceOptions);

            accessServiceOptions = new HashMap<>();
            accessServiceOptions.put("SupportedZones", maintenanceZones);
            accessServiceOptions.put("DefaultZones", newDataZone);
            accessServiceOptions.put("PublishZones", assetLookupZones);

            client.configureAccessServiceNoTopics("asset-owner", accessServiceOptions);
            client.configureAccessServiceNoTopics("data-manager", accessServiceOptions);
            client.configureAccessServiceNoTopics("asset-manager", accessServiceOptions);
            client.configureAccessServiceNoTopics("governance-program", accessServiceOptions);
            client.configureAccessServiceNoTopics("digital-architecture", accessServiceOptions);
        }
    }
    catch (Exception error)
    {
        System.out.println("There was an " + error.getClass().getName() + " exception when calling the platform.  Error message is: " + error.getMessage());
    }
}

Managing configuration documents

The ConfigurationManagementClient supports the retrieval of a single OMAG Server's configuration document, or all available configuration documents. It also supports the deployment of configuration documents to different OMAG Server Platforms.

ConfigurationManagementClient

Example: retrieving all available configuration documents
1
2
3
ConfigurationManagementClient configurationManagementClient = new ConfigurationManagementClient(clientUserId, platformURLRoot);

Set<OMAGServerConfig> configuredServers = configurationManagementClient.getAllServerConfigurations();

Starting and stopping OMAG Servers

The OMAGServerOperationsClient supports the starting and stopping of OMAG Servers on an OMAG Server Platform.

The code sample shows the method calls to start and stop named OMAG Servers.

Example: starting and stopping servers
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
/**
 * Start the named server on the platform.  This will fail if the platform is not running,
 * or if the user is not authorized to issue operations requests to the platform or if the
 * server is not configured.
 *
 * @param serverName string name
 */
private void startServer(String serverName)
{
    try
    {
        OMAGServerOperationsClient client = new OMAGServerOperationsClient(clientUserId, serverName, platformURLRoot);

        System.out.println("Starting " + serverName + " ...");
        System.out.println(client.activateWithStoredConfig());
    }
    catch (Exception error)
    {
        System.out.println("There was an " + error.getClass().getName() + " exception when calling the platform.  Error message is: " + error.getMessage());
    }
}


/**
 * Stop the requested server.    This will fail if the server or the platform is not running,
 * or if the user is not authorized to issue operations requests to the platform.
 *
 * @param serverName string name
 */
private void stopServer(String serverName)
{
    try
    {
        OMAGServerOperationsClient client = new OMAGServerOperationsClient(clientUserId, serverName, platformURLRoot);

        System.out.println("Stopping " + serverName + " ...");

        client.deactivateTemporarily();

        System.out.println(serverName + " stopped.");
    }
    catch (Exception error)
    {
        System.out.println("There was an " + error.getClass().getName() + " exception when calling the platform.  Error message is: " + error.getMessage());
    }
}

Querying the active server status

It is also able to retrieve the status of the services running within an active server.

Example: retrieving the status of the services in an active server

```java linenums="1" OMAGServerOperationsClient serverOperationsClient = new OMAGServerOperationsClient(clientUserId, serverName, platformURLRoot);

ServerServicesStatus adminServerStatus = serverOperationsClient.getServerStatus();

if (adminServerStatus != null) { System.out.println(adminServerStatus.getServerActiveStatus()); System.out.println(adminServerStatus.getServerType()); System.out.println(adminServerStatus.getServices()); } ````

The status of the server (and its nested services) is one of 5 values:

  • Unknown - The state of the server is unknown. This is equivalent to a null value.
  • Starting - The server is starting.
  • Running - The server has completed start up and is running.
  • Stopping - The server has received a request to shutdown.
  • Inactive - The server is not running.

The server type is derived by the administration services when it starts the server. It is based on an assessment of the services requested in the configuration document.

Further information

  • The administration guide describes how to use the administration services to configure OMAG Server Platforms and OMAG Servers.
  • The operations guide describes how to use the administration services to start/stop OMAG Servers on OMAG Server Platforms and retrieve diagnostics.

Raise an issue or comment below