• The flow definition
  • The definition file
  • The code
• Predefined VARIABLES
• Where flows live
  • Local to the project
  • Shared repository
  • Arbitrary URL
• The flow registry
• Variable naming conventions

Create custom flows

Flows are designed to be easily usable, and once they have been created, managing them on a project is a simple task. Nevertheless, the creation of a new flow is relatively involved task. It involves several steps

• Defining the flow.

  The means writing the actual code that performs the automation, as well as the formal definition of the interface to the flow so that other flows, and UI tools can interact with it.

• Deciding where the flow will live.

  Will it be simply a private part of one project? Will it be in a shared repository on WVS? Will it be at some other location accessible by URL.

• Registering the Flow.

  You can choose to register the flow in the WVS flow registry so that UI tools are aware of its existence (if desired).

• Testing the flow on a live project.

  Since flows run in the cloud and operate on data comitted to the repo, any testing strategy has to take place in the cloud and not at the desktop. There are best practices on how to test

The flow definition

A flow definition consists of two files that have an identical name that differs only in the extension.

• The flow definition file. (json)
• The flow code. (yml)

The flow code file can include other code files, so technicall the flow definition could comprise many files, but at the very least there are always two files that have the same base name and differ only in the extension. For example: UnrealShippingBuild.json and UnrealShippingBuild.yml.

The definition file

The definition file is a json file that describes the attributes of the flow, as well as the input and outputs.

Example - Flow.json:

{
    "version" : 4,
    "name": "UE5 Build",
    "category": "build",
    "requireEngine": true,
    "engineName": "ue",
    "validEngineVersions" : [],
    "validEngineTargetPlatforms" : ["windows"],
    "jobName": ".build_ue_win",
    "inputs" :
    [
        {
            "inputName" : "PROJECT_DIR",
            "inputType" : "variable",
            "required" : true
        },
        {
            "inputName" : "PROJECT_FILE",
            "inputType" : "variable",
            "required" : true
        },
        {
            "inputName" : "TARGET",
            "inputType" : "variable",
            "required" : true
        } 
    ],
    "outputs" :
    [
        {
        "outputName" : "OUTPUT_BUILD_ARTIFACT",
        "outputType" : "artifact"
        }
    ]
}

Parameters:

FlowInput parameters:

FlowOutput parameter:

The code

The code that implements the flow lives in a .yml file that has the same root name as the corresponding json file described above.

There are no restrictions on what the file contain. By definition, besides system-predefined variables, the only other input variables it should depend on are those defined in the corresponding json file. That way the system can make sure that all inputs are satisfied before the flow is called.

There must be a job with the name identified in the jobName field in the corresponding flow definition file. In the case of our example “.build_ue_win”.

The syntax of the yml is derived from gitlab CI syntax.

Example - Flow.yml:

.build_ue_win:
  variables:
    # Output variables (defined in json)
    OUTPUT_BUILD_ARTIFACT: StagedBuild

  stage: build_dev

  script:
    - 'cd $uebatpath'
    - '& .\runuat -nop4 -verbose BuildCookRun -project="$PROJECT_FILE" -Target="$TARGET" -targetplatform="$FLOW_ENGINE_TARGET_PLATFORM_X" -cook -clean -unattended -stage -stagingdirectory="$PROJECT_DIR/$OUTPUT_BUILD_ARTIFACT" -build -CookAll -package'
    - Add-Content -Path $CI_PROJECT_DIR/build.env -Value "OUTPUT_BUILD_ARTIFACT=$OUTPUT_BUILD_ARTIFACT"
       
  artifacts:
      name: "$CI_JOB_NAME-$CI_COMMIT_REF_NAME"
      paths:
        - $PROJECT_DIR/$OUTPUT_BUILD_ARTIFACT
      reports:
        dotenv: build.env

Predefined VARIABLES

The following variables are defined by the system and should not be overridden.

The following variables are defined by the system based on the flow definition.

Where flows live

Local to the project

Shared repository

Arbitrary URL

The flow registry

Variable naming conventions

Appropriately, variables are used various ways in various places. It is the fact that they are also defined in various places that makes it convenient to stick to a naming convention that lets flow developers easily know where a variable is defined.

This is the convention that WVS currently uses:

This is just a convention and it is not enforced but it is followed by WVS defined flows.

The variables used internally to the flow definition, and as input and output parameters can follow any convention desired by the author. Each flow has its own scope for variables and so those variables do not need to be unique across flows.