Create, Read, and Update Excel Files in Jinba Flow

Use EXCEL_CREATE to build a file, EXCEL_GET_ROWS, EXCEL_GET_ROW, EXCEL_GET_CELL_WITH_COORDINATE, and EXCEL_GET_IMAGES to read data, and EXCEL_UPDATE or EXCEL_UPDATE_BY_COORDINATE to write values.

Excel tools provide comprehensive functionality for working with Excel files (.xlsx). You can create new files from array data, read data, update cells, retrieve specific rows, extract embedded images, and manipulate Excel files from URLs.

• EXCEL_CREATE
  • Create a new Excel file from a 2D array and return a download URL
• EXCEL_GET_ROWS
  • Retrieve multiple rows from an Excel sheet as a 2D array, optionally limited to a range (e.g. “A1:C10”)
• EXCEL_GET_ROW
  • Get a single row from an Excel sheet using a range (e.g. “A5:C5”)
• EXCEL_GET_CELL_WITH_COORDINATE
  • Get cell values with their coordinates from a range defined by a start cell and an end cell
• EXCEL_GET_IMAGES
  • Extract images embedded in an Excel file, with their sheet name and cell range
• EXCEL_UPDATE
  • Update Excel file with new data using range selection
• EXCEL_UPDATE_BY_COORDINATE
  • Update specific cells using coordinate-based positioning

No authentication required. Excel tools work directly with file URLs.

Create an Excel file

- id: create_excel
  name: create_excel
  tool: EXCEL_CREATE
  input:
    - name: data
      value: [
        ["Name", "Role", "Salary"],
        ["John Doe", "Manager", "50000"],
        ["Jane Smith", "Developer", "60000"]
      ]
    - name: sheetName
      value: "Members"
    - name: outputFilename
      value: "members.xlsx"
    - name: startCell
      value: "A1"

The result is a URL to download the created Excel file.

Read rows, cells, and images

- id: get_excel_rows
  name: get_excel_rows
  tool: EXCEL_GET_ROWS
  input:
    - name: url
      value: "https://example.com/data.xlsx"
    - name: sheetName
      value: "Sheet1"
    # Optional: omit range to read the entire sheet
    - name: range
      value: "A2:C10"

- id: get_specific_row
  name: get_specific_row
  tool: EXCEL_GET_ROW
  input:
    - name: url
      value: "https://example.com/data.xlsx"
    - name: sheetName
      value: "Sheet1"
    - name: range
      value: "A5:C5"

- id: get_cell_value
  name: get_cell_value
  tool: EXCEL_GET_CELL_WITH_COORDINATE
  input:
    - name: url
      value: "https://example.com/data.xlsx"
    - name: sheetName
      value: "Sheet1"
    - name: startCell
      value: "B5"
    - name: endCell
      value: "B5"

- id: get_images
  name: get_images
  tool: EXCEL_GET_IMAGES
  input:
    - name: url
      value: "https://example.com/data.xlsx"
    # Omit sheetName to extract images from all sheets
    - name: sheetName
      value: "Sheet1"

EXCEL_GET_ROWS returns the cell values as a 2D array in result, and EXCEL_GET_ROW returns a single row as an array. EXCEL_GET_CELL_WITH_COORDINATE returns an array of {coordinate, content} objects for each cell in the range from startCell to endCell.

EXCEL_GET_IMAGES returns a URL, file extension, MIME type, sheet name, and covered cell range for each extracted image, plus the total image count. The workbook may be at most 30 MiB, and it must expand to no more than 256 MiB once unzipped; a larger or malformed workbook returns an ExcelTooLargeError error instead of images.

Update cells

calculate_total stands for an earlier step in your flow; its result is assumed to contain the computed total in sum.

- id: update_excel_range
  name: update_excel_range
  tool: EXCEL_UPDATE
  input:
    - name: url
      value: "https://example.com/template.xlsx"
    - name: sheetName
      value: "Data"
    - name: startCell
      value: "A2"
    - name: endCell
      value: "C4"
    - name: data
      value: [
        ["John Doe", "Manager", "50000"],
        ["Jane Smith", "Developer", "60000"],
        ["Bob Johnson", "Designer", "45000"]
      ]

- id: update_specific_cell
  name: update_specific_cell
  tool: EXCEL_UPDATE_BY_COORDINATE
  input:
    - name: url
      value: "https://example.com/report.xlsx"
    - name: sheetName
      value: "Summary"
    - name: updateData
      value: [
        {"coordinate": "E10", "content": "{{steps.calculate_total.result.sum}}"}
      ]

Example: Excel Data Processing Workflow

- id: read_source_data
  name: read_source_data
  tool: EXCEL_GET_ROWS
  input:
    - name: url
      value: "{{secrets.EXCEL_SOURCE_URL}}"
    - name: sheetName
      value: "RawData"
    - name: range
      value: "A2:C100"

- id: process_data
  name: process_data
  tool: PYTHON_SANDBOX_RUN
  needs: [read_source_data]
  input:
    - name: data_type
      value: OBJECT
    - name: code
      value: |
        import json
        
        # Get data from previous step (a 2D array of cell values)
        raw_data = json.loads(r'''{{steps.read_source_data.result}}''')
        
        # Process and transform data
        processed_data = []
        for row in raw_data:
            if row[0] and row[1]:  # Check if name and value exist
                processed_data.append([
                    str(row[0]).upper(),  # Uppercase name
                    float(row[1]) * 1.1,  # Increase value by 10%
                    "Processed"
                ])
        
        print(json.dumps({"processed_data": processed_data}))

- id: update_target_excel
  name: update_target_excel
  tool: EXCEL_UPDATE
  needs: [process_data]
  input:
    - name: url
      value: "{{secrets.EXCEL_TARGET_URL}}"
    - name: sheetName
      value: "ProcessedData"
    - name: startCell
      value: "A2"
    - name: data
      value: "{{steps.process_data.result.data.processed_data}}"

Tips and Best Practices

• Always specify the sheet name to avoid working with the wrong sheet
• Use coordinate notation (A1, B2, etc.) for precise cell references
• When updating ranges, ensure your data array dimensions match the specified range
• For large datasets, consider processing data in chunks to avoid timeouts
• Validate data format before updating Excel files to prevent errors

Notes

• A single read covers at most 1,000,000 cells. This applies to the range of EXCEL_GET_ROWS and EXCEL_GET_ROW and to the startCell–endCell rectangle of EXCEL_GET_CELL_WITH_COORDINATE; A1:ALL1000 (1,000 rows × 1,000 columns) fits, while a larger rectangle — including a whole-sheet range such as A1:XFD1048576 — fails with an error that names the range and the limit. Read a smaller range, or read the sheet in several steps.
• A range — or the startCell / endCell of EXCEL_GET_CELL_WITH_COORDINATE — that cannot be parsed as a cell range (for example not-a-range) now fails with an Invalid cell range error instead of returning an empty result.
• EXCEL_GET_ROWS without range reads the sheet’s own dimension when it fits the limit, so the output is unchanged for ordinary files. If the sheet declares a larger dimension than its cells use, only the rectangle that actually holds cells is read; a sheet whose cells alone exceed the limit must be read with an explicit range.
• EXCEL_GET_ROWS, EXCEL_GET_ROW, EXCEL_GET_CELL_WITH_COORDINATE, EXCEL_UPDATE and EXCEL_UPDATE_BY_COORDINATE check the .xlsx container before parsing it and reject an archive that would expand far beyond its size: more than 10,000 entries, more than 256 MiB in one entry or 1 GiB in total, or — once it expands past 8 MiB — more than 200× its compressed size. EXCEL_UPDATE and EXCEL_UPDATE_BY_COORDINATE additionally reject a file that is not a genuine workbook, including password-protected, encrypted or otherwise malformed archives; the three read tools apply the check to ZIP inputs only and leave other formats to the parser. EXCEL_GET_IMAGES has its own limits, described above.