Record

The Record class represents a single data record on a table. It is available as a global in all script actions — no import is needed.

Constructor

record = Record(table=context.table, data={})

Parameter	Type	Required	Default	Description
table	APITable	Yes	—	The table this record belongs to. Use context.table.
data	dict[str, Any]	Yes	—	Field values keyed by field name. Pass {} for an empty record.
primary_key_value	Any	No	None	Explicit primary key. Auto-derived from data if omitted.
context	dict[str, Any]	No	{}	Contextual/response parameters from the API.
attachment_metadata	list[AttachmentMetadata] | None	No	None	Attachment metadata for this record.
attachments	list[Attachment]	No	[]	Attachment file data.
mapping_variables	dict[str, Any]	No	{}	Temporary variables used during field mapping.
lookup_records	dict[str, list[Record]]	No	{}	Lookup results keyed by lookup definition name. Set by the migration engine when lookups are configured; rarely set manually.
source_record	Record | None	No	None	Linked source record (set by the migration engine).
target_record	Record | None	No	None	Linked target record (set by the migration engine).

Note: On construction, any fields defined on the table that are missing from data are automatically filled with None.

Properties

Property	Type	Description
data	dict[str, Any]	The record's field values. Read and write via record.data["field_name"].
primary_key_value	Any	The primary key value. Auto-set from data using the table's primary key field.
context	dict[str, Any]	Contextual parameters (e.g. API response metadata).
table	APITable	The table this record belongs to.
attachment_metadata	list[AttachmentMetadata] | None	Attachment metadata entries.
attachments	list[Attachment]	Attachment file data.
mapping_variables	dict[str, Any]	Temporary variables for use during mapping.
source_record	Record | None	Linked source record (set by the migration engine).
target_record	Record | None	Linked target record (set by the migration engine).
lookup_records	dict[str, list[Record]]	Lookup results keyed by lookup definition name.
record_report	RecordReport	Status and error tracking for this record.

Methods

set_primary_key_value

record.set_primary_key_value(value=None)

Explicitly set the primary key value. If value is None, the method attempts to derive it from record.data using the table's primary key field name, falling back to record.context.

This also updates record.data[pk_field_name] to keep the data dict in sync.

lighten

light = record.lighten()

Returns a lightweight copy of the record with only table, data, and primary_key_value — no attachments, source/target links, or report.

Common Patterns

Creating a record from API response data

record = Record(table=context.table, data={})
record.data["sys_id"] = item.get("sys_id")
record.data["name"] = item.get("name")
record.data["status"] = item.get("status")

Bulk-populating fields from a dict

record = Record(table=context.table, data={})
for key, value in api_response.items():
    record.data[key] = value

Setting the primary key after insert

# After the API returns the new ID
record.data["id"] = response_data.get("id")
record.set_primary_key_value()  # re-derives from data

Reading the primary key

pk = record.primary_key_value
# or equivalently:
pk = record.data[context.table.primary_key_field.name]