1. Qube
2. Qube! Documentation
3. Developer's Guide
4. Customizing the Qube UI
5. Submission Interface Plugins

Submission Interface Plugins

Like the menu and panel plugin types, the submission plugins are written in Python 3. Each submission plugin is executed directly by the plugin system so, for example, you can use Python to automate the building of parameters, pre-fill default values, or adapt to changes the user makes.

The best place to start when creating a new submission plugin is to copy an existing one that's closest to what you intend to make. For the purposes of this documentation we'll start from scratch and create a new plugin for making proxy images using imagemagick.

The process is as follows:

1. Add the submission type.
2. Add a new page for the input path field.
3. Add parameters.
4. Override defaults for fields in the Qube Basics page.
5. Set the command template.

1. Add the submission type

The first thing to do is tell the UI we're adding a new submission plugin, we do this by calling the built-in function add_submission_type() . For this example we use the following parameters:

# Create a new submission type
add_submission_type('Make proxy',
                    short_name='Make Proxy',
                    type="makeProxy",
                    has_range=False,
                    can_batch=False,
                    thread_control='all',
                    prototype="cmdline",
                    group="Pipeline")

2. Add a new page for the input path field

Use pages to group related fields together. We add pages by calling add_page() with a single argument, the page's name.

add_page("Input")

3. Add parameters

After you add a page it becomes current, every field that follows is added to that page until you add a new one. We'll add a Source Path field using add_field().

add_field("Source Path",
          type="path",
          required=True,
          destination="package.sourcePath")

A description of all supported field types and their arguments is included at the end of this page so we'll just go over the arguments used in this example here. The first argument is always the name of the parameter and is generally shown along side the parameter in the submission dialog. The type argument is optional but recommended, it explicitly specifies what kind of parameter this is, such as a text field, a list or in this case a directory path (if we wanted a file path we'd use 'filename' as the parameter type). The required argument, when True, stops the user from submitting their job until the parameter has a valid value in the submission dialog. The destination argument tells the UI to store the value of the parameter in the submitted Qube! job in the specified position, in our example we store the Source Path in the job package. After submitting the job we can retrieve the value like this:

>>> my_job = qb.jobinfo(id=103307)[0]
>>> print(my_job['package']['sourcePath'])
/film/rotk/cv28_k1/2d/comp/3_01/1920x1080
>>>

You can also view it in the Job Package section of the Job Internals panel inside Qube! UI.

Let's keep going and make a parameter for the output path.

add_page("Output")

add_field("Destination Path",
          type="path",
          required=True,
          destination="package.destinationPath")

First we make a new page for our output parameters. The Destination Path parameter is nearly identical to our Source Path parameter so we skip explaining it and move on.

add_field("ProxyScale",
          default=50,
          min=1,
          max=100,
          required=True,
          destination="package.proxyScale")

We now add a parameter to specify the scale of the proxy as a percentage, this parameter is also required but since it also has a default (50%) we don't need to fill it manually, as long as we're happy with a 50% proxy that is. Notice that we haven't specified the parameter type, the UI infers that this is a integer spin box from the fact that we have min / max arguments and their values are integers. If no type can be inferred by the arguments the UI will use a single line text filed ( string type), this would have been the case for our source/destination path parameters if we hadn't explicitly set the type to path .

add_field("File Pattern",
          type="string",
          default="*.exr",
          required=True,
          destination="package.filePattern")

Our last field is a simple single line text field that allows the user to specify a file glob for the images to be resized, we set it's default to *.exr . 

3. Override defaults for fields in the Qube Basics page

For our proxy submission type we only want a single worker processing the images so we need to override some preexisting values controlling this.

set_field(page="Qube Basics", name="Farm Concurrency CPUs", value=1)
set_field(page="Qube Basics", name="Farm Concurrency Max", value=1)
set_field(page="Qube Basics", name="Retries", value=0)
set_field(page="Qube Basics", name="Retry Delay", value=0)

To set existing fields we use their page and parameter names and pass in a new value. Note that both page and parameter names are case sensitive.

4. Set the command template.

# Set the command template
set_command_template('mkdir -p %(Source Path)s/proxy; /usr/local/bin/magick mogrify -path %(Destination Path)s -resize %(ProxyScale)s%% %(Source Path)s/%(File Pattern)s')

The command template is where we specify the commands to be run on a Qube! worker during job execution. Firstly, for those new to Python you can create a string variable like this:

>>> my_dictionary = {}
>>> my_dictionary['name'] = 'Joe'
>>> my_dictionary['place'] = 'Rylstone'
>>> my_string = 'Hello %(name)s, have you been to %(place)s?' % my_dictionary
>>> print(my_string)
Hello Joe, have you been to Rylstone?
>>>

The command template works in the same way, where the parameter names act as the keys to the dictionary. In our example command template we make a new directory and then run magick to resize the images.

Supported Parameter types

Common arguments

string

A simple single line text field.

text

A multi line text field.

bool

A checkbox.

int

A integer spinbox.

float

A floating point spinbox.

combo

A drop down menu, allows for a single selection from a list of items.

path

A single line text field with a browse button that opens a file dialog to select a directory path.

combo_path

The same as the path parameter type but also allows for selection of paths from a combo.

filename

A single line text field with a browse button that opens a file dialog to select a file path.

combo_file

The same as the filename parameter type but also allows for selection of file paths from a combo.

list

A list box where the user can select either a single or multiple values.

table

A table of values of given dimensions that the user can enter values.

datetime

A date and time selection parameter.

selectorString

A selectorString parameter uses a Python function to generate a list of strings, take this example from the Worker Selection page (found in python/99_qube_parameters.py in the standard plugin path on your system).

def uniqueNoEmpty(l):
    regex = re.compile("^\s*$")
    return list(set([i for i in l if not regex.search(i)]))

def hostsSelector():
    return uniqueNoEmpty([host['name'] for host in qb.hostinfo()])
 
...

add_field("Hosts",
          tooltip="Specify which workers will run this job.\nSelecting no workers means that all workers "
                  "are elligible.",
          destination="hosts",
          selector=hostsSelector)

Here we create a Python function that takes no arguments and returns a list. We use the Qube! Python API module qb to find all Qube! workers and return that. Here's how that looks on my Qube! network after clicking the corresponding ... button.