> ## Documentation Index
> Fetch the complete documentation index at: https://explore.airia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Add Worksheet

> Add a new worksheet to a OneDrive-hosted Excel file.

The **Excel — Add Worksheet** step adds a new, empty worksheet to an existing Excel file in OneDrive or SharePoint. Use it before [Write Row](/building-and-deploying-agents/agent-basics/onedrive-excel-write-row) when you want a dedicated tab — for example, a fresh worksheet per agent run, per day, or per customer.

***

## Prerequisites

* The **OneDrive Excel** steps must be enabled on your workspace (feature flag: `step-sdk-onedrive-excel`).
* A **Microsoft OAuth credential** with edit access to the file.
* The Excel file already exists at the configured **Path**. The step does not create the file.

***

## Inputs

| Parameter          | Required | Description                                                             |
| ------------------ | -------- | ----------------------------------------------------------------------- |
| **Credential**     | Yes      | The Microsoft OAuth credential used to access the file.                 |
| **Path**           | Yes      | The file path in OneDrive, for example `/Documents/MySpreadsheet.xlsx`. |
| **Worksheet Name** | Yes      | The name for the new worksheet, for example `NewSheet1`.                |

<Info>
  Both **Path** and **Worksheet Name** accept `{{variable}}` expressions, so the name can be derived at runtime — for example `Run-{{Helpers.currentDateTime}}`.
</Info>

***

## Outputs

| Variable               | Type     | Description                                                                         |
| ---------------------- | -------- | ----------------------------------------------------------------------------------- |
| `Worksheet.Id`         | `string` | The Graph-assigned identifier for the new worksheet.                                |
| `Worksheet.Name`       | `string` | The worksheet name as stored by Excel (after Excel applies any name normalization). |
| `Worksheet.Position`   | `int`    | The zero-based position of the new worksheet within the workbook.                   |
| `Worksheet.Visibility` | `string` | The worksheet's visibility state. New worksheets are `Visible` by default.          |

Reference these as `{{Steps.Add_Worksheet.Worksheet.Name}}`.

***

## Examples

### 1) Create a dated worksheet, then write to it

1. **Add Worksheet**
   * **Path:** `/Logs/Agent Runs.xlsx`
   * **Worksheet Name:** `Run-{{Helpers.currentDateTime}}`
2. **[Write Row](/building-and-deploying-agents/agent-basics/onedrive-excel-write-row)**
   * **Path:** `/Logs/Agent Runs.xlsx`
   * **Worksheet Name:** `{{Steps.Add_Worksheet.Worksheet.Name}}`
   * **Row Values:** `{{Steps.Run.Result}},{{Steps.Run.Duration}}`

Using `Worksheet.Name` from the Add step is safer than hardcoding the same expression, because Excel may normalize names (for example, trimming or replacing invalid characters).

### 2) Conditionally add a worksheet

1. **[List Worksheets](/building-and-deploying-agents/agent-basics/onedrive-excel-list-worksheets)**.
2. **Compare step** — does the list contain an entry with `Name == "Today"`?
   * If no → **Add Worksheet** with **Worksheet Name** = `Today`.
   * If yes → skip.
3. Continue with **Write Row** to `Today`.

***

## Notes and limitations

* **No file creation.** The step requires an existing Excel file.
* **Name conflicts cause failure.** If a worksheet with the same name already exists, Graph returns an error. Use [List Worksheets](/building-and-deploying-agents/agent-basics/onedrive-excel-list-worksheets) to check first if you can't guarantee uniqueness.
* **Excel name rules apply.** Worksheet names cannot exceed 31 characters and cannot contain `: \ / ? * [ ]`. Graph rejects invalid names.
* **New worksheets are appended** at the end of the workbook. Reordering is not supported by this step.