Metadata

In this tutorial we will cover the Metadata interface and its use.

This section assumes a connection has been established; see the getting started tutorial as necessary.

The metadata object

The getMetadata method of a Session returns a Metadata object. Metadata will only be fully populated when connecting into a R9 (or above) gateway.

The metadata object contains maps that indicate all of the available data sources, symbologies and dictionaries at the time of connection. It also has some utility functions for mapping names and ids for data sources, symbologies and dictionaries,

Data Source

All content on the platform is assigned to a specific source defined by a data source. Each data source is permissioned independently and has its own dictionary and symbology.

Symbology

All data sources on the platform have a native symbology, for example, the native symbology for the activ data source is the activ symbology. The platform supports presenting content to the API using different symbologies, this could be a third-party service or a file-based mapping service. This feature is only generally available for custom installations.

Dictionary

Each data source has an associated dictionary that defines the relationship between field ids and their associated name and type.

It is not necessary to use a dictionary to make use of the platform. The platform data feed is self describing and contains everything needed for deserialization. Therefore by default this information is not downloaded. To enable use of field information from dictionaries enableDictionaryDownload should be set to true in the session parameters for the session. With this enabled all dictionaries will be downloaded by default, if only a limited set of dictionaries is required this can be specified using a comma seperate list of dictionary ids in the dictionaryDownloadList parameter.

const session = await activOneApi.connect({
    sessionParameters: {
        // Set to true to enable the dictionaries to be downloaded
        enableDictionaryDownload: true,
        // Optionally specifiy the list of dictionaries to download, in this case the platform and activ dictionaries
        dictionaryDownloadList: "0,1"
    }
});

Once a dictionary is downloaded and populated it can be used to find information about the data type or name of fields. Each data source has a dictionary that is associated with it. The correct dictionary can be found by looking up using the dictionaryId field on the DataSource object, or there is a utility function getDataSourceDictionary that gets the correct dictionary for a given data source directly from the Metadata object.

Here's an example of using a dictionary to print the field information for the dictionary used for the activ data source.

/* global activOneApi */
// You may have to update the userId and password fields below.
const user = "__ACTIV_SESSION_USER_ID__";
const password = "__ACTIV_SESSION_PASSWORD__";
const host = "aop-ny4-replay.activfinancial.com";

(async function() {
    try {
        const session = await activOneApi.connect({
            host,
            user,
            password,
            onLogMessage(logType, message) {
                console.log(message);
            },
            sessionParameters: {
                // Set to true to enable the dictionaries to be downloaded
                enableDictionaryDownload: true
            }
        });

        // Get the dictionary helper for the activ data source.
        let metadata = session.getMetadata();
        let dictionary = metadata.getDataSourceDictionary(activOneApi.DataSourceId.activ);

        // Print the dictionary name.
        console.log("ACTIV data source uses the dictionary " + dictionary.name);

        // Get the field information by id.
        const fieldInfoById = dictionary.getFieldInfo(activOneApi.FieldId.FID_BID);
        console.log("FID_BID name: " + fieldInfoById.name);
        console.log("FID_BID field type: " + activOneApi.FieldType[fieldInfoById.type]);
        
        // Its also possible to get the field information by name.
        const fieldInfoByName = dictionary.getFieldInfo("Bid");
        console.log("FID_BID id: " + fieldInfoByName.id);

        // If all we want is the field name then we can get that directly from the dictionary without needing a field info object.
        console.log("FID_BID name: " + dictionary.getFieldName(activOneApi.FieldId.FID_BID));
    } catch (e) {
        console.error(`Failure: ${e}`);
    }
})();