Open Metadata Collection Store Connectors Documentation

The open metadata collection store connectors are used to integrate an existing metadata repository into the the open metadata ecosystem. There are two types of connectors.

The event mapper connector often calls the repository connector to expand out the information needed by the OMRS. The links below provide more information.

Getting Started Implementing a New Connector

Setup a project

Egeria has been designed to allow connectors to be developed in independent projects from the core itself. As an example, the IBM InfoSphere Information Governance Catalog Repository Connector is available in its own separate GitHub repository, and could be a useful reference point when following the remainder of these instructions.

Start by defining a new Maven project in your IDE of choice, and at the root-level POM be sure to include the following:

    <properties>
        <open-metadata.version>1.1-SNAPSHOT</open-metadata.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.odpi.egeria</groupId>
            <artifactId>open-metadata-adapter-package</artifactId>
            <version>${open-metadata.version}</version>
        </dependency>
    </dependencies>

Naturally change the version to whichever version of Egeria you’d like to build against; the open-metadata-adapter-package dependency ensures you’ll have the necessary portion of Egeria to build your connector against (ie. the base classes that you’ll need to extend in the steps below).

Implement the repository connector

As implied by the overview above, a logical place to start in implementing a new Open Metadata Collection Store Connector is by implementing the repository connector.

You can start to build this within your new project by creating a new Maven module called something like adapter. Within this adapter module, in a package like ...repositoryconnector, implement the following:

Once these minimal starting points are implemented, you should be able to configure the OMAG server chassis as a proxy to your repository connector by following the instructions in using the admin services. Important: this will not necessarily be the end-state pattern you intend to use for your repository connector, but can provide a quick way to start testing its functionality.

This very basic initial scaffold of an implementation allows a connection to be instantiated to your repository, and translation between your repository’s representation of metadata and the open metadata standard types.

The configuration and startup sequence is important, to start with the following should be sufficient (ie. you should not need to configure the access services or event bus initially to just test your OMRSMetadataCollection logic):

  1. Enable access to a cohort, by picking a name for your cohort and POSTing according to the instructions linked.
  2. Enable OMAG Server as a repository proxy, specifying your canonical OMRSRepositoryConnectorProvider class name for the connectorProvider={javaClassName} parameter.
  3. Start the server instance, by POSTing according to the instructions.

You should then be in a position to invoke the REST API endpoints of the OMAG server, which will in turn invoke the various methods of your implemented OMRSMetadataCollection.

(And of course from there you can continue to Override methods of the OMRSMetadataCollectionBase class to implement the other metadata functionality for searching, updating and deleting as well as retrieving other instances of metadata like relationships.)

Add an event mapper

Once you have the basic OMRSMetadataCollection working, you can then implement an event mapper.`

Within the same adapter Maven module, perhaps under a new sub-package like ...eventmapper, implement the following:

The bulk of the logic in the event mapper should then define how events that are received from your repository are processed (translated) into OMRS events: those dealing with Entities, Classifications and Relationships.

Typically you would want to construct such instances by calling into your OMRSMetadataCollection, ensuring you produce the same payloads of information for these instances both through API connectivity and the events.

Once you have the appropriate OMRS object, you can make use of the methods provided by the repositoryEventProcessor, configured by the base class, to publish these to the cohort. For example:

To add the event mapper configuration to the configuration you started with above, add:

  1. Configure the cohort event bus. This can be done first, before any of the other configuration steps above
  2. Configure the event mapper. This can be done nearly last: after all of the other configuration steps above, but before the start of the server instance.

Test your connector

As you progress with the implementation of your connector, it is a good idea to test it against the Egeria Conformance Suite, in particular to gain guidance on what features you may still need to implement to conform to the open metadata standards.

Package your connector

Once you have sufficiently implemented and tested your connector, and if you intend to simply make it available through the proxy ability of the OMAG Server Platform we’ve used above, you can package it into a distributable .jar file using another Maven module, something like distribution.

In this module’s POM file include your adapter module (by artifactId) as a dependency, and consider building an assembly that uses the following in order to compile a minimal .jar file for just your connector and its non-Egeria dependencies.

<useTransitiveDependencies>false</useTransitiveDependencies>

Again, since we would just be using this connector alongside the existing OMAG Server Platform, this avoids ending up with a .jar file that includes the entirety of the Egeria OMAG Server Platform (and its dependencies) in your connector .jar – and instead allows your minimal .jar to be loaded at startup of the core OMAG Server Platform and configured through the REST calls covered above.

(Of course, if you intend to embed or otherwise implement your own server, the packaging mechanism will likely by different.)

For a more detailed example of this minimal packaging to make use of the proxy, refer to the IBM InfoSphere Information Governance Catalog Repository Connector’s distribution module.


License: CC BY 4.0, Copyright Contributors to the ODPi Egeria project.