With Synqly integrations, mappings can adapt to the need of your product by configuring what mapping is applied to the integration. This is available at the integration point and integration level. Configuration for integrations and integration points work similarly. The main difference is the integration point acts as a template for any integrations created within it, while the integration level configuration only applies to itself.

Before registering a mappings, you may wish to first [create a customer defined mapping](/api-reference/customer-defined-mappings) to use.

## Registering Custom Mappings

### [Integrations](https://docs.synqly.com/api-reference/management/integrations/integrations_create)

To define a custom mapping chain on an integration, populate the 'mapping' field with a list of mapping chains. Each mapping chain contains a set of mappings, and a list of operation IDs which it apples for. As an example, this configuration sets up an opensearch integration with custom mappings for events read and write.


```json
{
  "name": "siem-opensearch-example",
  "provider_config": {
    "create_index": "logs-synqly-default",
    "index": "logs-*",
    "credential": {
      "type": "basic_id",
      "value": "00000000-0000-0000-0000-000000000000"
    },
    "url": "https://example.opensearch.com:9200",
    "type": "siem_opensearch"
  },
  "mappings": [
    {
      "mappings": ["custom-create", "@synqly-default.opensearch.events:1.3.0.0"],
      "operation_ids": ["siem_post_events"]
    },
    {
      "mappings": ["synqly-default.opensearch.events:1.3.0.0", "custom-read"],
      "operation_ids": ["siem_query_events"]
    }
  ]
}
```

When writing events (operation ID "siem_post_events"), Synqly will first find and run the 'custom-create' mapping. This might transform the events sent to Synqly from a bespoke format into OCSF. The result of that mapping transform is then passed to the synqly default opensearch event transform. Version 1.3.0.0 transforms OCSF 1.3.0 events into Elastic Common Schema for consumption by OpenSearch.

Similarly when reading events (operation ID "siem_query_events"), Synqly will first find and run the 'synqly-default.opensearch.events:1.3.0.0' mapping. This transforms the events coming from OpenSearch in ECS format into OCSF 1.3.0 event format. The result of that mapping transform is then passed to the 'custom-read' mapping. This might transform the events from OCSF format into a bespoke format that is easier to process in the requesting application.

Chains can contain any number of transformations, or may just contain 1. The result of each transformation is passed as input to the next transformer in the chain.

### [Integration Points](https://docs.synqly.com/api-reference/management/integrationpoints/integrationpoints_create)

Integration points allow you to define the default set of mappings for any integrations created within it. When creating an integration point, rather than directly defining mapping chains, you instead define mapping chain templates. Any integration created within the integration point will have the integration point mapping template applied to it prior to saving.

It is worth noting two behaviors. First, if the integration is created with its own mapping defined for an operation ID, then the mapping created directly on the integration overrides the integrapoint point mapping definition. The one defined by the integration itself, *not* the integration point template mapping is used in this case. However if a template specifies a mapping with several operation IDs on a template, and the integration created only specifies one of those operation IDs, the template will still get applied for the other operation IDs. Second, once the template is applied, the mappings belong to the integration. If the template is updated, existing integrations within the integration point are not modified. The integrations themselves are always the source of truth for what mappings to apply.

Within the mapping template, in addition to specifying the mappings and operation IDs, the template offers the ability to specify which providers the mapping should apply to. This allows you to specify different mapping chains for different provider types if desired.

This example shows an integration point creation request, setting a custom mapping template. A mapping for "siem_post_events" and "siem_query_events" is created that applies to the opensearch and elasticsearch SIEM providers. A third mapping for "siem_query_investigations" is created which is set to apply to ALL providers (*).


```json
{
    "name": "custom-siem-mappings",
    "connector": "siem",
    "mappings": [
        {
            "providers": ["siem_opensearch", "siem_elasticsearch"],
            "mappings": ["custom:1.1.2", "default:0"],
            "operation_ids": ["siem_post_events"]
        },
        {
            "providers": ["siem_opensearch", "siem_elasticsearch"],
            "mappings": ["default:0", "custom-2:1.0.0"],
            "operation_ids": ["siem_query_events"],
        },

        {
            "providers": ["*"],
            "mappings": ["custom-3:1.0.0-beta.1"],
            "operation_ids": ["siem_query_investigations"],
        },
    ]
}
```

When a provider of type 'siem_opensearch' or 'siem_elasticsearch' is created in this integration point, the custom mapping templates for "siem_post_events" and "siem_query_events" will be applied so long as the create integration request does not also contain a custom mapping for those operation IDS. Any other provider type created in this integration point will use the default mappings for "siem_post_events" and "siem_query_events". However all SIEM providers created in this integration point will have the mappings for "siem_query_investigations" applied unless they have it defined already upon creation.

Notice as well in this example that in the mappings that apply to "siem_opensearch" and "siem_elasticsearch" we are using the mapping ID "default:0". This is a special mapping ID that is replaced at runtime with the default mapping for the provider. Special mapping IDs like this are available within both mapping templates and integration-level mappings.

## Mapping Transforms and Mapping IDs

Internally Synqly uses a system for defining and addressing mapping transformations using an ID string and a version string. In string form these are concatenated with a ':' into a mapping ID. For example in Splunk, the default event mapping is at "synqly-default.splunk.events:1.3.0.0". Within Synqly this mapping is for transforming events in the Splunk Common Information Model to the OCSF 1.3.0 event schema. The version number is indicating that the transformation is targeting OCSF schema version 1.3.0 and is the initial version 0 of this transformation (1.3.0.0).

In cases where both read and write are offered, generally the transformation ID is pre-pended with an '@' symbol to indicate it is a reverse transformation. "synqly-default.splunk.events:1.3.0.0" is for transforming events from Splunk Common Information Format into OCSF. However when the reverse is required -- OCSF to Splunk Common Information Format -- we can use the reverse transformation ID "@synqly-default.splunk.events:1.3.0.0". Note that this is built-in to the special "default:0" transformation, so there there is never a need to specify "@default:0".

### Special Mapping IDs

There are a small number for special mapping IDs that are helpful to be aware of.

**default:0**

When applying a transformation chain, this transformation ID is replace with the set of default transformations of the provider. This is very helpful in transformation mapping templates. For example, if your application requires a custom data format rather than OCSF, a transformation could be registered going from OCSF to your custom format. However the providers themselves do not return data in OCSF format. The Synqly default transformations do this for each provider type. However by specifying a chain for `["default:0", "custom-transformation:1.0.0"]`, you tell the system to use the provider default first, transforming whatever is return from the provider into OCSF, and then transform the OCSF event into the custom format defined by "custom-transformation:1.0.0".

**synqly-default.passthrough:0**

When no mapping is defined, integrations will automatically apply the default transformation. However, this may not be the desired behavior. The "synqly-default.passthrough:0" transformation can be applied instead. This performs no transformation operations on the data -- a passthrough.

## What is my operation ID?

Transformation mappings are applied by operation ID. To find the ID of any given operation, you can navigate to the relevant operation in the [API reference](/api-reference/overview) and find the line starting with **Operation ID:** followed by the operation ID in a code snippet.

As an example, we have been looking at the `siem_post_events` operation. By reviewing the [refence page for this API operation on our docs site](/api-reference/connectors/siem/siem_post_events), we see the operation ID:

> **Operation ID**: `siem_post_events`


A couple more examples:

* [SIEM / Get Investigation](/api-reference/connectors/siem/siem_get_investigation)
> **Operation ID:** `siem_get_investigation`
* [EDR / Create IOCs](/api-reference/connectors/edr/edr_create_iocs)
> **Operation ID:** `edr_create_iocs`
* [Identity / Query Audit Log](/api-reference/connectors/identity/identity_query_audit_log)
> **Operation ID:** `identity_query_audit_log`