Asset Consumer Open Metadata Access Service (OMAS)¶

Overview¶

The Asset Consumer OMAS provides services to an individual who wants to work with digital resources such as:

• data stores, data sets and data feeds
• reports
• APIs
• functions such as analytical services

These resources are represented in open metadata as assets.

Asset Consumer OMAS supports:

• the retrieval of connection objects from the open metadata repositories. A connection object is used to create a connector to an asset.
• the creation of a connector based on the properties in a connection object.
• the retrieval of properties about an asset. These properties are called the connected asset properties.
• the adding of feedback (comments, ratings and likes) to an asset.
• the maintenance of informal tags and the attachment of them to an asset.
• the adding of an audit log record for an asset.
• the publishing of notifications about assets on Asset Consumer OMAS's out topic.
• the use of the open metadata store interface.

Adding feedback through the Asset Consumer OMAS results in Karma Points being awarded to the individual. These are maintained in the individual's profile. A karma point is awarded for each contribution of feedback through the API. (The awarding of Karma points is managed by the Community Profile OMAS.)

The connectors returned by the Asset Consumer OMAS are Open Connector Framework (OCF) connectors. The caller can use the connector to access the contents of the asset itself and the properties about the asset it is accessing. This service is provided by the OCF Metadata Management Common Service.

User Guide¶

The Asset Consumer OMAS is designed for use by an application that is accessing data sources and services through connectors. These data sources and services are called digital resources. Digital resources are represented in open metadata as Assets, hence the name of this OMAS is Asset Consumer.

Typically, the first action to take is to create the connector to get access to the asset content and its properties. Connectors are created from Connection objects. Connection objects can be created by the calling application, or stored in one of the open metadata repositories that are accessible to the Asset Consumer OMAS.

Alternatively, if the consumer only needs access to the asset's properties, they can use the Asset Consumer OMAS to locate the identifier of the asset and then retrieve the asset properties.

Within the asset properties are links to glossary terms. It is possible to look up the full description of a term to further understand the asset.

There are also capabilities to log messages about the asset, add feedback to the asset in terms of likes, star ratings, reviews and comments, and add tags to the asset.

Interface choices¶

The Asset Consumer OMAS offers the following types of interface:

• Java client.
• Out Topic Events for receiving events about assets.
• REST API.

Connectors are only available through the Java client.

Configuration¶

Details of how to configure the Asset Consumer OMAS can be found in the admin guide

Scenarios¶

This is the list of documented scenarios:

• Working with Connectors (overview)
• Creating a connector
• Locating the connected asset
• Retrieving asset properties
• Logging audit messages about an event
• Adding Feedback to an Asset
• Looking up the meanings of terms assigned to an asset
• Adding descriptive tags to an asset

Working with connectors¶

An open connector is a Java client to a digital resource that implements the Connector interface defined in the Open Connector Framework (OCF). It has 2 parts to its interface:

• The specialized interface to work with the specific contents of the resource. For example, if the connector was for data stored in a relational database, this interface would probably follow the Java Database Connectivity (JDBC) specification. The documentation for this interface is found with the specific connector.

• A generalized interface to extract all the open metadata known about the resource. This is referred to as the connected asset properties.

This is an example of the JDBC Resource connector

An application creates a connector using the Asset Consumer OMAS client. When a resource is catalogued in open metadata, there is a Connection object linked to it. This defines all the properties required to create the connector.

See Creating a connector for step-by-step instructions on creating connectors. Asset Consumer OMAS looks up the Connection object and calls the Connector Broker to create the connector.

Once the connector is created, an application may use it to retrieve the content of the asset and the connected asset properties.

When the application has finished with the connector, it should call disconnect() to release any resources that the connector may be holding.

Creating a connector for application use¶

The Asset Consumer OMAS supports a REST API to extract metadata from the open metadata repositories linked to the same open metadata cohort as the Asset Consumer OMAS. It also has a Java client that provides an equivalent interface to the REST API plus connector factory methods supported by an embedded Connector Broker.

The Connector Broker is an Open Connector Framework (OCF) component that is able to create and configure instances of compliant connectors. It is passed a Connection object which has all the properties needed to create the connector.

The Asset Consumer OMAS java client extracts the Connection object from the open metadata repositories and then calls the Connector Broker.

The code sample below creates the Asset Consumer OMAS Client. It is passed the server name and platform URL root for the metadata access server that will supply the connection object.

      AssetConsumer client = new AssetConsumer(serverName, serverURLRoot);

• Supplying a hard-coded Connection object.
• Supplying the unique identifier (guid) of the Connection object in the metadata repositories that Asset Consumer OMAS has access to.
• Supplying the unique identifier (guid) of an Asset. The connector is created using the Connection linked to the asset.

In this first example, the connector is created from the hard-coded connection.

    /**
     * This method creates a connector using a hard coded connection object.  This connector will be able
     * to retrieve the data from the file, but it will not be able to retrieve the metadata about
     * the file.
     *
     * @return connector to requested file
     */
    private CSVFileStoreConnector getConnectorUsingHardCodedConnection()
    {
        CSVFileStoreConnector connector = null;

        try
        {
            AssetConsumer client = new AssetConsumer(serverName, serverURLRoot);

            connector = (CSVFileStoreConnector)client.getConnectorByConnection(clientUserId, getHardCodedConnection(fileName));
        }
        catch (Exception error)
        {
            System.out.println("The connector can not be created with Asset Consumer OMAS.");
        }

        return connector;
    }


    /**
     * This method creates a connection.  The connection object provides the OCF with the properties to create the
     * connector and the properties needed by the connector to access the asset.
     *
     * The Connection object includes a Connector Type object.  This defines the type of connector to create.
     * The Connection object also includes an Endpoint object.  This is used by the connector to locate and connect
     * to the Asset.
     *
     * @param fileName name of the file to connect to
     * @return connection object
     */
    private Connection getHardCodedConnection(String   fileName)
    {
        final String endpointGUID      = "8bf8f5fa-b5d8-40e1-a00e-e4a0c59fd6c0";
        final String connectorTypeGUID = "2e1556a3-908f-4303-812d-d81b48b19bab";
        final String connectionGUID    = "b9af734f-f005-4085-9975-bf46c67a099a";

        final String endpointDescription = "File name.";

        String endpointName    = "CSVFileStore.Endpoint." + fileName;

        Endpoint endpoint = new Endpoint();

        endpoint.setType(Endpoint.getEndpointType());
        endpoint.setGUID(endpointGUID);
        endpoint.setQualifiedName(endpointName);
        endpoint.setDisplayName(endpointName);
        endpoint.setDescription(endpointDescription);
        endpoint.setAddress(fileName);


        final String connectorTypeDescription   = "CSVFileStore connector type.";
        final String connectorTypeJavaClassName = CSVFileStoreProvider.class.getName();

        String connectorTypeName = "CSVFileStore.ConnectorType.Test";

        ConnectorType connectorType = new ConnectorType();

        connectorType.setType(ConnectorType.getConnectorTypeType());
        connectorType.setGUID(connectorTypeGUID);
        connectorType.setQualifiedName(connectorTypeName);
        connectorType.setDisplayName(connectorTypeName);
        connectorType.setDescription(connectorTypeDescription);
        connectorType.setConnectorProviderClassName(connectorTypeJavaClassName);


        final String connectionDescription = "CSVFileStore connection.";

        String connectionName = "CSVFileStore.Connection.Test";

        Connection connection = new Connection();

        connection.setType(Connection.getConnectionType());
        connection.setGUID(connectionGUID);
        connection.setQualifiedName(connectionName);
        connection.setDisplayName(connectionName);
        connection.setDescription(connectionDescription);
        connection.setEndpoint(endpoint);
        connection.setConnectorType(connectorType);

        return connection;
    }

The next example, uses the Connection GUID:

    try
    {
        /*
         * Return a connector for the connection.
         */
        return (CSVFileStoreConnector) client.getConnectorByGUID(clientUserId, connectionGUID);
    }
    catch (Exception error)
    {
        System.out.println("Unable to create connector for connection: " + connectionGUID);
    }

The final example uses the Asset GUID:

    try
    {
        /*
         * Return a connector for the asset.
         */
        return (CSVFileStoreConnector) client.getConnectorForAsset(clientUserId, assetGUID);
    }
    catch (Exception error)
    {
        System.out.println("Unable to create connector for asset: " + assetGUID);
    }

Why use the Asset Consumer OMAS java client rather than the ConnectorBroker?¶

Each connector has a method called getConnectedAssetProperties. This returns the metadata known about the asset that the connector is accessing. When you create a connector using the Asset Consumer OMAS java client, and the Connection used is linked to an asset then getConnectedAssetProperties returns all the metadata known about the asset.

            ConnectedAssetProperties assetProperties = connector.getConnectedAssetProperties(clientUserId);

            if (assetProperties != null)
            {
                AssetUniverse assetUniverse = assetProperties.getAssetUniverse();

                if (assetUniverse != null)
                {
                    System.out.println("Type Name: " + assetUniverse.getAssetTypeName());
                    System.out.println("Qualified Name: " + assetUniverse.getQualifiedName());
                }
                else
                {
                    System.out.println(assetProperties.toString());
                }
            }
            else
            {
                System.out.println("No asset properties  ...");
            }

Locating the connected asset¶

Retrieving asset properties¶

Logging messages about an asset¶

Adding feedback to an asset¶

Raise an issue or comment below

Looking up the meanings of terms¶

Tagging an asset¶

Raise an issue or comment below