# FDC3 Intents

Canonical page: https://www.adaptabletools.com/docs/handbook-fdc3-intents

- This AdapTable Help Page is being actively updated
- AdapTable has just upgraded to FDC3 2.0 and we are working on updating the documentation

- AdapTable fully supports FDC3 Intents; users can:
  - Raise Intents
  - Listen for Intents
  - Create Custom Intents

Intents are FDC3 **actions** that a user wants to perform or react to.  

AdapTable supports Intents through the `intents` property in FDC3 Options.

This object is of type [`Fdc3IntentOptions`](https://www.adaptabletools.com/docs/reference/fdc3intentoptions.md) which contains these properties:

| Property | Type | Description |
| --- | --- | --- |
| [handleIntent](https://www.adaptabletools.com/docs/reference/fdc3intentoptions.md#handleintent) | `(context: `[`HandleFdc3IntentContext`](https://www.adaptabletools.com/docs/reference/handlefdc3intentcontext.md)`) => Promise<IntentResult> \| void` | Handles incoming Intents (standard and custom) |
| [handleIntentResolution](https://www.adaptabletools.com/docs/reference/fdc3intentoptions.md#handleintentresolution) | `(context: `[`HandleFdc3IntentResolutionContext`](https://www.adaptabletools.com/docs/reference/handlefdc3intentresolutioncontext.md)`) => Promise<void>` | Handles the IntentResolution that a raised Intent might return |
| [listensFor](https://www.adaptabletools.com/docs/reference/fdc3intentoptions.md#listensfor) | `Intent[]` | Subscribe to given standard Intent(s) |
| [raises](https://www.adaptabletools.com/docs/reference/fdc3intentoptions.md#raises) | [`RaiseIntentConfiguration`](https://www.adaptabletools.com/docs/reference/raiseintentconfiguration.md) | Raises given standard Intent(s) on various Grid Actions |

As can be seen, users are able both to **Raise** and **Listen For** FDC3 Intents.

## Available Intents

The FDC3 Intents supported by AdapTable (and the Contexts they can be used in) are as follows:

| FDC3 Intent                                                                  | Available Contexts                                           |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------ |
| [StartCall](https://fdc3.finos.org/docs/intents/ref/StartCall)               | Contact, ContactList                                         |
| [StartChat](https://fdc3.finos.org/docs/intents/ref/StartChat)               | Contact, ContactList, ChatInitSettings                       |
| [StartEmail](https://fdc3.finos.org/docs/intents/ref/StartEmail)             | Email                                                        |
| [ViewAnalysis](https://fdc3.finos.org/docs/intents/ref/ViewAnalysis)         | Instrument, Organization, Portfolio                          |
| [ViewChart](https://fdc3.finos.org/docs/intents/ref/ViewChart)               | Chart, Instrument, Organization, Portfolio, Position         |
| [ViewContact](https://fdc3.finos.org/docs/intents/ref/ViewContact)           | Contact                                                      |
| [ViewHoldings](https://fdc3.finos.org/docs/intents/ref/ViewHoldings)         | Instrument, InstrumentList, Organization                     |
| [ViewInstrument](https://fdc3.finos.org/docs/intents/ref/ViewInstrument)     | Instrument                                                   |
| [ViewInteractions](https://fdc3.finos.org/docs/intents/ref/ViewInteractions) | Contact, InstrumentList, Organization                        |
| [ViewNews](https://fdc3.finos.org/docs/intents/ref/ViewNews)                 | Country, Instrument, InstrumentList, Organization, Portfolio |
| [ViewOrders](https://fdc3.finos.org/docs/intents/ref/ViewOrders)             | Contact, InstrumentList, Organization                        |
| [ViewProfile](https://fdc3.finos.org/docs/intents/ref/ViewProfile)           | Contact, Organization                                        |
| [ViewQuote](https://fdc3.finos.org/docs/intents/ref/ViewQuote)               | Instrument                                                   |
| [ViewResearch](https://fdc3.finos.org/docs/intents/ref/ViewResearch)         | Contact, InstrumentList, Organization                        |

## Raising Intents

Intents are raised using the `raises` property in the `intents` section of FDC3 Options.

Each Intent to raise is listed by type (e.g. `ViewQuote`) and followed by the Intent-raising behaviour.

- Make sure **all intents** you raise are referenced in the `gridDataContextMapping` property of FDC3 Options
- This is a required step which AdapTable uses to [map columns and fields to FDC3 objects](https://www.adaptabletools.com/docs/handbook-fdc3-mappings/index.md)

This behaviour can take one of 2 forms:

- a [Context Menu](https://www.adaptabletools.com/docs/ui-context-menu/index.md) entry
- an [FDC3 Action Column](https://www.adaptabletools.com/docs/handbook-fdc3-ui-components/index.md) (either a button or full Column definition can be provided)

It is possible to raise an Intent using **both** [Context Menu](https://www.adaptabletools.com/docs/ui-context-menu/index.md) and [FDC3 Action Column](https://www.adaptabletools.com/docs/handbook-fdc3-ui-components/index.md)

### `raises`

Raises given standard Intent(s) on various Grid Actions

  [`RaiseIntentConfiguration`](https://www.adaptabletools.com/docs/reference/raiseintentconfiguration.md)

Property which defines which FDC3 Intents can be raised.

It provides an object of type [`RaiseIntentConfiguration`](https://www.adaptabletools.com/docs/reference/raiseintentconfiguration.md).

It is essentially a collection of [`RaiseIntentConfig`](https://www.adaptabletools.com/docs/reference/raiseintentconfig.md) each of which is defined as follows:

| Property | Type | Description |
| --- | --- | --- |
| [actionButton](https://www.adaptabletools.com/docs/reference/raiseintentconfig.md#actionbutton) | [`Fdc3AdaptableButton`](https://www.adaptabletools.com/docs/reference/fdc3adaptablebutton.md) | Definition of Action Button (to be put in default FDC3 Action Column) |
| [actionColumn](https://www.adaptabletools.com/docs/reference/raiseintentconfig.md#actioncolumn) | `\{ columnId: string; friendlyName?: string; button: `[`Fdc3AdaptableButton`](https://www.adaptabletools.com/docs/reference/fdc3adaptablebutton.md)`; width?: number; \}` | Custom FDC3 Action Column definition for the Intent |
| [contextMenu](https://www.adaptabletools.com/docs/reference/raiseintentconfig.md#contextmenu) | `\{ columnIds: string[]; icon?: '_defaultFdc3' \| `[`AdaptableIcon`](https://www.adaptabletools.com/docs/reference/adaptableicon.md)`; \}` | Columns to display a &#39;Raise Intent&#39; Context Menu item |
| [contextType](https://www.adaptabletools.com/docs/reference/raiseintentconfig.md#contexttype) | `ContextType` | Key of Context being Raised |
| [handleIntentResolution](https://www.adaptabletools.com/docs/reference/raiseintentconfig.md#handleintentresolution) | `(context: `[`HandleFdc3IntentResolutionContext`](https://www.adaptabletools.com/docs/reference/handlefdc3intentresolutioncontext.md)`) => Promise<void>` | Handles the IntentResolution for this specific raise intent configuration |

Each Intent Config has a Key which is the Intent being raised (e.g. `ViewQuote`, `StartCall`).

It includes 2 main elements:

- **context type** - the `contextType` property specifies which context to use (e.g. fdc3.instrument)

- This context should be referenced in the `gridDataContextMapping` property of FDC3 Options
- See [Mapping columns and fields to FDC3 objects](https://www.adaptabletools.com/docs/handbook-fdc3-mappings/index.md) for more information

- **behaviour** - how to Raise the Intent (i.e. via the [Context Menu](https://www.adaptabletools.com/docs/ui-context-menu/index.md) or using an [Action Column / Button](https://www.adaptabletools.com/docs/handbook-action-column/index.md))

See [FDC3 Action Columns and Buttons](https://www.adaptabletools.com/docs/handbook-fdc3-ui-components/index.md) for full details on how these Buttons and Action Columns are rendered

```tsx {2,3,4,20}
fdc3Options: {
  intents: {
    raises: {
      ViewQuote: [
        {
          contextType: 'fdc3.instrument',
          contextMenu: {
            columnIds: ['ticker'],
          },
          actionButton: {
            id: 'ViewQuoteButton',
            label: 'View Quote',
            icon: {
              name: 'info',
            },
            tooltip: '_defaultFdc3',
          },
        },
      ],
      ViewInstrument: [
        {
          contextType: 'fdc3.instrument',
          contextMenu: {
            columnIds: ['instrument', 'ticker'],
          },
          actionColumn: {
            columnId: 'fdc3ViewInstrumentColumn',
            friendlyName: 'FDC3: ViewInstrument',
            button: {
              id: 'ViewInstrumentButton',
              label: '_defaultFdc3',
              tooltip: '_defaultFdc3',
            },
          },
        },
      ],
    },
  },
},
```

## Listening for Intents
Listening for Intents from external applications is done in 2 stages:

Both of these steps uses a property in the `intents` section of FDC3 Options

- all Intents to handle are listed in the `listensFor` property
- an implementation is given for the `handleIntent` function property
### `listensFor`

Subscribe to given standard Intent(s)

  [`FDC3 intent type`](https://www.adaptabletools.com/docs/reference/fdc3intentoptions.md#listensfor)

Lists which FDC3 Intents are listened for.
The array is a list of FDC3 intent names (e.g. `ViewInstrument`, `StartCall`) — see [`listensFor`](https://www.adaptabletools.com/docs/reference/fdc3intentoptions.md#listensfor)
```tsx {2,3}
contexts: {
  listensFor: ['ViewQuote', 'ViewInstrument', 'StartCall'],
  handleIntent: (fdc3IntentContext: HandleFdc3IntentContext) => {
    console.log(`Received context: `, fdc3IntentContext);
  },
},
``` 
These Intents are then typically handled in the `handleIntent` function property (see below).

   
## Handling Intents
Incoming FDC3 Intents is handled by the `handleIntent` property.
### `handleIntent`

 Handles incoming Intents (standard and custom)

Property used to handle incoming FDC3 Intents.

Make sure that the Intent is listed in the `listensFor` property - also in the `intents` object

```tsx
handleIntent?: (context: HandleFdc3IntentContext) => Promise<IntentResult> | void;
```

As can be seen the function:
- receives an object of type [`HandleFdc3IntentContext`](https://www.adaptabletools.com/docs/reference/handlefdc3intentcontext.md) which simply contains the FDC3 Intent
- asynchronously returns FDC3's `IntentResult` object (which is of type `Context | Channel | void`)

```tsx {2}
contexts: {
  handleContext: (context: HandleFdc3Context) => {
    console.log(`Received context: `, eventInfo);
  },
},
```
