# Add Rows in Grid

The Add Row(s) in Grid step lets you create new rows or update existing rows in any Grid from within your workflow. Use this step when you need to write data to a different Grid or add new rows beyond the current row where your workflow is running.

{% hint style="info" %}
If you want to map workflow outputs to columns in the same row where your workflow is running, you don't need this step. Use a JSON step at the end of your workflow and map the outputs as columns in the Grid interface.
{% endhint %}

## How to Configure

### 1. Select Grid and Sheet

Choose the target Grid and Sheet where you want to write data. Both fields support Static or Dynamic selection:

* **Static**: Select from a dropdown of available Grids/Sheets
* **Dynamic**: Reference a variable containing the Grid or Sheet ID

### 2. Choose an Action Type

Select one of four action types based on your needs:

| Action Type              | Description                                             |
| ------------------------ | ------------------------------------------------------- |
| **Add Single Row**       | Create one new row from a single JSON object            |
| **Add Multiple Rows**    | Create multiple new rows from an array of objects       |
| **Update Single Row**    | Update one existing row using its `__id`                |
| **Update Multiple Rows** | Update multiple existing rows using their `__id` values |

### 3. Provide the Data Variable

Select a variable containing your row data:

**For single row actions**, provide an object:

```json
{
  "title": "Ultimate Guide to Link Building",
  "backlinks": "150"
}
```

**For multiple row actions**, provide an array of objects:

```json
[
  {
    "title": "Ultimate Guide to Link Building",
    "backlinks": "150"
  },
  {
    "title": "SEO Best Practices",
    "backlinks": "89"
  }
]
```

### 4. Map Object Keys to Grid Columns

Use the column mapping interface to connect your JSON keys to existing Grid columns. Click **Add Column Mapping** and specify:

* **Key**: The key name from your JSON object
* **Column**: The target column in your Grid

### 5. Set Failure Behavior

Choose what happens if the step fails:

* **Terminate Workflow**: Stop the workflow execution
* **Continue**: Proceed to the next step despite the error

## Updating Existing Rows

When using **Update Single Row** or **Update Multiple Rows**, your data must include the `__id` field to identify which rows to update. This field is automatically included when you read rows using the Read from Grid step.

### Example: Read, Modify, and Update

**Step 1**: Use Read from Grid to get existing rows with their `__id` values:

```json
[
  {
    "__id": "123",
    "title": "Blog Post Draft",
    "status": "Draft"
  },
  {
    "__id": "456",
    "title": "SEO Guide",
    "status": "In Review"
  }
]
```

**Step 2**: Transform the data in a Code step while preserving the `__id`:

```javascript
const rows = steps.read_grid.output;
return rows.map(row => ({
  __id: row.__id,
  status: "Published",
  published_date: new Date().toISOString()
}));
```

**Step 3**: Use Add Row(s) in Grid with **Update Multiple Rows** to write the changes back.

### Update Behavior

* Each object must include an `__id` that matches an existing row
* Only the columns you include will be updated; other columns remain unchanged
* Rows with non-matching `__id` values will be skipped
* You don't need to map `__id` in the column mapping section

## When to Use This Step

**Use Add Row(s) in Grid when:**

* Creating new rows in a separate Grid
* Adding multiple rows generated from a single workflow run
* Updating existing rows in any Grid

**Use a JSON step instead when:**

* Mapping outputs to columns in the current Grid row
* Organizing multiple outputs into a structured format for the same row