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
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.
Common concepts
The TIE API defines these JSP files:
tieapi.jsp
The standard TIE API view, for normal requestserror_tieapi.jsp
The TIE API error view, for server-side errorsendsession_text.jsp
Used for ending a sessionCORS.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:
Parameter | Description |
---|---|
viewtype | Specifies the type of view to handle the request. Should be “tieapi” for this view. |
userinput | A string containing the user’s input (e.g. the value of the user input box in the web UI). Leave empty to send a request without any natural language user input. |
usertimezone | A string specifying the user Time Zone |
Example Request
groovy
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
groovy
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
Key | Description |
---|---|
status | A status code indicating if there is an active session and there was no error handling the request.0 – There is a session and there was no error.Any successful response from the STANDARDJSONP view will have this value as it will either use the existing session or start a new one. |
sessionId | Value of the Session ID that will be used to maintain the server session. |
input | User input. It contains the text sent by the user, as well as all the parameters sent along with the request. |
output | Contains the following elements: The text returned by the Engine Any emotion associated with the response Any link provided by the response And the response parameters. |
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
groovy
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.
Key | Description |
---|---|
status | A status code indicating there has been an error. The value of this field for error messages is always -1. |
message | Message indicating there has been an error. For any error message it will be always “Teneo backend error” |
input | User input received by the server. It contains two fields: Text: containing the user input text sent for the engine to interpret. Parameters: parameters sent by the user along with the request |
sessionId | The session identifier of the session the erroneous transaction belongs to |
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:
Parameter | Description |
---|---|
viewtype | Specifies the type of view to handle the request. Should be “tieapi” for this view. |
Example Request
groovy
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
groovy
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.
Key | Description |
---|---|
status | A status code indicating if there is an active session. 1 – There is no session. Any successful response from a call to the end session URL will have this value as it will have ended the session. |
message | Message indicating the result of the end session operation |
POSTing to Engine as application and json
Query Parameters (GET)
curl --request GET '<engine_location>?userinput=Hello%20Julia%21&viewtype=tieapi&additionaldata=1234'
Form Encoded (POST): application/x-www-form-urlencoded
curl --request POST '<engine_location>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'userinput=Hello Julia!' \
--data-urlencode 'viewtype=tieapi' \
--data-urlencode 'additionaldata=1234'
NEW JSON Encoded (POST): application/json
curl --request POST '<engine_location>' \
--header 'Content-Type: application/json' \
--data-raw '{
"viewtype": "tieapi",
"userinput": "Hello Julia!",
"additionaldata": 1234
}'
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:
engineEnvironment.getParameterMap():
'{
"userinput": [
"Hello Julia!"
],
"viewtype": [
"tieapi"
],
"additionaldata": [
"1234"
]
}'
When calling the new getParameters
method from a JSON format request body - engine is able to interpret the types of the objects more natively:
engineEnvironment.getParameters():
'{
"userinput": "Hello Julia!",
"additionaldata": 1234,
"viewtype": "tieapi"
}'
Whereas calling the same from either query parameters or form formatted body the results are the same as for getParameterMap
:
engineEnvironment.getParameters():
'{
"userinput": [
"Hello Julia!"
],
"viewtype": [
"tieapi"
],
"additionaldata": [
"1234"
]
}'
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
Query Parameter | Body Parameter | API Method | application/x-www-form-urlencoded | application/JSON |
---|---|---|---|---|
number1=1 | number2=2 | engineEnvironment.getParameterMap() | number1=["1"], number2=["2"] | number1=["1"], number2=["2"] |
number1=1 | number2=2 | engineEnvironment.getParameters() | number1=["1"], number2=["2"] | number1=["1"], number2=2 |
number=1 | number=2 | engineEnvironment.getParameterMap() | number=["1","2"] | number=["2"] |
number=1 | number=2 | engineEnvironment.getParameters() | number=["1","2"] | number=2 |
WI API (deprecated)
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:
groovy
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:
groovy
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:
groovy
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:
Parameter | Description |
---|---|
viewname | Specifies the view to handle the request. Should be ‘STANDARDJSONP’ for this view. |
userinput | A string containing the user’s language input (e.g. the value of the user input box in the web UI). Leave empty to send a request without any natural language user input. |
callback | A string specifying the name of the callback function to be used in the formatted JSONP response. |
Viewtype | Should have the value “STANDARDJSONP” |
Example STANDARDJSONP GET request
groovy
1GET https://teneo-server/?viewname=STANDARDJSONP&userinput=Hello%20world&callback=handleJSONResponse
2
Example STANDARDJSONP response
groovy
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.
Key | Description |
---|---|
status | A status code indicating if there is an active session and there was no error handling the request. 0 – There is a session and there was no error. Any successful response from the STANDARDJSONP view will have this value as it will either use the existing session or start a new one. |
applicationUrl | The URL the application should use for future requests. This may be different from the URL used for the previous request due to load balancing. |
applicationEndSessionUrl | The URL the application should use to end the current session. This may change over time due to load balancing. |
isNewSession | Indicates if the session that generated the response is new. This will be true for the first response received from the server and may be true for future responses if a new session needed to start. This may happen if, for example, the session timed out due to inactivity or if the server restarted. |
lastinput | The value of the ‘USERINPUT’ view variable. This will be the user input, as received by the engine as a URL encoded string. |
answer | The answer text produced by the engine (after markup processing) as a URL encoded string. |
extraData | All view variables from answer text markup processing or produced by the engine except for the ‘USERINPUT’ and ‘LINKTARGET’ variables will appear in the extraData object as encoded key/value string properties. |
emotion | The name of the emotion returned by the engine, encoded as a URL string. |
link | A JSON object describing the URL returned by the engine and how it should be opened. It contains the following properties: href – the URL as a URL encoded string target – the value of the ‘LINKTARGET’ view variable as a URL encoded string. Historically, this value was embedded as the target attribute of anchor tabs and so will generally contain one of the HTML target keyword values as described hereIt is up to the web-application to decide how these values are used. |
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.
Parameter | Description |
---|---|
callback | A string specifying the name of the callback function to be used in the formatted JSONP response. |
Example error_standardjsonp GET request
groovy
1GET https://teneo-server/?viewname=STANDARDJSONP&userinput=Hello%20world&callback=handleJSONResponse
2
Example error_standardjsonp response
groovy
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.
Key | Description |
---|---|
status | A status code indicating if there is an active session and there was no error handling the request. -1 – there was an error. Any successful response from the error_standardjsonp view will have this value as it is only used in the event of an error. |
statusDescription | A string containing a text error message. Hardcoded to: “Backend error, concurrent session limit exhausted or invalid license”. |
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:
Parameter | Description |
---|---|
viewname | Specifies the view to handle the request. Should be ‘STANDARDJSON’ for this view. |
userinput | A string containing the user’s natural language input (e.g. the value of the user input box in the web UI). Leave empty to send a request without any natural language user input. |
Viewtype | Should have the value “STANDARDJSON” |
Example STANDARDJSON GET request
groovy
1GET https://teneo-server/?viewname=STANDARDJSON&userinput=Hello%20world
2
Example STANDARDJSON response
groovy
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.
Key | Description |
---|---|
emotion | The name of the emotion returned by the engine, encoded as a URL string. |
lastinput | The value of the ‘USERINPUT’ view variable. This will be the user input as received by the engine as a URL encoded string. |
answer | The answer text produced by the engine as a URL encoded string. |
link | A JSON object describing the URL returned by the engine and how it should be opened. It contains the following properties: href – the URL as a URL encoded string; target – the value of the ‘LINKTARGET’ view variable as a URL encoded string. Historically, this value was embedded as the target attribute of anchor tabs and so will generally contain one of the HTML target keyword values as described hereIt is up to the web application to decide how these values are used. |
extraData | All view variables produced by the engine except for the ‘USERINPUT’, ‘LINKTARGET’, ‘LINGUBOTURL’, ‘LINKSTYLE’ and ‘SESSION_ID’ variables will appear in the extraData object as encoded key/value string properties. |
responseSession | A JSON object describing the current session. It contains the following properties: id – the session ID transaction – the transaction ID |
responseDetails | Legacy property, always null. |
responseStatus | Legacy property, always 200. |
applicationUrl | The URL the application should use for future requests. This may be different from the URL used for the previous request due to load balancing. |
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
groovy
1GET https://teneo-server/?viewname=STANDARDJSON&userinput=Hello%20world
2
Example error_standardjson response
groovy
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.
Key | Description |
---|---|
emotion | A string, always: neutral |
lastinput | An empty string |
answer | A URL encoded string, always decodes as: I am currently busy. Please try again later. |
link | A placeholder JSON object that would usually describe the URL returned by the engine and how it should be opened. It contains the following properties: href – an empty string target – an empty string |
extraData | An empty JSON object |
responseSession | A placeholder JSON object that would usually describe the current session. It contains the following properties: id – an empty string transaction – an empty string |
responseDetails | Legacy property, always null. |
responseStatus | Legacy property, always 200. |
applicationUrl | The URL the application should use for future requests. This may be different from the URL used for the previous request due to load balancing. |
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.
Parameter | Description |
---|---|
callback | A string specifying the name of the callback function to be used in the formatted JSONP response. |
Redirect (optional) | The URL the calling application will be redirected to. If this parameter is set, the HTTP response code will be 302 and the Location header will be set to the specified URL. |
Viewtype | Should have the value “STANDARDJSON” |
Example endsession GET request
groovy
1GET <https://teneo-server/endsession?callback=handleJSONResponse&redirect=https%3A%2F%2Fteneo-example%2Ffarewell%2F>&viewtype=standardjson
2
Example endsession response
groovy
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.
Key | Description |
---|---|
status | A status code indicating if there is an active session. 1 – There is no session. Any successful response from a call to the end session URL will have this value as it will have ended the session. |
redirect | The URL the JSP view should redirect the response to after terminating the session. |