Turn your extractor’s JSON output into clean, structured rows in Google Sheets with ease.

Why this guide?

After your document is processed by an extractor in UpBrains AI, the results arrive as a JSON object. Two keys matter most when you’re ready to push data into a spreadsheet:

• fields – all header-level values (e.g., Invoice Number, Invoice Total, Vendor Name)

• items – all line-item values (e.g., individual products/services, quantities, prices)

You can see a full JSON example in Section B (Structured Output JSON example) of our docs: https://upbrains.ai/documentation/extractor-data-schema.

This post walks you through mapping those JSON values into a Google Sheet using the Google Sheet Tool in your UpBrains AI flow.

Prerequisites

1. A completed Extract Information step in your agent flow (i.e., you already ran the extractor on a document and tested).

2. A Google account and a spreadsheet set up (or permission to create one).

3. The Google Sheet Tool enabled in your UpBrains AI workspace (with a valid connection).

Step 1. Add the Google Sheet Tool After Extraction

In your flow builder:

1. Using the + sign, select Google Sheet tool right after your Extract Information action.

Step 2. Configure the Tool to Insert a Row

Inside the Google Sheet Tool node:

1. Action: Select Insert Row.

2. Connection: Choose or create your Google Sheet connection (OAuth). Once authorized, a list of your spreadsheets will appear.

3. Spreadsheet & Sheet: Select the specific spreadsheet and sheet to target. If authorization is successful, these lists populate automatically.

Step 3. Confirm Header Row and Load Columns

If your first row in Google Sheets contains column headers:

• Toggle “Are the first row headers?” to ON.

• The tool will then load and display your column names, so you can map values to them. You should see something like this:

Step 4. Map Extracted Data Into Spreadsheet Rows

The key to mapping is navigating the extractor JSON tree in the value picker. Use the search box in the mapping dialog to jump straight to fields by name.

4.1 Header Fields (fields key)

You’ll map each desired header field to its corresponding sheet column. For example, to map the Invoice Total from your extractor result to a Price column in Google Sheets, choose one of the following JSON paths depending on whether you want the numeric or textual version:

• Numeric value without currency symbols:
  Extract Information → Extractor Information 0 → Extractor Result → documents → document 0 → fields → Invoice Total → details → value

• Text content (may include symbols like "$"):
  Extract Information → Extractor Information 0 → Extractor Result → documents → document 0 → fields → Invoice Total → content

Once you select the respective key in the tree, you will see it assigned to the respective cell in the sheet:

Pro tip: Type the name of your field (e.g., “invoice total”) into the search box in the mapping dialog to jump directly to the field.

4.2 Line Items (items key) – Loop & Insert Rows

Because items is an array (one entry per line item), you’ll usually want each item to become its own row. Here’s how:

1. Add a Loop step after the extraction step (before the Google Sheet tool), and set the Loop’s Input Array to the line items:
   Extract Information → Extractor Information 0 → Extractor Result → documents

   

2. Inside the Loop, add another Google Sheet Tool → Insert Row action:

   • Map each line item field from the Loop item (e.g., item.description, item.quantity, item.unit_price) to a column in the sheet.

   • Each iteration of the loop creates one new row in the spreadsheet.

     The typical path for the value is as before, but from the Loop on Items element:

     • Loop on Items → item → items 0 → Unit Price → content (if the field type is declared as Text in the extractor)

     • Loop on Items → item → items 0 → Unit Price → details → value(if the field type is declared as Number in the extractor)

The Loop step’s item object corresponds to a single line item from the extractor JSON. Map from item.fields.<FieldName>.details.value or item.fields.<FieldName>.content depending on what you need.

Example Flow (High-Level)

You can insert a single header row (invoice-level info) first, and then append the line items below it using the loop. Alternatively, if your sheet is dedicated to line items only, just run the loop insert.

Tips & Troubleshooting

1. Numeric vs. Text Values (depending on the choice is made in the Extractor definition time for each field type)

• Use details.value for clean numeric values.

• Use content for text as-is (e.g., includes “$” or additional formatting).

2. Missing Columns?

• If your sheet’s first row isn’t recognized as headers, either toggle the flag or manually create the row. Then refresh the tool configuration.

3. Append vs. Update

• This guide covers Insert Row (append). If you need to update existing rows, look for Find Row and Update Row actions or use a formula/index in the sheet.

4. Rate Limits & Errors

• Google Sheets API may enforce quotas. If your flow inserts many rows in quick succession, consider batching or adding delays.

5. Date & Currency Formatting

• Google Sheets will auto-format if the cell format is set correctly. If you see unexpected text, set the cell format (e.g., currency, date) in the sheet.

6. Backups

• Consider writing the entire JSON to a “raw” column as a backup (e.g., in JSON string form) for auditing.

Going Further

• Multiple Sheets: Send header data to one sheet and line items to another.

• Conditional Logic: Only insert rows when certain fields meet criteria (e.g., totals above a threshold).

• Aggregation: Use a separate step to sum line items before writing to the header row.

Wrap-Up

Exporting data from extractor JSON into Google Sheets is straightforward once you know whether you’re dealing with header-level fields or line-item items. Map the values, loop for line items, and let the Google Sheet Tool handle row insertion.

If you run into edge cases or have ideas to streamline your flow, let us know—we’re always improving the builder experience.

Happy automating! 🚀