Skip to main content

Integrations

Integrations are reusable sets of scripts most commonly to connect to external services or on-device applications. Integrations create a sophisticated user experience to provide end-users with information in real time about, for example, the weather or the latest news.

The sections on this page provide information about the various aspects of Integrations:

Concept​

Integrations are reusable sets of scripts, most commonly used to connect to external services and on-device applications.

They allow you to create sophisticated user experiences by smoothly providing end users with information, in real time, about anything from weather forecasts and currency conversions, to the latest news.

The Integration Manager allows teams to collaborate, having tech-savvy developers defining the Integration's scripts and methods in a central place while other users can add the Integration in Flows. This way scripts can be defined once - globally - for the whole solution, allowing the dialogue to seamlessly communicate with external systems and processes via third-party APIs and then be applied throughout the solution by means of Integration nodes in Flows.

Passing information​

When using Integrations to connect to external services, they specify the data that should be passed between Teneo and that service. For example, for a weather service, an API key may be required along with the location for which the data conditions should be obtained, the number of days for the forecast and the format in which the data should be received (JSON, XML, CSV). For a contact center or chat handover Integration, information related to live agents and available agents might be relevant in order to answer the end user correctly.

Scripting with Integrations​

The execution scripts of the Integration's methods have access to the Integration's Input Parameters and the solutions Global Variables. Scripts can populate their Output Parameters as well as Global Variables.

The scripting language in Teneo is Groovy. Read more about scripting in Teneo here.

Components​

Availability setting​

When an Integration is available, it can be added to Flows. Integrations that are not available will continue to work in Flows that they have been added to but new usages cannot be created and the unavailable Integration is not visible in new Flows.

note

Note that in Teneo Studio Web this is done by clicking the Info button with the integration open and disabling/enabling the Integration.

Execution Script​

The execution script is the script which is executed when the integration is called by a Flow.

Both the Integration's input parameters and the solution's Global Variables are available inside the script. A method's script can populate its output parameters as well as Global Variables.

Input parameters​

The Input parameters allow the method to receive information from a Flow and can be strings, lists, objects, etc. The type depends on the type of the variable that was transferred by the Flow.

Input parameters are optional and their names cannot contain spaces.

Output parameters​

The Output parameters allow the method to send information back to a Flow, and just as input parameters, the output parameters can be of type strings, lists, objects, etc.

Output parameters are optional and their names cannot contain spaces.

How To​

Integration Manager​

Open​

There are two options to open an Integration in Teneo Studio Web:

  • In the Integrations tile on the Solution dashboard, click on the name of an existing Integration, or
  • In the list of Integrations, accessible in the Solution dashboard > Integrations tile, click on the header or the right-pointing arrow, and then click on the name of the Integration.

Create​

To create a new Integration:

  1. First, either:
    • Click the Create button directly in the Integration tile (upper, right corner) on the Solution dashboard, or
    • In the Integrations list, click on Create New Integration.

web-create-integration

  1. The Create New Integration opens. Write the Name and optionally a description.
  2. Then, click Create.
  3. The new Integration is opened. Now add the Name of the Method (Default Method field) and write the execution script in the Script editor.
  4. In the right side add any needed Inputs and Outputs parameters. Give each Inputs/Outputs parameter a Name and optionally a Description.
  5. Remember to click Save in the top ribbon.

Save​

To save an integration:

  1. Click Save in the top right corner of the window.
  2. Optionally, add a comment.
  3. Click Save to confirm the save action or Cancel to abort the save.

A successful save is confirmed with a "Document saved successfully!" message. Close this message by clicking elsewhere in the browser window.

Close​

To close an Integration in Teneo Studio Web:

  1. First, remember to Save if any changes were performed in the Integration to preserve these; Teneo Studio will prompt the user to save if unsaved changes are detected.
  2. Next, simply navigate back by using the back arrow of the browser or by clicking a location in the folder path available in the top ribbon.

Delete​

To delete an Integration in Teneo Studio Web:

  1. Navigate to the list of Integrations (Solution dashboard > Integrations tile > right-pointing arrow).
  2. Hovering over the Integration an icon of a recycle bin appears in the right side of the browser window. Click on it.
  3. The user will be prompt to confirm the deletion of the Integration.
    • Click Delete to perform usage check before deletion.
    • Check Do not check usage and click Delete to delete without performing a usage check.
    • Click Cancel to abort the deletion.

Read more about deletion and usage check here.

note

Note that deletion of an Integration currently cannot be undone in Teneo Studio Web. For this action please refer to the Recycle Bin available in Teneo Studio Desktop.

Filter​

A text filter is available in the top ribbon of Teneo Studio Web. This filter allows you to filter on the displayed list of documents; simply write the desired letter combination to start filtering on the list.

The filter works on the following columns: Name, Description, and Author.

Clicking the column headers allows you to sort the list of documents alphabetically when clicking the Name, Description or Author headers. Click Updated to sort by the date/time the documents were updated or created.

note

This section currently only applies to Teneo Studio Desktop.

To find out where an Integration is used in a solution:

  1. Go to the Integration manager in the backstage of Teneo Studio (Solutions tab > Resources > Integration).
  2. Select the Integration you want to search for.
  3. Click Search in the ribbon in the right side of the view.
  4. The Search results in the frontstage of Teneo Studio are automatically displayed.

Integration nodes​

Add Integration node​

With the Flow open, follow the below steps to add a call to an Integration:

  1. Click the Plus icon, and depending on the icon's location in the Flow graph and the desired behavior, select one of the following options:
    • Continue With > an Integration to query or control another system > select the name of the wanted Integration.
    • Split Path > to an Integration to query or control another system > select the name of the wanted Integration.
  2. Lastly, remember to Save the Flow to preserve the changes.

* The name of the Integration depends on the name given in the Integration manager.

Edit Integration node​

With the Flow open, follow these steps to edit the Integration:

  1. In the Integration node, click Add name to give the node a name.
  2. To edit the Integration, simply click the value to update and select a new value from the menu.
  3. Click add variable mapping to configure any in/out parameters.
  4. Remember to Save the Flow to preserve the changes.

Delete Integration node​

In the open Flow, follow the below steps to delete a Call Integration:

  1. Locate the Call Integration node in the Flow graph.
  2. Click the Recycle Bin in the sidebar.
  3. Remember to Save the Flow to preserve the changes.

UI​

Integration Manager View​

The Integrations are available on the Solution dashboard in the Integrations tile. Clicking the tile header or the right-pointing arrow takes the user to the list of Integrations. Clicking the name of an existing Integration opens the Integration window.

web-integration-view

ElementComment
List of existing IntegrationsThis area displays a list of any existing Integrations in the solution.
Order per columnOrder the list per column header.
Create new IntegrationClick the Plus icon to create a new Integration.
Filter documentsThe text filter allows to filter Integrations, especially useful when the list is long.

Integration Manager Window​

The Integration window is accessed from the list of Integrations by either creating a new Integration or by clicking any existing Integration; it is also possible to open an existing Integration from the Solution dashboard by clicking the name of the Integration in the Integrations tile.

web-integration-window

ComponentComment
PathThe solution path allows for easy return to the list of Integrations or the Solution dashboard.
MethodsThe Methods panel is available in the left side of the window.
Name and Execution ScriptThe editor in the middle of the view contains the name of the select Method and its execution script.
Input ParametersThis section in the right side of the view allows you to define Input Parameters.
Output ParametersThe Output Parameters in the right side of the view allows you to define Output Parameters.

Integration node​

The following options are available in the Flow when working with Integrations:

integration node web

Practical Examples​

Implementing an Integration​

Let's take a look at a simple example of how an Integration could be used in a solution. For more complex examples in bigger solutions, see Teneo x Generative AI and the Contact Center Connector Framework.

In this example, we will create a Flow that uses an Integration to convert units of mass:

User: 2 kgs to lbs

Bot: A mass of 2 kilograms is equivalent to 4.41 pounds.

Create the Integration​

  1. Navigate to the solution backstage and click on Resources followed by Integration.
  2. Click on Add.
  3. Give the new Integration a name like Mass conversion and click on the back arrow to edit it. Optionally, give the default method a different name as well.
  4. In the Inputs section, click on Add three times to add three input variables.
  5. Name the new input variables amount, fromUnit, and toUnit.
  6. In the Outputs section, click on Add twice to add two output variables.
  7. Name the new output variables result and success.
  8. In the Execution script, paste in the following script: 
    def convertMass = [ ounces: [ pounds:'1/16', stone: '1/224', grams:'28.35', kilograms:'1/35.274'], pounds: [ ounces:'16', stone: '1/14', grams:'453.592', kilograms:'1/2.205' ], stone: [ ounce:'224', pounds:'14', grams:'6350.293', kilograms:'6.35' ], grams: [ ounces:'1/28.35', pounds:'1/453.592', stone: '1/6350.293', kilograms:'1/1000' ], kilograms: [ ounces:'35.274', pounds:'2.205', stones: '1/6.35', grams:'1000']]

    def multiplier

    if (fromUnit==toUnit)
    { 
        success = false
    }
    else
    {

        try {
              def cell = convertMass.get(fromUnit).get(toUnit)
    	   if (cell.startsWith("1/")) 
                 { multiplier = 1.0 / cell.substring(2).toDouble()}
              else
                 { multiplier = cell.toDouble()}

              result = amount * multiplier;
         }
         catch (error) { success = false }
    }

    import java.text.DecimalFormat;
    if (result >= 0.01)
    {
       DecimalFormat df2 = new DecimalFormat(".00");
       result = df2.format(result);
    }
  9. Save the Integration.

Create the Flow​

Now let's create a Flow that uses the Integration we just created.

  1. Add a Flow and give it a name like Convert mass units.
  2. Name the trigger Convert mass units.
  3. Add a TLML Syntax Match to the trigger and paste in the following: 
    (%CONVERT.VB.LEX/%CALCULATE.VB.SYN/%CHANGE.NN.SYN/%HOW_MANY_MUCH.PHR)
    &^
    %UNITS.ENTITY
    /
    %UNITS.ENTITY
  4. Add a Listener After Match and add the following to the TLML Syntax field; you can leave the execution script empty, as the TLML includes a propagation script that carries out the action we are after, namely extracting the relevant values from the user input: 
    == Get value and unit, as one token ==
    (
    == Get unit to convert to ==
    (%UNITS.ENTITY^{toUnit=lob.unit;}):O
    )

    /

    == Get value and associated unit to convert from ==
    ((
    (((%A.FW.LEX/%ONE.FW.LEX)^{amount=1.0}):O/ 
    ((%HALF.NN.LEX>>(%A.FW.LEX):O)^{amount=0.5}):O
    ) /
    (%NUMBER.ANNOT^{amount = lob.TLR_nNumericValue})
    >>%UNITS.ENTITY^{fromUnit=lob.unit}
    )
    &^
    == Get unit to convert to ==
    (%UNITS.ENTITY^{toUnit=lob.unit;})
    )
  5. Save the Flow.

Expand the Flow​

We have now created the Flow and populated the trigger; let's finish adding the remaining parts of the Flow.

  1. Name the output node Get unit and amount to convert from and give it the answer text Please enter the amount and unit you wish to convert from.
  2. Click on the Plus icon below the output node and select Continue With followed by a Transaction.
  3. Name the new output node Get unit to convert to and give it the answer text What did you want to convert ${fromUnit} to?.
  4. Select the transition between the two output nodes and name it Detect from unit and amount.
  5. Add a TLML Syntax Match to the transition and paste in %NUMBER.ANNOT>>%UNITS.ENTITY.
  6. Add a Listener After Match to the transition and paste in 
    == Get value and associated unit to convert from ==
    (
    (((%A.FW.LEX/%ONE.FW.LEX)^{amount=1.0}):O/ 
    ((%HALF.NN.LEX>>(%A.FW.LEX):O)^{amount=0.5}):O/
    (%NUMBER.ANNOT^{amount = lob.TLR_nNumericValue})
    ) 
    >>%UNITS.ENTITY^{fromUnit=lob.unit;}
    )
    &^
    == Get unit to convert to ==
    (%UNITS.ENTITY^{toUnit=lob.unit;}):O

    )

    /


    (
    == Get unit to convert to ==
    (%UNITS.ENTITY^{toUnit=lob.unit; toUnitPlural=lob.unitPlural;conversionTypeDestination=lob.type}):O
  7. Below the last output node, click on the Plus icon and select Continue with and a Transaction.
  8. Select the transition that was created and name it Detect target unit.
  9. Add a TLML Syntax Match to the transition and paste in (%UNITS.ENTITY^{toUnit=lob.unit;}).
  10. Add a Listener After Match to the transition and paste in 
    ( (("-")^{negative=true}):O>>%NUMBER.ANNOT^{amount = lob.TLR_nNumericValue})
    >>%UNITS.ENTITY^{toUnit=fromUnit; fromUnit=lob.unit;}

Now let's use the Integration method within our Flow.

  1. Beneath the Detect target unit transition, click on the Plus icon and select Continue With followed by Integration and the name of the Integration method.
  2. As you can see in the Integration configuration panel, we can choose to send and/or receive information from the Integration method. To do this, let's add some Flow variables:
    • On the left-hand side of the window, in the Flow section, click on Variables.
    • Click on Add and name the variable amount. Give it an initial value of 1.0.
    • Do the same for the following variables:
Variable nameInitial value
fromUnit""
toUnit""
result0.0
successfalse
  1. Now head back to the main view of the Flow and complete the steps:
  • Click on the Integration node again and select amount, fromUnit, and toUnit in output parameters, and result and success in input parameters.

Finish the Flow​

Let's add a path for if there's an error in the calculation:

  1. Right under the Integration node, click on the Plus icon and select Split Path, followed by transaction element and Output.
  2. Click on the Plus icon above the left output node and add a Flow Variable Match. In the configuration panel that opens, select the Flow variable success and set its value to true.
  3. Select the left-hand output node, name it Show result of mass conversion, and paste in the answer text A mass of ${amount} ${fromUnit} is equivalent to ${result} ${toUnit}.
  4. Select the right-hand output node and set both its name and answer text to Sorry, something went wrong.

Finally, let's add some Skip conditions to a few of the nodes to make the conversation a bit more natural:

  1. In the 'Get unit and amount to convert from' output node, add a skip condition and paste in fromUnit. In the dropdown, select the name of the transition to skip to, in this case 'Detect from unit and amount'.
  2. In the 'Get unit to convert to' output node, add a skip condition and paste in toUnit. In the dropdown, select the name of the transition to skip to, in this case 'Detect target unit'.

Try it out​

Now your Flow is using your new Integration method to convert mass units. Try it out:

User: 2 kgs to lbs

Bot: A mass of 2 kilograms is equivalent to 4.41 pounds.