Add Rows in Grid

What is the Add Rows in Grid Step?

The Add Rows in Grid step is specifically designed to create or update separate rows in an AirOps Grid beyond the current row where your workflow is running. This is different from simply mapping outputs to columns in your current Grid row.

⚠️ Important Distinction: If you just want to map workflow outputs as columns in the current Grid row where your workflow is running, you do not need the Add Rows in Grid step. Instead, use a JSON step at the end of your workflow.

When to Use Add Rows in Grid vs. JSON Step for Grid Outputs

Use a JSON Step (Not Add Rows in Grid) When:

You simply want to map workflow outputs to columns in the same row where your workflow is running
You want to organize multiple output values into a structured format
You're running a workflow in a Grid and want to see results in that same row

Example: Your workflow generates a title, content, and meta description.You want these to appear as columns in your Grid next to your inputs.

Use the Add Rows in Grid Step Only When:

You need to create entirely new rows in a separate Grid or in the same Grid
You want to update existing rows in another Grid

Example: Your workflow analyzes one keyword but generates 10 related keywords,each needing its own row in a separate Grid for further processing.

How to Map Outputs in a Grid (Without Add Rows in Grid)

Add a JSON step as the final step in your workflow
Structure your outputs as key-value pairs
When you run the workflow in a Grid, these keys will automatically be available to map as output columns
Select "Add Outputs as Columns" in the Grid interface after running

How to Configure the Add Rows in Grid Step (For Creating/Updating Separate Rows)

When you actually need to create or update separate rows beyond your current workflow row:

Select a Grid

Choose the Grid where you want to write your data:

Create a New Grid: Generate a new Grid to store your data
Select Existing Grid: Add data to an already existing Grid

Output Mapping

Define how the data from your workflow should be mapped to columns in the separate Grid:

Column Names: Define the names of the columns in your target Grid
Values: Select which workflow step outputs should populate each column

Write Mode

Choose how your data should be written to the Grid:

Append: Add new rows to the existing Grid data
Replace: Clear existing Grid data and replace it with the new data
Update: Update specific rows in the Grid based on a key column

How to Update Existing Rows Using `__id`

When you need to update existing rows in a Grid (rather than creating new ones), you must include the special __id field in your data. This field identifies which specific row should be updated.

Understanding `__id`

The __id field is a unique identifier that represents a specific row in your Grid:

Automatically included when you use the "Read from Grid" step
Required when updating existing rows
Must match an existing row in the target Grid
Should be an integer value (e.g., 123, not "123")

Common Workflow Pattern: Read → Modify → Update

The most common pattern for updating rows involves three steps:

Step 1: Read from Grid Use the "Read from Grid" step to get existing rows. The output will include __id for each row:

[
  {
    "__id": "123",
    "title": "Blog Post Draft",
    "status": "Draft",
    "word_count": "500"
  },
  {
    "__id": "456",
    "title": "SEO Guide",
    "status": "In Review",
    "word_count": "1200"
  }
]

Step 2: Process/Transform Data Use a Code step or other transformation steps to modify the data while preserving the __id:

// Example: Update status for all rows
const rows = steps.read_grid.output;
return rows.map(row => ({
  __id: row.__id,  // Keep the __id to identify which row to update
  status: "Published",
  published_date: new Date().toISOString()
}));

Step 3: Write Back to Grid Use the "Add Rows in Grid" step with Update mode to write the changes back. Make sure your data includes the __id field:

[
  {
    "__id": "123",
    "status": "Published",
    "published_date": "2024-01-15"
  },
  {
    "__id": "456",
    "status": "Published",
    "published_date": "2024-01-15"
  }
]

Single Row Update Example

To update a single row:

{
  "__id": "123",
  "status": "Completed",
  "completion_date": "2024-01-15",
  "notes": "Task finished successfully"
}

Multiple Row Update Example

To update multiple rows at once:

[
  {
    "__id": "123",
    "order_status": "Shipped",
    "tracking_number": "1Z999AA10123456784"
  },
  {
    "__id": "456",
    "order_status": "Shipped",
    "tracking_number": "1Z999AA10123456785"
  },
  {
    "__id": "789",
    "order_status": "Delivered",
    "delivery_date": "2024-01-14"
  }
]

Important Notes About Updating with `__id`

Required Field: When using Update mode, every object in your data must include the __id field
Existing Rows Only: The __id must reference an existing row in the Grid. If the row doesn't exist, that update will be skipped with a warning
No Duplicates: Each __id should appear only once in your update data. Duplicate IDs will be skipped
Partial Updates: You only need to include the columns you want to update. Other columns in the row will remain unchanged
Column Mapping: You still need to map the column names in the Output Mapping section, but you don't need to map the __id field - it's handled automatically

When to Use Update vs. Append

Use Update mode when:

You want to modify existing rows
You have the __id values from a previous "Read from Grid" step
You need to change specific values while keeping the row identity

Use Append mode when:

You want to add completely new rows to the Grid
You don't have __id values
You're creating fresh data entries

By understanding the distinction between simple output mapping (JSON step) and creating separate rows (Add Rows in Grid step), you'll be able to build more efficient and effective workflows.

Last updated 9 days ago

Was this helpful?