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
For easier usage with non-web deployed frontends, the Teneo Platform now supports interacting with a published engine via POSTing as JSON as well as the previously supported Forms and query parameters formats
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'
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 |