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 some Caplin Trader Motifs, 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.

How to configure Liberator to handle CSV/XLSX snapshot requests

To use the Liberator snapshot web service, your Liberator must be licenced to use the snapshot module.

The CSV / XLSX snapshot capability in Liberator is provided as a (built-in) Config blade called BlotterExport. This blade isn’t active when you first install Liberator, so to allow Liberator to handle snapshot requests, activate the blade:

  1. Make sure your current (working) directory is set to the Deployment Framework’s topmost directory.

  2. Enter the command:

    ./dfw activate BlotterExport

    To which the response should be:

    Activating BlotterExport
Blades ok
The configuration has been updated. The new configuration will not be active until the Framework is restarted.

  3. To check whether the blade is activated, enter the command

    ./dfw versions

    The response will be like this:

    Deployment Framework           6.2.0-295123

Core components                Version
-----------------------------------------------------------
Liberator                      6.2.2-297456
Transformer                    6.2.3-298229

Deployed blades                Version            State
-----------------------------------------------------------
RefinerService                 6.2.3-297580       Active
BlotterExport                  6.2.2-297456       Active
DirectConnection               6.2.2-297456       Active

How to make a CSV or XLSX snapshot request

To make a snapshot request, your client application must send the Liberator an HTTP request in the following format:

http(s)://[liberator-hostname]:[liberator-http(s)-port]/[exportdir]/[snapshotFileName]?[parameters]

  • [liberator-http(s)-port] is the standard (configured) Liberator HTTP or HTTPS port (see http-port and https-port).

  • [exportdir] is the value of the url option in the Liberator’s add-webmod configuration item, without the preceding ‘/’

    (add-webmod is defined in the BlotterExport blade configuration file <Framework-root>/kits/Liberator/Liberator-<version>/etc/blades/BlotterExport/Liberator/etc/rttp.conf where <Framework-root> is the file path of the Deployment Framework’s topmost directory for the Platform installation).

  • [snapshotFileName] is the name of the file into which the snapshot is written. You should include the file extension (.csv or .xlsx), as this isn’t automatically added to the name.

  • [parameters] is the HTTP request parameters.

In practice, you would use the StreamLink API to build the HTTP request for the CSV or XLSX file.

For example, in StreamLink JS:

  1. Call the createWebRequestParameters() method of the caplin.streamlink.Streamlink object, passing it:

    1. the name of the Liberator web module, which is snapshot

    2. a Map containing each of the HTTP request parameters you wish to send. The required and optional parameters are defined below in The HTTP request parameters.

  2. The method returns an instance of caplin.streamlink.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 to obtain the URI and HTTP post body that must be sent to the Liberator.

The HTTP request parameters

The HTTP request must contain the following parameters:

Parameter name Description

sessionid

The session ID of the client’s StreamLink connection to the Liberator. Your client application can obtain this from the StreamLink API.

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

The names of the fields in the container records to be exported.

  • The format is FieldName1,FieldName2,…​ or FieldName1=ColumnName1,FieldName2=ColumnName2,…​

  • You can specify any of the fields in the alternative format FieldName=ColumnName. The column for the FieldName in the returned CSV file is then given the name ColumnName. Columns that aren’t specified using the ‘=’ syntax aren’t named in the CSV file.

  • You can merge multiple fields into a single CSV column, using the format FieldName1;FieldName2;FieldName3=ColumnName

separator

The separator character to be used in the CSV file.

For example: separator=@

  • If the separator is %, specify it as separator=%25

  • The default separator is of course ‘,’ (comma)

You can include these optional HTTP request parameters:

PARAMETER NAME 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=frwhich 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.
You can also format individual fields before they are exported to the CSV or XLSX file.

Example URI for requesting a container snapshot:

In this example, the parameter names are emphasised like this:

https://myliberator:18081/exportcsv/mysnapshot.csv?sessionid=1fP_oSRrY4Al&export=/EXAMPLES/PRICING/CONTAINERS/EQUITIES&separator=,&fields=BestBid=BidPrice,BestAsk=AskPrice

  • The Liberator hostname is myliberator, and its port (18081) is the standard HTTPS port used in the Deployment Framework.

  • [exportdir] is the directory exportcsv, corresponding to the value of the url option in the Liberator’s add-webmod configuration item.

    (add-webmod is defined in the BlotterExport blade configuration file <Framework-root>/kits/Liberator/Liberator-<version>/etc/blades/BlotterExport/Liberator/etc/rttp.conf).

  • [snapshotFileName] is the file mysnapshot.csv

  • The sessionid parameter is the Liberator session 1fP_oSRrY4Al

  • The export parameter specifies a container whose subject is /CONTAINER/SimpleContainer

  • The separator parameter specifies that the separator character in the CSV file is to be a comma (,) .

  • The fields parameter specifies:

    • BestBid=BidPrice The field BestBid is to be included in a column headed “BidPrice”.

    • BestAsk=AskPrice The field BestAsk is to be included in a column headed “AskPrice”.

  • Since the HTTP request doesn’t contain a mode parameter, Liberator produces the container snapshot in CSV format.

See also: