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.

sequenceDiagram
	participant user as User
	participant app as Application
	participant jsp as JSP View
	participant server as Server
	participant engine as Engine

	user->>app:Input text
	app->>server:Request
	server->>engine:Engine input
	engine->>server:Engine output
	server->>jsp:Response
	jsp->>app:JSON data
	app->>user:Displays output

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.

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:

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`

Interfacing with API JSPs

Overview

Views provided by Artificial Solutions

API (TIE-API)

Common concepts

TIE-API

Request parameters

Example Request

Example response

Response elements

ERROR_TIE-API

Example response

Response elements

Endsession

Request parameters

Example Request

Example response

Response elements

POSTing to Engine as application and json

Query Parameters (GET)

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

JSON Encoded (POST): application/json

Details on request parsing

Engine API Methods

Note: Duplicate Values in URL vs Body

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

JSON Encoded (POST): `application/json`