Version: 8.1.0

Engine API

Developers may need to interact with the Teneo Engine (or 'engine', in short) for various reasons, such as session management and Cross-Origin Resource Sharing (CORS). In order to interact with the engine, the developer should use the Engine API. This page outlines the main uses of the Engine API.

Access the Teneo Engine Scripting API here.

Legacy JSP Views

Custom JSP views are deprecated and only relevant for legacy solutions. This documentation retains JSP information for backward compatibility, but new integrations should use the JSON API exclusively.

Engine URL

Once a solution has been developed and tested in Teneo Studio, it can be published to an engine. Once published, the engine contains the solution data and has a unique URL that client applications can use to interact with it.

You can find the URL in the publication endpoint of your solution, in the Publish section in the solution backstage.

Session Management

The client applications maintain a session with the engine to allow the engine to remember details between requests by the users. The engine handles sessions as follows:

info

Please note that the extra functionalities of the "X-Gateway/Teneo-Session" handling is only available in SaaS.

1. When a request comes in that does not contain session details, a new session will be created on the server. The session ID will be included in the JSON response and as a cookie in the response header.
   • If the response contains the header X-Gateway-Session then the next request must include the header X-Teneo-Session with the value JSESSIONID=session_ID followed by ; and the value received from the X-Gateway-Session header.

Example

Session ID	X-Gateway-Session	X-Teneo-Session
31992FA776A3XXXXX1031B5F	FOO=BAR	JSESSIONID=31992FA776A3XXXXX1031B5F; FOO=BAR

2. To maintain a dialogue in the same session, the next request of the client should include the session ID received in the response, and in responses where the X-Gateway-Session header was present, the X-Teneo-Session header is required.

info

The X-Teneo-Gateway handling is to keep sessions working when cookies may be blocked. The prime example being in browsers.

3. The engine will expire the session, after 10 minutes of inactivity. All details stored in the session will be forgotten.
4. If a request comes in with a session ID that is expired or unknown, the engine will create a new empty session and include the new session ID in the response.

You should make sure the session cookie received from the engine is included in the request header. The way to do this depends on the language used. In Node.js, for example, this could be achieved as follows:

https.get({
      host: 'https://some.teneo',
      path: 'engine-url/?viewtype=tieapi&userinput=What%20time%20is%20it%3F&usertimezone=CEST',
      method: 'POST',
      headers: {
          'Cookie': 'JSESSIONID=31992FA776A35DABA3291A4EE1031B5F',
          // If the response header X-Gateway-Session is set
          'X-Teneo-Session': 'JSESSIONID=31992FA776A35DABA3291A4EE1031B5F' // Followed by ';' and the value of X-Gateway-Session
      }
}, function(response) {
        // handle response
});

Ending a session

The best practice is to end sessions when possible, e.g. by closing the bot's window in Teneo Web Widget. If the session is not ended, the engine will automatically expire sessions after 10 minutes of inactivity by default.

You can end session by appending endsession to the engine URL. Make sure the session cookie and X-Teneo-Session header (when the X-Gateway-Session header is present in responses) is included in the request, as the engine won't know which session to end otherwise.

Example request

curl -X POST \
  https://some.teneo/engine-url/endsession \
  -H 'Content-Type: application/x-www-form-urlencoded'

Example response

{
    "status" : 1,
    "message" : "logout"
}

Accessing Parameters in Solutions

Within your solution, use the engineEnvironment object to access request data.

Recommended: Use getParameters() for better type handling with JSON:

engineEnvironment.getParameters()
// Returns: { "userinput": "Hello Julia!", "additionaldata": 1234, "viewtype": "tieapi" }

Legacy: getParameterMap() treats all values as arrays:

engineEnvironment.getParameterMap()
// Returns: { "userinput": ["Hello Julia!"], "additionaldata": ["1234"], "viewtype": ["tieapi"] }

Cross-Origin Resource Sharing (CORS)

When interacting with the Teneo Engine using JavaScript in a browser, the domain that is making requests is often different from the domain used by the Teneo Engine. Cross-Origin Resource Sharing (CORS) is a mechanism that uses additional HTTP headers to tell a browser to give a web application running at one origin (domain) permission to access selected resources from a server at a different origin.

By default, the Teneo Engine includes CORS headers in the responses to browser requests coming from any domain. This means any site can interact with a Teneo Engine. If you want to restrict your solution to only include CORS headers for specific domains, you can add a file called tieapi_cors_origins.txt to your solution. In Teneo Studio, use the File Manager to add the file to the views folder. The file should contain the list of allowed origin domains (one domain per line, domains should include port numbers if applicable).