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

**📌 NOTE**\
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](../deployment-framework/cdf-built-in-blades.md)) [Config blade](../deployment-framework/cdf-blade-types.md#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 xref:../deployment-framework/cdf-the-deployment-framework-command-utility-dfw.md#activate[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 xref:../deployment-framework/cdf-the-deployment-framework-command-utility-dfw.md#versions[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`](liberator-http-configuration-part-1.md) and [`https-port`](liberator-https-configuration.md)).
* `[exportdir]` is the value of the `url` option in the Liberator’s `add-webmod` configuration item, without the preceding <q>``/``</q>

  (`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:

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](#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. |
| `<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` | 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 <q>``=``</q> 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 <q>``,``</q> (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](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. |

**📌 NOTE**\
You can also [format individual fields](liberator-format-fields-for-export-to-a-csv-or-xlsx-file.md) 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 <q>``BidPrice``</q>.
  * `BestAsk=AskPrice` The field `BestAsk` is to be included in a column headed <q>``AskPrice``</q>.
* Since the HTTP request doesn’t contain a `mode` parameter, Liberator produces the container snapshot in CSV format.

---

**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)