Change an existing XLSX file

This example changes Remediation!E2 from In Progress to Closed. The output is a new XLSX file. The source file is not overwritten.

• Download the input workbook
• Download the checked output workbook
• Inspect the operation result and verification
• Run this operation from the quick start

Run the same change locally

Install with npm install @runstamp/sdk. The code below uses the public input workbook and the local transport. It does not upload the file to Runstamp.

import { createHash } from "node:crypto";
import { writeFile } from "node:fs/promises";
import { runstamp } from "@runstamp/sdk";

const response = await fetch(
  "https://runstamp.com/demo-evidence/operation-evidence/xlsx/xlsx.transform/input-01-workbookBase64.xlsx",
);
if (!response.ok) throw new Error(`Input download failed: ${response.status}`);
const source = Buffer.from(await response.arrayBuffer());
const artifactId = createHash("sha256").update(source).digest("hex");

const result = await runstamp.operations.run("xlsx.transform", {
  workbookBase64: source.toString("base64"),
  artifactId,
  writes: [{
    locator: { artifactId, scheme: "xlsx.a1", value: ["Remediation", "E2"] },
    value: "Closed",
  }],
});

if (!result.ok) throw new Error(`${result.error.code}: ${result.error.remediation}`);
const checks = result.verification?.ladder;
if (checks?.valid.state !== "pass"
  || checks.preserved.state !== "pass"
  || checks.intendedChangeVerified.state !== "pass") {
  throw new Error("The bounded workbook change did not pass its required checks.");
}
await writeFile("remediation-closed.xlsx", result.value.output.bytes);

In a clean install of @runstamp/sdk@3.1.0, this code produced the output above, SHA-256 e830675c803c0a75cba7c0fac81430a82ac3101a2b74de5c2b82c987f8d24a7b. valid, preserved and intendedChangeVerified pass. Preservation covers workbook identities, styles, names, tables, hidden state, validation and cells outside the declared change.

result.value.mutation.changes is the record of the cells the operation changed. On the Managed API it lists every cell that differs between the file you sent and the file returned: each cell you wrote (cause: "write") and each formula cell nobody wrote whose saved result was recomputed because it reads a written cell (cause: "recalculation", with the formula and the saved result before and after). A cell is listed when its stored value differs, even if the cell's number format shows both values the same, as with a percentage of 5.3% before and after. The local SDK lists the same cells from @runstamp/sdk@3.2.1. A formula that may read a written cell but that the engine cannot recompute (for example an unsupported function or an array formula) keeps its saved result until the workbook recalculates, which Excel does on open; each such cell is named in result.value.mutation.issues with code XLSX_FORMULA_NOT_RECALCULATED, its formula and its saved result.

The local operation reports deliveryReady: not_checked. It does not verify appearance or behavior in the recipient's Excel version, or whether Closed is the right business decision. Check those separately before delivery.

For a variant that reads the value before writing, follow the quick start. To evaluate a customer workbook, send the exact change and acceptance requirements through Contact sales. Send confidential files only through approved channels.