# Worksheets

Source: https://docs.interop.io/adapters/bloomberg/tapi-bridge/worksheets/index.html

## Overview

The Bloomberg Worksheets are spreadsheets containing a list of securities to monitor. Through the Bloomberg Adapter API, when you create, delete or update a Bloomberg worksheet, the changes are synchronized across the Bloomberg apps and your interop-enabled apps in both directions.

## Worksheet Operations

### Get Worksheets

To get the known Bloomberg Worksheets, use the `"T42.BBG.GetWorksheets"` method.

The `"T42.BBG.GetWorksheets"` method doesn't accept any arguments and returns an array of `Worksheet` objects with the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `id` | `string` | Bloomberg ID of the worksheet. |
| `isActive` | `boolean` | Whether the worksheet is active or deactivated. |
| `name` | `string` | Name of the worksheet. |

Example:

```javascript
const result = await io.interop.invoke("T42.BBG.GetWorksheets");

// Example value:
// [
//     { id: "w-3621FCB487E84794A4DB8E4D6CA2042F", name: "Test Worksheet", isActive: true },
//     { id: "w-4FA26721722F47A9817AFA05FFF60F87", name: "New Worksheet", isActive: true }
// ]
const worksheets = result.returned.worksheets;
```

### Create Worksheets

To create a new Bloomberg Worksheet with an initial list of securities, use the `"T42.BBG.CreateWorksheet"` method. This will create a new worksheet within the Bloomberg Terminal which can later be updated by `worksheetId`.

The `"T42.BBG.CreateWorksheet"` method accepts as an argument an object with the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `name` | `string` | **Required.** The name for the new worksheet. |
| `securities` | `string[]` | **Required.** An array of securities to include in the worksheet. |

The `"T42.BBG.CreateWorksheet"` method returns a `Worksheet` object with the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `id` | `string` | Bloomberg ID of the created worksheet. |
| `isActive` | `boolean` | Whether the worksheet is active or deactivated. |
| `name` | `string` | Name of the worksheet. |

Example:

```javascript
const invocationArgs = {
    name: "Test Worksheet",
    securities: ["VOD LN Equity", "BARC LN Equity"]
};

const result = await io.interop.invoke("T42.BBG.CreateWorksheet", invocationArgs);

// Example value:
// { id: "w-954D2AD1EB8D4C6C9DD7514E940D46AB", name: "Test Worksheet", isActive: true }
const worksheet = result.returned.worksheet;
```

## Worksheet Context

### Get Worksheet Securities

To retrieve the securities of a worksheet by a given worksheet ID, use the `"T42.BBG.GetWorksheetSecurities"` method. IDs can be retrieved with a `"T42.BBG.GetWorksheets"` call for existing worksheets or `"T42.BBG.CreateWorksheet"` for new worksheets.

The `"T42.BBG.GetWorksheetSecurities"` method accepts as an argument an object with the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `worksheetId` | `string` | **Required.** The Bloomberg ID of the worksheet. |

The `"T42.BBG.GetWorksheetSecurities"` method returns a string array of the securities that the worksheet contains.

Example:

```javascript
const worksheetsResult = await io.interop.invoke("T42.BBG.GetWorksheets");
const worksheets = worksheetsResult.returned.worksheets;
const worksheet = worksheets.find(w => w.name === "Test Worksheet");

const invocationArgs = { worksheetId: worksheet.id };
const result = await io.interop.invoke("T42.BBG.GetWorksheetSecurities", invocationArgs);

// Example value: ["VOD LN Equity", "BARC LN Equity"]
const securities = result.returned.securities;
```

### Replace Worksheet Securities

To replace the securities of a worksheet, use the `"T42.BBG.SetWorksheetSecurities"` method. All existing securities will be removed and replaced by the specified ones.

The `"T42.BBG.SetWorksheetSecurities"` method accepts as an argument an object with the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `securities` | `string[]` | **Required.** An array of securities with which to replace the existing ones. |
| `worksheetId` | `string` | **Required.** The Bloomberg ID of the worksheet. |

The `"T42.BBG.SetWorksheetSecurities"` method returns `void`.

Example:

```javascript
const worksheetsResult = await io.interop.invoke("T42.BBG.GetWorksheets");
const worksheets = worksheetsResult.returned.worksheets;
const worksheet = worksheets.find(w => w.name === "Test Worksheet");

const invocationArgs = {
    worksheetId: worksheet.id,
    securities: ["MSFT US Equity"]
};

await io.interop.invoke("T42.BBG.SetWorksheetSecurities", invocationArgs);
```

### Append Worksheet Securities

To append securities to a worksheet, use the `"T42.BBG.AppendWorksheetSecurities"` method. The specified securities will be appended to the existing ones.

The `"T42.BBG.AppendWorksheetSecurities"` method accepts as an argument an object with the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `securities` | `string[]` | **Required.** An array of securities to append to the existing ones. |
| `worksheetId` | `string` | **Required.** The Bloomberg ID of the worksheet. |

The `"T42.BBG.AppendWorksheetSecurities"` method returns `void`.

Example:

```javascript
const worksheetsResult = await io.interop.invoke("T42.BBG.GetWorksheets");
const worksheets = worksheetsResult.returned.worksheets;
const worksheet = worksheets.find(w => w.name === "Test Worksheet");

const invocationArgs = {
    worksheetId: worksheet.id,
    securities: ["VOD LN Equity", "BARC LN Equity"]
};

await io.interop.invoke("T42.BBG.AppendWorksheetSecurities", invocationArgs);
```

### Remove Worksheet Securities

To remove securities from a worksheet, use the `"T42.BBG.RemoveWorksheetSecurities"` method. The specified securities will be removed from the worksheet.

The `"T42.BBG.RemoveWorksheetSecurities"` method accepts as an argument an object with the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `securities` | `string[]` | **Required.** An array of securities to remove from the worksheet. |
| `worksheetId` | `string` | **Required.** The Bloomberg ID of the worksheet. |

The `"T42.BBG.RemoveWorksheetSecurities"` method returns `void`.

Example:

```javascript
const worksheetsResult = await io.interop.invoke("T42.BBG.GetWorksheets");
const worksheets = worksheetsResult.returned.worksheets;
const worksheet = worksheets.find(w => w.name === "Test Worksheet");

const invocationArgs = {
    worksheetId: worksheet.id,
    securities: ["MSFT US Equity"]
};

await io.interop.invoke("T42.BBG.RemoveWorksheetSecurities", invocationArgs);
```