# Workbook Recalculation Report (`l3digital/workbook-recalculation-report`) Actor

Experimental bounded LibreOffice formula recalculation and cache comparison for a small caller-owned XLSX.

- **URL**: https://apify.com/l3digital/workbook-recalculation-report.md
- **Developed by:** [L3Digital](https://apify.com/l3digital) (community)
- **Categories:** Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$0.05 / complete workbook recalculation report

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

### Use from an AI agent through MCP

Add this URL to a client that supports remote HTTP MCP, then authorize with your
own Apify account using the [Apify MCP setup guide](https://docs.apify.com/integrations/mcp):

```text
https://mcp.apify.com/?tools=l3digital/workbook-recalculation-report
```

This configuration selects the Actor directly. Availability still depends on
Apify account and Actor eligibility. Call `l3digital/workbook-recalculation-report`
with the example input below; the pricing and input restrictions on this page apply.

When using `call-actor`, its response contains run status and storage IDs. If the
run is still active, check that run with `get-actor-run`. After success, retrieve
the report with `get-dataset-items` using the returned dataset ID
(`defaultDatasetId` in the run API). These retrieval tools load with the Actor.
Retrieve the existing result instead of starting another run. Inspect the report
status and the coverage or refusal fields described below before using its values.

### What does Workbook Recalculation Report do?

Receive one **XLSX formula and cache report** from a small workbook you are authorized to process. The Actor records the original formulas and stored caches, explicitly asks [LibreOffice](https://www.libreoffice.org/) to calculate all cells, and reads the separately exported XLSX caches. This experimental TRYOUT tests the convenience of an Apify API call for callers without a spreadsheet engine installed.

Private validation of corrected build 0.1.2 passed a native LibreOffice
25.2.3.2 proof for 11 frozen formulas and five normal platform cases. The
complete known-answer case persisted one report and one `useful-report` event.
Its observed run duration was 9.987 seconds, peak memory was 196.602 MiB, and
conservative platform cost was $0.0006161991178890069. This is one small,
frozen sample: it is not a maximum-workload or customer-latency benchmark, and
it does not establish general spreadsheet fidelity or demand. These are owner-QA
observations, not customer usage or settlement evidence.

### Why use this workbook report?

An agent or backend can receive the original observations and engine results in one structured dataset record. The source SHA-256 and actual engine version help identify what ran. The report gives a caller explicit outcomes and missing-value diagnostics instead of treating a stored cache as evidence of freshness.

The admitted subset is deliberately small. Native Excel or LibreOffice are complete alternatives when you already operate them. This Actor makes no universal Excel compatibility or freshness guarantee.

### How to submit a workbook

1. Choose `recalculate` in the input form.
2. Encode the original XLSX bytes as strict base64 and put that string in `workbookBase64`.
3. Run the Actor and inspect the single dataset record's `status` before using `formulaResults`.

See the input tab for the flat configuration options. The API tab provides programmatic access. No URL, source account, network acquisition or output-workbook download is involved.

The submitted base64 workbook is retained as platform input. Sheet/cell names,
formulas and original/recalculated values appear in the result. Submit only data
you are authorized to store and process on Apify. Native temporary-file cleanup
does not delete the platform input or result.

The default input is an uncharged, engine-free illustration:

```json
{"mode": "demo"}
```

A recalculation request has this shape (replace the descriptive string with real base64):

```json
{"mode": "recalculate", "workbookBase64": "BASE64_OF_AUTHORIZED_XLSX"}
```

### Supported workbook subset and limits

Static finite numbers, booleans and text are supported. Formula syntax covers `+ - * / ^`, unary signs, parentheses, `= <> < <= > >=`, bounded A1 cell/range references, quoted or unquoted cross-sheet references, numeric/text/boolean literals, and `SUM`, `MIN`, `MAX`, `AVERAGE`, `ABS`, `ROUND`, `IF`. Range values are allowed in aggregate functions, not as standalone scalar results. Formula admission parses syntax; LibreOffice performs the calculation.

| Limit | Maximum |
| --- | ---: |
| Decoded XLSX | 2,097,152 bytes (2 MiB) |
| Actual ZIP expansion | 16,777,216 bytes (16 MiB) |
| ZIP entries | 128 |
| Sheets / nonempty cells / formulas | 3 / 5,000 / 200 |
| Cell and reference grid | Rows 1–1000, columns A–CV (100 columns) |
| Formula characters, including leading `=` | 1,000 |
| Native exported XLSX / report JSON | 4 MiB / 1 MiB |
| Bridge receipt and each monitored process log | 64 KiB |
| Monitored temporary workspace | 32 MiB, 512 files |

Date/error input cells, custom/date number formats, named/array/shared formulas, structured references, unknown functions, external dependencies, macros, embeddings and refresh content are refused. A workbook with no formulas is also refused. Any unsupported workbook is wholly refused before native loading. Formatting support is conservative; simplify the workbook to plain scalar cells if it is refused.

Native startup has a 15-second bound and the native operation has a 95-second budget. Linux process file limits and monitored output bounds supplement the total 120-second application deadline. The owner terminates and waits for engine and bridge process groups and removes their private profile and temporary files on controlled outcomes.

The headless engine has a 32 MiB hard per-file ceiling because uncompressed
temporary XML can exceed the compressed 4 MiB export limit. Export monitoring
still refuses files above 4 MiB; version and UNO bridge processes retain 64 KiB
hard ceilings. The 32 MiB/512-file workspace thresholds are polled refusal
bounds, so transient peaks may cross them before termination; they are not a
hard aggregate filesystem quota.

### Report output

| Field | Meaning |
| --- | --- |
| `status` | `demo`, `complete`, `unsupported`, `calculation_error` or `incomplete` |
| `sourceSha256` | Hash of original decoded bytes, or null when decoding was unavailable |
| `engine` | Actual invoked LibreOffice name/version, or null when no version was established |
| `formulaResults` | Sheet, cell, original formula/cache, new cache-derived scalar, comparison |
| `diagnostics` | Bounded reasons for refusal or incomplete calculation |
| `contractVersion` | Version of this report contract |

An illustrative formula entry is:

```json
{"sheet":"Inputs","cell":"A3","formula":"=A1+A2","originalCachedValue":999,"recalculatedValue":15,"comparison":"changed"}
```

`complete` requires a present finite scalar result for every admitted formula. Engine error cells produce `calculation_error`; unavailable engines, timeouts or missing output/caches produce `incomplete`. Empty text is a present value; null means no cache/result was observed. Booleans remain distinct from numbers.

`changed` and `unchanged` compare original and exported values. Numeric equality uses absolute and relative tolerance `1e-9`; booleans and text compare by exact type and value. `no_cached_value` records absence of an original cache. These labels do not certify freshness or correctness. You can download the dataset as JSON or other platform-supported formats; nested formula results are best consumed as JSON.

### How much does a report cost?

The initial test price is **$0.05 per accepted
`useful-report` event**. Only a complete useful recalculation report with at
least one formula can attempt that event, after its dataset record has
persisted. Demo, refusal, calculation errors, incomplete work and persistence
failures emit zero events. An accepted count other than one, or a charge
exception, fails visibly and is never retried automatically. Unpriced development
runs do not attempt a charge. The five corrected
private cases produced one accepted event for the complete case and zero for
the other four. This is a configured experimental price, not revenue or paid
settlement evidence.

Across the two private builds and seven runs, conservative workbook execution
cost was $0.02762387464959423. That accounting includes the retained initial
incomplete run whose profile-lock race was fixed in the corrected build. It does
not establish economics for larger files, other request mixes, or sustained
traffic. External demand, customer savings and sustained commercial margin
remain unvalidated.

### Troubleshooting and support

For `unsupported`, inspect the diagnostic and reduce unsupported content or workbook size. For `incomplete`, keep the original input and engine identity when reproducing the issue. A formula error remains `calculation_error` even if other formula results exist. Report useful reproduction details through the Issues tab without sharing private workbook contents.

Maintainers can find the locked offline checks and the exact native
build-verification procedure in [VALIDATION.md](VALIDATION.md). Private
configuration uses 1024 MiB, a 180-second platform timeout, automatic restart
disabled and standby off. The present evidence covers the stated frozen cases;
it does not extend the supported subset or resource limits.

# Actor input Schema

## `mode` (type: `string`):

Demo is illustrative and uncharged; recalculate requires workbookBase64.

## `workbookBase64` (type: `string`):

Required only for recalculate. Maximum decoded bytes 2097152. No URLs.

## Actor input object example

```json
{
  "mode": "demo"
}
```

# Actor output Schema

## `reports` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("l3digital/workbook-recalculation-report").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("l3digital/workbook-recalculation-report").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call l3digital/workbook-recalculation-report --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,l3digital/workbook-recalculation-report"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/Lxp1vW6IU2enHueDi/builds/65nUdPHJdNjL5KPEq/openapi.json