---
title: "Add Worksheet"
description: "Add a new worksheet to a OneDrive-hosted Excel file."
icon: "plus"
---

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.
