zSYNC Code Fields

zSYNC Code Fields are Python based data fields, used across many Worker types (Mapper, Python Code Worker, Web Worker, SQL Executor, and more), to allow for deeper customisability of each pipeline. Data is passed between workers as Zebroo Sets — a Python wrapper around dicts/lists that adds dot-notation access and JSON serialisation — and every code field also gets access to a standard set of variables and helpers.

Available Variables

Variable	Available In	Description
record	Workers with list input	The current record being processed.
data	Workers with list input	The input records of the current batch - all input records only with Batch Size 0. See Batches.
index	Workers with list input	Index (0-based) of the current record within the current batch.
errors	Python Code Worker	Read-only: the errors of the batches of this pipeline run that already failed. Writing to it raises an error.
input	Workers with list input	Alias of the worker's input data, available alongside data.
response	Web workers	The HTTP response object of the request triggered by the worker.
env	All code fields	The Odoo environment, e.g. env['account.move'].
instance	All code fields	The current zbs.instance record (this pipeline run).
instance_env	All code fields	The instance environment dict — runtime values shared across workers in the same pipeline run.
initial_data	All code fields	The payload the pipeline run was started with, unchanged by later workers. Useful in REST-triggered pipelines to reach the original request body from any worker.
instance_line	All code fields	The zbs.pipeline.line currently executing — this worker's own position in the pipeline.
vars	All code fields	Named, per-environment variables, e.g. vars.my_variable.
environment	All code fields	The current zbs.environment record.
logger	All code fields	Logging object, e.g. logger.info(...).
arrow	All code fields	The Arrow date library.
datetime, date, timedelta	All code fields	Python's standard datetime objects.
base64	All code fields	Python's base64 module.
Path	All code fields	pathlib.Path.
last_execution_date	All code fields	Datetime of the last successful pipeline run — commonly used in Grabber domains for incremental syncs.
SkipRecord	All code fields	Exception to raise to skip the current record and continue the pipeline.
ZBSPipelineException	All code fields	Exception to raise to abort the pipeline with an error.

For record, data, index, and response — the variables tied to the data flowing through the pipeline — see Zebroo Sets.

Batches: what data and index cover

A pipeline line splits its input into batches of Batch Size records and runs each batch on its own. data and index always refer to the current batch, not to everything the previous step produced:

Batch Size on the line	data contains	index
0 (default)	all input records, in one batch	position in all input records
1	exactly one record - the current one	always 0
n	up to n records	position within the batch

Logic that has to see the whole input - removing duplicates ("first occurrence wins"), counting, sums, checking whether a value already appeared - only works with Batch Size 0 on that line. With a smaller batch size it runs once per batch and silently misses everything outside the current batch. The same applies to "Do not aggregate step results": the code gets the records of the current batch, not of the whole run.

Small batches are useful where one failing record must not stop the others (e.g. one HTTP call per record). Then do the checks that need all records in a step before, with Batch Size 0.

Errors of earlier batches (errors)

errors lists the errors of the batches of this pipeline run that already failed. It is collected only when your code uses it, so pipelines that never look at it don't pay for it.

errors is read-only. Appending to it (errors.append(...), errors += [...]) used to have no effect at all; it now fails the record with an error. To report something, use logger.warning(...); to leave a record out, raise SkipRecord; to fail a record, raise an exception.

if not record.vat:
    logger.warning("Customer %s has no VAT id - skipped" % record.name)
    raise SkipRecord
record

Odoo Environment (env)

Available in every code field, env is the standard Odoo environment. It gives full access to any model available on the Odoo instance zSYNC is installed on, exactly as in server-side Odoo Python code.

# Browse and act on records directly
env["account.move"].browse(record.invoice_id).action_post()

Instance and Instance Env (instance, instance_env)

instance is the current zbs.instance record — the specific pipeline run currently executing. instance_env is that run's environment dict, used to pass values between workers without routing them through the record data itself (session tokens, counters, flags, or values received from a trigger).

instance_env["session_cookies"] = {"bearer_token": response.headers["Authorization"]}

Variables and Environment (vars, environment)

environment is the current zbs.environment record (e.g. "Production", "Staging") the pipeline is running under. vars gives access to named, typed variables (string/int/float/bool) configured per environment, so the same pipeline can behave differently depending on which environment it runs in.

api_key = vars.my_api_key

Logging (logger)

Use logger to write to the standard Odoo/zSYNC logs instead of print(), so messages show up correctly in log output and instance debugging views.

logger.info(f"Processing record {record.id}")

Dates (arrow, datetime, date, timedelta)

Standard Python date/time handling is available in every code field, plus the Arrow library for more ergonomic date arithmetic and parsing.

from_date = datetime.strptime(record.date, '%Y.%m.%d')
record.date = from_date.strftime('%d/%m/%Y')
record

Other Helpers (base64, Path)

base64 (Python's standard module) and Path (pathlib.Path) are pre-imported for convenience when handling encoded payloads or file paths.

Last Execution Date (last_execution_date)

The datetime of the pipeline's last successful run. Most commonly used in a Grabber's domain/filter to fetch only records changed since then, e.g. an Odoo Grabber domain of [('write_date', '>=', last_execution_date)].

Exceptions

Raise these from any code field to control pipeline flow:

raise SkipRecord                          # skip this record, continue the pipeline
raise ZBSPipelineException("message")     # abort the pipeline with an error
raise RetryableJobError("message", seconds=60)  # retry this step after N seconds (Queue Jobs only)
raise RetryInNextTimeframe                 # retry in the next scheduled run