> For the complete documentation index, see [llms.txt](https://docs.eximee.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.eximee.com/documentation/documentation-en/budowanie-aplikacji/logika-biznesowa/scriptcode/skrypty-scriptservice/api-skryptow/podstawy-pracy-ze-skryptami/przetwarzanie-plikow-arkuszy.md).

# Processing spreadsheet files (XLSX)

The Eximee platform enables reading and processing data directly from spreadsheet files (XLSX) attached by the user to the request (e.g. using the Attachments (UploadFile) component). This functionality is very useful when mass importing data, such as employee lists, financial statements, or inventory tables.

{% hint style="warning" %}
**System requirements:** For this functionality to work correctly, an independent module is required **`xlsx-sheet-handling-module`**. Since it is provided as a separate service, the platform administrator must first properly configure access to its external endpoint (in the example below defined under the REST API key as `excelDocument`).
{% endhint %}

## Operating mechanism

File processing is based on integration via the built-in client `api.rest.v1`. The file is sent to the processing module as an encoded string (Base64), and a structured data map is returned in response.

### Request

An object containing the property `content`. The value of this property must be a Base64 file. This is the format in which files are stored in memory when we retrieve them from the file upload component (`UploadFile`). In the case of adding multiple files, this component stores them as a list of Base64 strings.

```json
{
    "content": "UEsDBBQAAAAIA..." 
}
```

### Response

In response, the module returns a nested structure (map) in JSON format that reflects the physical layout of the spreadsheet, divided into: **Sheet name ➔ Row number ➔ Column letter**.

```json
{
    "sheet1": {
        "1": {
            "A": "Value from cell A1",
            "B": "Value from cell B1"
        },
        "2": {
            "A": "Value from cell A2"
        }
    }
}
```

## Example usage in a script

The script below shows how to retrieve a file from the component, send it to the XLSX processing module, and return the decoded data structure to the script output, while ensuring safe handling of integration errors.

```javascript
function callService(context) {
    // 1. Retrieve the list of files from the component (e.g. with ID "GesUploadFile1")
    let files = context.getParameters("GesUploadFile1");
    
    // Protection against calling without files
    if (files.size() === 0) {
        return [{}];
    }
    
    let header = {};
    
    // 2. Prepare the payload with the first attached file (index 0)
    let body = { 'content': files.get(0) };
    
    try {
        // 3. Call the external XLSX module via the platform REST API
        // Parameters: configuration key ('excelDocument'), paths ('xlsx', 'v1'), headers, body
        let response = api.rest.v1.post('excelDocument', { pathParams: ['xlsx', 'v1'] }, header, body);
        
        // 4. Return the processed cells as a JSON structure
        return [{'output': JSON.stringify(response.body)}];
        
    } catch (error) {
        // Safe error handling in case of network problems or an invalid file
        Logger.info("An error occurred while parsing the XLSX file: {}", error);
        return [{'output': 'An error occurred while processing the file.'}];
    }
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.eximee.com/documentation/documentation-en/budowanie-aplikacji/logika-biznesowa/scriptcode/skrypty-scriptservice/api-skryptow/podstawy-pracy-ze-skryptami/przetwarzanie-plikow-arkuszy.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
