Workflow Documentation

This documentation provides information on the Worfklow class and its API reference.

If you are new to developing Xi-CAM plugins, it is recommended that you follow the quick-start documentation first.

For more general development resources, see the Resources page.

Note that the examples in this documentation can be run in a python interpreter outside of Xi-CAM (for demonstration purposes). Auxiliary support code to be able to do this is marked with a comment # Only need if not running xicam. When developing within Xi-CAM, you will not need the lines of code marked with that comment.

What Is a Workflow?

In Xi-CAM, a Workflow is represents a sequence of one or more OperationPlugins to execute. Basically, it allows you to process data through some pipeline of operations. Multiple operations can be linked together in a Workflow, provided that the connection between any two operations is compatible (based on inputs and outputs). Execution can be performed asynchronously or synchronously.

Where Is Workflow?


What Does a Workflow Look Like?

As mentioned previously, a Workflow can be thought of as a graph-like structure. We can add operations (nodes) and connect them with links (edges).


from xicam.core import execution  # Only need if not running xicam
from xicam.core.execution import localexecutor  # Only need if not running xicam
from xicam.core.execution import Workflow
from xicam.plugins.operationplugin import operation, output_names

execution.executor = localexecutor.LocalExecutor()  # Only need if not running xicam

# Define our operations
def my_add(x, y):
    return x + y

def my_sqrt(n):
    from math import sqrt
    return sqrt(n)

# Instanciate operations
add_op = my_add()
sqrt_op = my_sqrt()

# Create a Workflow and add our operation instances to it
workflow = Workflow()
workflow.add_operations(add_op, sqrt_op)

# Link the "sum" output of add_op to the "n" input of sqrt_op
workflow.add_link(add_op, sqrt_op, "sum", "n")

# Execute the workflow, sending 1 and 3 as initial inputs to add_op (the first operation)
# This should give us sqrt(1 + 3) -> 2.0.
result = workflow.execute_synchronous(x=1, y=3)
print(result)  # Should be ({"square_root": 2.0},)

In this example, we use an addition operation and a square root operation in our Workflow. We want to add two numbers, then take the square root of the sum.

First, we instanciate our two operation types. This gives us an add_op operation object and a sqrt_op operation object.

Next, we add our operations to the workflow.

We then want to link the operations together so we first add two numbers, then take the square root of the result. We do this by connecting add_op’s “sum” output to sqrt_op’s “n” input.

Now that we have added our operations and connected them as we like, we can run our workflow. In this case, we will use execute_synchronous (there are other methods for execution which will be explained later).

However, if we just were to try workflow.execute_synchronous(), the workflow wouldn’t know what the “x” and “y” inputs are supposed to be for the first operation, add_op.

We can either:

  1. pass in data into the first operation(s)’ inputs when we call an execute method on the workflow

  2. have a GUI widget that exposes the operations through the GUI (such as WorkflowEditor), which can provide values directly to the operations’ inputs

In this example, we used option 1 (for an example of option 2, see the ExamplePlugin’s use of WorkflowEditor in the quick-start documentation). To do this, we passed x=1 and y=3 to our execute_synchronous call, which provided values for the invert operation’s x and y input arguments.

Useful Methods for Modifying the Workflow

Here is a condensed version of the various ways to modify a Workflow’s operation and links. For more information, see the API Reference.

Adding, Inspecting, and Removing Operations

Adding operations:

  • add_operation – add an operation to the Workflow

  • add_operations – add multiple operations to the Workflow

  • insert_operation – insert an operation at a specific index in the Workflow

Inspecting operations:

  • operations – get the operations currently in the Workflow

Removing operations:

  • remove_operation – remove an operation from the Workflow

  • clear_operations – remove all operations from the Workflow

Enabling and Disabling an Operation

It is possible to enable or disable operations. By default, all operations added to a Workflow are enabled. For more information, see the API Reference.

Executing a Workflow

When you execute a Workflow, the operations are executed based on how they are linked together.

There are a few ways to run a Workflow: execute, execute_synchronous, and execute_all.

Synchronous Execution

As we saw in our example earlier, we can use execute_synchronous to run a Workflow as a normal snippet of Python code. When this method is run, the we wait until we get a result back before the interpreter can continue running code.

API Reference