Flow Quickstart

Here you will find the necessary information for getting started with adding and controlling flows on your project. For a very high-level introduction to WVS flows, see: What are Flows?.

Prerequisites

Before setting up flows, please read Preparing for flows and follow the instructions there.

Managing all aspects of flows is currently done with the WVS Command Line Interface. This document assumes that you have run the WVS installer on your desktop and you have authenticated your WVS CLI.

As with all CLI commands, the utility decides which project you are operating on based on your current working directory. In order to issue WVS command line commands for your project, make sure that you change your current directory to be somewhere in the project’s directory hierarchy.

Saving your changes

One of the features of WVS projects is that all important information is kept inside the project repository with the rest of the project. This includes the configuration of flows. Although you will be interacting with the WVS command line to control the flows, you are actually modifying the flow configuration files that are saved in your projects .wvs folder.

To have the changes you make actually take effect, you will need to submit those changes to the repo. Using your client of choice, whether it is one of the WVS clients, or your favorite git client, make sure to submit/push any changes inside the .wvs\flows directory.

Seeing the status of flows in your project.

To see the status of all flows assigned to your project, use the flow status command:

wvs flow status

The first column displays the Name of each flow instance. You may need to use the column to refer to individual instances of flows in other commands.

If one connects flows together (by specifying that the output of one flow becomes the input to another), there are dependencies established between the flows. The flow status command provides optional flags to display these dependencies.

To display the list of predecessors (i.e. the list of flows that provide data as input to any given flow), use the –predecessors options:

wvs flow status --predecessors

To display the list of followers (i.e. the list of other flows to which a given flow provides data), use the –followers option:

wvs flow status --followers

Use of the above flags will produce the following output:

Seeing what flows can be added

WVS has a registry of standard flows that you can use on your project. As new flows are developed, or the community contributes flows, the list of available flows keeps growing. To see what flows are available to add to your project, you can use the flow registry command.

wvs flow registry

Adding a new flow instance to your project

Flows are units of automation and each one can have many configuration settings. When you want to add a flow to your project, you are adding a flow instance, or in other words a copy of that flow that you can specifically configure for your project. You can add many instances of the same flow: for example, you can add three instances of the “ue_build_game_windows” flow, and each instance can have a different configuration to make a slightly different kind of build.

To add a flow instance to your project, you can use the flow add command:

flow add <flow_name>
or
flow add <flow_name> --name <new_instance_name>

The flow_name parameter is the name of the flow to be added, as reported by the flow registry command (shown above).

The command will automatically assign a name to the instance if you use the first form of the command, but as you use more and more flows in your project, the automatically assigned names can be uninformative and confusing, so it is highly recommended that you use the second form of the command and explicitly assign a name to the instance with the –name option. The name you assign must have no space or special characters.

In the above example, you can see that we started out with no flows in the project, and then added the same flow as two different instances with different. Below you can see how we can configure those two flows to do different things.

Validating flows

Many flows can simply be added to a project with no additional configuration required to make them work. (Of course, on your project you will probably want to customize each flow to suit your specific needs).;

Some flows, however require additional information that requires some work on your part. For example, if you add a flow to deploy your builds to a service like TestFlight or Steam, you will need to provide your account information for those flows to work.

You can use the flow validate command to have WVS scan the current flow configuration and look for issues that you will definitely need to address before being able to successfully run your flows.

wvs flow validate

If all your flows look correctly configured, you will just see an “OK:

If however you added a flow that requires additional configuration you will see a message with the details:

In this case, the flow validate command has realized that we have added a “zip” flow that compresses data, but we have not set the “INPUT1” value, which specifies what it is that we want to compress, or the “OUTPUT_NAME” value, which specifies what the resulting zip file should be called.

The sections below detail how to set values and attributes of the flows.

It is important to note that the flow validate command will report all problems it sees with flows, regardless of whether they are enabled or disabled. If you submit your changes so that the system actually runs the flows, it will only process those flows that are enabled and so any configuration problems in flows that are disabled that may be reported by flow validate will not impact the system.

Also, unless connected (see below), flows are independent and it is possible for an individual flow to fail, but all other flows will run. In other words, failure of a single flow does not impact the execution of other flows.

Enabling and disabling flows

Once flows have been added to a project, it is common for teams to want to turn individual flows on or off at different times. For example, the team might want to keep certain types of builds on, but turn other kinds of builds off during different phases of their project. This is easily achieved with the flow enable and flow disable commands:

wvs flow enable <flow_name>
wvs flow disable <flow_name>

Looking at the results of the flow status commands in the example above, you can see that the flow disable command that was issued, disabled the ShippingBuild flow.

The flows remember all of their configuration and do not need to reconfigured after being reenabled.

Inspecting a specific flow instance

To see details about a specific flow instance, use the flow inspect command:

wvs flow inspect <flow_name>

The flow inspect command shows you the most important details about the flow instance. These values can be changed as needed with the flow set commands summarized below.

Configuring flow values

If you look at the output of the flow inspect command above, you can see that there are several sections of values. Two of those sections, Attributes and Input Variables summarize the values that you can configure to suit your needs.

The Attributes section contains values that you will find on all flows, regardless of the type of flow.

The Input Variables section contains values that are specific to a single flow and are documented by the author of that flow.

As with all other WVS command line commands, you can get a list of possible commands with a help command:

wvs flow set --help

The help message for each set command can be displayed the same way:

wvs flow set <attribute> --help

Below are details on some of attributes that are commonly configured.

Branches

The branch attribute allows you to constrain the execution of the flow so that it only executes if changes committed to the repository were on specific branches.

By default, the branch attribute is empty, which means that the flow can execute regardless of the branch to which changes to the repository were commited. Of course, the branch attribute is not the only attribute used to determine if the flow will actually execute, but if this list is empty, then the branch will not play any factor in that decision.

The branch attribute can contain an arbitrary number of branches.

To set the list of valid branches:

wvs flow set branch <flow_name> <branch_name> ...

For example to trigger the flow instance called DebugBuild on the main, dev, and stable branches, you would do:

wvs flow set branch DebugBuild main dev stable

To allow the flow instance ShippingBuild to only execute on the stable branch, do:

wvs flow set branch ShippingBuild stable

If a flow has been configured with a set of branch entries and you wish to clear them out and thus allow the flow to execute on any branch, simply set an empty list of branches.

wvs flow set branch ShippingBuild

The examples above show the entire set of branches being modified at once. If you have a long list of branches already configured and simply want to add some branches to the list, you can use the –add option to add to the existing list. For example, if you wish to add newBranch1 and newBranch2 to the list of branches, do:

wvs flow set branch ShippingBuild newBranch1 newBranch2 --add

Conversely, if you wish to delete oldBranch1 and oldBranch2 from the list but leave all the other branches as they are, you can use the –delete option:

wvs flow set branch ShippingBuild oldBranch1 oldBranch2 --delete

Changes

The change attribute allows you to constrain the execution of the flow so that it only executes when there were changes to certain files, or certain sections of the repository tree.

To set the list of change patterns:

wvs flow set change <flow_name> <branch_name> ...

For example on a project, you can constrain the ShippingBuild flow to only execute if there were changes in the Content directories:

wvs flow set change ShippingBuild Content/**/*

You may notice the pattern of asterixes after “Content”. There is a power set of pattern matching primitives you can use to speciy what files to match.

For example, if you wish to allow a flow to execute if any .cpp file changed, in any folder, then you could do:

wvs flow set change ShippingBuild *.cpp

If you wanted to change that rule to be any .cpp file, as long as it is directly in the Source folder, then you could do:

wvs flow set change ShippingBuild Source/*cpp

If, however, you want to change that rule be any .cpp file anywhere in the Source tree, regardless of how deep, then you could do:

wvs flow set change ShippingBuild Source/**/*.cpp

This command uses a standard “glob syntax” for the wildcards used in the patterns. The supported wildcard characters in the patterns are:

        /**/   - match zero or more directories
        {a,b}  - match a or b, no spaces
        *      - match any non-separator char
        ?      - match a single non-separator char
        **/    - match any directory, start of pattern only
        /**    - match any this directory, end of pattern only

By default, the change attribute is empty, which means that the flow can execute regardless of what files changed. Of course, the change attribute is not the only attribute used to determine if the flow will actually execute, but if this list is empty, then the specific list of files modified will not play any factor in that decision.

Any number of pattersns can be added to the change attribute. The following will allow the flow to execute if there were changes within the Content tree, the Source tree, or to the main project file:

wvs flow set change ShippingBuild Content/**/* Content/**/* MyProject.uproject

If a flow has been configured with a set of change patterns and you wish to clear them out and thus allow the flow to execute regardless of the files changed, simply set an empty list of changes.

wvs flow set change ShippingBuild

The examples above show the entire set of change patterns being modified at once. If you have a long list of change patterns already configured and simply want to add some additional patterns to the list, you can use the –add option to add to the existing list. For example, if you wish to add level1 and level2 folders to the list of patters, do:

wvs flow set change ShippingBuild Content/level1/**/* Content/level2/**/* --add

Conversely, if you wish to delete the above entries from the existing list of change patterns, but leave all the other entries as they are, you can use the –delete option:

wvs flow set change ShippingBuild Content/level1/**/* Content/level2/**/* --delete

IMPORTANT: All paths and patterns must be specified using the forward slash character “/”. This means that if you are on windows and are using the shell’s file completion, or copying file paths from the file browser, you will need to change the windows-native backslash “" character to a forward slash “/”.

DefRef

When you find a useful flow in the registry and assign it to your project, the system will automatically assign the most recent version of the flow and set up your project so it will automatically take patch updates to that flow.

Sometimes it may be appropriate to lock your flow to a particular version, or set of versions, especially as you try to lock your project and finalize it. Other times, during development, it may be appropriate to agressively take the newest version of a flow to get new featurres as quickly as possible.

The set defref command is used to set the flow definition reference to a specific version, or to indicate what range of versions to automatically update.

The general syntax is:

wvs set defref <flow_name> <version>

Flow versions are standardized to be in the form vX.Y.Z where X is the major version, y is the minor version, and Z is the patch version. So, for example, the most recent version of a flow could be v1.4.2

Issuing the following command will lock the flow to that specific version of the flow and it will never update:

wvs flow set ShippingBuild defref v1.4.2

Patches are defined as those that fix bugs or improve existing functionality but do not change behavior or require any configuration updates on the part of the flow user. To put a flow into a mode where it takes patch updates automatically, you would do:

wvs flow set defref ShippingBuild v1.4.x

Minor releases are releases that are backwards compatible with previous version but might change behaviors and may require minor configuration changes on the part of the flow user. To set a flow up to take minor releases automatically, you would do:

wvs flow set defref ShippingBuild v1.x.x

Major releases of flows imply signficant functinoality or configuration changes. There is no way to configure the flow to automatically apply major updates. A explicit major version must be specified in all set defref commands.

Display Name

All flow instances have a unique name, such as “ShippingBuild” used in the previous example. This unique name must not have spaces or special characters. As your project grows, from a user standpoint, these names may be less informative than desired. For this reason, flows have a display name attribute which defines a friendly name for flows that will be used in user interfaces and reports. This attribute is used purely for display purposes and is not used for any configuration purposes.

The general syntax for setting the display name is:

wvs flow set displayName <flow_name> <display_name>

Because the display_name parameter can contain spaces or special characters, it may be necessary to specify it in quotes. There is no harm in quoting even those parameters that don’t need to be and so it is a best pracitce to alway put quotes around the display_name.

To set the display name, for example:

wvs flow set displayName ShippingBuild "UE Shipping Build"

Flavor

As a project grows and the number of flows increases, it can be convenient for the project team to categorize the flows in a way that makes sense for their specific project

For example, while the team may be working towards a finished product, they may have variations of flows that target outputs for specific stakeholders. For example, there might be builds and renders that target QA and have some debug information on the screen, and there might be “exec review” versions of the same builds and renders that don’t have debug information on the screen.

The general syntax for setting the flavor is:

wvs flow set flavor <flow_name> <flavor>

The flavor parameter can be any string. It is a best practice to not have it contain spaces or special characters. It is treated case sensitively, so “flavorX” is not the same as “flavorx”.

By assigning flavors to different flows, the UI is able to visibly group related flow data for the user. For example:

wvs flow set flavor ShippingBuild1 QA
wvs flow set flavor ShippingBuild2 ExecReview
wvs flow set flavor LevelRenderA ExecReview
wvs flow set flavor LevelRenderB ExecReview
wvs flow set flavor GameplayRender QA

When viewing flow results in the Web UI, the flavor attribute will be used to group data.

Manual Trigger

The various attributes on a flow control when a flow actually runs. By default, if no attributes are set, flows will trigger on anychange in the repository, regardless of what changed. In practice, it is rare for teams to want to trigger flows this liberally and they will usuallyl specify branch and file location constraints on the flow.

The manualTrigger attribute lets you define a string of your choosing, and if that string is found in a commit message, than the flow will trigger, regardless of the setting of any other attribute.

One can think of the manual trigger as an override which allows any team member to trigger a flow based on their commit message.

The general syntax for setting the manual trigger is:

wvs flow set manualTrigger <flow_name> <trigger_string>

For example, to trigger the ShippingBuild flow whenever the string “-doBuild” occurs in the commit message, you would enter:

wvs flow set manualTrigger ShippingBuild "-doBuild"

The string that is specified is a regular expression using standard go regex syntax. If you wish to have special characters in the string, you may need to escape them in order to get the results you expect.

Disabled flows cannot be manually triggered.

Manual Only

The manual only attribute, if true, turns off all automatic triggering of the flow and the flow will execute only if the string defined by the manualTrigger attribute is found in a commit message.

If a flow has manualOnly set to true, then all other flow attributes that constrain flow execution are ignored, and only the manualTrigger attribute is used.

Disabled flows cannot be manually triggered.

The general syntax for setting the manualOnly attribute is:

wvs flow set manualOnly <flow_name> <true / false>

For example:

wvs flow set manualOnly ShippingBuild true

Setting Variables

The attributes of a flow which can be configured as described in the sections above are common to all flows. However, flows are a general purpose mechanism for units of automation, and as such any given flow might need extra data or configuration value in order to operate. These “flow specifc” values are flow variables.

Each flow can have any number of input variables and output variables. While the output variables are set by the flow itself, some of the input variables may need to be set when a flow instance is added to a project.

When a project is added, if the flow validate command indicates that some variables need definition, they can be defined by the following command:

wvs flow set variable <flow_name> <variable_name> <variable_value>

For example, in the following example, a flow is added and the validate command indicates that there are some flow specific input variables that need to be set:

The situation in this example can be resolved by issuing the following:

wvs flow set variable zipTheBuild OUTPUT_NAME MyOutputFile.zip
wvs flow set variable zipTheBuild INPUT1 TheInputFileToZip

Connecting flows

A common situation is where one wants a flow to take the output of another flow and do something to it. In other words, the two flows are connected. This is accomplished by setting the input variable of the second flow to be the output variable of the first flow.

The flow connect command can be used to accomplish this:

wvs flow connect <flow1> [<var1>] to <flow2> [<var2>]

At its most verbose, the command requires you to enter the names of the source flow and output variable of that flow, as well as the name of the destination flow and the input variable of that flow.

However, the names of the output variable of the source flow and the input variable of the destination flow are optional and the system will attempt to deduce them if possible. If it is not possible, it will output an error message to that effect and prompt the user to to enter the names explicitly.Aliases:

Note the “to” keyword between the source flow parameters and the destination flow paramters. It must be provided in the correct position.

For example, if the build flow myBuild only has one output and the deploy flow myDeploy only had one input, you can do the following:

wvs flow connect myBuild to myDeploy

If necessary (or desired), you can specify the names of either or both the input and output variables:

wvs flow connect myBuild myBuildOutput to myDeploy
wvs flow connect myBuild to myDeploy myDeployInput
wvs flow connect myBuild myBuildOutput to myDeploy