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 configuration for an OMAG Server is maintained in a Configuration Document and these configuration documents are stored in a configuration document store. The implementation for the configuration document store is plugged into the OMAG Server Platform as a configuration document store connector.

The administration services support the commands to:

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.

Dynamically configuring the Configuration Document Store Connector

The Configuration Document Store Connector manage the storage and retrieval of configuration documents. This connector can be configured though the OMAGServerPlatformConfigurationClient.

OMAGServerPlatformConfigurationClient

The OMAGServerPlatformConfigurationClient is responsible for setting up the configuration document store connector for the OMAG Server Platform. This configuration needs to be re-applied each time the platform starts 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. The platform's configuration is not stored - it needs to be added/updated each time the platform starts.

Example: retrieving all available configuration documents

==== "Java"

```java linenums="1"
OMAGServerPlatformConfigurationClient platformConfigurationClient = new OMAGServerPlatformConfigurationClient(clientUserId, platformURLRoot);

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

==== "REST API"

!!! post "POST - configure the configuration document store connector"
    ```
    {{platformURLRoot}}/open-metadata/platform-services/users/{{adminUserId}}/stores/connection
    ```

    The request body should be a connection object used to create the connector to the configuration
    document store.

!!! attention "Ensure the connector is available in the classpath"
    In order to use any connector other than the default, you need to also ensure that the Connector and its ConnectorProvider class are available to the server platform (i.e. the jar file containing them is available in the `LOADER_PATH` location of the server platform).

??? example "Example: (unencrypted) file store connector"
    For example, this connection would set up the (unencrypted) file store connector:

    ```json linenums="1"
    {
        "class": "Connection",
        "connectorType": {
            "class": "ConnectorType",
            "connectorProviderClassName": "org.odpi.openmetadata.adapters.adminservices.configurationstore.file.FileBasedServerConfigStoreProvider"
        },
        "endpoint": {
            "class": "Endpoint",
            "address": "omag.server.{0}.config"
        }
    }
    ```

??? example "Example: encrypted JSON file store, non-default location"
    As another example, this connection uses the default encrypted JSON file store, but the files are stored in a different location (`/my-config/omag.server.{0}.config`).

    ```json linenums="1"
    {
        "class": "Connection",
        "connectorType": {
            "class": "ConnectorType",
            "connectorProviderClassName": "org.odpi.openmetadata.adapters.adminservices.configurationstore.encryptedfile.EncryptedFileBasedServerConfigStoreProvider"
        },
        "endpoint": {
            "class": "Endpoint",
            "address": "/my-config/omag.server.{0}.config"
        }
    }
    ```

Determine configured store

It is possible to query the setting of the configuration document store connector using the following command:

GET - retrieve configured configuration document store

{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/stores/connection
Response indicating default configuration store (encrypted JSON file store) 
{
    "class": "ConnectionResponse",
    "relatedHTTPCode": 200
}
Response indicating a specific connector

If the response looks more like the JSON below, a connector is configured. The connectorProviderClassName tells you which connector is being used and the address shows where the configuration documents are stored.

{
    "class": "ConnectionResponse",
    "relatedHTTPCode": 200,
    "connection": {
        "class": "Connection",
        "connectorType": {
            "class": "ConnectorType",
            "connectorProviderClassName": "org.odpi.openmetadata.adapters.adminservices.configurationstore.file.FileBasedServerConfigStoreProvider"
        },
        "endpoint": {
            "class": "Endpoint",
            "address": "omag.server.{0}.config"
        }
    }
}

Remove configured store

It is also possible to remove the configuration for the connector using the following command:

DELETE - remove configured configuration store

{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/stores/connection

This reverts the store to the default encrypted JSON file store.

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();

Raise an issue or comment below