Dimension Matching Rules

Why Matching Rules Matter

Before ParitySync can identify gaps, it needs to determine which source members correspond to which target members. A cost center called 6100 - Marketing in NetSuite and MKT_6100 in Adaptive Planning are the same thing -- but only if you tell VersionForge how to match them.

Matching rules define the logic for pairing source and target dimension members. You configure them per dimension type, and they execute in priority order until a match is found or all rules are exhausted.

Matching Strategies

Exact Match

The simplest strategy. A source member matches a target member when a specified field is identical on both sides.

matching:
  - strategy: "exact"
    sourceField: "code"
    targetField: "code"

Exact match is fast and deterministic. Use it when source and target systems share a common code or identifier. This is the most common strategy for account codes, entity IDs, and other system-generated identifiers.

Alias Match

A lookup table maps source values to target values. This handles cases where the same concept has different names or codes across systems.

matching:
  - strategy: "alias"
    sourceField: "name"
    targetField: "name"
    aliases:
      "Engineering - Platform": "ENG_PLAT"
      "Engineering - Infrastructure": "ENG_INFRA"
      "Sales - Enterprise": "SALES_ENT"

Aliases can also be loaded from a CSV file or a database table for large mapping sets:

matching:
  - strategy: "alias"
    sourceField: "code"
    targetField: "code"
    aliasSource: "s3://config-bucket/department-aliases.csv"

Fuzzy Match

When exact and alias matching fail, fuzzy matching uses string similarity to suggest probable matches. VersionForge computes a similarity score between source and target member names using normalized Levenshtein distance.

matching:
  - strategy: "fuzzy"
    sourceField: "name"
    targetField: "name"
    threshold: 0.85       # minimum similarity score (0.0 to 1.0)
    requireReview: true   # fuzzy matches always go to review queue

Fuzzy matches are never applied automatically by default. They are surfaced as suggestions in the ParitySync review interface, where an implementer confirms or rejects each proposed match.

Rule Priority

Matching rules execute in the order they are defined. The first rule that produces a match wins. A typical configuration layers all three strategies:

dimensions:
  cost_center:
    matching:
      - strategy: "exact"
        sourceField: "code"
        targetField: "code"
      - strategy: "alias"
        sourceField: "code"
        targetField: "code"
        aliasSource: "cost-center-aliases.csv"
      - strategy: "fuzzy"
        sourceField: "name"
        targetField: "name"
        threshold: 0.85
        requireReview: true

This means: try exact code match first, then check the alias table, then fall back to fuzzy name matching. Any member that fails all three strategies is flagged as an unresolved gap.

Handling Case Sensitivity

By default, exact and alias matching are case-insensitive. If your target system distinguishes between MKT and mkt, enable case-sensitive matching:

matching:
  - strategy: "exact"
    sourceField: "code"
    targetField: "code"
    caseSensitive: true

Fuzzy matching always normalizes case before computing similarity scores, regardless of the caseSensitive setting.

Multi-Field Matching

Some dimensions require matching on more than one field. A department might share a code with another department in a different entity, so you need to match on both code and parent_entity:

matching:
  - strategy: "exact"
    sourceFields: ["code", "parent_entity"]
    targetFields: ["code", "parent_entity"]

Multi-field matching requires all specified fields to match. It is available for exact and alias strategies. Fuzzy matching operates on a single field at a time.

Custom Matching Expressions

For scenarios that do not fit the built-in strategies, you can write a custom matching expression using VersionForge's expression language:

matching:
  - strategy: "expression"
    expr: "source.code == target.code.split('_')[1]"

This example strips a prefix from the target code before comparing. Custom expressions have access to all fields on both the source and target member records.