The Flow Instance - assigning a flow to a project

A flow is a unit of automation which usually takes some input parameters that control what it does. It is common that there are multiple instances of a flow assigned to the same project. For example, there can be a single flow that defines how to make a Unreal debug build, but there can be several instances of that flow assigned to a project, each making a different flavor of the build on a different branch.

Generally, you never edit or interact with the flow instance files directly. They are created and modified by the user interface or various other tools. However, whichever tool you use to interact with flow instances, in the end, the result is a .json file in your project.

The flow instance file

Flow instance files associated with a project are always found in the .wvs/flows directory. There is exactly one file, with a .json extension, for each instance of a flow assigned to the project.

The name of the flow instance file defines the canonical name of the flow isntance. While a “display name” is defined by the flow instance, which is how that instance shows up in unser interfaces and reports, when looking at log files or scripts, the name of flow instance file is used as the “system name” of the flow.

The filename can be anything you want and can be renamed at any time. Flow instance files must not have spaces in their names.

Example - DoBuildType1.json: 

{
    "version" : 4,
    "enabled" : true,
    "displayName" : "UE Build",
    "flavor" : "Debug",
    "location" : "file",
    "definition" : "build_ue5_wd",
    "manualTrigger" : "-doDevBuildWd",
    "manualOnly" : false,
    "engineVersion" : "4.27",
    "engineTargetPlatform" : "windows",
    "branches" : 
    [
    ],
    "changes" : 
    [
       "Content/**/*",
        "Source/**/*",
        "Plugins/**/*",
        "Config/**/*",
        ".wvs/flows/*",
        ".wvs/flowRepo/*",
        "README.md"
    ],
    "inputs" :
    [
        {
            "name" : "PROJECT_DIR",
            "value" : "$CI_PROJECT_DIR"
        },
        {
            "name" : "PROJECT_FILE",
            "value" : "$PROJECT_DIR/ShooterGame.uproject"
         
        },
        {
            "name" : "TARGET",
            "value" : "ShooterGame"
         
        }

     ]
}

Parameters:

Attribute Type Required Description
version integer yes The file format version for this file. Should be 4
enabled bool yes If false, this flow instance is not processed and, for all intents and purposes, does not exist. However, because it still needs to be parsed in order to determine the ‘enabled’ field, the file must be syntactically correct.
displayName string required Defines the name for this flow instance that will be used in the user interface and various reports. Must not be an empty string. Does not need to be unique, but for the noble purpose of user sanity, it is recommended to be so.
location string yes Defines the source of this flow. Currently valid values are: “wvs”, “file”, “url”. A value of “wvs” indicates that this flow definition is hosted in a separate project on WVS. A value of “file” indicates that the flow definition is a file in the current project. A value of “url” means that the flow definition is coming from an arbitrary URL. Please see the section below on Flow Locations for more information.
definition string yes A resource reference to the specific flow being used, at the location defined in the location field.
manualTrigger string no The string used to trigger this flow manually. If this string is encountered anywhere in a commit message, the flow will be executed, regardless of any branch, file filer, or other restrictions that might have been defined. If this field is the empty string, or is not provided, there is no way to manually trigger the flow. This field is treated as a regular expression, allowing for more complex triggers. If it is desired that the trigger contain a character that is used as a special character in regular expressions, that character must be escaped with a ‘'.
manualOnly bool no If true, this flow will never trigger unless a manualTrigger string is encountered in a committ message. Defaults to false if not provided.
branches []string] yes An optional array of branch names. if this array is non-empty, then this flow instance will only run on branches named in that array. Names are case sensitive. If the array is empty, the flow instance will run on any branch.
changes []string] yes An optional array of path names. if this array is non-empty, then this flow instance will only run if there are modified files that match at least one of the patterns in the array. If the array is empty, then the flow instance will run regardless of what modification exist in the commit. Each patter is a standard glob pattern (as used by golang) relative to the root of the repository.
inputs []InstanceInput] no An array of definition for the inputs to this flow instance. The number is of entries is determined by the number of inputs required by the flow referenced by location & definition. There must be exactly one entry in the inputs array for each required input, and an optional entry for any optional inputs. See below for a detailed description of the InstanceInput type.
flavor string no An optional identifer assigned to this instance of the flow to allow for better categorization of results in the the UI.
engineVersion string yes * If the flow being referred to by this flow instance (location & definition) has requireEngine defined to true, then it defines which engine is being used for this flow and this field (engineVersion) defines the version of that engine being used by the project for this flow instance.
engineTargetPlatform string yes * If the flow being referred to by this flow instance (location & definition) has requireEngine defined to true, then it defines which engine is being used for this flow and this field (engineVersion) defines the target platforms.

InstanceInput parameters

Attribute Type Required Description
version integer yes The file format version for this file. Should be 4

Flow locations

wvs

file

url