Lesson 4 - Outputs and Results

Goal

In this lesson we’ll write a bit of a more complex operation that returns an output and results.

Get Started

Let’s create a new file in the tutorials/hiring folder named check_availability.sl in which we’ll house an operation to check whether a given email address is available.

We’ll also start off our new operation in much the same way we did with the print operation. We’ll put in a namespace, the operation key, the name of the operation and an input.

namespace: tutorials.hiring

operation:
  name: check_availability

  inputs:
    - address

Action

This time we’ll have a little more of a complex action. The idea here is to simulate checking the availability of the given address. We’ll import and use the Python random module to get a random number between 0 and 2. If the random number we get is 0 we’ll say the requested email address is already taken.

We’ve added a commented-out line, using a Python comment (#) to print the random number that was generated. We can uncomment this line during testing to see that our operation is working as expected.

python_action:
  script: |
    import random
    rand = random.randint(0, 2)
    vacant = rand != 0
    #print rand

Note

YAML Note: Since we’re writing a multi-line Python script here we use the pipe (|) character to denote the usage of literal style block notation where all newlines will be preserved.

Outputs

In the outputs section we put any information we want to send back to the calling flow. In our case, we want to return whether the requested address was already taken. The outputs are a list of key:value pairs where the key is the name of the output and the value is the expression to be returned. In our case, we’ll just return the value in the vacant variable. Outputs must be strings so we’ll use the Python str() function to convert the value.

outputs:
  - available: ${str(vacant)}

Notice the special ${} syntax. This indicates that what is inside the braces is a CloudSlang expression. If we would have just written str(vacant), it would be understood as a string literal. We’ll see this syntax in action again in a few moments.

For more information, see Expressions in the DSL reference.

At this point we won’t be using the output value, but we will soon enough. In lesson 5 - Default Navigation we publish the available output and use it in another step.

For more information, see outputs in the DSL reference.

Results

The last section of our operation defines the results we return to the calling flow. The results are used by the navigation of the calling flow. We’ll start by using the default result values, SUCCESS and FAILURE. If the email address was available, we’ll return a result of SUCCESS, otherwise we’ll return a result of FAILURE. There always must be a default ending result that does not have an expression or explicitly maps to the value true. Here, we will use the SUCCESS result as our catchall. When the operation is run, the first result whose expression is true or empty is returned. It is therefore important to take care in the ordering of the results.

results:
  - FAILURE: ${rand == 0}
  - SUCCESS

The results are used by the calling flow for navigation purposes. You can see the default navigation rules in action in lessons 5 - Default Navigation and 6 - Handling Failure Results. And you can learn how to create custom navigation in lesson 7 - Custom Navigation.

For more information, see results in the DSL reference.

Run It

Let’s save and run this operation by itself before we start using it in our flow to make sure everything is working properly. (You might want to uncomment the line that prints out the random number while testing.) To run the operation, enter the following in the CLI:

run --f <folder path>/tutorials/hiring/check_availability.sl --i address=john.doe@somecompany.com

Run the operation a few times and make sure that both the SUCCESS and FAILURE cases are working as expected.

Download the Code

Lesson 4 - Complete code

Up Next

In the next lesson we’ll integrate our new operation into our flow, using the output and results it sends.

New Code - Complete

check_availability.sl

namespace: tutorials.hiring

operation:
  name: check_availability

  inputs:
    - address

  python_action:
    script: |
      import random
      rand = random.randint(0, 2)
      vacant = rand != 0
      #print rand

  outputs:
    - available: ${str(vacant)}

  results:
    - FAILURE: ${rand == 0}
    - SUCCESS