Scripts and Python API

Bernard can be automated in two ways:

• scripts that Bernard launches itself, on a task (script task), on a selection (action), at a date (event) or when a value changes (trigger);
• the Python API (CallBernard): a library that a script, a plugin or an external tool uses to read and modify what Bernard contains.

Scripts and the API are meant for TDs and pipeline developers. An artist does not need them to work.

What scripts can do

Through the API, a script can:

• search for objects (projects, items, tasks, files, users…);
• read and write properties, one at a time or several at once;
• create and delete objects (a deletion made by a script goes to the Garbage bin, and can be restored just like a deletion made in the interface);
• compute paths according to the path variation and the workstation's system, create file versions, save or regenerate thumbnails;
• copy, move, upload or download files between path variations;
• read the instructions of a task and tick them, read and write the time spent;
• build template workflows (tasks, compounds, links) in a single call;
• open a media in the studio's player, as Bernard would (see Review);
• display a message window or a file selection window in the client.

A script acts with the permissions of the signed-in user. A write refused by the rules (state machine, permissions) does not raise an error: the call returns False. See Workflows, states and templates for these rules.

Script tasks

A script task is a workflow task that launches a command. The script thus becomes a step of the workflow, with its sources, its successors and its states.

What it carries:

How it runs:

1. When the task becomes Ready (its sources are finished), the Bernard on the designated workstation launches it. There is no Run button: to run a script again, set its task back to Ready.
2. It goes to WIP and its output (normal and errors) is written to Log. While it runs, the Log is updated every 5 seconds.
3. It goes to Done if the script ends with code 0, to Failed otherwise.

Rules to know:

• Which workstation? With Launch On filled in, it is that workstation, whichever user is signed in. With Launch On empty, it is the current workstation of the assigned user. In both cases the task must have exactly one assignee; a workstation that is off or several assignees prevent the automatic launch (a warning explains it in the Log). The typical case is a "robot" user alone in its department × role pair.
• Queue. At most 3 scripts run at the same time on a workstation (Local Settings › Max Simultaneous Script). The others wait, by priority; with equal priority, in the order in which they became Ready.
• Script chains. With the studio setting Subsequent scripts are executed first, the chain of scripts of one shot finishes before those of another shot continue.
• Stopping. Setting a task to Aborted stops the running script (and the processes it launched). If a task is reassigned while it runs (another user, department or workstation), the script stops and the task goes to Failed. Closing Bernard while a script is running asks for confirmation.
• Log. The Log keeps the end of the output if it is too long (studio settings Max number of lines for the logs of a task script and Max size in kiloBytes for the logs of a task script).
• Only one Bernard per workstation runs scripts: the main instance.

Actions, triggers and events

• An action is a command saved in the settings, which you launch by hand on a selection (right-click, submenus by department), which can start with Bernard, or which is fired by an event. At most three actions run at the same time (Max Simultaneous Action). An action succeeds if it writes nothing to its error output. The Action Log view shows "Waiting", "Running", "Success" or "Failed".
• A trigger watches a property (state, version, value) and launches an action when a condition is met. A Changed trigger does not fire if the value does not change.
• An event launches an action at a date, for users or roles, with a repetition (Never, Every Day, Every Week, Every Hour). An event that is no longer assigned to you no longer launches its action.

The Python API

Reference

The complete reference, generated from the code and kept up to date with every version, is online:

bernardengineapi.readthedocs.io

There you will find the CallBernard class (communicating with Bernard), tools for paths and third-party software (3DEqualizer, Nuke…) and the constants to use with the API. For each method: what it does, what it accepts, what it returns and the errors it reports. The application opens this reference from Help › API Documentation.

Connecting

The API talks to the Bernard client open on the same workstation, like a content creation software plugin (see DCC integrations).

• The Bernard client must be running and signed in.
• One connection per thread: calling CallBernard() again returns the same one.
• Objects are designated by their identifier (24 hexadecimal characters), properties by their name (State, Start Frame…).
• If no client is listening, the connection is refused (ConnectionRefusedError). An error on the Bernard side raises an exception with the client's trace.

from Bernard import CallBernard
from Bernard.Static import State, ClassName

bernard = CallBernard()
print(bernard.GetCurrentUserID())

Examples

The examples use made-up identifiers.

# My tasks to do, and set the first one to WIP
for task_id in bernard.GetMyTasks():
    print(bernard.GetPropertyValue(task_id, "Name"))

task_id = bernard.GetMyTasks()[0]
if not bernard.SetPropertyValue(task_id, "State", State.wip):
    print("refused: assignment, checklist, active fix…")

# Publish a new version of a file and get its path on this workstation
bernard.IncrementVersion(file_id)
print(bernard.GetPathValue(nodeID=file_id))

# The shots of a sequence that have a task in progress
shots = bernard.FindNodeIDs(parentIDs=[sequence_id], classNames=[ClassName.projectItem],
                            projectItemModelName="Shot")
wip = bernard.FindNodeIDs(parentIDs=[sequence_id], classNames=[ClassName.task],
                          propertyFilter={"State": [State.wip, State.pause]})

# Open a file in the studio player
bernard.OpenInPlayer(nodeID=file_id)

Method families

The complete list and the parameters are in the online reference.

What is new in the API in 2.1.48

• Create and configure tasks and compounds in the workflow of a template in a single call (properties, global / local modes, links), export them, change the mode of a property; everything is checked before anything is written.
• Create a project item template with its empty workflow.
• Search by property with a list of values (for example several states for State): an item matches if it has any of them.
• List all the applications able to open an extension, by priority, so as to take the first one installed on the workstation.
• An API that refuses to create a file under a validation task, where it would be visible nowhere.
• Searching the children of a folder no longer reads the whole database and is no longer interrupted after 60 seconds (fix of 2026-11-09, see Release notes).

Studio automation examples

These examples show what studios have automated with the API. They are scripts specific to studios, not product features. They are described here without any studio or project name, to illustrate the possibilities.

Principles these examples illustrate:

• ask Bernard for paths (GetPathValue), according to the workstation's path variation, instead of hard-coding them;
• find the applications and FFmpeg through the Bernard installation, not through a fixed path;
• go through the public CallBernard API, in a separate process, rather than through internal interfaces of the client.

Going further

• Workflows, states and templates: task states, script tasks in the workflow.
• DCC integrations: the plugins of content creation software, which use the same API.
• Review: opening a media in Bernard Review.
• API reference: bernardengineapi.readthedocs.io.