Interfacing with API JSPs

Applications can use the Teneo API to send and receive messages from the Teneo Engine. This section describes how to use the Teneo API JSPs via HTTP(S) and also provides a section describing how POSTing to Engine as application/json is possible.

Access the Teneo Engine Scripting API here.

Overview

An application can communicate with the Teneo Engine over HTTP(S) via the provided JSP views. JSP views can read the Engine response and post-process and/or format the data before it is returned to the application.

While custom JSP views may be used, this section focuses on the use of the provided views.

Views provided by Artificial Solutions

The JSP views provided by Artificial Solutions described in this section belong to the following categories:

• Standard views take an Engine response, apply post-processing and format the data for the HTTP(S) response
• Error views handle the response in the event of an error accessing a standard view
• End-session views used to end the session and are called differently from other views; see more in the Endsession section

With Teneo Platform 5.1 the former STANDARDJSONP and STANDARDJSON views were deprecated in favor of the new TIE-API. Their documentation can be foundhere.

API (TIE-API)

The web API is available as a web-service, which is accessible by any application capable of communicating by HTTP(S). Both GET and POST request are supported. Recommended best practice is to use POST requests to avoid running into URL length limitations.

The web-service is not stateless, so applications using this API need to maintain a session: in the first request coming to the TIE-API without a session header, a sessionId

attribute will be added to the response; all the upcoming interactions for the same session will have to include a Cookie named JSESSIONID

with that value or it will be considered a session-starting interaction.

This document assumes that the reader is familiar with HTTP(S) / JSONP.

Note: for the examples in the following sections, the URL for the Teneo server is assumed to behttp://teneo-server/

Common concepts

The TIE API defines these JSP files:

• tieapi.jsp
  The standard TIE API view, for normal requests
• error_tieapi.jsp
  The TIE API error view, for server-side errors
• endsession_text.jsp
  Used for ending a session
• CORS.jsp
  Cross-origin resource sharing directives.

TIE-API

This view offers a basic interaction with the Engine services.

Request parameters

The valid parameters for a TIE-API request are:

Example Request

1POST http://va-publishing.artifcial-solutions.com:8085/vapath/ HTTP/1.1
2host: ci8.dev.artificial-solutions.com:8085
3content-type: application/x-www-form-urlencoded
4content-length: 47
5Connection: close
6
7userinput=Someuserinput&usertimezone=CEST&viewtype=tieapi
8

Example response

1HTTP/1.1 200
2Set-Cookie: JSESSIONID=AAAAAABBBBBB000000999999911111; Path=/vapath; HttpOnly
3Content-Type: application/json;charset=UTF-8
4Content-Length: 251
5Date: Fri, 22 Mar 2019 16:06:56 GMT
6Connection: close
7Server:
8
9{
10	"status":0,
11	"input":{
12		"text":"cow",
13		"parameters":{"usertimezone":"CEST"}
14	},
15	"output":{
16		"text":"This is the output generated by the Engine!",
17		"emotion":"",
18		"link":"",
19		"parameters":{}
20	},
21	"sessionId":"AAAAAAABBBBBB000000999999911111"
22}
23

Response elements

ERROR_TIE-API

If an error occurs while processing the user input, a response will be returned by the error_tieapi.jsp.

This view will never be called by the user.

Example response

1{
2	"status":-1,
3	"input":{
4		"text":"Input that generated the error",
5		"parameters":{}
6	},
7	"message":"Teneo backend error",
8	"sessionId":"AAAAAAEEEEE9999991123456789"
9}
10

Response elements

The JSON object in the response contains a single element named responseData

; this element is a JSON object itself, containing the following elements.

Endsession

The endsession view is used to end the current session. It is special because it is called calling a specific endsession URL.

The endsession view has the following responsibilities:

• Terminating the current session
• Redirecting the request if necessary
• Setting response headers
• Returning the logout status

Request parameters

The valid parameters for an Endsession request are:

Example Request

1POST http://ci8.dev.artificial-solutions.com:8085/contest486/endsession HTTP/1.1
2Cookie: JSESSIONID=F764A2CE4D4811BC5AD60C2D623EDFC7
3host: ci8.dev.artificial-solutions.com:8085
4content-type: application/x-www-form-urlencoded
5content-length: 15
6Connection: close
7
8viewtype=tieapi
9

Example response

1HTTP/1.1 200
2P3P: CP="NOI CURa ADMa DEVa TAIa OUR BUS IND UNI COM NAV INT"
3Content-Type: text/javascript;charset=UTF-8
4Content-Length: 39
5Date: Fri, 22 Mar 2019 17:04:24 GMT
6Connection: close
7Server:
8
9{
10	"status":1,
11	"message":"logout"
12}
13

Response elements

The JSON object in the response contains a single JSON object, containing the following elements.

POSTing to Engine as application and json

Query Parameters (GET)

Form Encoded (POST): application/x-www-form-urlencoded

NEW JSON Encoded (POST): application/json

Details on request parsing

• The request body must contain a single, JSON object
  • The properties of this JSON object provide the input parameter names and values
  • Standard properties required by the Engine (eg: userinput
    , viewtype
    ) are to be provided as top-level properties of this object
  • A request just containing a primitive or an array is not supported and will cause a HTTP 400 (Bad request) error
• The object's top-level properties are converted:
  • Name of the property becomes the input parameter name
  • Value of the property is parsed according to these rules
    • if the property value is a primitive type then the parameter value becomes the property value
    • if the property value is an array then the parameter value becomes the List<Object>
      representation of the array, where array elements are converted recursively, according to these rules
    • if the property value is a JSON object then the parameter value becomes the Map<String, Object>
      representation of that object, where sub-properties are converted recursively, according to these rules

Engine API Methods

The parsed parameter data is exposed within a running solution via a new method getParameters

on the engineEnvironment

object - the original getParameterMap

method is still available for backwards compatibility

When calling getParameterMap

the results will be the same whichever request format is used, eg: for all the above request examples:

When calling the new getParameters

method from a JSON format request body - engine is able to interpret the types of the objects more natively:

Whereas calling the same from either query parameters or form formatted body the results are the same as for getParameterMap

:

Note: Duplicate Values in URL vs Body

Passing a value for a particular property as both a query parameter and in the request body is not recommended and the behavior will differ depending on request body type

WI API (deprecated)

The WI API is deprecated as of Teneo Platform 5.1.

STANDARDJSONP

The STANDARDJSONP view is typically used by web applications that need to use JSONP to receive data. The standard JSONP view has the following responsibilities:

• Determining if the current session is new
• Parsing answer text mark-up
• Generating the application and end-session URLs
• Setting response headers
• Creating a formatted JSONP response containing the Engine response data, session status, and application URL data.

What does 'Parsing answer text mark-up' mean?

This view applies post-processing to the Engine answer text to handle a simple mark-up that splits the answer text into text that will either remain in the answer text or be moved to view variables.

An example of an answer text containing mark-up may look something like:

1Initial text to show in the main answer area
2[$:param1]
3This is the text to add in param1
4[$:]
5Second text in the main answer area
6[$:param2]
7This is the text to add in param2
8[$:param1]
9Second text to add in param1
10[$:]
11Third text in the main answer area
12

After being processed by the STANDARDJSONP view, the answer text will contain:

1“Initial text to show in the main answer area
2Second text in the main answer area
3Third text in the main answer area”
4

While the rest of the text is moved to the view variables specified by the mark-up:

1param1: “This is the text to add in param1
2Second text to add in param1”
3param2: “This is the text to add in param2”
4

STANDARDJSONP request parameters

The valid parameters for a STANDARDJSONP request are:

Example STANDARDJSONP GET request

1GET https://teneo-server/?viewname=STANDARDJSONP&userinput=Hello%20world&callback=handleJSONResponse
2

Example STANDARDJSONP response

1handleJSONResponse({
2	"responseData" : {
3		"status" : 0,
4		"applicationUrl" : "<https://teneo-server/>",
5		"applicationEndSessionUrl" : "<https://teneo-server/endsession/>",
6		"isNewSession" : true,
7		"lastinput" : "Hello%20world",
8		"answer" : "Greetings%20human!",
9		"extraData" : {
10			"my_view_variable":"This%20is%20my%20view%20variable",
11		}
12		"emotion" : "Happy",
13		"link" : {
14			"href" : "https%3A%2F%2Fteneo-example%2Fanotherpage%2F",
15			"target" : "_new"
16		}
17	}
18})
19

STANDARDJSONP response elements

The JSON object in the response contains a single element named responseData

; this element is a JSON object itself, containing the following elements.

Error_standardjsonp

If an error occurs during a call to STANDARDJSONP, the error response is directed to the error_standardjsonp view.

This view has the following responsibilities:

• setting response headers
• creating a formatted JSONP response containing an error message.

Error_standardjsonp request parameters

The error view will receive the same request parameters that were sent to the view for which it is handling the error, but error_standardjsonp only uses the following parameter.

Example error_standardjsonp GET request

1GET https://teneo-server/?viewname=STANDARDJSONP&userinput=Hello%20world&callback=handleJSONResponse
2

Example error_standardjsonp response

1handleJSONResponse({
2	"responseData" : {
3		"status" : "-1",
4		"statusDescription" : "Backend error, concurrent session limit exhausted
5or invalid license"
6	}
7})
8

error_standardjsonp response elements

The JSON object in the response contains a single element named responseData

; this element is a JSON object itself, containing the following elements.

STANDARDJSON

The STANDARDJSON view is typically used by applications that wish to receive the data as JSON, but do not need to use the JSONP callback technique.

The standard JSON view has the following responsibilities:

• Setting response headers
• Generating the application URL
• Creating a formatted JSON response containing the engine response data and application URL data.

STANDARDJSON request parameters

The valid parameters for a STANDARDJSON request are:

Example STANDARDJSON GET request

1GET https://teneo-server/?viewname=STANDARDJSON&userinput=Hello%20world
2

Example STANDARDJSON response

1{
2	"responseData" : {
3		"emotion":"Happy",
4		"lastinput":"Hello%20world",
5		"answer":"Greetings%20human!",
6		"link": {
7			"href":"https%3A%2F%2Fteneo-example%2Fanotherpage%2F",
8			"target":"_new"
9		},
10		"extraData": {
11			"my_view_variable":"This%20is%20my%20view%20variable",
12		},
13		"responseSession": {
14			"id":"123456789ABCDEF",
15			"transaction":"1"
16		},
17		"responseDetails": null,
18		"responseStatus": 200,
19		"applicationUrl": "<https://teneo-server/>"
20	}
21}
22

STANDARDJSON response elements

The JSON object in the response contains a single element named responseData

; this element is a JSON object itself, containing the following elements.

error_standardjson

If an error occurs during a call to STANDARDJSON, the error response is directed to the error_standardjson view.

This view has the following responsibilities:

• Setting response headers
• Generating the application URL
• Returning formatted JSON containing an error message.

error_standardjson request parameters

The error view will receive the same request parameters that were sent to the view for which it is handling the error, but error_standardjson does not use them.

Example error_standardjson GET request

1GET https://teneo-server/?viewname=STANDARDJSON&userinput=Hello%20world
2

Example error_standardjson response

1{
2	"responseData" : {
3		"emotion":"neutral",
4		"lastinput":"",
5		"answer":"I%20am%20currently%20busy.%20Please%20try%20again%20later.",
6		"link": {
7			"href":"",
8			"target":""
9		},
10		"extraData": {},
11		"responseSession": {
12			"id":"",
13			"transaction":""
14		},
15		"responseDetails": null,
16		"responseStatus": 200,
17		"applicationUrl": "<https://teneo-server/>"
18	}
19}
20

error_standardjson response elements

The JSON object in the error response matches the format of the STANDARDJSON response, but the data is not fully populated. It contains a single element named responseData

, this element is itself a JSON object containing the following elements.

endsession

The endsession view is used to end the current session. It is special because it is not called by setting the viewName parameter, but instead by calling a specific endsession URL.

The endsession view has the following responsibilities:

• Terminating the current session
• Redirecting the request if necessary
• Setting response headers
• Returning formatted JSONP containing the logout status.

When sending a request to the ‘endsession’ view, the API response will return JSON wrapped in the specified callback function.

endsession request parameters

The valid parameters for an endsession request are as follows.

Example endsession GET request

1GET <https://teneo-server/endsession?callback=handleJSONResponse&redirect=https%3A%2F%2Fteneo-example%2Ffarewell%2F>&viewtype=standardjson
2

Example endsession response

1handleJSONResponse({
2	"responseData" : {
3		"status" : 1,
4		"statusDescription" : "logout"
5	}
6})
7

endsession response elements

The JSON object in the response contains a single element named responseData

; this element is a JSON object itself, containing the following elements.