> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alana.shopping/llms.txt
> Use this file to discover all available pages before exploring further.

# Pipeline Settings

> Configure custom Silver field mappings, Gold scoring weights, auto-trigger behavior, and preview mode for your workspace pipeline.

## Overview

**Pipeline Settings** let you customize how the Bronze → Silver → Gold pipeline behaves for your workspace. You can define custom field mappings (Silver), adjust scoring weights (Gold), enable auto-triggers, and use preview mode to test changes safely.

***

## Accessing pipeline settings

**Via UI:**

1. Navigate to **Settings** → **Pipeline**
2. The settings page shows tabs for **Silver Mappings**, **Gold Weights**, and **Behavior**

**Via API:**

* `GET /api/workspace/{workspaceId}/settings/pipeline` — read current settings
* `PUT /api/workspace/{workspaceId}/settings/pipeline` — update settings

Settings are applied at the **workspace level** and affect all catalogs in the workspace. Team-level overrides are available on Enterprise plans.

***

## Silver field mappings

Silver mappings define how non-standard source fields are mapped to the Alana product schema.

### Why you need mappings

When supplier files use column names like `"item_code"` instead of `"sku"`, or `"prod_name"` instead of `"title"`, Silver won't know how to map them without explicit configuration.

### Mapping rules

Each mapping rule has:

| Property      | Type              | Description                                                                                 |
| ------------- | ----------------- | ------------------------------------------------------------------------------------------- |
| `sourceField` | string            | The column name as it appears in the source file                                            |
| `targetField` | string            | The Alana schema field to map to                                                            |
| `transform`   | string (optional) | Transformation to apply: `"uppercase"`, `"lowercase"`, `"trim"`, `"prefix:X"`, `"suffix:X"` |

### Example mappings

```json theme={null}
{
  "silverMappings": [
    {
      "sourceField": "product_name",
      "targetField": "title",
      "transform": "trim"
    },
    {
      "sourceField": "item_code",
      "targetField": "sku"
    },
    {
      "sourceField": "cat",
      "targetField": "categoryPath",
      "transform": "prefix:Apparel > "
    },
    {
      "sourceField": "vendor",
      "targetField": "brand"
    }
  ]
}
```

### Available target fields

| Target field       | Type   | Description                        |
| ------------------ | ------ | ---------------------------------- |
| `title`            | string | Product name                       |
| `sku`              | string | Stock-keeping unit                 |
| `gtin`             | string | Global Trade Item Number           |
| `price`            | number | Selling price                      |
| `originalPrice`    | number | Pre-discount price                 |
| `currency`         | string | ISO 4217 code                      |
| `brand`            | string | Brand name                         |
| `categoryPath`     | string | Category hierarchy (`>` separated) |
| `description`      | string | Full product description           |
| `shortDescription` | string | Brief description                  |
| `primaryImageUrl`  | string | Main image URL                     |
| `availability`     | string | Stock status                       |

***

## Gold scoring weights

Gold weights define the importance of each of the 7 scoring stages. All weights must sum to 100.

### Default weights

| Stage                                 | Default weight |
| ------------------------------------- | -------------- |
| Identity (SKU, GTIN, brand)           | 20%            |
| Taxonomy (category depth)             | 15%            |
| Content (title, description, bullets) | 25%            |
| Media (images, video)                 | 20%            |
| Pricing (price, currency, original)   | 10%            |
| Attributes (category-specific specs)  | 5%             |
| SEO (slug, meta, keywords)            | 5%             |

### Custom weight example

For a media-heavy catalog (e.g., fashion photography):

```json theme={null}
{
  "goldWeights": {
    "identity": 15,
    "taxonomy": 10,
    "content": 20,
    "media": 35,
    "pricing": 10,
    "attributes": 5,
    "seo": 5
  }
}
```

<Warning>
  All weight values must sum to exactly 100. The API returns a 422 error if the sum is incorrect.
</Warning>

***

## Behavior settings

| Setting             | Type    | Default | Description                                           |
| ------------------- | ------- | ------- | ----------------------------------------------------- |
| `autoTriggerSilver` | boolean | `false` | Run Silver automatically after every Bronze ingest    |
| `autoTriggerGold`   | boolean | `false` | Run Gold automatically after Silver completes         |
| `previewMode`       | boolean | `false` | Simulate pipeline changes without writing to products |

<Note>
  `autoTriggerGold: true` is not recommended for large catalogs. Gold scoring has a cost and can be slow for 10,000+ products. Use manual or scheduled triggering instead.
</Note>

***

## Preview mode

When `previewMode: true`, pipeline operations **simulate** transformations and return what would happen — without modifying any product records.

Use preview mode to:

* Test a new Silver mapping before applying it to real data
* See how new Gold weights would affect scores
* Validate field mapping logic without risk

### Example preview response (Silver)

```json theme={null}
{
  "preview": true,
  "results": [
    {
      "productId": "prod_abc",
      "status": "would_succeed",
      "fieldsWouldNormalize": ["title", "categoryPath", "brand"],
      "currentValues": {
        "title": "blue running shoe",
        "categoryPath": "shoes"
      },
      "newValues": {
        "title": "Blue Running Shoe",
        "categoryPath": "Apparel > Footwear > Running"
      }
    }
  ]
}
```

***

## Read current settings

<CodeGroup>
  ```bash curl theme={null}
  curl "https://app.alana.shopping/api/workspace/WORKSPACE_ID/settings/pipeline" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    `https://app.alana.shopping/api/workspace/${workspaceId}/settings/pipeline`,
    { headers: { 'Authorization': `Bearer ${apiKey}` } }
  );
  const settings = await response.json();
  console.log('Current Gold weights:', settings.goldWeights);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      f"https://app.alana.shopping/api/workspace/{workspace_id}/settings/pipeline",
      headers={"Authorization": f"Bearer {api_key}"}
  )
  settings = response.json()
  print("Current Silver mappings:", settings["silverMappings"])
  ```
</CodeGroup>

***

## Update settings

<CodeGroup>
  ```bash curl theme={null}
  curl -X PUT "https://app.alana.shopping/api/workspace/WORKSPACE_ID/settings/pipeline" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "silverMappings": [
        { "sourceField": "product_name", "targetField": "title" },
        { "sourceField": "item_code", "targetField": "sku" }
      ],
      "goldWeights": {
        "identity": 20,
        "taxonomy": 15,
        "content": 25,
        "media": 20,
        "pricing": 10,
        "attributes": 5,
        "seo": 5
      },
      "autoTriggerSilver": true,
      "autoTriggerGold": false,
      "previewMode": false
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    `https://app.alana.shopping/api/workspace/${workspaceId}/settings/pipeline`,
    {
      method: 'PUT',
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        silverMappings: [
          { sourceField: 'product_name', targetField: 'title' },
          { sourceField: 'item_code', targetField: 'sku' },
        ],
        goldWeights: {
          identity: 20, taxonomy: 15, content: 25,
          media: 20, pricing: 10, attributes: 5, seo: 5,
        },
        autoTriggerSilver: true,
        autoTriggerGold: false,
        previewMode: false,
      }),
    }
  );
  const updated = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.put(
      f"https://app.alana.shopping/api/workspace/{workspace_id}/settings/pipeline",
      headers={"Authorization": f"Bearer {api_key}"},
      json={
          "silverMappings": [
              {"sourceField": "product_name", "targetField": "title"},
              {"sourceField": "item_code", "targetField": "sku"},
          ],
          "goldWeights": {
              "identity": 20, "taxonomy": 15, "content": 25,
              "media": 20, "pricing": 10, "attributes": 5, "seo": 5,
          },
          "autoTriggerSilver": True,
          "autoTriggerGold": False,
          "previewMode": False,
      }
  )
  updated = response.json()
  print("Settings updated:", updated)
  ```
</CodeGroup>

***

## Score coherence

Gold scores are recalculated only when Gold is triggered. If you change `goldWeights`, existing scores on products are **stale** until Gold is re-run. A banner in the UI warns when settings have changed since the last scoring run.

To refresh scores after changing weights:

```bash theme={null}
# Re-run Gold on all products after updating weights
curl -X POST "https://app.alana.shopping/api/workspace/WORKSPACE_ID/catalogs/CATALOG_ID/batch/gold" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scope": "all"}'
```

***

## Best practices

<AccordionGroup>
  <Accordion title="Configure mappings before the first import">
    If your supplier files use non-standard column names, configure Silver mappings before importing. This ensures your first import lands correctly without requiring a re-import.
  </Accordion>

  <Accordion title="Use preview mode for mapping changes">
    Before applying new mappings to a live catalog, enable preview mode and run Silver on a small selection. Review the `newValues` output to confirm mappings behave as expected.
  </Accordion>

  <Accordion title="Re-run Gold after changing weights">
    After updating Gold weights, trigger a full catalog re-analysis so all product scores reflect the new configuration.
  </Accordion>

  <Accordion title="Enable autoTriggerSilver for automated feeds">
    If you have a recurring import job (daily supplier feed, nightly CSV), enable `autoTriggerSilver: true` so imported products are normalized automatically.
  </Accordion>
</AccordionGroup>