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:

flow layout

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' tab in the solution's main window and select 'Resources'.
  2. Navigate to 'Integration' at the top.
  3. Click the 'Add' button to create an integration.
  4. Name the integration Nutrition.
  5. Click the 'back button' in the top left to leave the integration's backstage view so that you enter the main integration view.

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 by replacing 'Default Method' in the 'Name' field with Get calories and add the description Returns calories for a given drink and the walking duration required to burn the calories.
  2. On the right, click on the ‘Inputs’ and the ’Outputs’ tab to see the input and output parameters (if not yet visible already).
  3. Click 'Add' in the input parameters 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 output parameters 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:

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

Finally, 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 select the trigger and call it How many calories in flat white. Give the trigger these Intent inputs:

example-inputs

1How many calories in a flat white
2Number of calories in an espresso
3Whats the calorie count in a macchiato
4How many calories is there in a lungo?
5How many calories in a latte?
6What's the calorie count in a ristretto?
7Tell me the calories in an cortado
8What is the number of calories in a brewed coffe
9What's the calories in a frappuccino
10Could you tell me about the calorie count in an americano
11How many calories in a cappuccino
12Number of calories in a macchiato
13
  1. Generate a Match.

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. Select the 'FLOW' tab.
  2. Click 'Variables' on the left.
  3. Click the 'Add' button and give your variable a name by replacing 'Variable1' with mentionedCoffeeType.
  4. We will initialise 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. Select 'Listeners' to the left.
  2. Click on the 'Add' button.
  3. Call your listener Pick up coffee type.
  4. Add the following TLML Syntax condition: %COFFEES_SERVED.ENTITY^{ mentionedCoffeeType = lob.coffeeType }
  5. Save the listener.

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 the integration to the flow

Next, we will add the Nutrition integration to our flow. The integration appears as 'Nutrition' in the ribbon. Make sure nothing is selected in your flow by clicking anywhere in the white area around your flow nodes. Then simply click the Nutrition icon in the ribbon.

Currently, the integration is dangling and not connected to any of the other elements in the flow. However, we want our integration to be executed immediately after the flow is triggered, and right before an answer is given to the user. To put the integration in its place we need to follow these steps:

  1. Select the integration 'Nutrition' in the 'Add Node' section of the top ribbon.
  2. In the ribbon choose 'Set start node'. This points the trigger straight to the integration.
  3. Draw a line from the integration to the output node.

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 this too:

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

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. Select the integration in your flow.
  2. For the field 'query' in the Send section, select our flow variable 'mentionedCoffeeType' from the dropdown.

Receive calories and walking duration

Now that we have added the variables calories and walkingDuration, we will need to make sure that the values returned by the integration are actually stored in them:

  1. Select the integration in your flow and give it a name like Get calories for a drink.
  2. For 'calories' in the Receive section, select the flow variable calories from the dropdown.
  3. For 'walkingDuration' in the Receive section, select the flow variable walkingDuration from the dropdown.

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 when 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. Hover over 'Split Path', followed by 'transaction element' and add an Output.
  3. Add the following answer text to the new output Unfortunately I can't lookup calories currently.
  4. Give the output the name Can't lookup calories currently.

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 (the transition should have the transition order 1).
  2. Hover over 'Match' and click on 'TLML Syntax'.
  3. Enter the following Syntax Condition inside the editor: {calories}.
  4. Give the transition a name, like Results found.

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.

If you like, you can give the second transition the name Results not found, but this is not required.

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.