Create List from Excel (.xlsx)

Audience: Low-code Engineers

Skill Prerequisites: Actions, Lists, Tokens

Reads a sheet of an Excel file (.xlsx) and turns it into a list. Each row becomes one list item. You can take every column, or pick the columns you want and name their properties.

The file must already be on the site, for example uploaded through a form or created by another action. After the action runs, [<ListName>:Count] holds the number of items in the list. You can then go through the list with Execute Actions for each List Entry, or use it with the other list actions.

The list only exists while the current actions run. It isn't saved anywhere.

note

This action requires the Excel feature package (EXGEN) to be licensed.

Typical Use Cases

• Import the rows of an uploaded Excel file into a table with Import List into Database
• Send an email to each person listed in a spreadsheet
• Read only some columns, or some rows, of a sheet
• Read a specific sheet after checking its name with Get Excel Sheet Names

Don't use it to

• Read older .xls files. Only .xlsx files can be read. Save the file as .xlsx first.
• Read CSV files. Use Create List from a CSV source instead.
• Write a list to an Excel file. Use Create Excel from List instead.

Related Actions

Action Name	Description
Get Excel Sheet Names	Reads the sheet names of an Excel file.
Execute Actions for each List Entry	Runs actions once for each item in the list.
Import List into Database	Saves the list items into a SQL Server table.
Remap List	Renames or reshapes list properties.
Create List from a CSV source	Creates a list from CSV text or a CSV file.
Create Excel from List	Does the opposite: writes a list to an Excel file.

Input Parameter Reference

Parameter	Description	Supports Tokens	Default	Required
File / Field	The Excel file to read. It can be a file ID, a relative URL, an absolute URL of a file on the site, a LinkClick URL or a physical path. In a form, the parameter is called Field: select the Single File Upload field the user uploaded the file into, or switch to an expression to pass any of the other values.	Yes	empty string	Yes
List Name	The name of the list to create, for example CustomersList. If it's empty, the default list of the current context is used, for example the rows of a listing. If there's no default list, the action fails. See Lists that already exist.	Yes	empty string	Yes
Use first row as column names	Uses the first row of the sheet as column names, and doesn't read it as data. When it's off, every row is data and the columns are named by position: column A is Field0, B is Field1 and so on.	No	false	No
Include All Fields	Reads every column. Each column becomes a property with the column's name. When it's on, Properties is ignored.	No	false	Yes, unless Properties has rows
Properties	The columns to read. Each row has an Excel Name, which is the column name, for example E-mail, and a List Property Name, for example Email. The column name is the header text, or Field0, Field1 and so on when Use first row as column names is off. Enter property names without square brackets.	No	empty	Yes, unless Include All Fields is on
Sheet Name	The name of the sheet to read, for example Customers. If it's empty, the first sheet is used.	Yes	empty string	No
Start Row	The sheet row number to start reading at, for example 2. If it's empty, reading starts at the first row with data, or the row after the header. See Choosing rows.	Yes	empty string	No
EndRow	The sheet row number to stop reading at, including that row, for example 500. If it's empty, reading stops at the last row with data.	Yes	empty string	No
On Error	Actions to run if reading fails. They can use the [Exception], [ExceptionType], [ExceptionMessage] and [ExceptionStack] tokens. See Errors.	No	empty	No

Output Parameters Reference

Output	Description
List <List Name>	The list, one item per sheet row.
[<List Name>:Count]	The number of items in the list, for example [CustomersList:Count]. If the list already had items, they're counted too.

Inside Execute Actions for each List Entry, use the properties as [ListName:PropertyName], for example [CustomersList:Email].

Choosing rows

The action reads the used area of the sheet, from the first row and column that have content to the last ones.

• Header row. With Use first row as column names on, the column names come from the first row that has content. It doesn't have to be row 1.
• Start Row empty. Reading starts at the first row with content, or at the row after the header.
• Start Row set. It's the row number you see in Excel. The header row isn't skipped for you, so if the header is in row 1, set Start Row to 2 or more. A value before the first row with content is moved up to that row.
• EndRow set. Reading stops at that row, even if it's past the last row with data. Rows past the data become items with empty values.
• Blank rows inside the range aren't skipped. They become items with empty values.
• A value that isn't a number is treated as empty.

Columns and values

• Header names are used exactly as written, including spaces and case. Columns with an empty header cell are skipped.
• Duplicate headers. With Include All Fields on, the action fails if two header cells have the same text. Rename one of them in the file.
• Columns without a header row are named by their position in the sheet. If the data starts in column C, the first property is Field2.
• Columns in Properties that aren't in the sheet are skipped. No error is raised.
• Values are text. Each cell's stored value is converted to text. Number formatting, such as currency symbols or thousands separators, isn't applied, and the decimal separator can follow the current language settings.
• Formulas give the result that was saved in the file the last time it was calculated. Formulas aren't recalculated.
• Dates may come through as date text in the server's format, or as an Excel serial number, for example 45292, depending on the cell's format. If you need a fixed format, store dates as text in the file, or convert them after the import.
• Empty cells give empty values.

Lists that already exist

If a list with the same name already exists, the new rows are added to the end of it, and [<List Name>:Count] counts all the items. The list's properties are replaced by the columns read in this run.

To start fresh, use a list name that isn't used yet in the current actions.

Errors

• Please provide an entity name. when List Name is empty and there's no default list. The On Error actions don't run for this error.
• For other errors, the On Error actions run first. Then the action still fails, unless an On Error action ends execution itself, for example Stop Execution. These errors include:
  • Excel file not found. when the file can't be found.
  • No excel worksheet named <Sheet Name> found. when the sheet doesn't exist.
  • A file that isn't a valid .xlsx, for example an .xls or a password-protected file.
  • An empty sheet.
  • Duplicate header names with Include All Fields on.
• Low-code engineers and administrators see the original error. Other users see a generic message.

Considerations

• Set a List Name. In a listing, an empty name adds the rows to the listing's default list instead of a new list.
• Formatted but empty cells. Excel can count cells that only have formatting as part of the used area. That can add empty items at the end of the list. Set EndRow, or delete the extra rows in Excel.
• Hidden rows, columns and sheets are read like any others.
• Merged cells. Only the first cell of a merged range has a value. The other cells give empty values.
• Restrict the upload field to .xlsx files, so users can't upload files the action can't read.

Examples

tip

To understand how to use the below examples, please see Running Examples.

1. Read every column of an uploaded file

This action runs in a form. It reads the first sheet of the file uploaded into the ImportFile field. The first row has the column names, and every column becomes a property. The list is called CustomersList, and [CustomersList:Count] holds the number of rows.

{
    "Title": "Create List from Excel (.xlsx)",
    "ActionType": "LoadEntitiesFromExcelFile",
    "Description": "Read the uploaded customers file",
    "Parameters": {
        "FilePath": {
            "Expression": "",
            "Value": "ImportFile",
            "IsExpression": false,
            "Parameters": {}
        },
        "EntityName": "CustomersList",
        "UseFirstRowAsColumnNames": true,
        "IncludeAllFields": true,
        "SheetName": "",
        "StartRow": "",
        "EndRow": "",
        "OnError": []
    }
}

2. Read two columns of a named sheet

This action reads the Orders sheet of the file with the ID in the [FileId] token, for example from an API request or a workflow. The header is in row 1. Only the Order No and Total Amount columns are read, into the OrderNumber and Total properties. Reading starts at row 2 and stops at row 1001, so at most 1,000 orders are read.

{
    "Title": "Create List from Excel (.xlsx)",
    "ActionType": "LoadEntitiesFromExcelFile",
    "Description": "Read order numbers and totals",
    "Parameters": {
        "FilePath": "[FileId]",
        "EntityName": "OrdersList",
        "UseFirstRowAsColumnNames": true,
        "IncludeAllFields": false,
        "EntityProps": [
            {
                "name": "Order No",
                "value": "OrderNumber"
            },
            {
                "name": "Total Amount",
                "value": "Total"
            }
        ],
        "SheetName": "Orders",
        "StartRow": "2",
        "EndRow": "1001",
        "OnError": [
            {
                "Title": "Log Error",
                "ActionType": "LogError",
                "Parameters": {
                    "Message": "Order file import failed: [ExceptionMessage]"
                }
            }
        ]
    }
}

Revised 09/27/2026