768 Add ViewMessages Intent & SearchCriteria Context

CHANGELOG.md

@@ -8,6 +8,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ### Added
 
+* Added a `ViewMessages` intent to be used when a user wants to search and see a list of messages. ([#797](https://github.com/finos/FDC3/pull/797))
+* Added a context type representing a ChatSearchCriteria (`fdc3.chat.searchCriteria`). ([#797](https://github.com/finos/FDC3/pull/797))
+
 ### Changed
 
 ### Deprecated

docs/context/ref/SearchCriteria.md

@@ -0,0 +1,64 @@
+---
+id: ChatSearchCriteria
+sidebar_label: ChatSearchCriteria
+title: ChatSearchCriteria
+hide_title: true
+---
+# `ChatSearchCriteria`
+
+A context type that represents a simple search criterion, based on a list of other context objects, that can be used to search or filter messages in a chat application.
+
+## Type
+
+`fdc3.chat.searchCriteria`
+
+## Schema
+
+https://fdc3.finos.org/schemas/next/chatSearchCriteria.schema.json
+
+## Details
+
+| Property         | Type            | Required | Example Value        |
+|------------------|-----------------|----------|----------------------|
+| `type`           | string          | Yes      | `'fdc3.chat.searchCriteria'`     |
+| `criteria` | (Instrument &#124;<br>Contact &#124;<br>Organization &#124;<br>string)[] | Yes | <pre>[<br>&emsp;&emsp;{<br>&emsp;&emsp;&emsp;&emsp;"type": "fdc3.instrument",<br>&emsp;&emsp;&emsp;&emsp;"id": {<br>&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;"ticker": "AAPL"<br>&emsp;&emsp;&emsp;&emsp;}<br>&emsp;&emsp;},<br>&emsp;&emsp;{<br>&emsp;&emsp;&emsp;&emsp;"type": "fdc3.contact",<br>&emsp;&emsp;&emsp;&emsp;"name":"Jane Doe",<br>&emsp;&emsp;&emsp;&emsp;"id": {<br>&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;"email": "jane.doe@mail.com"<br>&emsp;&emsp;&emsp;&emsp;}<br>&emsp;&emsp;},<br>&emsp;&emsp;{<br>&emsp;&emsp;&emsp;&emsp;"type": "fdc3.organization",<br>&emsp;&emsp;&emsp;&emsp;"name":"Symphony",<br>&emsp;&emsp;},<br>&emsp;&emsp;"#OrderID45788422",<br>]</pre> |
+
+⚠️ Operators (and/or/not) are not defined in `fdc3.chat.searchCriteria`. It is up to the application that processes the FDC3 Intent to choose and apply the operators between the criteria.
+
+Empty search criteria can be supported to allow resetting of filters.
+
+## Example
+
+```js
+const searchCriteria = {
+    type: "fdc3.chat.searchCriteria",
+    criteria: [
+        {
+            type: "fdc3.instrument",
+            id: {
+                ticker: "AAPL"
+            }
+        },
+        {
+            type: "fdc3.contact",
+            name: "Jane Doe",
+            id: {
+                email: "jane.doe@mail.com"
+            }
+        },
+        {
+            type: "fdc3.organization",
+            name: "Symphony"
+        },
+        "#OrderID45788422"
+    ]
+}
+
+fdc3.raiseIntent('ViewMessages', searchCriteria);
+```
+
+## See Also
+
+Intents
+
+* [ViewMessages](../../intents/ref/ViewMessages)

docs/context/spec.md

@@ -159,6 +159,7 @@ The following are standard FDC3 context types:
 
 * [`fdc3.chart`](ref/Chart) ([schema](/schemas/next/chart.schema.json))
 * [`fdc3.chat.initSettings`](ref/ChatInitSettings) ([schema](/schemas/next/chatInitSettings.schema.json))
+* [`fdc3.chat.searchCriteria`](ref/ChatSearchCriteria) ([schema](/schemas/next/chatSearchCriteria.schema.json))
 * [`fdc3.contact`](ref/Contact) ([schema](/schemas/next/contact.schema.json))
 * [`fdc3.contactList`](ref/ContactList) ([schema](/schemas/next/contactList.schema.json))
 * [`fdc3.country`](ref/Country) ([schema](/schemas/next/country.schema.json))

docs/intents/ref/ViewMessages.md

@@ -0,0 +1,124 @@
+---
+id: ViewMessages
+sidebar_label: ViewMessages
+title: ViewMessages
+hide_title: true
+---
+# `ViewMessages`
+
+Search and display a list of messages (for example in a chat application or CRM) to the user. 
+
+## Intent Name
+
+`ViewMessages`
+
+## Display Name
+
+`View Messages`
+
+## Possible Contexts
+
+* [ChatSearchCriteria](../../context/ref/ChatSearchCriteria)
+
+## Example
+
+Request display of messages relating to a specific `fdc3.instrument` (representing a ticker):
+```js
+const searchCriteria = {
+    type: "fdc3.chat.searchCriteria",
+    criteria: [
+        {
+            type: "fdc3.instrument",
+            id: {
+                ticker: "AAPL"
+            }
+        }
+    ]
+}
+
+fdc3.raiseIntent('ViewMessages', searchCriteria);
+```
+
+Request display of messages relating to a specific `fdc3.contact`:
+
+```js
+const searchCriteria = {
+    type: "fdc3.chat.searchCriteria",
+    criteria: [
+        {
+            type: "fdc3.contact",
+            name: "Jane Doe",
+            id: {
+                email: "jane.doe@mail.com"
+            }
+        }
+    ]
+}
+
+fdc3.raiseIntent('ViewMessages', searchCriteria);
+```
+
+Request display of messages relating to a specific `fdc3.organization`:
+
+```js
+const searchCriteria = {
+    type: "fdc3.chat.searchCriteria",
+    criteria: [
+        {
+            type: "fdc3.organization",
+            name: "Symphony"
+        }
+    ]
+}
+
+fdc3.raiseIntent('ViewMessages', searchCriteria);
+```
+
+Request display of messages relating to a specific **phrase**:
+
+```js
+const searchCriteria = {
+    type: "fdc3.chat.searchCriteria",
+    criteria: [
+        "#OrderID45788422"
+    ]
+}
+
+fdc3.raiseIntent('ViewMessages', searchCriteria);
+```
+
+Request display of messages matching _multiple_ criteria:
+```js
+const searchCriteria = {
+    type: "fdc3.chat.searchCriteria",
+    criteria: [
+        {
+            type: "fdc3.contact",
+            name: "Jane Doe",
+            id: {
+                email: "jane.doe@mail.com"
+            }
+        },
+        {
+            type: "fdc3.organization",
+            name: "Symphony"
+        },
+        "#OrderID45788422"
+    ]
+}
+
+fdc3.raiseIntent('ViewMessages', searchCriteria);
+```
+
+## See Also
+
+Context
+
+* [ChatSearchCriteria](../../context/ref/ChatSearchCriteria)
+* [Instrument](../../context/ref/Instrument)
+* [Contact](../../context/ref/Contact)
+* [Organization](../../context/ref/Organization)
+
+Intents
+
+* [ViewChat](ViewChat)

docs/intents/spec.md

@@ -156,6 +156,7 @@ A list of standardized intents are defined in the following pages:
 * [`ViewHoldings`](ref/ViewHoldings)
 * [`ViewInstrument`](ref/ViewInstrument)
 * [`ViewInteractions`](ref/ViewInteractions)
+* [`ViewMessages`](ref/ViewMessages)
 * [`ViewNews`](ref/ViewNews)
 * [`ViewOrders`](ref/ViewOrders)
 * [`ViewProfile`](ref/ViewProfile)

src/context/ContextType.ts

@@ -8,10 +8,11 @@ export enum ContextTypes {
   Email = 'fdc3.email',
   Instrument = 'fdc3.instrument',
   InstrumentList = 'fdc3.instrumentList',
+  Nothing = 'fdc3.nothing',
   Organization = 'fdc3.organization',
   Portfolio = 'fdc3.portfolio',
   Position = 'fdc3.position',
-  Nothing = 'fdc3.nothing',
+  ChatSearchCriteria = 'fdc3.chat.searchCriteria',
   TimeRange = 'fdc3.timerange',
   Valuation = 'fdc3.valuation',
 }

src/context/ContextTypes.ts

@@ -187,6 +187,11 @@ export interface Position {
   name?: string;
 }
 
+export interface ChatSearchCriteria {
+  criteria: (Instrument | Organization | Contact | string)[];
+  type: string;
+}
+
 export interface Valuation {
   CURRENCY_ISCODE?: string;
   expiryTime?: Date;

src/context/schemas.json

@@ -13,6 +13,7 @@
   "Organization": ["https://fdc3.finos.org/schemas/next/organization.schema.json"],
   "Portfolio": ["https://fdc3.finos.org/schemas/next/portfolio.schema.json"],
   "Position": ["https://fdc3.finos.org/schemas/next/position.schema.json"],
+  "ChatSearchCriteria": ["https://fdc3.finos.org/schemas/next/chatSearchCriteria.schema.json"],
   "TimeRange": ["https://fdc3.finos.org/schemas/next/timerange.schema.json"],
   "Valuation": ["https://fdc3.finos.org/schemas/next/valuation.schema.json"]
 }

src/context/schemas/chatSearchCriteria.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://fdc3.finos.org/schemas/next/chatSearchCriteria.schema.json",
+  "type": "object",
+  "title": "ChatSearchCriteria",
+  "allOf": [{ "$ref": "context.schema.json#" }],
+  "properties": {
+    "type": { "const": "fdc3.chat.searchCriteria" },
+    "criteria": {
+      "type": "array",
+      "items": { 
+        "anyOf": [
+          { "$ref":"instrument.schema.json#" },
+          { "$ref": "organization.schema.json#" },
+          { "$ref": "contact.schema.json#" },
+          { "type": "string" }
+        ]
+      }
+    }
+  },
+  "required": ["criteria"]
+}

src/intents/Intents.ts

@@ -8,6 +8,7 @@ export enum Intents {
   ViewHoldings = 'ViewHoldings',
   ViewInstrument = 'ViewInstrument',
   ViewInteractions = 'ViewInteractions',
+  ViewMessages = 'ViewMessages',
   ViewNews = 'ViewNews',
   ViewOrders = 'ViewOrders',
   ViewProfile = 'ViewProfile',

website/sidebars.json

@@ -46,6 +46,7 @@
           "intents/ref/ViewHoldings",
           "intents/ref/ViewInstrument",
           "intents/ref/ViewInteractions",
+          "intents/ref/ViewMessages",
           "intents/ref/ViewNews",
           "intents/ref/ViewOrders",
           "intents/ref/ViewProfile",
@@ -73,6 +74,7 @@
           "context/ref/Organization",
           "context/ref/Portfolio",
           "context/ref/Position",
+          "context/ref/ChatSearchCriteria",
           "context/ref/TimeRange",
           "context/ref/Valuation"
         ]

website/static/schemas/next/chatSearchCriteria.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://fdc3.finos.org/schemas/next/chatSearchCriteria.schema.json",
+  "type": "object",
+  "title": "ChatSearchCriteria",
+  "allOf": [{ "$ref": "context.schema.json#" }],
+  "properties": {
+    "type": { "const": "fdc3.chat.searchCriteria" },
+    "criteria": {
+      "type": "array",
+      "items": { 
+        "anyOf": [
+          { "$ref":"instrument.schema.json#" },
+          { "$ref": "organization.schema.json#" },
+          { "$ref": "contact.schema.json#" },
+          { "type": "string" }
+        ]
+      }
+    }
+  },
+  "required": ["criteria"]
+}