# 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.

**📌 NOTE**\
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](liberator-web-modules.md)) 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.

## Enabling the Snapshot web module

**📌 NOTE**\
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](../deployment-framework/cdf-built-in-blades.md)) [Config blade](../deployment-framework/cdf-blade-types.md#config-blade) called **BlotterExport**. This blade is deactivated by default.

To activate the **BlotterExport** blade, follow the steps below:

1. From the root directory of your Deployment Framework, enter the command below:

   ```
   ./dfw activate BlotterExport
   ```
2. 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`](https://docs.caplin.com/developer/api/streamlinkjs/latest/classes/WebRequestParameters.html) 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__)`](https://docs.caplin.com/developer/api/streamlinkjs/latest/classes/StreamLink.html#createWebRequestParameters) of your application’s [`StreamLink`](https://docs.caplin.com/developer/api/streamlinkjs/latest/classes/StreamLink.html) 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`](https://docs.caplin.com/developer/api/caplin_trader/latest/module-ct-dom_FileDownloader.html) 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](#snapshot-module-parameters).

The method returns an instance of [`WebRequestParameters`](https://docs.caplin.com/developer/api/streamlinkjs/latest/classes/WebRequestParameters.html) 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**

```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](#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`](liberator-http-configuration-part-1.md) and [`https-port`](liberator-https-configuration.md)).
* `<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`](https://docs.caplin.com/developer/api/caplin_trader/latest/module-ct-dom_FileDownloader.html) 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](#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.

**📌 NOTE**\
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](liberator-format-fields-for-export-to-a-csv-or-xlsx-file.md).

**Mandatory parameters**

| Parameter | Description |
| --- | --- |
| `<a name="export"></a>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](liberator-snapshot-web-module-configuration.md#export-separator) in `<framework-root>/global_config/overrides/servers/Liberator/etc/snapshot.conf`. By default, [export-separator](liberator-snapshot-web-module-configuration.md#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](liberator-format-fields-for-export-to-a-csv-or-xlsx-file.md). |
| `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](#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](liberator-format-fields-for-export-to-a-csv-or-xlsx-file.md#translating-field-values-using-the-translate-formatter) in How can I... [Format fields for export to a CSV or XLSX file](liberator-format-fields-for-export-to-a-csv-or-xlsx-file.md). 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 <q>``,``</q> 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](liberator-format-fields-for-export-to-a-csv-or-xlsx-file.md#setting-a-timezone-offset-using-the-localtime-formatter) in [Format fields for export to a CSV or XLSX file](liberator-format-fields-for-export-to-a-csv-or-xlsx-file.md)). 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](liberator-format-fields-for-export-to-a-csv-or-xlsx-file.md)
* Reference: Liberator [Snapshot web module configuration](liberator-snapshot-web-module-configuration.md)
* Features and Concepts: [Liberator web modules](liberator-web-modules.md)
* Features and Concepts: [Containers](../datasource/datasource-containers.md)
* [How containers work](../datasource/datasource-how-containers-work.md)
* How can I... [Configure container usage in Liberator](liberator-configure-container-usage-in-liberator.md)
* How can I... [Create containers in an Integration Adapter](../datasource/datasource-create-containers-in-an-integration-adapter.md)
* How can I... [Obtain container data from several sources](../datasource/datasource-obtain-container-data-from-several-sources.md)
* Filtering and sorting containers using [Transformer’s Refiner Service blade](../transformer/transformer-refiner-overview.md)