Configure flows

This page shows you how to configure flows after you’ve added them to your WVS project. These configurations include the following:

  • Set conditions for running flows
  • Enable or disable automatic flow updates
  • Set the display name of a flow instance
  • Categorize flows
  • Set input variables
  • Connect flows

Flow attributes

If you look at the output of the flow inspect command, 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

The following sections detail flow 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 previous sections 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 

What’s next