# FDC3 Data Grid Context Mappings

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

- FDC3 Mappings define which columns / fields should be used for which FDC3 objects
- It enables a data-first approach to using FDC3 which is incredibly flexible

Grid Data Mappings provide the "glue" to map AG Grid's data and columns to required FDC3 behaviour.

AdapTable looks at the mappings to work out which columns to use when creating Intents and Contexts.

- Previously AdapTable provided FDC3 Columns which defined which contexts to use
- These have been replaced with mappings which allow for a richer and more intuitive "data-first" approach

Mappings are provided in the `gridDataContextMapping` property of FDC3 Options.

### `gridDataContextMapping`

 Maps Context Type to AdapTable Grid Data

  [`GridDataContextMapping`](https://www.adaptabletools.com/docs/reference/griddatacontextmapping.md)

This property is used to tell AdapTable which columns and fields should be used in FDC3 Context.

These are then used when raising Intents or broadcasting Context.

The [`GridDataContextMapping`](https://www.adaptabletools.com/docs/reference/griddatacontextmapping.md) object provides the FDC3 Context.

**Grid Data Context Mapping**

ֵEach Grid Data Context Mapping has the same structure (though the details will differ according to the Context type):
- a **key** - a formal FDC3 type (e.g. `fdc3.instrument` or `fdc3.currency`)
- an associated **FDC3 Context object**
 
The FDC3 Context object contains 2 properties:
- `name` - an **FDC3 Data Mapping**
- `id` - an object which can contain multiple properties.  Each of the properties will provide a FDC3 Data Mapping

**FDC3 Data Mapping**

Each FDC3 Data Mapping tells AdapTable where to find the data to build the Context.

The Data Mapping can always be one of 2 types of object:
- a **Column** - either AdapTable or AG Grid; using the `_colId` prefix (e.g. `_colId.instrument`)
- a **Field** in the Grid's data source; using the `_field` prefix (e.g. `_field.ticker`)

```tsx {1}
gridDataContextMapping: {
  'fdc3.instrument': {
    name: '_colId.instrument',
    id: {
      ticker: '_colId.ticker',
      BBG: '_field.bbgId',
    },
  },
}
```

### Creating FDC3 Grid Data Mappings

Lets look in more detail at the example above - which uses a `fdc3.instrument`.

We therefore provide an FDC3 Instrument Context (see formal object definition [here](https://fdc3.finos.org/docs/context/ref/Instrument)) and then reference it to raise Intents and broadcast Contexts.

First provide the Mapping using the `gridDataContextMapping` property

Then define each Mapping as required.

The key is always a FDC3 Context type.

In this example its an Instrument defined as `fdc3.instrument`

```tsx [[1, 1, "gridDataContextMapping"], [1,2, "'fdc3.instrument'"]]
  gridDataContextMapping: {
    'fdc3.instrument': {
      name: '_colId.instrument',
      id: {
        ticker: '_colId.ticker',
        BBG: '_field.bbgId',
      },
    },
```

Each mapping has 2 properties:

- `name` - typically one column
- `id` - an object with multiple properties, each will be a Data Mapping

In this example of fdc3.instrument, the id can include many different properties, and we have provided 2 (`ticker` and `BBG`)

```tsx [[2, 3, "name"], [2, 4, "id"]]
  gridDataContextMapping: {
    'fdc3.instrument': {
      name: '_colId.instrument',
      id: {
        ticker: '_colId.ticker',
        BBG: '_field.bbgId',
      },
    },
```

Map Columns or Fields to each Data Mapping as required.

Columns use the prefix `_colId`  - here we reference 2 Columns:
- `Instrument` - which we provide for `name` property
- `Ticker` - which we provide for the `ticker` property
 
Fields in the DataSource use the prefix  `_field` - as in this example:
- `bbgId` - which we provide for the `BBG` property

```tsx [[3, 3, "'_colId.instrument'"], [3, 5, "'_colId.ticker'"] ,[3, 6, "'_field.bbgId'"]]
  gridDataContextMapping: {
    'fdc3.instrument': {
      name: '_colId.instrument',
      id: {
        ticker: '_colId.ticker',
        BBG: '_field.bbgId',
      },
    },
```

Now we can use it to manage Intents.  We are able to:
- **raise** the `ViewInstrument` Intent 

We use both Context Menu and Action Column

- **listen for** the `ViewQuote` Intent

In both cases, AdapTable will automatically use the mapping supplied in Step 1 when providing context.

```tsx [[4, 1, "intents"], [4, 2, "raises"], [4, 16, "listensFor"]]
 intents: {
  raises: {
    ViewInstrument: [
      {
        contextType: 'fdc3.instrument',
        contextMenu: {
          columnIds: ['ticker'],
        },
        actionButton: {
          id: 'viewInstrumentButton',
          label: 'View Instrument',
        },
      },
    ],
  },
  listensFor: ['ViewQuote', 'ViewInstrument'],
},
```

Similarly we can use the mapping with Contexts.  We are able to:
- **broadcast** Instrument Context

Again, we use both Context Menu and Action Column

- **listen for** the `fdc3.instrument` context being broadcast in other applications

And, again, AdapTable will automatically use the mapping supplied in Step 1 when providing context.

```tsx [[5, 1, "contexts"], [5, 2, "broadcasts"], [5, 13, "listensFor"]]
 contexts: {
  broadcasts: {
    'fdc3.instrument': {
      contextMenu: {
        columnIds: ['ticker'],
      },
      actionButton: {
        id: 'broadCastInstrumentButton',
        label: 'Broadcast Ticker Info',
      },
    },
  },
  listensFor: ['fdc3.instrument'],
},
```

## Available Contexts

The following FDC3 2.0 Contexts can be provided in Grid Data Context Mappings:

Click the link to see full details of the Context in the FDC3 2.0 documentation

- [Chart](https://fdc3.finos.org/docs/context/ref/Chart)                       
- [ChatInitSettings](https://fdc3.finos.org/docs/context/ref/ChatInitSettings) 
- [Contact](https://fdc3.finos.org/docs/context/ref/Contact)                   
- [ContactList](https://fdc3.finos.org/docs/context/ref/ContactList)           
- [Country](https://fdc3.finos.org/docs/context/ref/Country)                   
- [Currency](https://fdc3.finos.org/docs/context/ref/Currency)                 
- [Email](https://fdc3.finos.org/docs/context/ref/Chart)                       
- [Instrument](https://fdc3.finos.org/docs/context/ref/Instrument)             
- [InstrumentList](https://fdc3.finos.org/docs/context/ref/InstrumentList)     
- [Organization](https://fdc3.finos.org/docs/context/ref/Organization)         
- [Portfolio](https://fdc3.finos.org/docs/context/ref/Portfolio)               
- [Position](https://fdc3.finos.org/docs/context/ref/Position)                 
- [TimeRange](https://fdc3.finos.org/docs/context/ref/TimeRange)               
- [Valuation](https://fdc3.finos.org/docs/context/ref/Valuation)
