UBI docs consolidation

.github/vale/styles/Vocab/OpenSearch/Products/accept.txt

@@ -88,6 +88,7 @@ Simple Schema for Observability
 Tableau
 TorchScript
 Tribuo
+User Behavior Insights
 VisBuilder
 Winlogbeat
 Zstandard

_search-plugins/index.md

@@ -70,6 +70,8 @@ OpenSearch provides the following search relevance features:
 
 - [Querqy]({{site.url}}{{site.baseurl}}/search-plugins/querqy/): Offers query rewriting capability.
 
+- [User Behavior Insights]({{site.url}}{{site.baseurl}}/search-plugins/ubi/): Link user application behavior to their queries for improving search relevance insights.
+
 ## Search results
 
 OpenSearch supports the following commonly used operations on search results:

_search-plugins/ubi/client_datastructures.md

@@ -0,0 +1,93 @@
+---
+layout: default
+title: Client Data structures old
+parent: User behavior insights
+has_children: false
+nav_order: 7
+---
+
+The datastructures that we use for indexing events adhere to the following nested structure that aligns with the Ubi schemas.  See the [schemas](.././schemas.md) for descriptions and examples of the following fields.
+
+`struct UbiEvent {`
+- application
+- action_name
+- user_id
+- query_id
+- session_id
+- page_id
+- message_type
+- timestamp
+- <details>
+	<summary>event_attributes {</summary>
+	<p>
+
+  - <details>
+  	<summary>position {</summary>
+
+  		- ordinal
+  		- x
+  		- y
+  		- trail
+  	}
+  	</details>
+  - <details>
+  	<summary>object {</summary>
+
+  		- internal_id
+  		- object_id
+  		- object_type
+  		- description
+  		- object_details /
+        - object_details.json
+  		}
+  	</details>
+	}
+  </details>}
+`}`
+
+Typescript versions of these classes can be found in [ts/UbiEvent.ts](./ts/UbiEvent.ts).
+
+Example javascript code:
+```js
+    // basic message format
+    let e = new UbiEvent('chorus', 'add_to_cart', user_id, query_id);
+    e.message_type = 'PURCHASE';
+    e.message = item.title + ' (' + item.primary_ean + ')';
+    e.session_id = session_id;
+    e.page_id = window.location.pathname;
+
+    // adding custom data fields
+    e.event_attributes['user_info'] = {user_name:'TheJackal', phone:'555-555-1234'}
+
+    // associate the object added to the cart
+    e.event_attributes.object = new UbiObject('product', item.primary_ean, item.title, item);
+
+    // save any click info
+    e.event_attributes.position = new UbiPosition({x:event.clientX, y:event.clientY});
+
+    // index here
+    console.log(e.toJson());
+```
+
+With very similar [python data structures](./py/ubi.py):
+```python
+if __name__ == '__main__':
+	e = UbiEvent(application='chorus', action_name='add_to_cart', 
+              user_id='USER-' + guuid(), query_id='QUERY-ID-'+ guuid(), session_id='SESSION-' + guuid(),
+              # object added to the cart
+              object= UbiObject(
+                  		object_type='product', 
+                    	object_id='ISBN-' + guuid(), 
+                      description='a very nice book', details={'product_data':'random product data'}              
+            )
+	)
+	e.message_type = 'PURCHASE'
+
+	# adding custom attribute fields
+	e.event_attributes['user_info'] = {'user_name':'TheJackal', 'phone':'555-555-1234'}
+
+ 	# product position information
+	e.event_attributes.position = UbiPosition(ordinal=3, x=250, y=400)
+
+	print(e.to_json())
+```

_search-plugins/ubi/data-structures.md

@@ -0,0 +1,126 @@
+---
+layout: default
+title: Client data structures
+parent: User behavior insights
+has_children: false
+nav_order: 7
+---
+
+# Sample data structures
+The data structures below can be used to create events that follow the [UBI event schema](schemas.md).
+
+The developer just needs to decide on implementations for the following functions:
+- `getUserId()`
+- `getQueryId()`
+- `getSessionId()`
+- `getPageId()`- e.g.:
+  ```js
+    function getPageId(){
+ 	 return location.pathname;
+	}
+  ```
+Other sample implementations can be found [here](#TODO).
+
+```js
+/*********************************************************************************************
+ * Ubi Event data structures
+ * The following structures help ensure adherence to the UBI event schema
+ *********************************************************************************************/
+
+export class UbiEventData {
+  constructor(type, id=null, description=null, details=null) {
+    this.object_type = type;
+    this.object_id = id;
+    this.description = description;
+    this.object_detail = details;
+
+    //override if using key_field's and values
+    this.key_value = id;
+  }
+}
+export class UbiPosition{
+  constructor({ordinal=null, x=null, y=null, trail=null}={}) {
+    this.ordinal = ordinal;
+    this.x = x;
+    this.y = y;
+    this.trail = trail;
+  }
+}
+
+
+export class UbiEventAttributes {
+  /**
+   * Attributes, other than `object` or `position` should be in the form of
+   * attributes['item1'] = 1
+   * attributes['item2'] = '2'
+   *
+   * The object member is reserved for further, relevant object payloads or classes
+   */
+  constructor({attributes={}, object=null, position=null}={}) {
+    if(attributes != null){
+      Object.assign(this, attributes);
+    }
+    if(object != null && Object.keys(object).length > 0){
+      this.object = object;
+    }
+    if(position != null && Object.keys(position).length > 0){
+      this.position = position;
+    }
+  }
+}
+
+
+
+export class UbiEvent {
+  constructor(action_name, {message=null, event_attributes={}, data_object={}}={}) {
+    this.action_name = action_name;
+    this.user_id = getUserId();
+    this.query_id = getQueryId();
+    this.session_id = getSessionId();
+    this.page_id = getPageId();
+    this.timestamp = Date.now();
+
+    this.message_type = 'INFO';
+    if( message )
+      this.message = message;
+
+    this.event_attributes = new UbiEventAttributes({attributes:event_attributes, object:data_object});
+  }
+
+  /**
+   * Use to suppress null objects in the json output
+   * @param key
+   * @param value
+   * @returns
+   */
+  static replacer(key, value){
+    if(value == null || 
+      (value.constructor == Object && Object.keys(value).length === 0)) {
+      return undefined;
+    }
+    return value;
+  }
+
+  /**
+   *
+   * @returns json string
+   */
+  toJson() {
+    return JSON.stringify(this, UbiEvent.replacer);
+  }
+}
+```
+
+# Sample Usage
+
+```js
+export async function logDwellTime(action_name, page, seconds){
+  console.log(`${page} => ${seconds}`);
+  let e = new UbiEvent(action_name, {
+    message:`On page ${page} for ${seconds} seconds`,
+    event_attributes:{dwell_seconds:seconds},
+    data_object:TimeMe
+  });
+  logEvent(e);
+}
+```