# Display and annotate spreadsheets

Spreadsheets with a consistent table structure are well suited to normalization into datasets. To normalize spreadsheets into datasets, use Pipeline Builder's [Extract rows from an Excel file](../../pipeline-builder/functions-index/index.md#extract-rows-from-an-excel-file) transform, the [Microsoft Excel connector](../../available-connectors/microsoft-excel/index.md), or [Transforms Excel Parser](../../microsoft-excel/transforms-excel-parser/index.md).

Spreadsheet media sets preserve each `.xlsx` file and support workflows where file structures vary or the original spreadsheet must remain the source of truth. This guide shows how to import spreadsheet files, create objects and extract their contents in Pipeline Builder, and configure display and annotation in Workshop.

Review the [supported spreadsheet formats and restrictions](../media-overview/index.md#supported-media-set-schemas) before importing files.

## Prerequisites

Before you begin, ensure you have:

* Permissions to create media sets in the folder where you want to work.
* Permissions to create and deploy a [Pipeline Builder](../../pipeline-builder/overview/index.md) pipeline.
* Permissions to create action types in your Ontology. See [ontology permissions](../../object-permissioning/ontology-permissions/index.md) for more information.

## Part 1: Import spreadsheet files

To create and populate the media set:

1. Navigate to the folder where you want to create the media set. Select **New > Media set**.

   ![The New media set option in a Foundry folder.](../../../assets/63c826e117038f5c93630864979c89153bc589f1aa0c36e3cb11fe1c9f9af860.webp)

2. Enter a name for the media set and select **Spreadsheet** as the media type. Choose a [transaction policy](../media-set-settings/index.md#transaction-policies), then select **Create media set**.

3. Add one or more `.xlsx` files to the media set.

   ![Three spreadsheet files in a media set.](../../../assets/47b3dcb242836337eaa80b61e9a4002d45149ad07387d2bc58181d962b84259f.webp)

   Once added, the **Spreadsheet** media items include metadata such as the author, title, and size. Select a file to preview its sheets and cells in Foundry.

## Part 2: Create objects from spreadsheet files

Create a batch pipeline to make each spreadsheet available as an object:

1. From the media set, select **All actions > Create new pipeline**.

   ![The Create new pipeline option in the All actions menu.](../../../assets/a21bc46a01ba579140efab8a650130a9c242159263ca170e5f08ab142ebe0d84.webp)

2. From the media set node, select **Add output**.

   ![The Add output option for a spreadsheet media set node.](../../../assets/a3c21e1fee69785c0f035eddf5d081a83949e9b9f43570cd85712caed0e73d21.webp)

3. Select **New object type**.

   ![The New object type output option.](../../../assets/9952ff6c70d235609be635b8685e1ae5dc6ac25fa3b4bbef001aff85e07e28ea.webp)

4. Enter a name for the object type, such as `Spreadsheet`. Keep the `media reference` property mapped and set `media item RID` as the primary key.

   ![An object type output configured for spreadsheet media items.](../../../assets/f64b7d9f26a3d3124593796805da35e7dd159a91c762e3caa411a51bd6f00ac6.webp)

5. [Save and deploy the pipeline](../../pipeline-builder/outputs-deliver-pipeline/index.md).

### Extract cell contents

To process cell contents in a separate tabular branch of the pipeline:

1. Select the media set node, then select **Transform**.
2. Search for and select [**Extract content from spreadsheets in JSON**](../../pipeline-builder/functions-index/index.md#extract-content-from-spreadsheets-in-json).
3. Set **Media reference** to the `media reference` column. Configure **Output fields** and **Error handling** as needed, then select **Apply**.

The output is a map keyed by sheet name. Each value contains the selected **Table** and **Merged cells** fields. Continue transforming the extracted content or add it to a pipeline output.

## Part 3: Create an annotation object type and action

This example is illustrative. Because your Ontology is customized to your data, the object and action types referenced below may not exist in your enrollment. Create equivalents that match your data model.

Annotations are stored as objects. In Ontology Manager, create an annotation object type with the following properties:

* A primary key, such as an `annotation ID` string
* A `sheet name` string
* A `cell range` string in the [JSON format returned by the Spreadsheet Display widget](../../workshop/widgets-spreadsheet-display/index.md#configuration-options)
* A link to the `Spreadsheet` object type, so annotations can be filtered to the displayed spreadsheet

Cell ranges are zero-indexed, so cell A1 is `(0,0)`.

Create an [action](../../workshop/actions-use/index.md) that creates an annotation object. Add parameters for the sheet name, cell range, and current spreadsheet object. Map these parameters to the corresponding properties and link, and populate the annotation primary key.

## Part 4: Display and annotate spreadsheets in Workshop

To build the Workshop module:

1. From the deployed object output, select **Create Workshop module**.

   ![The Create Workshop module option on a deployed object output.](../../../assets/273149f33aefc5f7b5e4ec550f91eb7d8087889d151fad40dd1d18bf7c9f8f16.webp)

2. Add an [**Object List**](../../workshop/widgets-object-list/index.md) or [**Object Table**](../../workshop/widgets-object-table/index.md) widget and a **Spreadsheet Display** widget to the module.

3. In the **Spreadsheet Display** widget, set **Object set with a single object** to the active object from the list or table. Set **Spreadsheet media reference property** to the `media reference` property created in Part 2.

4. Enable **Spreadsheet annotations**, add an annotation layer, and configure the following inputs:

   * **Annotation layer name:** Enter a name for the layer.
   * **Object set:** Select the annotation object set and filter it to the active spreadsheet object.
   * **Sheet name property:** Select the `sheet name` property.
   * **Cell range property:** Select the `cell range` property.

5. Under **Configure Interactions**, add an interaction and select the action created in Part 3. Map the widget-provided **Sheet Name** and **Selected Cell Range** values to the corresponding action parameters. Map the active spreadsheet object to the link parameter.

You can now select a cell range and run the action to save an annotation. For all configuration options, see [Spreadsheet Display widget](../../workshop/widgets-spreadsheet-display/index.md).