Package: Engine-Conversation

Class: Conversation

Introduction

Environment: container

A conversation object is a container for all the information related to current conversation.

It is the start point to write covnersation rules in a subject. In the rules, you can access the conversation object by using the variable self or conversation.

For example, to bind a parameter from a http header, you can write:

userName := self httpHeaders at: 'x-user-name'.
self parameters at: 'user_name' put: userName.

All attributes for a conversation object are listed below in category accessing.

Instance Method

Category: accessing

currentInput - Returns the current input of the conversation as a string.
httpHeaders - Returns an object of type HTTPHeader that contains all the http headers passed from the client to the server.
httpRequestBody - Returns an object of type HTTPRequestBody that contains the http request body passed from the client to the server.
parameters - Returns an object of type Parameter that contains all the parameters in current scope.
predefinedSubject: - Returns a predefined subject object of the given subject type.
The subject type can be one of the following:
- #:introduction
- #:conclusion
For example:
```
introductionSubject := self predefinedSubject: #:introduction.
self response: 'introduction subject id is ', introductionSubject id.
```
webhook - Returns an object of type RuntimeWebHook that contains all the information about the runtime webhook request.

Category: advance operations

check: - ask for the check step for the parameter value of a given parameter.
The parameter name is given as a string.
For example:
```
self check: 'user_name'.
```
response: - Show a message as a response.
For example:
```
self response: 'Updated parameter value of x to 10.'.
```
At the present moment, it is utilized solely for debugging purposes, allowing us to display additional information during the development of the subject.

Class: HTTPHeader

Introduction

Environment: container

A key-value pair is known as a HTTPHeader object for current conversation.

The origin of the initial values of http headers can be

the subject configurations for a web hook call
- Such http headers are only accessable in before/after rules for a web hook.
additional http headers when requesting a conversation to Mind Expression.
- Such http headers are accessable in all rules.

The key name, a string, serves as the HTTP header name, while the value, also a string, corresponds to the http header value.

To retrieve the value of a http header, you can utilize the following syntax:

a_header := self httpHeaders at: 'a-header-key'.

"If the http header is not set, return a default value 100."
a_header := (self httpHeaders at: 'a_header_key' ifAbsent: '100') asInteger.

Below is an example of setting a default value of a http header:

header := self httpHeaders at: 'webhook_header_key'.
header ifNil: [ 
  self httpHeaders at: 'webhook_header_key' put: 'default_webhook_header_value_3' ].

Class Method

Category: accessing

at: - Get the value of the HTTPHeader with specified name for current webhook.
```
a_header_key := (self httpHeaders at: 'a_header_key') asInteger.
```

at:ifAbsent: - Get the value of the HTTPHeader with specified name, and specify a default value if absent.

The parameter for the default value can be:

a code block, which will be evaluated if the HTTPHeader is absent.
a value, which will be returned if the HTTPHeader is absent.

"The default value can be a value."
a_header_key := (self httpHeaders at: 'a_header_key' ifAbsent: '100') asInteger.
"The default value can be a code block to evaluate."
a_header_key := (self httpHeaders at: 'a_header_key' ifAbsent: [(100 + 1) asString]) asInteger.

at:put: - Update the value of the HTTPHeader with specified name.
```
self httpHeaders at: 'a_header_key' value: '1000'.
```

Category: removing

removeKey: - Remove the HTTPHeader with the given name.
```
self httpHeaders removeKey: 'a_header_key'.
```

Class: HTTPRequestBody

Introduction

Environment: container

The HTTPRequestBody class represents the body of an HTTP request in current conversation.

This class provides a convenient way to interact with the content of an HTTP request, whether it's a raw string or a structured JSON object.

If the body of the HTTP request is not a json object, you can retrieve it directly by method rawData.

"The request body may be a raw string, or a number."
rawData := self httpRequestBody rawData.

If the body contains a JSON object, you can interact with it as if it's a dictionary, allowing you to retrieve values by their keys.

"Retrieve the value of the key 'user_name' from http request body."
userName := self httpRequestBody at: 'user_name' ifAbsent: ''.
"store the value of the key 'user_name' as a parameter." 
self parameters at: 'user_name' put: userName.

Instance Method

Category: accessing

rawData - Get the raw data of the HTTP request body.

" Occasionally, the body of the HTTP request ma be a simple string rather than a JSON object."
rawData := self httpRequestBody rawData.

Category: reflective operations

doesNotUnderstand: - By default, for any message that is not understood by a HTTPRequestBody object, the message will be forwarded to the request body dictionary, which can unerstand all messages for a Dictionary class.
If the body of the request is a JSON object, you can extract the 'user_name' key value in this way:
```
"Retrieve the value of the key 'user_name' from http request body."
userName := self httpRequestBody at: 'user_name' ifAbsent: ''.
```

Class: Parameter

Introduction

Environment: container

A key-value pair is known as a parameter object within the context of this conversation.

It inherits from the Dictionary class, so it has all the methods of a dictionary.

The parameter's name, given as a string, serves as the key, while its value, also a string, corresponds to the parameter's value.

To retrieve the value of a parameter, you can utilize the following syntax:

cash_flow_string := self parameters at: 'cash_flow'.

"If the parameter is not set, will return a default value 100."
cash_flow := (self parameters at: 'cash_flow' ifAbsent: '100') asInteger.

Below is an example of setting the value of a parameter:

self parameters at: 'cash_flow' put: '1000'.

When extracting a parameter from a web hook response using jsonpath, it will retrieve multiple matching values.

For instance, if the parameter cash_flow is created using the jsonpath expression $.cash_flow, the extraction process should be as follows:

cash_flow := (self parameters at: 'cash_flow' ifAbsent: {'100'}) first asInteger.

By default, the scope of a parameter is local to current subject, but you can also set the scope to global by using the following syntax:

self parameters at: 'a_global_parameter' value: '1000' as: #global.

That means, the parameter a_global_parameter will be available to all subjects within the current scope.

Class Method

Category: accessing

at:put: - Update the specified local parameter's value with the provided name within the current subject's scope.
```
self parameters at: 'cash_flow' value: '1000'.
```
at:put:as: - Update the parameter's value with the given name at the specified scope.
The scope can be:
- #local - the parameter will be valid in current subject.
- #global - the parameter will be valid in all subjects.
```
"Register a global parameter."
self parameters at: 'a_global_parameter' value: '1000' as: #global.
```
getSourceOf: - Get the data source of the parameter with specified name.
The possible data source can be
- #:input - the value of the parameter is derived from the query.
- #:history - the value of the parameter is derived from the previous query.
- #:webhook - the value of the parameter is derived from a web hook response.
- #:rules - the value of the parameter is derived by MindScript rules.
- #:default - The value of the parameter is derived from the default value.
- #':http-headers' - the value of the parameter is derived from http headers.
- nil - the data source of the parameter is not available.
```
"Get the source of parameter 'a'"
source := self parameters getSourceOf: 'a'.
```

Category: reflective operations

doesNotUnderstand: - By default, for any message that is not understood by a Parameter object, the message will be forwarded to a class Dictionary, which can unerstand all messages for a Dictionary class.

Class: RuntimeWebHook

Introduction

Environment: container

This class would correspond to the runtime web hooks that are involved in the actual live conversation, handling the HTTP requests and responses.

Instance Method

Category: accessing

method - the HTTP method of the webhook.
It can be one of the following values:
- #:get
- #:post
request - The body string of the webhook request; only applicable for POST requests.
If the request is a json string, we can extract the json object by using the following code:
```
request := JSONReader fromString: self webhook request.
event := (request at: 'event').
self parameters at: 'event' put: event.
```

response - the response string of the webhook.

If the resonse is a json string, we can extract the json object by using the following code:

response := JSONReader fromString: self webhook response.
"The key is 'all'"
all := response at: 'all'.
" If the json path is 'all.0.name', we can get the value by using the following code:"
firstName := response nestedAt: {'all'. 1. 'name'}.

response is only available in after rules for a webhook.

statusCode - The HTTP status code from the webhook response. It's an integer value like 200, 404, etc. See the wiki page for more details.
When write a rule, we can stop the execution of the rule when webhook fails by using the following code:
```
"If webhook failed, just return from current rule."
self webhook statusCode = 200 ifFalse: [ ^ nil ].
```
statusCode is only available in after rules for a webhook.
url - This is the actual URL used to call the webhook, also known as the rendered URL of the webhook.

PreviousPackage: Collections-Strings NextPackage: Kernel-HTTP

Last updated 1 month ago