Day #7 with Cloud Workflows: Pass an input argument to your workflow

All the workflow definitions we’ve seen so far, in this series, were self-contained. They were not parameterized. But we often need our business processes to take arguments (the ID of an order, the details of the order, etc.), so that we can treat those input values and do something about them. That’s where workflow input parameters become useful!

Let’s start with a simple greeting message that we want to customize with a firstname and lastname. We’d like our workflow to look something like this:

- output:
    return: ${"Your name is " + person.firstname + " " + person.lastname}

In the example above, we have a person variable, on which we’re requesting the fields firstname and lastname. This is actually a dictionary. But how do we let Cloud Workflows know about this variable? We need to define it somehow. 

Workflow arguments are global to all the steps, so they need to be defined outside the scope of the steps themselves. Actually, workflows can be structured in sub-workflows: there’s a main workflow, and possibly additional sub-workflows which are like routines or internal function definitions. We’ll revisit the topic of sub-workflows in a later article. To declare our input parameter, we’ll do it at the level of the main workflow, but in a more explicit fashion, with the following notation:

    params: [person]
        - output:
            return: ${"Your name is " + person.firstname + " " + person.lastname}

We explicitly show the name of our main workflow. We use the params instruction. Note that our single argument, person, is surrounded by square brackets. The main workflow can only take a single dictionary parameter, however, as we’ll see later, sub-workflows can take several input arguments, hence the square brackets notation to specify a list of arguments.

How do we pass this input argument? In the execution screen, in the input pane on the left, we create a JSON object, with a firstname and lastname keys. This JSON object is the dictionary in the person variable of our workflow definition.

In this video, you'll see input arguments in action:

Day #6 with Cloud Workflows: arrays and dictionaries

So far, in this series of articles on Cloud Workflows, we have used simple data types, like strings, numbers and boolean values. However, it’s possible to use more complex data structures, like arrays and dictionaries. In this new episode, we’re going to use those new structures.

Arrays can be defined inline (like anArray) or spanning over several lines (like anotherArray):

- assignment:
        - anArray: ["a", "b", "c"]
        - anotherArray:
            - one
            - two
- output:
    return: ${anArray[0] + anotherArray[1]}

The output step will return the string “atwo”.

For dictionaries, you can define them as follows:

- assignment:
        - person:
            firstname: "Guillaume"
            lastname: "Laforge"
            age: 43
            kids: ["Marion", "Erine"]
- output:
    return: ${person.firstname + " and " +[1]}

The output step will return the string “Guillaume and Erine”. 

Notice that we nested an array within a dictionary. So you can easily create dictionaries containing arrays, containing other dictionaries, etc, just like any JSON or YAML structures. 

In the example we were able to access the second kid of the person, mixing both the field (dot) and index (square brackets) notations to access fields of our dictionary, and elements of our array.

This video shows both arrays and dictionaries in action:

In the coming articles, we’ll see that such data structures are handy for dealing with API endpoint calls.

Day #5 with Cloud Workflows: visualizing the structure of your workflow definition

So far, in our Cloud Workflows series, we have seen some of the YAML syntax for defining workflows. However, steps are defined after each other, as a series of step definitions, but in spite of the jump instructions, the conditionals, you don’t really see visually what is going to be the next potential step in a workflow execution. 

Fortunately, a new UI enhancement has landed in the Google Cloud Console: the ability to visualize a workflow definition with a graph, when you’re editing the definition. Furthermore, the graph is updated in quasi real-time as you make updates to the definition.

Let’s see this in action in the video below:

Thanks to this visualization, it’s easier to further understand how your workflow definition is structured, how executions operate. You can more easily track which steps follows a particular step.


Day #4 with Cloud Workflows: jumping with switch conditions

In the previous articles about Google Cloud Workflows, we talked about how to assign variables, create expressions, and also how to jump from a step to another. It’s time to combine both aspects to understand how we can do conditional jumps, thanks to the switch instruction.

Let’s start with a first step defining a variable, whose value we’ll use in our switch condition:

- assignement:
        - number: 42

Then we’re going to create our second step that will use a switch instruction, with an expression:

- evaluate:
        - condition: ${number > 100}
          next: highValue
        - condition: ${number < 100}
          next: lowValue
    next: end

We define two conditions with two expressions, checking if the number is above or below 100, then we go to a different step (highValue or lowValue steps). If none of the conditions are met, we go to the end of the workflow (or we could return some value or raise some error).

We also need our two steps to go to:

- highValue:
    return: "It's high!"
- lowValue:
    return: "It's rather low!"

And we’re done! If the number is 42, like in our case, the execution of the workflow will go through the lowValue step, and return the string saying that it’s a low value.

Thanks to switch conditionals, with expressions and jumps, we can have non-linear logic in our workflow definitions. In upcoming articles, we will also have a look at how to use more complex data structures like arrays and dictionaries, and how to define inputs and outputs.

Day #3 with Cloud Workflows: variable assignment and expressions

Now that we have multiple steps in our workflow definition, let’s see how we can pass data around, from a step to another.

In a step, you can assign values to variables. Those values can be ints, doubles, strings, or booleans (and also null). Use the assign keyword as follows:

- assignments:
        - two: 2
        - pi: 3.14
        - message: "Hello"
        - bool: True

Those variables are available in the whole scope of the workflow, and can be accessed in other steps. So let’s see how we can do something with those variables. Let’s add a second step to our workflow definition:

- twoPi:
    return: ${"Twice pi is " + string(two * pi)}

We are using the ${} notation to create an expression. We’re multiplying two numbers, we’re converting them to a string, and we’re concatenating two strings together, to get our final value. 

Note that not all operations are allowed on all types, so you might need to do some conversions with built-in conversion functions like the string() function in our example. There are all sorts of arithmetic operators or boolean logic operators.

For more information, you can read about variable assignments, data types, and expressions. Next time, we’ll also have a look at more complex data types.

© 2012 Guillaume Laforge | The views and opinions expressed here are mine and don't reflect the ones from my employer.