Creating a backend connector

Backend Connectors
1

The Teneo Developers website provides backend connectors to help developers quickly integrate with online services or backend systems from Studio. These backend connectors are provided as solutions that developers can either import as a new solutions or merge into existing solutions.

This page outlines the requirements for these backend connector solutions and their documentation.

Note: this page refers to ‘the developer’ as the person who is going to import and use the backend connector solution.

Solution requirements

To prevent conflicts when importing the backend connector into an existing solution, keep the following guidelines in mind when creating backend connector solutions:

  • Don’t base your solution on the Teneo Dialogue Resource template solutions, create an empty solution instead
  • Feel free to use the language objects, entities and annotations that exist in Teneo Lexical Resources. However, make sure you only use Teneo Lexical Resources that are available on Teneo Developers. See: Languages.
  • In your solution, create a top-level folder with the name of your solution. Create subfolders for you flows, language objects etc. For example:
    • Salesforce
      • Flows
      • Language objects
      • Subflows
  • Don’t use top-levels folder with any of the following names:
    • Dialogue
    • Flows
    • Greeting Message
    • Language Objects
    • Safetynet
  • If your solution contains only one trigger, you should use a Conditional Match Requirement.
  • Avoid using global scripts if possible, as they will overwrite the global scripts in the developers’ solution when merging.
    • For solution loaded scripts, you can use use .groovy files that you add to the Solution Resources instead.
    • If you solution needs other types of global scripts, you may choose to provide them in the readme with instructions on where to add the code.
  • When creating global assets, like global variables, global listeners, global contexts, integrations or files in resources, you may want to prefix them with your solution name, like salesforceApiVersion or weatherCity.
  • Make sure global variables are clean/empty and don’t contain values that you used during development.
  • Order groups require special attention:
    • Add a default order group called ‘Default’, but don’t add any triggers to it.
    • Add an order group called ‘[Solution Name] Triggers’ (for example ‘Salesforce Triggers’). Add your triggers to this group. This will make sure they are not added to the existing default group when the solution is merged.
  • Don’t add a Safetynet flow. This will most likely result in unexpected behavior when the solution is imported into an existing solution.
  • Keep the solution focussed, omit edge cases. Prevent the solution from becoming overwhelming.
  • Because you don’t know which channel the developer will use for their bot, make sure you don’t include frontend specific code in your solution.
  • The backend integration should work in tryout after following the appropriate instructions.

Integrations

  • Give you integration and its methods a meaningful name.
  • If applicable, add multiple methods to your integration, for example to create, retrieve, update or delete data the backend system.
  • Write your code in Groovy as much as possible.
    • If needed, you can store your code in a .groovy class that you use in your integration.
  • Avoid using external .jar files/libraries for functions that can be easily implemented using classes and methods that are available in the groovy/java version that comes with Teneo. This doesn’t mean you can’t use jars at all however. For example, if the service you integrate with provides jar files/libraries that simplify the integration, you should not hesitate to use them.
  • Make sure your integration handles exceptions and your flows handle them gracefully.

Authentication

  • Many backend integrations require authentication, which can get quite complicated. Familiarize yourself with the various authentication options offered by the api you integrate with.
  • In an ideal world you choose an authentication method that does not store credentials in Studio but uses tokens or an authentication mechanism where the user allows the bot to interact with the api on the user’s behalf (OAuth 2). That last approach quite often can only be achieved by also making changes to the frontend connector that is being used (like the Bot Framework Connector or Teneo Web Chat). To not complicate the implementation you can then choose to store credentials in global variables in Studio but your readme should make it clear that this approach should be used for development/proof of concept purposes only and that for production implementations other authentication approaches should be considered.
  • You may choose to implement example authentication flows for different authentication approaches. See the Salesforce solution for an example. This is not required however.
  • Make sure that by the time you deliver the solution, the credentials/tokens you used during development are removed from the solution.

Readme

In addition to your solution, you should provide a readme file with documentation. The readme file should give the developer an overview of what the solution does as well as provide step by step instructions to get the integration working in tryout.

Keep the following in mind:

  • The readme should be provided as a README.md file written in markdown.
  • The readme should include the following:
    • Introduction
      A short introduction describing the solution and its integration.
    • Solution contents
      Describe the main contents of the solution, like:
      • Integration
      • List of example flows
    • Example conversations
      Provide one or more example conversations that developers can try once they have imported your solution and followed the instructions. This gives an impression of what they can expect from the solution as well as something to try and demonstrate in tryout.
    • Getting started
      This section describes the what the developer needs to do the able to simulate the example conversation in tryout. This section might include:
      • Prerequisites
      • Setup instruction that are required in the third-party service
      • Instructions of details to store or update in the prebuilt solution
    • Important other information
      Any other information that you think is important for the developer to know. For example details on authentication.
    • Download
      • Link to How to import solutions page.
      • Additional instructions that the developer needs to follow after importing the solution (like assigning libraries, copying code to global script etc).
      • A link to the solution will be added by Artificial Solutions.

You can use the Salesforce and UiPath pages and solutions as a reference.