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.
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
- How to make a CSV or XLSX snapshot request
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:
- Make sure your current (working) directory is set to the Deployment Framework's topmost directory.
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.
To check whether the blade is activated, enter the command
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
To make a snapshot request, your client application must send the Liberator an HTTP request in the following format:
- [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.
Building the HTTP request parameters using StreamLink
In practice, you would use the StreamLink API to build the HTTP request for the CSV or XLSX file.
For example, in StreamLink JS:
- Call the createWebRequestParameters() method of the caplin.streamlink.Streamlink object, passing it:
- the name of the Liberator web module, which is snapshot
- 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.
- 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 must contain the following parameters:
|sessionid||The session ID of the client's StreamLink connection to the Liberator. Your client application can obtain this from the StreamLink API.|
The subject of the container to export.
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.
The names of the fields in the container records to be exported.
The separator character to be used in the CSV file.
You can include these optional HTTP request parameters:
|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.
(Available from Liberator version 6.2.5)
Defines the format of the file containing the exported data:
If you don't define a mode, the file is created in CSV format.
Example URI for requesting a container snapshot:
In this example, the parameter names are emphasised like this.
- 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.
- 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