Write and Read Variables and Tables

This page uses the new zw. syntax. It will work starting with agent v1.1.72. If your agent is older, use the non-prefixed calls getRef() and setRef() instead of zw.getRef() and zw.setRef().

Read and write persistent values in variables and tables with zw.getRef() and zw.setRef().

API zw.getRef(), zw.setRef()

// Get a value from a table column or a variable
const profileName = await zw.getRef({ ref_id: 5079, name: "Profile Name" });

// Save a value to a table column or a variable
await zw.setRef({ ref_id: 4372, name: "Profile Name Copy", value: profileName });

---

At a Glance

• async await zw.getRef({ ref_id: number, name: string }) → string → returns the string value from a variable or table column.

• async/sync* await zw.setRef({ ref_id: number, name: string, value: string }) → void → saves a string value to a variable or table column.

*async in browser, sync locally (see Local vs. Browser Execution).

---

What’s ref_id?

In ZeroWork, tables and variables are data groups. Each data group has an ID called ref_id.

• Table ref_id is shown in the left sidebar next to the table name.

• Variables ref_id is shown in the Variables dialog.

  

• name identifies a table column or a variable in the Variables group. Names are case-sensitive.

  // Read a table column by its table ref_id and column name
  const profileName = await zw.getRef({ ref_id: 5079, name: "Profile Name" });
  
  // Same variables ref_id for different variable names
  const date = await zw.getRef({ ref_id: 4379, name: "date" });
  const counter = await zw.getRef({ ref_id: 4379, name: "counter" });

---

Saving Non-String Values

Values are stored as strings. To store arrays or objects, stringify on write and parse on read. Passing a non-string value to zw.setRef() throws an error.

// 🚫 Won't work (value must be a string)
await zw.setRef({ ref_id: 4379, name: "chars", value: ["a", "b", "c"] });
// Error: The value argument must be a string.

Example

// Save objects or arrays (stringify on write)
await zw.setRef({
  ref_id: 4379,
  name: "animals",
  value: JSON.stringify([{ category: "cat" }, { category: "dog" }]),
});

// Read and use it (parse on read)
const animalsArray = JSON.parse(
  await zw.getRef({ ref_id: 4379, name: "animals" })
);

---

Loops and Row Behavior

zw.getRef() and zw.setRef() follow ZeroWork’s loop logic:

• Read existing rows → place Start Repeat with dynamic loop before your Write JavaScript building block.

• Append new rows → place Start Repeat with standard loop before the block or use a custom append with appendIndex.

Read more about how loops work in ZeroWork: Start Repeat.

Custom append without Start Repeat

Use appendIndex to add rows from a loop in your code. appendIndex: 0 is the first appended row. If a table already has 3 rows, appendIndex: 0 becomes the 4th row.

⚠️ When using appendIndex, placing this Write JavaScript building block inside a Start Repeat loop can mix the built-in loop index with a custom appendIndex, causing mismatched rows.

Example

const valuesToSave = ["a", "b", "c"];
const TABLE_REF_ID = 4382;

let i = 0;
for (const val of valuesToSave) {
  await zw.setRef({
    ref_id: TABLE_REF_ID,
    name: "value",
    value: val,
    appendIndex: i,
  });
  i++;
}

The resulting table:

Update existing rows in a custom code loop

Add a dynamic Start Repeat building block to iterate rows and use the Write JavaScript building block within that loop. As long as your Write JavaScript is inside that loop, it will have access to the values inside the row that is currently being iterated over. If you need true in-code row access, share your use case in Discord in the #ideas-feature-suggestions channel.

---

Common Pitfalls

• Always use await in the browser. In the browser, zw.getRef() and zw.setRef() are async — use await.

  // 🚫 Won't work (running in the browser)
  const name = zw.getRef({ ref_id: 5079, name: "Profile Name" }); // missing await → name is a Promise, not a string
  await zw.setRef({ ref_id: 4379, name: "Copy", value: name }); // throws error
  // Error: The value argument must be a string.
  
  // ✅ Works
  const name2 = await zw.getRef({ ref_id: 5079, name: "Profile Name" });
  await zw.setRef({ ref_id: 4379, name: "Copy", value: name2 });

• Match the exact name (case-sensitive).

  // 🚫 Won't work (case mismatch)
  await zw.getRef({ ref_id: 5079, name: "profile name" });
  // Error: This variable or column does not exist.
  
  // ✅ Works
  await zw.getRef({ ref_id: 5079, name: "Profile Name" });