Teneo Developers
Table of Contents
Was this page helpful?

Share to

Add an integration

To correctly handle an input of a user, a bot may need to connect to external services. For example, you may want to provide weather information or your bot may need to initiate a reset password process. In Teneo these calls to external services and the handling of their responses are carried out by Integrations. You add an integration to your solution once, and after that it's available for any flow in that solution.

In this example, we will create a flow that uses an integration that provides the number of calories in a coffee, like this:

User: How many calories in a Cappuccino?
Bot: One flat white contains about 120 calories, a walk of about 30 minutes should be enough to burn them.

To make this possible, we are first going to set up an integration and then create a flow that makes use of the integration. The final result will look like this:

final flow layout

Teneo 7.5 introduces a new Flow User Interface in Teneo Studio Web. Images and videos will be updated gradually. Please refer to the Release Notes for a preview of the new look-and-feel.

Set up the nutrition integration

First we are going to set up the integration. These are the steps to add an integration in Teneo:

  1. Open the solution dashboard.
  2. Navigate to the Integration tile.
  3. Click the 'Add' button to create an integration.
  4. Name the integration Nutrition and add the description Returns calories for a given drink and the walking duration required to burn the calories.
  5. Click on Create.

Set up a method

An integration can contain multiple methods. A method is a block of code that only runs when it is called. You can pass data into the method and after executing the code, the method returns the results. Here we want to create a method that returns the calories and walking duration to burn these calories for the coffee drink that was passed into the method.

When you created the integration, a 'Default Method' was automatically created. Let's give it a proper name and add an input parameter we will use to pass data into the method and add two output parameters that we will use to return the results:

  1. Re-name the method to Get calories.
  2. Click on the Add button in the Inputs pane and give the input a name and a description:
  • Name the input parameter query.
  • Add the description: The coffee drink to find the calories for. For example: 'cappuccino' or 'espresso'..
  1. Now let's add an output parameter for the calories found. Click 'Add' in the Outputs panel and enter the following:
  • Name: calories.
  • Description: The calories found.
  1. Finally, add the last output parameter for the walking duration:
  • Name: walkingDuration.
  • Description Walk duration in minutes to burn the calories.

Add the script to the method

To complete the method, let's add the script which will be executed when the integration is called by the flow and save the method:

  1. Add the following script:

groovy

1def caloriesPerDrink = [
2    "americano": 9,
3    "cappuccino": 120,
4    "cortado" : 34,
5    "espresso": 3,
6    "frappuccino": 408,
7    "latte": 189,
8    "lungo": 3,
9    "macchiato": 8,
10    "ristretto": 5,
11    "flat white": 223,
12    "brewed coffee": 2
13]
14
15// populate output param 'calories' with calories found
16calories = caloriesPerDrink[query]
17
18// calculate walking duration
19def durationMinutes = (int)Math.ceil((calories/4))
20
21// populate output param 'walkingDuration'
22walkingDuration = (durationMinutes == 1 ? durationMinutes + " minute" : durationMinutes + " minutes")
23
  1. Save the integration.

For simplicity, the script above simulates a query to a nutrition API. If you prefer to use a real API, you can replace the script above with the contents of this file: nutritionix integration example script. However, make sure that you add the appropriate 'appId' and 'appKey' which you can obtain here: developer.nutritionix.com.

Create the nutrition flow

  1. Create a new flow and give it the name User asks about calories in a drink, then name the trigger How many calories in flat white. Give the trigger these Intent inputs:
  • How many calories in a flat white
  • Number of calories in an espresso
  • Whats the calorie count in a macchiato
  • How many calories is there in a lungo?
  • How many calories in a latte?
  • What's the calorie count in a ristretto?
  • Tell me the calories in an cortado
  • What is the number of calories in a brewed coffee
  • What's the calories in a frappuccino
  • Could you tell me about the calorie count in an americano
  • How many calories in a cappuccino
  • Number of calories in a macchiato
  1. Generate a Match by clicking on the Plus icon followed by Match and Generate a draft.

Add a flow variable and a flow listener to recognize and store the coffee type

We will need to pick up the type of coffee that the user mentioned, like espresso or cappuccino, so we can use it later to look up the number of calories. First, let's add a flow variable in which we can store the coffee type. Go ahead and add a flow variable:

  1. Click on the Variables icon followed by the Plus icon to create a new flow variable.
  2. Give your variable the name mentionedCoffeeType.
  3. We will initialize this variable as an empty String, so in the field below just add "".

Now that we have an empty flow variable for mentionedCoffeeType, we can use a flow listener to set it whenever a coffee type is mentioned in the flow.

  1. Click on the Listeners icon followed by the Plus icon to create a new flow listener.
  2. Call your listener Pick up coffee type.
  3. Add the following TLML Syntax condition: %COFFEES_SERVED.ENTITY^{ mentionedCoffeeType = lob.coffeeType }
  4. Click on 'confirm'.

As you can see, the TLML Syntax condition above uses the entity COFFEES_SERVED.ENTITY that we made when we created custom entities. The propagating script ^{ mentionedCoffeeType = lob.coffeeType } stores the coffee drink mentioned by the user in our flow variable mentionedCoffeeType.

explain propagation script

Add flow variables to store integration results

Now it is time to receive information returned by the integration. In our case, the integration returns two fields: calories and walkingDuration. We need to store these values somewhere, so you will need to add two flow variables for these too:

  • A flow variable called calories with value "".
  • A flow variable called walkingDuration that also has the value "".

Add the integration to the flow

Next, we will add the Nutrition integration to our flow.

  1. Click on the Plus icon above the output.
  2. Select 'Continue with' followed by Integration, then choose the Nutrition integration.
  3. Give it a name like Get calories for a drink.

Send the mentionedCoffeeType to the integration

Now that we have put the integration in its place, we can specify which variables should be transferred back and forth. In our case we will send the mentionedCoffeeType variable to the integration so it can use it to lookup the calories. Follow these steps to achieve that:

  1. Click on Add variable mapping on the integration node.
  2. In the first dropdown, select IN.
  3. Select our flow variable 'mentionedCoffeeType' in the second dropdown.
  4. Finally, select 'query' in the last dropdown.

Receive calories and walking duration

Next, we will need to make sure tha values returned by the integrationa re stored in our flow variables calories and walkingDuration:

  1. Click on Add variable mapping in the flow node and set it to OUT.
  2. Select 'calories' in the second dropdown and the flow variable calories from the last dropdown.
  3. Repeat the same process to add a mapping for walkingDuration.

The integration is now properly included. The coffee type that was picked up from the input is sent to it and after the integration is executed our flow will receive the calories and the time one needs to walk to burn the calories. The received values are stored in the flow variables calories and walkingDuration.

Populate the output

When we reach the output we want to provide the calories and the time it takes to burn them to the user. Add the following answer text to your output:

  • One ${mentionedCoffeeType} contains about ${calories} calories. A walk of about ${walkingDuration} should be enough to burn them.

Make sure you give your output a name like One flat white contains about 223 calories, a walk of about....

Add a fallback output node

There may be cases where the integration fails to provide a proper response, for example if the API that provides the details is down. It is good practice to add an output for that too:

  1. Select the Plus icon under the integration.
  2. Click on 'Split Path', followed by 'transaction element' and add an Output.
  3. Add the following answer text to the new output: Unfortunately I can't currently look up calories.
  4. Give the output the name Can't currently look up calories

Add a condition to your transition

You now have two outputs, one that should be shown when we found calories and one in case something went wrong and we could not find the calories. We will have to make sure that Teneo only shows the first output when calories were found.

  1. Select the Plus icon that points to the first output you made.
  2. Click on 'Match' and then 'TLML Syntax'.
  3. Enter the following Syntax Condition inside the editor: {calories}.

Please note that you can also add a Flow Variable Match to achieve same results.

The condition we added is a Groovy script, because it is surrounded by curly brackets {}. The expression returns true if the flow variable calories is not empty. For more details on how Groovy decides if an expression is true, read about the Groovy Truth.

Save and test your flow

That's it! Save your flow and give it a go in Tryout.

User: How many calories in a Cappuccino?
Bot: One flat white contains about 120 calories, a walk of about 30 minutes should be enough to burn them.

User: How many calories in a flat white?
Bot: One flat white contains about 223 calories, a walk of about 56 minutes should be enough to burn them.