CSV Get Rows

17 min

The CSV Get Rows native action is designed to extract data from a CSV file based on user-defined configurations. This action allows precise control over which rows and columns to retrieve from the CSV file, making it ideal for processing large CSV files in chunks or extracting specific data subsets.

Key Benefits

Native Action: Integrated directly into the playbook builder for streamlined workflow creation.

Efficient Processing: Skips rows before the offset without reading them into memory, optimizing performance for large files.

Flexible Column Selection: Include specific columns or exclude unwanted columns from results.

Pagination Support: Use offset and limit to process large files in manageable chunks.

Error Handling: Option to continue processing even when individual rows have errors.

At Least Once Execution: Ensures data is retrieved even if the playbook is retried.

Inputs

The CSV Get Rows action requires the following inputs:

Required Inputs

Attachment: The CSV file attachment to process. This can be:

An attachment from an upstream action (e.g., Export Records action output)

An attachment from playbook inputs

An attachment reference using expressions

Note: The attachment must be a valid CSV file. The action automatically detects and skips the header row.

Optional Inputs

Offset: The number of data rows to skip before starting to return rows.

Default: 0 (starts from the first data row)

Minimum: 0

Note: The header row is automatically skipped and does not count toward the offset. Offset 0 means start from the first data row after the header.

Limit: The maximum number of rows to return.

Default: 0 or null (returns all rows from offset to end of file)

Minimum: 0

Note: If limit is 0 or not specified, all remaining rows from the offset position are returned.

Return Columns: An array of column names to include in the result.

Default: All columns are included if not specified

Format: Array of strings (column names must match CSV header exactly, case-sensitive)

Note: If specified, only these columns are included in the output (unless also specified in Omit Columns).

Omit Columns: An array of column names to exclude from the result.

Default: No columns are omitted if not specified

Format: Array of strings (column names must match CSV header exactly, case-sensitive)

Note: Omit Columns is applied after Return Columns. If both are specified, Return Columns is applied first, then Omit Columns filters out any matching columns.

Continue On Error: Whether to continue processing if an error occurs while reading a row.

Default: false

Options:

true: Continue processing remaining rows even if individual rows have errors. Errors are collected and returned in the output.

false: Stop processing immediately when an error occurs and throw an exception.

Column Selection Logic: When both Return Columns and Omit Columns are specified:

First, Return Columns filters which columns to include

Then, Omit Columns removes any columns that match the omit list

If a column appears in both lists, it will be excluded (Omit Columns takes precedence)

Example: If Return Columns = ["A", "B", "C"] and Omit Columns = ["C"], the result will include only columns A and B.

Column Name Matching: Column names are case-sensitive and must match the CSV header exactly. Ensure column names in Return Columns and Omit Columns match the header row precisely.

Configuring the CSV Get Rows Action

Step 1: Select Attachment

From the Inputs tab, select the CSV file attachment:

Use the Select a property button to choose an attachment from upstream actions

Reference attachments using expressions (e.g., $actions.exportRecordsName.result.exportFile)

Use playbook input attachments

Step 2: Configure Row Selection

Offset: Set the number of data rows to skip (default: 0).

Offset 0 = Start from first data row

Offset 10 = Skip first 10 data rows, start from 11th row

Limit: Set the maximum number of rows to return (default: 0 = all rows).

Limit 100 = Return up to 100 rows

Limit 0 = Return all remaining rows from offset

Example: To get rows 11-110:

Set Offset to 10

Set Limit to 100

Step 3: Configure Column Selection (Optional)

Return Columns: Click Add array item to specify columns to include:

Enter column names exactly as they appear in the CSV header

Column names are case-sensitive

If not specified, all columns are included

Omit Columns: Click Add array item to specify columns to exclude:

Enter column names exactly as they appear in the CSV header

Column names are case-sensitive

Applied after Return Columns filtering

Step 4: Configure Error Handling (Optional)

Continue On Error: Choose error handling behavior:

false (default): Stop processing on first error

true: Continue processing and collect errors in output

Step 5: Apply Changes

Click Apply to save your configuration.

Outputs

The CSV Get Rows action provides the following outputs:

Success Output

When the action completes successfully, it returns:

result.data: An array of objects, where each object represents a row from the CSV file.

Each object has properties corresponding to column names

Values are strings (as read from CSV)

Empty cells are represented as empty strings

result.count: The number of rows returned in this operation.

result.nextOffset: The next offset value that should be used to fetch the next page of results.

Calculated as: currentOffset + count

Useful for pagination through large files

If all rows have been processed, nextOffset will be equal to or greater than the total rows

result.error (optional): Error information if continueOnError is true and errors occurred:

error.total: Total number of errors encountered

error.errors: Array of error objects, each containing:

row: The row number (0-based, excluding header) where the error occurred

message: The error message describing what went wrong

Example: Access CSV data in downstream actions:

# Access all rows
$actions.csvGetRowsName.result.data

# Access first row
$actions.csvGetRowsName.result.data[0]

# Access a specific column value from first row
$actions.csvGetRowsName.result.data[0].TransactionID

# Get row count
$actions.csvGetRowsName.result.count

# Get next offset for pagination
$actions.csvGetRowsName.result.nextOffset

# Check for errors
$actions.csvGetRowsName.result.error.total

Error Output

If the action fails (and continueOnError is false), the action returns:

error: Error information containing details about why the action failed.

Common Error Scenarios:

Invalid CSV file format

File attachment not found

Invalid offset or limit values

Column names not found in CSV header

Invalid data in a row (when continueOnError is false)

Use Cases

Example 1: Extract First 100 Rows

Scenario: Process the first 100 rows of a CSV file.

Configuration:

Attachment: Select CSV file

Offset: 0

Limit: 100

Return Columns: Leave empty (return all columns)

Result: Returns the first 100 data rows with all columns.

Example 2: Paginate Through Large File

Scenario: Process a large CSV file in chunks of 1000 rows.

Configuration (First Page):

Attachment: Select CSV file

Offset: 0

Limit: 1000

Result: Returns rows 1-1000, with nextOffset = 1000.

Configuration (Second Page):

Attachment: Same CSV file

Offset: Use $actions.csvGetRowsName.result.nextOffset (1000)

Limit: 1000

Result: Returns rows 1001-2000, with nextOffset = 2000.

Note: Use a Loop action to iterate through all pages until nextOffset indicates all rows have been processed.

Example 3: Extract Specific Columns

Scenario: Extract only transaction ID and amount columns from a CSV file.

Configuration:

Attachment: Select CSV file

Offset: 0

Limit: 0 (all rows)

Return Columns:

Add "TransactionID"

Add "Amount"

Result: Returns all rows with only TransactionID and Amount columns.

Example 4: Skip Header and Extract Subset

Scenario: Skip the first 10 data rows and retrieve the next 100 rows with specific columns.

Configuration:

Attachment: Select CSV file

Offset: 10

Limit: 100

Return Columns:

Add "TransactionID"

Add "Amount"

Add "Date"

Result: Returns rows 11-110 with only the specified columns.

Example 5: Exclude Columns

Scenario: Return all columns except sensitive data columns.

Configuration:

Attachment: Select CSV file

Offset: 0

Limit: 0 (all rows)

Omit Columns:

Add "SSN"

Add "CreditCard"

Add "Password"

Result: Returns all rows with all columns except the omitted ones.

Example 6: Handle Errors Gracefully

Scenario: Process a CSV file that may have some invalid rows, but continue processing the rest.

Configuration:

Attachment: Select CSV file

Offset: 0

Limit: 0 (all rows)

Continue On Error: true

Result: Returns all valid rows, with error information in result.error for any rows that failed to process.

Access Errors:

# Check total errors
$actions.csvGetRowsName.result.error.total

# Access error details
$actions.csvGetRowsName.result.error.errors[0].row
$actions.csvGetRowsName.result.error.errors[0].message

Best Practices

Use Pagination for Large Files: For very large CSV files, use offset and limit to process in manageable chunks. Use nextOffset to track your position.

Validate Column Names: Ensure column names in Return Columns and Omit Columns match the CSV header exactly (case-sensitive).

Handle Missing Columns: If a column specified in Return Columns doesn't exist in the CSV, it will be omitted from results without error.

Use Continue On Error for Data Quality Issues: If your CSV may have some invalid rows but you want to process the rest, set continueOnError to true and check the error output.

Optimize Column Selection: Use Return Columns or Omit Columns to reduce data size and improve performance, especially for large files.

Combine with Export Records: Use CSV Get Rows to process CSV files exported by the Export Records action:

Export Records → CSV Get Rows → Process Data

Loop Through Pages: Use a Loop action with a while condition to process all pages:

While: $actions.csvGetRowsName.result.nextOffset < totalRows

Validate File Format: Ensure the CSV file is properly formatted with a header row. The action automatically skips the header row.

Troubleshooting

No Rows Returned:

Check that the offset is not greater than the number of data rows in the file

Verify the CSV file has data rows (not just a header)

Ensure the attachment is a valid CSV file

Column Not Found:

Verify column names match the CSV header exactly (case-sensitive)

Check for extra spaces or special characters in column names

Ensure the CSV file has a header row

Invalid Offset or Limit:

Offset must be >= 0

Limit must be >= 0

Verify values are numbers, not strings

Processing Errors:

If continueOnError is false, check the error output for details

If continueOnError is true, check result.error for row-specific errors

Verify CSV file format is valid (proper quoting, escaping, etc.)

Empty Results:

Check that Return Columns doesn't exclude all columns

Verify Omit Columns doesn't omit all columns

Ensure there are data rows after the offset position

Pagination Issues:

Use nextOffset from the previous call as the offset for the next call

Check that nextOffset is less than the total number of rows

Verify limit is set appropriately for pagination

File Attachment Errors:

Ensure the attachment exists and is accessible

Verify the attachment is a CSV file (not another format)

Check that the attachment reference is correct (e.g., $actions.actionName.result.exportFile)