Request

Response

    Executor Specific Payloads

    Bifrost Executor Payload

    Using the Bifrost executor, this payload needs to be provided when submitting a job using the Create job endpoint.

    Working with Bifrost Graphs

    Use Maya to create and edit a Bifrost graph. See the documentation on how to build and modify graphs. Once a graph is created, it can be published as a JSON file. This graph file can be used with the Bifrost executor inside the Flow Graph Engine API. See the Maya documentation on publishing effects as graphs. Typically, to find value in running a graph on the Flow Graph Engine, the graph will be built and configured to produce some output file(s) on disk that can be retrieved as output in the API.

    See payload.definitionFiles below on how to provide the graph file(s) to the Bifrost executor.

    Available Bifrost Versions

    When using the Bifrost executor, different versions of Bifrost are available to execute a graph. It is strongly recommended to select the exact version of Bifrost for which the graph was created using the bifrostVersion attribute in the options. The currently available versions are 2.9.0.0 and 2.12.1.0. It is recommended to always provide the bifrostVersion option as the default Bifrost version being used when it is not provided is subject to change in the future.

    Payload Structure

    Expand all
    payload*
    object
    Specifies the Bifrost-specific information indicating what Bifrost should do.
    action*
    enum:string
    Specifies the overall action that Bifrost should perform for this job. Possible values: Evaluate, ListPorts
    options*
    object
    Additional options for this job.
    compound*
    string
    Specifies the fully qualified name for the Bifrost compound to evaluate.
    frames
    object
    Specifies which frames the job should iterate over. Using this option implies that this is a multi-frame sequential evaluation.
    start
    int
    The number of the first frame in the sequence.
    end
    int
    The number of the last frame in the sequence.
    fps
    number
    The frames per second value to use together with the frames to deduce time.
    terminalStates
    array: object
    The state of the Bifrost terminals for the executions
    name*
    string
    The fully qualified name of the port description of the terminal.
    enabled*
    boolean
    Whether the given terminal is enabled when the graph is executed.
    *
    maxPerExecutionTimeInSeconds
    int
    Max execution time for each execution, specified in seconds. The API will attempt to limit the execution to run for no longer than this. Can be set to up to 86400 seconds (24 hours).

    Note: Additional limitations may apply, meaning that an execution may be canceled prior to reaching this limit.

    bifrostVersion
    string
    The version of Bifrost to be used to execute the graph.
    definitionFiles
    array: object
    The list of Bifrost definition files to load. Each Bifrost definition file represents a published Bifrost graph in JSON file format, they will be loaded in the order they are provided.
    details
    object
    Provides task executor-specific additional details for the input resource
    source*
    one of
    Represents an external storage location, either a URI or a reference into a storage space.
    URI storage location*
    object
    A URI where a particular resource is located.
    uri*
    string
    The resource URI
    **
    Space storage location*
    object
    Represents a storage location within a specific storage space
    key*
    string
    The unique key within the storage space that refers to the particular object within the space.
    spaceId*
    string
    An ID for a specific storage space, unique within the job
    **
    target
    object
    Describes how a resource is mapped to a local view, e.g. a file path where the resource should be placed or found.
    path
    string
    A file system path referring to a location on disk. File system paths are always interpreted as Posix style and will always be transformed into relative paths. This includes them being case sensitive, and in addition control characters are not permitted.

    Max length: 4000

    ports
    object
    The list of Bifrost ports to set.

    See the documentation on input ports and job ports.

    inputPorts
    array: object
    List of Bifrost input ports to set
    name*
    string
    The name of the port to be set.
    value*
    string
    The value to set, as a JSON value serialized to string
    type*
    string
    The port type.
    *
    jobPorts
    array: object
    List of Bifrost job ports to set
    name*
    string
    The name of the port to be set.
    value*
    string
    The value to set, as a JSON value serialized to string
    type*
    string
    The port type.
    *
    executions
    array: object
    List of executions of the Bifrost graph to perform. Each execution specifies a set of configurations to be applied to the graph.
    inputs
    array: object
    List of inputs that are required for this execution. This specifies the inputs to be downloaded before the execution starts.

    Note: Execution inputs can be specified in addition to task inputs. While task inputs are downloaded at the start of the task for all subsequent executions, execution inputs are downloaded individually for each execution.

    details
    object
    Provides task executor-specific additional details for the input resource
    source*
    one of
    Represents an external storage location, either a URI or a reference into a storage space.
    URI storage location*
    object
    A URI where a particular resource is located.
    uri*
    string
    The resource URI
    **
    Space storage location*
    object
    Represents a storage location within a specific storage space
    key*
    string
    The unique key within the storage space that refers to the particular object within the space.
    spaceId*
    string
    An ID for a specific storage space, unique within the job
    **
    target
    object
    Describes how a resource is mapped to a local view, e.g. a file path where the resource should be placed or found.
    path
    string
    A file system path referring to a location on disk. File system paths are always interpreted as Posix style and will always be transformed into relative paths. This includes them being case sensitive, and in addition control characters are not permitted.

    Max length: 4000

    outputs
    array: object
    List of expected outputs for this execution. This specifies the outputs to be uploaded after the task completes.
    details
    object
    Additional executor-specific details for the expected output from a task.
    source
    object
    Describes how a resource is mapped to a local view, e.g. a file path where the resource should be placed or found.
    path
    string
    A file system path referring to a location on disk. File system paths are always interpreted as Posix style and will always be transformed into relative paths. This includes them being case sensitive, and in addition control characters are not permitted.

    Max length: 4000

    target*
    object
    Information about an expected output from a task. The output can be retrieved by clients using the resulting output path, which has the general format ‘[/{taskName}][/{taskIndex}]/{outputName}’, where the output name corresponds to the name property of the output.
    name*
    string
    A ‘path’ identifier to uniquely access an output or log produced by a task. The general format is ‘[/{taskName}][/{executionIndex}]/{outputName}’.
    jobPorts
    array: object
    List of Bifrost job ports to set for this execution.
    name*
    string
    The name of the port to be set.
    value*
    string
    The value to set, as a JSON value serialized to string
    type*
    string
    The port type.
    *
    inputPorts
    array: object
    List of Bifrost input ports to set for this execution.
    name*
    string
    The name of the port to be set.
    value*
    string
    The value to set, as a JSON value serialized to string
    type*
    string
    The port type.
    *
    templateRange
    one of
    The range of values that the template should be instantiated over.
    Range sequence
    object
    A range of integers from start to end (inclusive).
    start*
    int
    The first value in the range
    end*
    int
    The last value in the range
    *
    Range array
    array: integer
    A sequence of integers to be used as a range in a template.
    frameId
    one of
    Sets the frame number for the execution.

    Note: Frame Ids must be set for all or none of the executions.

    Frame Id
    int
    Frame Id to use to set time for this execution.
    Frame Id Template
    string
    Template that is instanced to generate the Frame Ids for templated executions.
    *
    * Required

    Templated Executions

    Templating facilitates the definition of multiple executions by specifying patterns and mappings. The templateRange attribute specifies a range or list of numbers that can be used to replace patterns in file paths, and in the frameId attribute. The typical use case is to create a series of executions mapping to specific frames with different inputs. Note that job ports and input ports cannot have patterns as part of the template.

    Here is an example of how to use the templateRange attribute in the payload along with the frameId attribute:

    {
      "executions": [
        {
          "templateRange": {
            "start": 5,
            "end": 10
          },
          "frameId": "{executionId:01d}",
          "inputPorts": [],
          "jobPorts": [],
          "inputs": [
            {
              "source": {
                "key": "graph_inputs.{executionId:04d}.bob",
                "spaceId": "scratch:@default"
              },
              "target": {
                "path": "graph_inputs/graph_inputs.{executionId:04d}.bob"
              }
            }
          ],
          "outputs": [
            {
              "source": {
                "path": "output{executionId:03d}.bob"
              },
              "target": {
                "name": "output{executionId:03d}.bob"
              }
            }
          ]
        }
      ]
    }
    
    Show More

    In this example, the templateRange attribute specifies a range from 5 to 10. One execution is created for each number in the range by replacing executionId in patterns in the inputs and outputs as well as in the optional frameId attribute. The frameId attribute maps each execution to a frame, so the associated Bifrost graph will be executed for frames 5 through 10.

    Format String in Patterns

    The format strings follow the Python format syntax. Formatted string literals (also called f-strings) let you include the value of Python expressions inside a string by writing expressions as {expression}. An optional format specifier can follow the expression to control how the value is formatted. Currently, the only expression allowed is executionId, which will be replaced by a number from the template range when an execution is created from a templated execution.

    For example, if you have an input file named graph_inputs.###.bob for a file cache writing node in Bifrost, the corresponding format string should be graph_inputs.{executionId:03d}.bob for the input field in the payload. The expression {executionId:03d} is substituted for the current number from the template range, zero-padded to three digits.

    Executions Ordering and Merging

    All executions that specify the same frame ID are merged into a single execution, and executions are performed ordered by frame ID, smallest first. If frame IDs are not specified in the executions, they are performed in the order they appear in the task definition. Note that either all or none of the executions should specify a frame ID.

    In this example, the definitions for frame 5 within the templated execution and for the specific execution for frameId 5 will be combined into one:

    {
      "executions": [
        {
          "templateRange": {
            "start": 1,
            "end": 10
          },
          "frameId": "{executionId:01d}",
          "outputs": [
            {
              "source": {
                "key": "graph_outputs.{executionId:04d}.bob",
                "spaceId": "scratch:@default"
              },
              "target": {
                "path": "graph_outputs/graph_outputs.{executionId:04d}.bob"
              }
            }
          ]
        },
        {
          "frameId": 5,
          "inputs": [
            {
              "source": {
                "key": "graph_inputs.0005.bob",
                "spaceId": "scratch:@default"
              },
              "target": {
                "path": "graph_inputs/graph_inputs.0005.bob"
              }
            }
          ]
        }
      ]
    }
    
    Show More

    Optional frames Attribute

    The optional frames attribute can be used to specify the start and end frames for sequential multi-frame executions. When a frame range is specified, the set of executions is validated to ensure there is one execution per frame. When frame IDs are not explicitly specified on the executions, the executions will be mapped to frames using the frames range, and the number of executions must match the number of frames in the range.

    Here is an example of how to use the frames attribute in the payload:

    {
      "options": {
        "frames": {
          "start": 11,
          "end": 20
        }
      },
      "executions": [
        {
          "templateRange": {
            "start": 1,
            "end": 10
          },
          "inputs": [
            {
              "source": {
                "key": "graph_inputs.{executionId:04d}.bob",
                "spaceId": "scratch:@default"
              },
              "target": {
                "path": "graph_inputs/graph_inputs.{executionId:04d}.bob"
              }
            }
          ]
        }
      ]
    }
    
    Show More

    The templateRange attribute generates input files using the numbers 1 to 10, and the frames attribute sets the frame IDs to 11 through 20 for the executions.

    Please be aware that a mismatch between the template range and frame IDs may lead to mismatched file paths during the execution of the graph. This can happen for instance if the Bifrost graph contains file patterns that need to be replaced by frame IDs, but the file paths where instantiated using a mismatched template range. This can lead to failure to perform the execution, or to unexpected results.