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 can present content to the API using different symbologies..

Alias symbols are provided using this mechanism under the activAlias symbology id. Alternative symbols could also be sourced from a third-party service or a file-based mapping service in custom installations.

Dictionary

Each data source has an associated dictionary that defines the relationship between field ids and their name and type. For the activ data sources there is a single dictionary, the activ dictionary, for local and platform data sources the platform dictionary is used. The API downloads all available dictionaries by default

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);
            },
        });

        // 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: ${activOneApi.StatusCode[e]}`);
    }
})();

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.

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