Skip to content

Commit 7ff1c18

Browse files
mistryvinaymistryvinay
committed
Merge branch '590-intent-proposal-start-email' of https://github.com/singletracksystems/FDC3 into singletracksystems-590-intent-proposal-start-email
2 parents 9223b88 + aabd80e commit 7ff1c18

14 files changed

Lines changed: 279 additions & 4 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
3535
* Added a context type for `ViewInteractions`. Used when a user wants to see the latest interactions (calls, meetings, conferences, roadshows) on a particular stock or with an individual or organization. ([#625](https://github.com/finos/FDC3/pull/625))
3636
* Added guide on how to submit a new Intent. ([#624](https://github.com/finos/FDC3/pull/624))
3737
* Added `ViewOrders`. Used when a user wants to see the order history of an individual, an institution or of a particular stock. ([#672](https://github.com/finos/FDC3/pull/672))
38+
* Added `StartEmail`. Initiate an email with a contact or list of contacts provided as part of an Email context. ([#632](https://github.com/finos/FDC3/pull/632))
3839

3940
### Changed
4041
* Consolidated `Listener` documentation with other types ([#404](https://github.com/finos/FDC3/pull/404))

‎docs/context/ref/Email.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
---
2+
id: Email
3+
sidebar_label: Email
4+
title: Email
5+
hide_title: true
6+
---
7+
# `Email`
8+
9+
A collection of information to be used to initiate an email with a Contact or ContactList
10+
11+
## Type
12+
13+
`fdc3.email`
14+
15+
## Schema
16+
17+
https://fdc3.finos.org/schemas/next/email.schema.json
18+
19+
## Details
20+
21+
| Property | Type | Required | Example Value |
22+
|-------------------|---------------------------------------|----------|---------------------|
23+
| `type` | string | Yes | `'fdc3.email'` |
24+
| `recipients` | fdc3.contact or fdc3.contactList | Yes | { type: "fdc3.contact", name: "John Doe", id: { "email": "john@sample.com"}} |
25+
| `subject` | string | No | `'The information you requested'` |
26+
| `textBody` | string | No | `'Blah, blah, bah` |
27+
28+
## Example
29+
30+
```js
31+
const email = {
32+
type: 'fdc3.email',
33+
recipients: {
34+
type: 'fdc3.contact',
35+
name: 'Jane Doe',
36+
id: {
37+
email: 'jane.doe@example.com'
38+
}
39+
},
40+
subject: 'The information you requested',
41+
textBody: 'Blah, blah, blah ...'
42+
}
43+
44+
45+
fdc3.raiseIntent("StartEmail", email)
46+
```
47+
48+
## See Also
49+
50+
Other Types
51+
* [Contact](Contact)
52+
* [ContactList](ContactList)
53+
54+
Intents
55+
* [StartEmail](../../intents/ref/StartEmail)

‎docs/context/spec.md‎

Lines changed: 98 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -135,6 +135,96 @@ E.g. `"CURRENCY_ISOCODE": "GBP"`
135135

136136
> Note: ISO 4217 only includes major currency codes, conversions to minor currencies is the responsibility of the consuming system (where required).
137137
138+
## Standard Context Types
139+
140+
The following are standard FDC3 context types.
141+
__Note:__ The specification for these types are shared with the [FINOS Financial Objects](https://fo.finos.org) definitions, JSON schemas are hosted with FDC3.
142+
143+
- __fdc3.contact__
144+
- A person contact that can be engaged with through email, calling, messaging, CMS, etc.
145+
- [Financial Objects Specification](https://fo.finos.org/docs/objects/contact)
146+
- [schema](/schemas/next/contact.schema.json)
147+
- __fd3.contactList__
148+
- A collection of contacts.
149+
- [Financial Objects Specification](https://fo.finos.org/docs/objects/contactlist)
150+
- [schema](/schemas/next/contactList.schema.json)
151+
- __fdc3.email__
152+
- A collection of information to be used to initiate an email with a Contact or ContactList
153+
- [schema](/schemas/next/email.schema.json)
154+
- __fdc3.country__
155+
- A standard country entity.
156+
- [Financial Objects Specification](https://fo.finos.org/docs/objects/country)
157+
- [schema](/schemas/next/country.schema.json)
158+
- __fdc3.instrument__
159+
- A financial instrument from any asset class.
160+
- [Financial Objects Specification](https://fo.finos.org/docs/objects/instrument)
161+
- [schema](/schemas/next/instrument.schema.json)
162+
- __fdc3.instrumentList__
163+
- A collection of instruments.
164+
- [Financial Objects Specification](https://fo.finos.org/docs/objects/instrumentlist)
165+
- [schema](/schemas/next/instrumentList.schema.json)
166+
- __fdd3.organization__
167+
- A standard organization entity.
168+
- [Financial Objects Specification](https://fo.finos.org/docs/objects/organization)
169+
- [schema](/schemas/next/organization.schema.json)
170+
- __fdc3.portfolio__
171+
- A collection of positions.
172+
- [Financial Objects Specification](https://fo.finos.org/docs/objects/portfolio)
173+
- [schema](/schemas/next/portfolio.schema.json)
174+
- __fdc3.position__
175+
- An amount of a security, asset, or property that is owned (or sold short) by some individual or other entity
176+
- [Financial Objects Specification](https://fo.finos.org/docs/objects/position)
177+
- [schema](/schemas/next/position.schema.json)
178+
- __fdc3.nothing
179+
- Explicit representation of a lack of context
180+
- [schema](/schemas/next/nothing.schema.json)
181+
182+
__Note:__ The below examples show how the base context data interface can be used to define specific context data objects. It is not the purpose of the specification at this stage to define standard representations for objects. It establishes the framework in which such definitions could be created.
183+
184+
### Examples
185+
186+
#### Contact
187+
```json
188+
{
189+
"type": "fdc3.contact",
190+
"name": "John Smith",
191+
"id":{
192+
"email": "john.smith@company.com",
193+
}
194+
}
195+
```
196+
197+
#### Email
198+
```json
199+
{
200+
"type": "fdc3.email",
201+
"recipients": {
202+
"type": "fdc3.contact",
203+
"name": "Jane Doe",
204+
"id": {
205+
"email": "jane.doe@example.com"
206+
}
207+
},
208+
"subject": "The information you requested",
209+
"textBody": "Blah, blah, blah ..."
210+
}
211+
```
212+
213+
#### Instrument
214+
```json
215+
{
216+
"type" : "fdc3.instrument",
217+
"name" : "Apple",
218+
"id" :
219+
{
220+
"ticker" : "aapl",
221+
"ISIN" : "US0378331005",
222+
"CUSIP" : "037833100",
223+
"FIGI" : "BBG000B9XRY4",
224+
}
225+
}
226+
```
227+
138228
## Example Context Object
139229

140230
An instrument could for example be derived as (note that the name is required and the type is fixed):
@@ -167,4 +257,11 @@ e.g. as a JSON payload:
167257
}
168258
```
169259

170-
It is important to note that the context data specification allows extra identifiers and properties to be added as needed for each interop use case. In the example above, `country` could represent extra data in addition to the agreed instrument representation.
260+
It is important to note that the context data specification allows extra identifiers and properties to be added as needed for each interop use case. In the example above, `country` could represent extra data in addition to the agreed instrument representation.
261+
262+
263+
264+
265+
266+
267+

‎docs/intents/ref/StartCall.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,4 +42,5 @@ Context
4242
- [ContactList](../../context/ref/ContactList)
4343

4444
Intents
45-
- [StartChat](StartChat)
45+
* [StartChat](StartChat)
46+
* [StartEmail](StartEmail)

‎docs/intents/ref/StartChat.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -71,4 +71,5 @@ Context
7171
- [ChatInitSettings](../../context/ref/ChatInitSettings)
7272

7373
Intents
74-
- [StartCall](StartCall)
74+
* [StartCall](StartCall)
75+
* [StartEmail](StartEmail)

‎docs/intents/ref/StartEmail.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
id: StartEmail
3+
sidebar_label: StartEmail
4+
title: StartEmail
5+
hide_title: true
6+
---
7+
# `StartEmail`
8+
9+
Initiate an email with a contact or list of contacts provided as part of an Email context.
10+
11+
## Intent Name
12+
13+
`StartEmail`
14+
15+
## Display Name
16+
17+
`Start Email`
18+
19+
## Possible Contexts
20+
21+
* [Email](../../context/ref/Email)
22+
23+
## Example
24+
25+
```js
26+
window.fdc3.raiseIntent('fdc3.StartEmail', {
27+
type: 'fdc3.email',
28+
recipients: {
29+
type: 'fdc3.contact',
30+
name: 'Jane Doe',
31+
id: {
32+
email: 'jane.doe@example.com'
33+
}
34+
},
35+
subject: 'The information you requested',
36+
textBody: 'Blah, blah, blah ...'
37+
})
38+
```
39+
40+
## See Also
41+
42+
Context
43+
* [Email](../../context/ref/Email)
44+
45+
Intents
46+
* [StartCall](StartCall)
47+
* [StartChat](StartChat)

‎docs/intents/spec.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -130,6 +130,7 @@ A list of standardized intents are defined in the following pages:
130130

131131
* [`StartCall`](ref/StartCall)
132132
* [`StartChat`](ref/StartChat)
133+
* [`StartEmail`](ref/StartEmail)
133134
* [`ViewChart`](ref/ViewChart)
134135
* [`ViewQuote`](ref/ViewQuote)
135136
* [`ViewNews`](ref/ViewNews)

‎src/context/ContextType.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,14 +4,15 @@ export enum ContextTypes {
44
ContactList = 'fdc3.contactList',
55
Country = 'fdc3.country',
66
Currency = 'fdc3.currency',
7+
Email = 'fdc3.email',
78
Instrument = 'fdc3.instrument',
89
InstrumentList = 'fdc3.instrumentList',
910
Organization = 'fdc3.organization',
1011
Portfolio = 'fdc3.portfolio',
1112
Position = 'fdc3.position',
1213
Nothing = 'fdc3.nothing',
1314
TimeRange = 'fdc3.timerange',
14-
Valuation = 'fdc3.valuation',
15+
Valuation = 'fdc3.valuation'
1516
}
1617

1718
export type ContextType = ContextTypes | string;

‎src/context/ContextTypes.ts‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,14 @@ export interface ContactID {
4040
FDS_ID?: string;
4141
}
4242

43+
export interface Email {
44+
type: string;
45+
recipients: object;
46+
subject?: string;
47+
textBody?: string;
48+
richTextBody?: object;
49+
}
50+
4351
export interface InstrumentList {
4452
instruments: Instrument[];
4553
type: string;
@@ -134,6 +142,14 @@ export class Convert {
134142
return JSON.stringify(uncast(value, r('ContactList')), null, 2);
135143
}
136144

145+
public static toEmail(json: string): Email {
146+
return cast(JSON.parse(json), r('Email'));
147+
}
148+
149+
public static emailToJson(value: Email): string {
150+
return JSON.stringify(uncast(value, r('Email')), null, 2);
151+
}
152+
137153
public static toInstrument(json: string): Instrument {
138154
return cast(JSON.parse(json), r('Instrument'));
139155
}
@@ -359,6 +375,16 @@ const typeMap: any = {
359375
],
360376
''
361377
),
378+
Email: o(
379+
[
380+
{ json: 'type', js: 'type', typ: '' },
381+
{ json: 'recipients', js: 'recipients', typ: u(undefined, '') },
382+
{ json: 'subject', js: 'subject', typ: u(undefined, '') },
383+
{ json: 'textBody', js: 'textBody', typ: u(undefined, '') },
384+
{ json: 'richTextBody', js: 'richTextBody', typ: u(undefined, '') },
385+
],
386+
'any'
387+
),
362388
InstrumentList: o(
363389
[
364390
{ json: 'instruments', js: 'instruments', typ: a(r('Instrument')) },

‎src/context/schemas/email.schema.json‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
{
2+
"$schema": "http://json-schema.org/draft-07/schema#",
3+
"$id": "https://fdc3.finos.org/schemas/next/email.schema.json",
4+
"type": "object",
5+
"title": "Email",
6+
"allOf": [{ "$ref": "context.schema.json#" }],
7+
"properties": {
8+
"type": { "const": "fdc3.email" },
9+
"recipients": {
10+
"oneOf": [
11+
{ "$ref": "contact.schema.json#" },
12+
{ "$ref": "contactList.schema.json#" }
13+
]
14+
},
15+
"subject": { "type": "string" },
16+
"textBody": { "type": "string" }
17+
},
18+
"required": ["recipients"]
19+
}

0 commit comments

Comments
 (0)
⚡