Obtain a container snapshot in a CSV or XLSX file

Here’s how a client application can obtain snapshots of container contents from Liberator, supplied in CSV (comma-separated values) or Office Open XML Workbook (.xlsx) formatted files.

The Office Open XML Workbook format is supported as a snapshot format by Linux builds of Liberator 6.2.5 or later.

You can use Liberator’s Snapshot web service (a web module) to download a file containing an image of a container. For example, in Caplin FX Professional, end-users can download snapshots of their trade blotters as CSV files.

The returned file contains the constituents of the container in individual rows with columns representing the fields you requested. If the request is for a single record, the record is returned as a single row. If a field you requested isn’t present in a record, the corresponding "cell" in the file is empty.

Contents:

Enabling the Snapshot web module
Requesting a container snapshot using SLJS and CT
Snapshot URL format

Enabling the Snapshot web module

To use the Liberator Snapshot web module, your Liberator must be licensed to use the Snapshot module.

The CSV / XLSX snapshot capability in Liberator is provided as a (built-in) Config blade called BlotterExport. This blade is deactivated by default.

To activate the BlotterExport blade, follow the steps below:

From the root directory of your Deployment Framework, enter the command below:
```
./dfw activate BlotterExport
```
To check whether the blade is activated, enter the command:
```
./dfw versions
```

Requesting a container snapshot using SLJS and CT

This section describes how to request a container snapshot using StreamLink JS’s WebRequestParameters class and Caplin Trader’s FileDownloader service. The WebRequestParameters class is designed specifically for building URLs to Liberator web modules.

To create an instance of WebRequestParameters call the method createwebrequestparameters(capability_name, options) of your application’s StreamLink instance, passing it the following parameters:

capability_name: the name of the web-module capability. The Snapshot web module exposes two capabilities: blotterexport and blotterexportxhr. To build a URL for use with the Caplin Trader FileDownloader object, specify the blotterexport capability.
options: a JavaScript map of the options to send the web-module. For the options supported by the Snapshot module, see Snapshot module parameters.

The method returns an instance of WebRequestParameters that contains the URI and HTTP post body used to access the required Liberator web module. Use the getUrl() and getPostBody() methods of the WebRequestParameters object to obtain the URI and HTTP post body that must be sent to the Liberator.

Requesting a container snapshot using StreamLink JS

/**
 * Convert a query-string encoded string into a JavaScript object
 */
function parseQueryString(qs) {
  qs = qs.replace('+', '%20');
  var obj = {};
  var pairs = qs.split('&');
  for (var i = 0; i < pairs.length; i++) {
    var elements = pairs[i].split('=');
    if (elements.length == 1) {
      obj[decodeURIComponent(elements[0])] = "";
    } else if (elements.length == 2) {
      obj[decodeURIComponent(elements[0])] = decodeURIComponent(elements[1]);
    }
  }
  return obj;
}

var ServiceRegistry = require("caplin/core/ServiceRegistry");
var FileDownloader = require("caplin/dom/FileDownloader");
var streamlink = ServiceRegistry.getService("caplin.connection-service").getStreamlink();

// Which capability of the Snapshot module to use
var webModCapability = "blotterexport";

var filename = "my-export.csv"; // File name must include the extension
var params = {
  "export": "/EXAMPLES/PRICING/CONTAINER/EQUITIES", // required
  "fields":"FullName,BestBid,BestAsk", // required
  "separator":",", // optional
  "lang":"en", // optional
  "mode":"csv" // optional
};

// Create a WebRequestParameters object
var webModParams = streamlink.createWebRequestParameters(webModCapability, params);

// Call Caplin Trader's FileDownloader to start the download
var url = webModParams.getUrl() + "/" + filename;
var fields = parseQueryString(webModParams.getPostBody());
FileDownloader.downloadFile(url, fields);

An example URL is shown below:

https://myliberator:18081/exportcsv/my-export.csv?mode=csv&sessionid=0QwrlRYSBfLLQbny2Re3Pa&export=/EXAMPLES/PRICING/CONTAINERS/EQUITIES&fields=FullName%2CBestBid%2CBestAsk&separator=%2C&lang=en

Snapshot URL format

This section is a reference for the Snapshot module’s URL format.

We recommend that you build Snapshot URLs using StreamLink’s WebRequestParameters class. See Requesting a container snapshot using SLJS and CT for more details.

Snapshot URL format

http(s)://<host>:<port>/<capability_name>/<snapshotFileName>?<parameters>

<port> is the standard (configured) Liberator HTTP or HTTPS port (see http-port and https-port).
<capability_name> is one of two capabilities exposed by the Snapshot web module: blotterexport and blotterexportxhr. To build a URL for use with the Caplin Trader FileDownloader object, specify the blotterexport capability.
<snapshotFileName> is an arbitrary filename for the snapshot. You should include the file extension (.csv or .xlsx), as this isn’t automatically added to the name.
<parameters> are parameters to pass to the Snapshot web module. See Snapshot module parameters below.

Example URL

https://myliberator:18081/exportcsv/my-export.csv?mode=csv&sessionid=0QwrlRYSBfLLQbny2Re3Pa&export=/EXAMPLES/PRICING/CONTAINERS/EQUITIES&fields=FullName%2CBestBid%2CBestAsk&separator=%2C&lang=en

Snapshot module parameters

This section details the query string parameters accepted by the Snapshot web module.

In addition to query string parameters, the Snapshot web module also accepts configuration for formatting exported fields. See Format fields for export to a CSV or XLSX file.

Mandatory parameters
Parameter	Description
`export`	The subject of the container to export. Example: `export=/EXAMPLES/PRICING/CONTAINERS/EQUITIES` Liberator version 6.2.4 and later: To export multiple containers, separate the container subjects with the separator defined by export-separator in `<framework-root>/global_config/overrides/servers/Liberator/etc/snapshot.conf`. By default, export-separator is not defined and only one container can be exported per snapshot.
`fields`	A comma-separated list of field names to export. Each field name in the list can be in one of two formats: `<field name>` `<field name>[;<field name>]…=<column title>` where `<field name>` is the name of the field and `<column title>` is the title to give the field’s column in the spreadsheet. If no `<column title>` is specified for field, it defaults to `null` (no title). The second format allows you to concatenate fields in a single column. For example: `field1;field2;field3=columnname`. To configure the formatting of exported fields, see Format fields for export to a CSV or XLSX file.
`sessionid`	The session ID of the client’s StreamLink connection to the Liberator. This is automatically included when you build the URL using a StreamLink `WebRequestParameters` object (see Requesting a container snapshot using SLJS and CT).

Optional parameters
Parameter	Description
`lang`	The language into which specified field values are to be translated. See Translating field values using the translate: formatter in How can I… Format fields for export to a CSV or XLSX file. For example: `lang=fr` which specifies translation to French.
`mode`	(Available from Liberator version 6.2.5) Defines the format of the file containing the exported data: `mode=xlsx` creates a file in XLSX (Office Open XML) format. `mode=csv` creates a file in CSV (Comma Separated Variables) format. If you don’t define a `mode`, the file is created in CSV format.
`separator`	The separator character to be used in the CSV file. Defaults to comma ‘`,`’ If the separator is `%`, use the URL encoding for the percentage symbol: `%25`
`zoneoffset`	The offset of the requester’s time zone from UTC, in minutes. This value is used for formatting timestamp values in local time (see the Localtime formatter in Format fields for export to a CSV or XLSX file). Examples: To specify an offset of 2 hours ahead of UTC, specify `zoneoffset=+120` To specify an offset of 2 hours behind UTC, specify `zoneoffset=-120`

See also:

How can I… Format fields for export to a CSV or XLSX file
Reference: Liberator Snapshot web module configuration
Features and Concepts: Liberator web modules
Features and Concepts: Containers
How containers work
How can I… Configure container usage in Liberator
How can I… Create containers in an Integration Adapter
How can I… Obtain container data from several sources
Filtering and sorting containers using Transformer’s Refiner Service blade