Consolidated PR for Context Data & Intents (CD&I) updates for 2.1

CHANGELOG.md

@@ -8,14 +8,27 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ### Added
 
+* Added `CreateInteraction` intent. To be used when a user wants to record an interaction into a system.  New context `Interaction` also introduced. An interaction might be a call, IM, email, a meeting (physical or virtual) or the preparation of some specialist data. ([#747](https://github.com/finos/FDC3/pull/747))
+* Added `TransactionResult` context. A context type representing the result of a transaction initiated via FDC3. Its purpose is to provide a status and message (where needed) for the transaction and MAY wrap a returned context object. ([#761] (https://github.com/finos/FDC3/pull/761))
 * Added a `MalformedContext` error to the `OpenError`, `ChannelError` and `ResolveError` enumerations, to be used when `broadcast`, `open`, `findIntents`, `raiseIntents` and other related functions are passed an invalid context Object. ([#972](https://github.com/finos/FDC3/pull/972))
 * Added error examples to the /v2 App Directory API routes ([#973](https://github.com/finos/FDC3/pull/973))
+* Added a `SendChatMessage` intent to be used when a user wants to send a message to an existing chat room. ([#794](https://github.com/finos/FDC3/pull/794))
+* Added a context type representing a chat message (`fdc3.chat.message`). ([#794](https://github.com/finos/FDC3/pull/794))
+* Added a context type representing a chat room (`fdc3.chat.room`). ([#794](https://github.com/finos/FDC3/pull/794))
+* Added a chat `Message` type in order to describe messages with rich content and attachments. ([#779](https://github.com/finos/FDC3/pull/779))
+* Added an `Action` type, encapsulating either a `Context` or the association of a `Context` with an `Intent` inside another object.  ([#779](https://github.com/finos/FDC3/pull/779))
+* Added a `ViewChat` Intent to be used when a user wants to open an existing chat room. ([#796](https://github.com/finos/FDC3/pull/796))
+* 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))
 * Added an indication that applications, that can be launched to receive intents or context via a raised intent or open with context, SHOULD add their context or intent listeners via the API within 15 seconds, and that Desktop Agents MUST allow at least a 15 second timeout for them to do so, and MAY set a longer timeout ([#987](https://github.com/finos/FDC3/pull/987))
 
 ### Changed
 
+* Updated definition of the `ChatInitSettings` context type to use the new `Message` type.  ([#779](https://github.com/finos/FDC3/pull/779))
+* Updated the `StartChat` intent to return a reference to the room. ([#794](https://github.com/finos/FDC3/pull/794))
 * Updated definition of the `Instrument` context type to include optional market identifiers ([#819](https://github.com/finos/FDC3/pull/819))
 * Corrected API functions and object types to always use `string` instead of `String` ([#924](https://github.com/finos/FDC3/pull/924))
+* Updated definition of the `otherConfig` element of the `Chart` context type from an Object to an array of Contexts as this allows the `type` of each additional item of config to be examined before it is used ([#985](https://github.com/finos/FDC3/pull/985))
 * Corrected the appD `interop.appChannels` metadata to use an `id` field to identify channels, rather than `name` ([#981](https://github.com/finos/FDC3/pull/981))
 
 ### Deprecated

docs/context/ref/Action.md

@@ -0,0 +1,75 @@
+---
+id: Action
+sidebar_label: Action
+title: Action
+hide_title: true
+---
+# `Action`
+
+A representation of an FDC3 Action (specified via a Context or Context & Intent) that can be inserted inside another object, 
+for example a chat message.
+
+The action may be completed by calling `fdc3.raiseIntent()` with the specified Intent and Context, or, if only a context is specified, by calling `fdc3.raiseIntentForContext()` (which the Desktop Agent will resolve by presenting the user with a list of available Intents for the Context).
+
+Accepts an optional `app` parameter in order to specify a certain app.
+
+## Type
+
+`fdc3.action`
+
+## Schema
+
+https://fdc3.finos.org/schemas/next/action.schema.json
+
+## Details
+
+| Property          | Type                                      | Required | Example Value           |
+|-------------------|-------------------------------------------|----------|-------------------------|
+| `type`            | string                                    | Yes      | `'fdc3.action'`         |
+| `title`           | string                                    | Yes      | `'Click to view Chart'` |
+| `intent`          | string                                    | No       | `'ViewChart'`           |
+| `context`         | string                                    | Yes      | See Below               |
+| `app`             | object                                    | No       | `'myApp'`               |
+| `app.appId`       | string                                    | Yes      | `'app1'`                |
+| `app.instanceId`  | string                                    | No       | `'instance1'`           |
+
+
+
+## Example
+
+```js
+const action = {
+    type: 'fdc3.action',
+    title: 'Click to view Chart',
+    intent: 'ViewChart',
+    context {
+        type: 'fdc3.chart',
+        instruments: [
+            {
+                type: 'fdc3.instrument',
+                id: {
+                    ticker: 'EURUSD'
+                }
+            }
+        ],
+        range: {
+            type: 'fdc3.dateRange',
+            starttime: '2020-09-01T08:00:00.000Z',
+            endtime: '2020-10-31T08:00:00.000Z'
+        },
+        style: 'candle'
+    },
+    app {
+        appId: 'MyChartViewingApp',
+        instanceId: 'instance1'
+    }
+}
+```
+
+## See Also
+
+Other Types
+* [Message](Message)
+
+Intents
+* [StartChat](../../intents/ref/StartChat)

docs/context/ref/Chart.md

@@ -31,9 +31,13 @@ In addition to handling requests to plot charts, a charting application may use
 | `instruments`    | Instrument[]  | 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.instrument",<br/>&emsp;&emsp;&emsp;&emsp;"id": {<br/>&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;"ticker": "MSFT"<br/>&emsp;&emsp;&emsp;&emsp;}<br/>&emsp;&emsp;}<br/>]</pre> |
 | `range` | TimeRange  | No       | <pre>{<br/>&emsp;&emsp;"type": "fdc3.timerange",<br/>&emsp;&emsp;"startTime": "2022-03-30T15:44:44+00:00",<br/>&emsp;&emsp;"endTime": "2022-04-30T23:59:59+00:00"<br/>}</pre>            |
 | `style`    | string  | No       | one of: `'line'`, `'bar'`, `'stacked-bar'`, `'mountain'`, `'candle'`, `'pie'`, `'scatter'`, `'histogram'`, `'heatmap'`, `'custom'`      |
-| `otherConfig`* | object  | No |  `{ /* unstandardized additional config */}`  |
+| `otherConfig`* | array  | No |  `[ {/* additional config context objects */} ]`  |
 
-\* It is common for charts to support other configuration, such as indicators, annotations etc., which do not have standardized formats, but may be included in the `otherConfig` element.
+::: info
+
+It is common for charts to support other configuration, such as indicators, annotations etc., which do not have standardized formats, but may be included in the `otherConfig` array as context objects.
+
+:::
 
 ## Example
 
@@ -60,20 +64,24 @@ const chart = {
         endTime: "2020-10-31T08:00:00.000Z"
     },
     style: "line",
-    otherConfig: {
-        indicators: [
-            {
-                name: "ma",
-                parameters: {
-                    period: 14,
-                    type: "ema"
-                }
-            },
-            {
-                name: "volume"
+    otherConfig: [
+        {
+            type: "somevendor.someproduct.indicator",
+            name: "stddev",
+            parameters: {
+                period: 10,
+                matype: "exponential"
             }
-        ]
-    }
+        },
+        {
+            type: "someothervendor.someotherproduct.formula",
+            formula: "standard-deviation",
+            fields: {
+                lookback: 10,
+                type: "ema"
+            }
+        }
+    ]
 };
 
 fdc3.raiseIntent("ViewChart", chart);

docs/context/ref/ChatInitSettings.md

@@ -22,12 +22,12 @@ A collection of settings to start a new chat conversation
 | Property                       | Type        | Required | Example Value                                                        |
 | ------------------------------ | ----------- | -------- | -------------------------------------------------------------------- |
 | `type`                         | string      | Yes      | `'fdc3.chat.initSettings'`                                           |
-| `chatName`                     | string      | No       | `'Instrument XYZ'`                                                    |
+| `chatName`                     | string      | No       | `'Instrument XYZ'`                                                   |
 | `members`                      | ContactList | No       | ContactList - cf. below                                              |
-| `initMessage`                  | string      | No       | `'Hello!'`                                                           |
+| `message`                      | Message     | No       | Message - cf. below                                                  |
 | `options.groupRecipients`      | boolean     | No       | `true`: if false a separate chat will be created for each member     |
-| `options.public`               | boolean     | No       | `true`: the room will be visible to everyone in the chat application |
-| `options.allowHistoryBrowsing` | boolean     | No       | `true`: members will be allowed to browse past messages             |
+| `options.isPublic`             | boolean     | No       | `true`: the room will be visible to everyone in the chat application |
+| `options.allowHistoryBrowsing` | boolean     | No       | `true`: members will be allowed to browse past messages              |
 | `options.allowMessageCopy`     | boolean     | No       | `true`: members will be allowed to copy/paste messages               |
 | `options.allowAddUser`         | boolean     | No       | `true`: members will be allowed to add other members to the chat     |
 
@@ -58,27 +58,46 @@ const initSettings = {
     },
     options: {
         groupRecipients: true, // one chat with both contacts
-        public: false, // private chat room
+        isPublic: false, // private chat room
         allowHistoryBrowsing: true,
         allowMessageCopy: true
     }
-    initMessage: 'Hello both!'
+    message: {
+      type: 'fdc3.message',
+      text: {
+        'text/plain': 'Hey all, can we discuss the issue together? I attached a screenshot'
+      },
+      entities: {
+         '0': {
+             type: 'fdc3.fileAttachment',
+              data: {
+              name: 'myImage.png',
+                    dataUri: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAABlBMVEX///+/v7+jQ3Y5AAAADklEQVQI12P4AIX8EAgALgAD/aNpbtEAAAAASUVORK5CYII'
+              }
+          }
+      }
+    }
 }
 
 const res = fdc3.raiseIntent('StartChat', initSettings);
-const roomRefs = await res.getResult();
+
+// Return a reference to the room
+const chatRoom = await res.getResult();
 ```
 
 ## See Also
 
 Other Types
 
+- [ChatRoom](ChatRoom)
 - [ContactList](ContactList)
+- [Message](Message)
 
 Intents
 
 - [StartChat](../../intents/ref/StartChat)
 - [StartCall](../../intents/ref/StartCall)
+- [SendChatMessage](../../intents/ref/StartChat)
 - [ViewContact](../../intents/ref/ViewContact)
 
 FINOS Financial Objects

docs/context/ref/ChatMessage.md

@@ -0,0 +1,51 @@
+---
+id: ChatMessage
+sidebar_label: ChatMessage
+title: ChatMessage
+hide_title: true
+---
+# `ChatMessage`
+
+A context representing a chat message. Typically used to send the message or to pre-populate a message for sending.
+
+## Type
+
+`fdc3.chat.message`
+
+## Schema
+
+- https://fdc3.finos.org/schemas/next/chatMessage.schema.json
+
+## Details
+
+| Property    | Type    | Required | Example Value     |
+|-------------|---------|----------|-------------------|
+| `type`      | string  | Yes      | `'fdc3.chat.message'`  |
+| `chatRoom`      | ChatRoom  | Yes       | `{ type: 'fdc3.chat.room', providerName: 'Symphony', id:{ streamId: 'j75xqXy25NBOdacUI3FNBH'} }`      |
+| `message`  | [Message](https://fdc3.finos.org/schemas/next/message.schema.json)  | Yes       | `'A message to send'` |
+
+## Example
+
+```js
+const chatMessage = {
+    type: "fdc3.chat.message",
+    chatRoom: {
+        type: 'fdc3.chat.room',
+        providerName: "Symphony",
+        id: {
+            streamId: "j75xqXy25NBOdacUI3FNBH"
+        }
+    },
+    message: "A message to send"
+}
+```
+
+## See Also
+
+Intents
+- [StartChat](../../intents/ref/StartChat)
+- [StartCall](../../intents/ref/StartCall)
+- [SendChatMessage](../../intents/ref/SendChatMessage)
+
+FINOS Financial Objects
+- [Contact](https://fo.finos.org/docs/objects/contact)

docs/context/ref/ChatRoom.md

@@ -0,0 +1,64 @@
+---
+id: ChatRoom
+sidebar_label: ChatRoom
+title: Contact
+hide_title: true
+---
+# `ChatRoom`
+
+Reference to the chat room(s) (which could be used later to send a message to the room(s)).
+
+## Type
+
+`fdc3.chat.room`
+
+## Schema
+
+https://fdc3.finos.org/schemas/next/chatRoom.schema.json
+
+## Details
+
+| Property    | Type    | Required | Example Value     |
+|-------------|---------|----------|-------------------|
+| `type`      | string  | Yes      | `'fdc3.chat.room'`  |
+| `providerName`      | string  | Yes       | `'Symphony'`      |
+| `id`  | object  | Yes       | `{ streamId: 'j75xqXy25NBOdacUI3FNBH', anyOtherKey: 'abcdef'}` |
+| `url` | string  | No       | `'http://symphony.com/ref/room/j75xqXy25NBOdacUI3FNBH___pqSsuJRdA'`      |
+| `name` | string  | No       | `'My new room'`      |
+
+The `url` is a universal url to access to the room. It could be opened from a browser, a mobile app, etc...
+
+## Example
+
+```js
+const chatRoom = {
+  type: "fdc3.chat.room",
+  providerName: "Symphony",
+  id: {
+      streamId: "j75xqXy25NBOdacUI3FNBH"
+  }
+  url: "http://symphony.com/ref/room/j75xqXy25NBOdacUI3FNBH___pqSsuJRdA",
+  name: 'My new room'
+};
+
+//Chat rooms are returned by the StartChat intent as a result
+const intentResolution = await fdc3.raiseIntent("StartChat", context);
+
+try {
+    const chatRooms = await intentResolution.getResult():
+} catch (error) {
+   //chat room were not created...
+}
+```
+
+## See Also
+
+Other Types
+* [ChatInitSettings](ChatInitSettings)
+
+Intents
+- [StartChat](../../intents/ref/StartChat)
+- [SendChatMessage](../../intents/ref/SendChatMessage)
+
+FINOS Financial Objects
+- [Contact](https://fo.finos.org/docs/objects/contact)

docs/context/ref/Contact.md

@@ -48,6 +48,7 @@ Other Types
 
 Intents
 
+- [CreateInteraction](../../intents/ref/CreateInteraction)
 - [StartChat](../../intents/ref/StartChat)
 - [StartCall](../../intents/ref/StartCall)
 - [ViewProfile](../../intents/ref/ViewProfile)

docs/context/ref/ContactList.md

@@ -64,6 +64,7 @@ Other Types
 
 Intents
 
+- [CreateInteraction](../../intents/ref/CreateInteraction)
 - [StartChat](../../intents/ref/StartChat)
 - [StartCall](../../intents/ref/StartCall)