Scripting API [Beta]

As of version 2.0, Workflower has its own scripting API in beta to automate all kinds of processes in After Effects + Workflower.

IMPORTANT: As of version 2.5.1, the scripting API variable has been changed from wfAPI to workflowerScriptAPI in order to prevent possible issues stemming from short global variables. Please adapt your scripts to this change. The legacy variable wfAPI is currently still active but will be disabled in the future. (You will always be able to use the old variable in coming versions by going to Settings > System > Use Legacy Scripting API Variable wfAPI.)

Please be aware that the API is experimental at the moment and has to be used with caution! Some functions might not work as expected.

Also, the API is still very limited but this will change in the future as more functions will get added.

API Variable

The API variable (a global variable) is called:

workflowerScriptAPI

Workflower needs to have been started at least once in your current session for the API variable to be active.

You can easily check whether the API exists, like this (and if it doesn't exist, just open and close the ScriptUI Panel, so the variable gets established):

// FUNCTION: Check whether Workflower API Variable exists
function workflowerScriptAPIExists(){
    
    // If it exists --> Return true
    if (typeof workflowerScriptAPI !== 'undefined'){
        return true;
    }
    
    // Check whether the ScriptUI Panel is installed (& return false if not)
    var wfMenuID = app.findMenuCommandId('Workflower ScriptUI Panel.jsxbin');
    if (!wfMenuID){
        return false;
    }
    
    // Open & Close ScriptUI Panel to establish API Variable
    app.executeCommand(wfMenuID);
    app.executeCommand(wfMenuID);
    
    // If API Variable now exists, return true, else false
    if (typeof workflowerScriptAPI !== 'undefined'){
        return true;
    } else {
        return false;
    }

}

How to use API Functions

The Workflower functions listed below are exposed to the API. Just call them and use their arguments if you want to.

If a parameter is undefined, the default execution value is used.

Using Functions in Non-Active Comps

Currently, it is recommended to only use API functions in your active comp. They theoretically work when processing other comps but unexpected behaviors can occur!

The exception to this is workflowerScriptAPI.refreshLayout() and workflowerScriptAPI.refreshLayouts() which should execute the other comps properly when fed into the function.

So to be safe when using all other functions, always check whether the comp you want to work on is active. Like this:

// FUNCTION: Start the Workflower Execution
function startWfExecution(elementsToProcess){

    // Get Comp to Process from Element
    var compToProcess;
    if (elementsToProcess[0] instanceof CompItem){
        compToProcess = elementsToProcess[0];
    } else {
        compToProcess = elementsToProcess[0].containingComp;
    }

    // Check Active Comp & Change if needed
    var saveOrigActiveItem = app.project.activeItem;
    if (compToProcess !== app.project.activeItem){
        compToProcess.openInViewer();
    }

    // Return with Original Active Item, so we can revert back to it later
    return saveOrigActiveItem;
    
}

// FUNCTION: End the Workflower Execution
function endWfExecution(saveOrigActiveItem){

    // Switch Active Comp back if needed
    if (saveOrigActiveItem !== app.project.activeItem){
        saveOrigActiveItem.openInViewer();
    }
    
}

// Execute Workflower Action
app.beginUndoGroup("Create Multi-Layer Matte");
var layersToMatteTo = [layer1, layer2, layer3];
var startWfInfo = startWfExecution(layersToMatteTo);
workflowerScriptAPI.createMatte(layersToMatteTo);
endWfExecution(startWfInfo);
app.endUndoGroup();

Undo Groups

When calling a function through the API, Workflower will not create any undo groups to ensure that you can wrap everything in your own undo groups and don't get any undo mismatch errors.

The only exception to this is workflowerScriptAPI.execute() which lets you define whether you want Workflower to create undo groups or not.

Error Handling

At the moment, the Workflower API will not throw any custom errors. So always double-check with the user guide that the function is called properly. If you come across any unexpected errors, please contact customer support.

Attributes

workflowerScriptAPI.scriptVersion

workflowerScriptAPI.scriptVersion

The currently installed version number of Workflower.

Type

String of script version number; read-only

workflowerScriptAPI.apiVersion

workflowerScriptAPI.apiVersion

The current version number of the Workflower API.

Type

String of API version number; read-only

System Check Functions

workflowerScriptAPI.scriptExists()

workflowerScriptAPI.scriptExists()

Checks whether the Workflower script exists.

Returns

Boolean

workflowerScriptAPI.scriptUiPanelExists()

workflowerScriptAPI.scriptUiPanelExists()

Checks whether the Workflower ScriptUI Panel exists.

Returns

Boolean

Layer & Group Check Functions

workflowerScriptAPI.cleanNames()

workflowerScriptAPI.cleanNames(layerNames)

Cleans layer names, i.e. removes all special characters added by Workflower as well as the indent.

Parameters

• layerNames: Array of layer name strings to be cleaned.

Returns

Array of layer name strings

workflowerScriptAPI.isWfComp()

workflowerScriptAPI.isWfComp(comp)

Checks whether a given comp is a Workflower comp.

Parameters

• comp: Comp object to be checked.

Returns

Boolean

workflowerScriptAPI.isGroupHeader()

workflowerScriptAPI.isGroupHeader(layer)

Checks whether a given layer is a group header.

Parameters

• layer: Layer object to be checked.

Returns

Boolean

workflowerScriptAPI.getAllGroupLayers()

workflowerScriptAPI.getAllGroupLayers(groupHeader[, excludeStartersFooters])

Gets all group layers to a given group header.

Parameters

• groupHeader: Layer object of the group header.

• excludeStartersFooters: Optional. Boolean to determine whether returning array should exclude Workflower's internal shy'd starter and footer layers. Default is false.

Returns

Array of layer objects of the group layers

workflowerScriptAPI.isInTagID()

workflowerScriptAPI.isInTagID(layer, tagID)

Checks whether a given layer is within a tag group with a certain ID (0 - 16). Added in script version 2.04 / API version 0.2.

Parameters

• layer: Layer object to be checked.

• tagID: Integer of tag ID (0 - 16).

Returns

Boolean

workflowerScriptAPI.isInTagName()

workflowerScriptAPI.isInTagName(layer, tagName)

Checks whether a given layer is within a tag group with a certain name. Added in script version 2.04 / API version 0.2.

Parameters

• layer: Layer object to be checked.

• tagName: String of tag name.

Returns

Boolean

Major Functions

workflowerScriptAPI.execute()

workflowerScriptAPI.execute(functionName[, doCreateUndoGroup])

Executes a function, as specified by the function name. Names are identical to KBar function names.

This function only calls the regular Workflower functions as they are called by the user interface. The other dedicated API functions, on the other hand, let you define custom arguments as well.

workflowerScriptAPI.execute() is the only API function that allows for the automatic creation of Workflower's regular undo groups. Set doCreateUndoGroup to true if you want to force it to create undo groups.

Parameters

• functionName: String of a function name to be executed. Names are identical to KBar function names.

• doCreateUndoGroup: Optional. Boolean to define whether you want Workflower to create its regular undo groups. Default is false.

Returns

Nothing

workflowerScriptAPI.kbarExecute()

workflowerScriptAPI.kbarExecute(functionName)

Allows to execute a function, as specified by the function name, via KBar's Run Scriplet feature. Names are identical to KBar function names.

Since workflowerScriptAPI.execute() cannot execute via KBar's Run Scriptlet feature, workflowerScriptAPI.kbarExecute() is needed instead.

workflowerScriptAPI.kbarExecute() always creates undo groups compared to the other API functions.

workflowerScriptAPI.kbarExecute() is only meant to execute a single command via KBar's Run Scriptlet feature. If you want to run multiple commands, you need to use workflowerScriptAPI.execute() or any other function listed here, wrap the commands within a function and call the function with app.setTimeout(), so for example:

function createAndStoreGroup(){
    app.beginUndoGroup("Create and Store Group");
    var layers = app.project.activeItem.selectedLayers;
    var newGroupHeader = workflowerScriptAPI.createGroup(layers, "New Group", false, false, false);
    newGroupHeader.selected = true;
    workflowerScriptAPI.execute("storeLayers1", false);
    app.endUndoGroup();
}
app.setTimeout(createAndStoreGroup, 1);

Parameters

• functionName: String of a function name to be executed. Names are identical to KBar function names.

Returns

Nothing

workflowerScriptAPI.refreshLayout()

workflowerScriptAPI.refreshLayout([comp, doNotLabelLayersOutsideToNone])

Refreshes the comp layout.

Parameters

• comp: Optional. Comp object to be refreshed. Default is current comp.

• doNotLabelLayersOutsideToNone: Optional. Sets the current comp to not label layers outside groups to 'None'. Default is false. Added in script version 2.03 / API version 0.11.

Returns

Nothing

workflowerScriptAPI.refreshLayouts()

workflowerScriptAPI.refreshLayouts(comps[, doNotLabelLayersOutsideToNone])

Refreshes the layout of multiple comps. Added in script version 2.04 / API version 0.2.

Parameters

• comps: Array of comp objects to be refreshed. Default is none.

• doNotLabelLayersOutsideToNone: Optional. Sets the comps to not label layers outside groups to 'None'. Default is false.

Returns

Nothing

workflowerScriptAPI.createGroup()

workflowerScriptAPI.createGroup(groupLayers[, groupName, parentGroup, groupOpacity, groupTrim])

Creates a Workflower group.

Parameters

• groupLayers: Array of layer objects to be grouped.

• groupName: Optional. String of the group name. Default is GROUP [Increment].

• parentGroup: Optional. Boolean to parent the group. Default is false.

• groupOpacity: Optional. Boolean to use group opacity. Default is false.

• groupTrim: Optional. Boolean to use group trim. Default is false.

Returns

Layer object of the group header

Example

This script creates a group and moves the group to the beginning of the composition.

// Define Layer Array to be grouped
var layersToGroup = [layer1, layer2, layer3];

// Create the new Group with our Layer Array
var newHeader = workflowerScriptAPI.createGroup(layersToGroup, "My New Group", true, false, false);

// Get All Group Layers, so we can move them (including internal Starters & Footers)
var allGroupLayers = workflowerScriptAPI.getAllGroupLayers(newHeader, false);

// Move all Group Layers (& make sure to unlock + re-lock Layers since Starters & Footers are locked Layers)
for (var i = allGroupLayers.length - 1; i >= 0; i--){
    var groupLayer = allGroupLayers[i];
    var wasLocked = groupLayer.locked;
    groupLayer.locked = false;
    groupLayer.moveToBeginning();
    groupLayer.locked = wasLocked;
}

// Afterwards, refresh Layout (in case, Indent or similar has to be adjusted)
workflowerScriptAPI.refreshLayout();

workflowerScriptAPI.selectGroups()

workflowerScriptAPI.selectGroups(groupHeaders)

Selects Workflower groups.

Parameters

• groupHeaders: Array of group header layer objects to be selected.

Returns

Nothing

workflowerScriptAPI.createMatte()

workflowerScriptAPI.createMatte(layers)

Creates a matte to a given set of layers. On regular layers, creates a matte to them. On group headers, creates a group matte.

Parameters

• layers: Array of layer objects for the matte to be created to.

Returns

Layer object of the created matte