---
title: "Set up document - Microsoft Excel"
slug: "set-up-document-microsoft-excel"
description: "Learn to read and write data in Microsoft Excel using a structured approach, including document naming, properties, and file handling best practices."
tags: ["Task topic"]
updated: 2026-03-20T07:51:00Z
published: 2026-03-20T17:44:14Z
canonical: "docs.staedean.com/set-up-document-microsoft-excel"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.staedean.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up document - Microsoft Excel

Use a **Microsoft Excel** document to read data from or write data to a Microsoft Excel file (XLSX).

### Steps

1. Click **Connectivity studio - Integration Design**.
2. Click the **Documents** tab.
3. Click **New**.
4. Define a meaningful name for the document. **Example:** If the document is used for a sales integration, you can use names like 'Sales - Order' or 'Sales - Invoice'. In the **Document** field, type a value.

> [!NOTE]
> **Best practice**
> 
> In the document name, do not use the:
> 
> - Application name: Use the **Application** field to define the applicable application.
> - Document type: Use the **Document type** field to define the applicable document type.
5. In the **Project** field, enter or select a value.
6. Define the applicable application for the document. For a **Microsoft Excel** document, for example, select a 'Windows folder' or 'Files' application.

In the **Application** field, enter or select a value.

> [!NOTE]
> **Note**
> 
> You can only select an application that is defined for the applicable project. You can define project applications on the **Projects** page.
7. In the **Document types** field, select '**Microsoft Excel**'.
8. Sub-task: Set properties.
  1. Expand the **Properties** section.
  2. You can process an external document in these ways:

    - **Direct**: You can use this to import or export (big sets of) simple data. For simple data, the document lines only have a root record. When a message is run, the data is directly mapped. More technically: It only loads the data in the memory of the record table (usually the **BisBufferTable**). As a result, the import or export of data is faster.
    - **Query**: You can use this to import or export complex data. For complex data, the document lines have several records and parent-child relations. When a message is run, the records are stored in the record table (usually the **BisBufferTable**) before the data is mapped. When the message run is finished, the records are deleted from the record table.

In the **Process type** field, select an option.
  3. To apply a predefined layout to your Microsoft Excel files, you can define a Microsoft Excel template file of type XLSX or XLTX to create a Microsoft Excel file. On data export, based on this template, a file is created to which the data is exported. If you do not define a template, a default Microsoft Excel file is created to which the data is exported.

In the **Template filename** field, enter or select a value.
9. Sub-task: Set custom handler.
  1. Expand the **Custom** section.
  2. For a **Microsoft Excel** document, several standard handler classes are available.

You can use a customized handler class. To do so, extend a standard handler class.

In the **Handler** field, enter or select a value.
10. Sub-task: Set read options.
  1. Define the filename settings based on which files are searched for when importing data from files.

Expand the **Read** section.
  2. Define the filename filter to define which files must be imported for the document.

You can use these variables:

You can also use other common search symbols.

**Example:** %1*.%2. As a result, files are only imported if the name starts with the current company ID and has the extension '**XLSX**'.

In the **Read filename** field, type a value.
    - **%1**: filters files based on the current active company ID.
    - **%2**: filters file based on the file extension. The applicable file extension is defined by the current document type. In this case, it is '**XLSX**'.
  3. You can block files with the same filename from being imported several times. Each processed file is stored in the file history. If **Read only once** is **Yes**, on import, the filenames are compared with the file history. If a file is found that is processed earlier, it is not processed but moved to the **Error folder**. Select **Yes** in the **Read only once** field.
  4. On running an applicable message, you can have a dialog shown with the data to be imported. You can review the data before it is actually imported. This can, for example, be useful when importing work breakdown structures, because you cannot easily undo the import. The dialog is only shown if you manually run the message. So, the dialog is not shown if you run the message in batch. Select **Yes** in the **Validate input** field.

> [!NOTE]
> **Note**
> 
> If you use input validation, make sure the **Process type** is set to '**Query**'.
  5. You can define the position on the sheet where reading the data from the Microsoft Excel file starts.

If you do not define a read start position, reading data starts at the A1 position.

In the **Read start position** field, type a value.
  6. You can define the sheet of the Microsoft Excel from which the data is read.

If you do not define a sheet, data is read from the first sheet.

In the **Read sheet name** field, type a value.
11. Sub-task: Set write options.
  1. 1. Define the filename settings based on which filenames are created when exporting data to files.

Expand the **Write** section.
    2. Using a variable, you can add the value of two table fields to the filename. If you want to do so, define the applicable table.

On write, this document is the target document. However, the file name is defined based on the root record values of the source document. So, make sure you select a table and table fields from the root record of the applicable source document.

In the **Table name** field, enter or select a value.

> [!NOTE]
> **Note**
> 
> You cannot use the table name itself as variable in the filename.
    3. Define the first table field which value you want to add to the file name. The related variable is '**%5**'.

In the **First field** field, enter or select a value.

> [!NOTE]
> **Note**
> 
> You can only select a field from the defined table.
    4. Define the second table field which value you want to add to the file name. The related variable is '**%6**'.

In the **Second field** field, enter or select a value.

> [!NOTE]
> **Note**
> 
> You can only select a field from the defined table.
    5. To make the filename unique, you can add a unique number to the filename, provided by a number sequence. The related variable is '**%4**'.

In the **Number sequence** field, enter or select a value.
    6. Define the filename for the files that are created based on the document.

You can use fixed values and variables. The available variables are:

In the **Write filename** field, type a value.
      - **%1**: The name of the current document.
      - **%2**: The current date.
      - **%3**: The current time.
      - **%4**: The unique number as provided by the defined number sequence.
      - **%5**: The value of the defined **First field**
      - **%6**: The value of the defined **Second field**
      - **%7**: The ID of the current company.
      - **%8**: The ID of the current user.
      - **%9**: The file extension as defined by the applicable document type. For example: 'xml' or ‘json’.
      - **%10**: The UTC internet date/time (RFC3339 with underscores). Example: 2021-01-05T14_38_51Z
    7. You can define the position on the sheet where writing the data to the Microsoft Excel file starts.

If you do not define a write start position, writing data starts at the A1 position.

In the **Write start position** field, type a value.
    8. You can define the sheet of the Microsoft Excel to which the data is written.

If you do not define a sheet, data is written to the first sheet.

In the **Write sheet name** field, type a value.
12. Sub-task: Set record layout options.
  1. Expand the **Record layout** section.
  2. You can have a header row in the Microsoft Excel file with the document record field names as column headers.

If **Use header** is set to **Yes**, and:

Select **Yes** in the **Use header** field.
    - No specific read or write start position is defined, reading or writing of the headers start at the A1 position.
    - A specific read or write start position is defined, reading or writing of the headers start at the defined position.
  3. You can have a first column added to the Microsoft Excel file to show the document record name as identification of the record.

If **Record identification** is set to **Yes**, and:

Select **Yes** in the **Record identification** field.
    - No specific read or write start position is defined, reading or writing of the record identifications start at the A1 position.
    - A specific read or write start position is defined, reading or writing of the record identifications start at the defined position.
  4. On import, you can split large Microsoft Excel files with a lot of records. To do so, define, the number of root records based on which the file is split.

When the message is run, the original file is put in the **Split folder** instead of the **Working folder**, as defined on the applicable connector. The original file is split in smaller files based on the split quantity. The smaller split files are put in the **Working folder**. The message processes the split files in parallel from the working folder.

In the **Split quantity** field, enter a number.

> [!NOTE]
> **Note**
> 
> Only use the split functionality for simple (one record level) data. It is not suitable for data with multiple levels (header and line records).
13. Sub-task: Define document properties.
  1. You can set the Microsoft Excel file properties in the document to make upload of a generated file to SharePoint easier.

Expand the **Document properties** section.
  2. If you have defined a template filename, you can read the properties from the template and upload these to the document.

Click **Read properties**.
  3. You can manually add properties that are used to set the Microsoft Excel file properties on creation.

Click **New**.
  4. Enter the name of the property.

In the **Name** field, type a value.
  5. Indicate if the property is a standard Microsoft Excel property (Core) or a customized property (Custom).

In the **Type** field, select an option.
  6. You can enter a fixed value for the property.

In the **Value** field, type a value.
  7. You can use a table field to define the property value on creation of the Microsoft Excel file.

You can only use a table field of the table as defined in the **Write** section, in the **Table name** field.

In the **Field name** field, enter or select a value.
  8. If you have defined a template filename, you can update the properties of the template based on the properties as defined for the document.

Click **Write properties**.
14. Close the page.

> [!NOTE]
> **Notes**
> 
> - Files with the extension '.xls' are not supported because these do not support Office Open XML.
> - If you need to export a lot of data (40.000 records or more), consider to use the SQL server exports to Microsoft Excel.

## Related

- [Customize document handler class](/customize-document-handler-class.md)
- [Create separate files](/create-separate-files.md)