Package: Engine-Conversation

PreviousPackage: Collections-Strings NextPackage: Kernel-HTTP

Last updated 7 months ago

Was this helpful?

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 that contains all the http headers passed from the client to the server.
httpRequestBody - Returns an object of type that contains the http request body passed from the client to the server.
parameters - Returns an object of type 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
- #:webhook
For example:
```
introductionSubject := self predefinedSubject: #:introduction.
self response: 'introduction subject id is ', introductionSubject id.
```
webhook - Returns an object of type that contains all the information about the runtime webhook request.

Category: advance operations

awaitHTTPResponse: - Wait for the HTTP response from the given HTTP client asynchronously.

The conversation will be paused at this point and will be resumed after the HTTP response is received. All responses before this point will be sent to the client.

For example:

  httpClient := HTTPClient new.
  httpClient url: 'https://webhook.mind.ai/ManualInfo'.
  httpClient method: #:get.
  result := self awaitHTTPResponse: httpClient.
  status := result at: 'status'.
  status = 200 ifFalse: [ self response: 'Failed to retrieve name from the web hook server!' ].
  response := JSONReader fromString: (result at: 'response').
  name := response nestedAt: { 'data'. 'full_name' }.
  self parameters at: 'name' put: name.

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'.
```

headers - Get all the HTTP headers as a Dictionary object.

self response: 'http headers: ', self httpHeaders headers asJson.

Category: reflective operations

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

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.

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: - Get the specified parameter's value with the provided name within the current subject's scope. A default value is returned if the parameter is not set, provided that a default value is available.
```
self parameters at: 'cash_flow'.
```
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: event handling

at:whenBoundSetHandler: - Register a block closure to handle the event when the value of the parameter is bound.
For example, if the parameter y depends on the parameter x, and we want to reset y when x changes, we can write:
```
self parameters at: 'x' whenBoundSetHandler: [self parameters removeKey: 'y'].
```

Category: reflective operations

Category: removing

removeKey: - Remove the association for the given parameter by its name.

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.

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 7 months ago

Was this helpful?

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 that contains all the http headers passed from the client to the server.
httpRequestBody - Returns an object of type that contains the http request body passed from the client to the server.
parameters - Returns an object of type 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
- #:webhook
For example:
```
introductionSubject := self predefinedSubject: #:introduction.
self response: 'introduction subject id is ', introductionSubject id.
```
webhook - Returns an object of type that contains all the information about the runtime webhook request.

Category: advance operations

awaitHTTPResponse: - Wait for the HTTP response from the given HTTP client asynchronously.

The HTTP client is an object of type .

The conversation will be paused at this point and will be resumed after the HTTP response is received. All responses before this point will be sent to the client.

For example:

  httpClient := HTTPClient new.
  httpClient url: 'https://webhook.mind.ai/ManualInfo'.
  httpClient method: #:get.
  result := self awaitHTTPResponse: httpClient.
  status := result at: 'status'.
  status = 200 ifFalse: [ self response: 'Failed to retrieve name from the web hook server!' ].
  response := JSONReader fromString: (result at: 'response').
  name := response nestedAt: { 'data'. 'full_name' }.
  self parameters at: 'name' put: name.

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'.
```

headers - Get all the HTTP headers as a Dictionary object.

self response: 'http headers: ', self httpHeaders headers asJson.

Category: reflective operations

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

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 , 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 .

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: - Get the specified parameter's value with the provided name within the current subject's scope. A default value is returned if the parameter is not set, provided that a default value is available.
```
self parameters at: 'cash_flow'.
```
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: event handling

at:whenBoundSetHandler: - Register a block closure to handle the event when the value of the parameter is bound.
For example, if the parameter y depends on the parameter x, and we want to reset y when x changes, we can write:
```
self parameters at: 'x' whenBoundSetHandler: [self parameters removeKey: 'y'].
```

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 , which can unerstand all messages for a Dictionary class.

Category: removing

removeKey: - Remove the association for the given parameter by its name.

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 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.