# Keep Existing Links Working After Switching Search

When a store switches to Retail Cloud Connect, existing storefront links, saved collection URLs, and email campaigns may still use query-parameter names from a previous search provider. The search App Block can translate those old parameter names into the equivalent Retail Cloud Connect filter keys, so those links keep working.

<br/>

## When to Use This

- Migrating from another search provider whose URLs use different parameter names.
- Preserving saved collection links or campaign URLs that already circulate.

<br/>

## How It Works

Define key mappings before the search App Block bundle mounts:

```js
window.Nimstrata = window.Nimstrata || {};
window.Nimstrata.search = window.Nimstrata.search || {};

window.Nimstrata.search.keyMappings = {
  resolution: 'attributes.resolution',
  stock: {
    key: 'availability',
    values: {
      0: 'OUT_OF_STOCK',
      1: 'IN_STOCK',
    },
  },
};
```

Common Shopify filter keys are mapped automatically. Storefront mappings override them.

Each object key is the old URL query parameter to accept. Each value is either a canonical filter field, such as `attributes.resolution`, or an object with a `key`, optional `values`, and optional `keepOriginal`. The `values` map converts old query-string values before applying the filter. With this example, `?stock=1` applies an `availability` filter of `IN_STOCK`.

The mapped `key` must resolve to a field the App Block already understands: a supported built-in facet such as `brands`, `sizes`, `availability`, `price`, or an `attributes.*` field. Unknown query parameters are ignored unless they appear in `keyMappings` or already match a supported field.

By default, generated search state uses canonical keys. Set `keepOriginal: true` when an integration also needs the old key. Shopper filter changes still write canonical keys to the browser URL.

Metaobject GIDs on mapped or `attributes.*` parameters are resolved to display text through the Storefront API before mapping. Explicit `values` mappings take priority, and unresolved GIDs remain unchanged.

<br/>

## Related Configuration

`keyMappings` is one of the manual `window.Nimstrata` storefront hooks; see [Additional Properties](/shopify/theme-installation/window-nimstrata/) for the full reference. For how normal filters are configured, see [App Block Filters](/shopify/filters-and-data/app-block-filters/).