Skip to main content
Version: 🚧 Next

Harmoney Data Due Diligence Provider

🎯 Functional Documentation​

The V3 Data Due Diligence Provider represents a major architectural evolution in how due diligence parameters are evaluated. Unlike its predecessor, which treated all data points generically, V3 introduces a Rule-Based Evaluation.

  1. Simple Value Rules: For direct 1:1 mapping of values (e.g., Boolean to Yes/No).
  2. List Lookup Rules: For checking values against external risk lists (e.g., Sanctions, Embargoes).
  3. Advanced Logic Rules: For complex, multi-field conditions (e.g., "If Company Age < 2 AND Sector = 'Crypto'").

⚙️ Configuration​

  • Implementation Class: eu.myharmoney.app.providers.duediligence.HarmoneyV3DataDueDiligenceProvider
  • Key Configuration Field: parameterConfig
important

This provider does not support due diligence document generation, so the configuration parameter DUE_DILIGENCE_DOCUMENT_FETCH will be of no use here.

The configuration is no longer a flat list of fields. Instead, each parameter is defined by the specific type of rule it employs.

The Three Rule Types​

1. Simple Value Rules (simpleValueRules)​

Best for direct 1:1 transformations of system data (like Booleans or Enums) into RBA results.

2. Advanced Logic Rules (advancedLogicRules)​

The powerhouse of the provider. Use this when a single field isn't enough. It supports nested boolean logic (AND, OR) and various operators (greaterThan, equals, in).

3. List Lookup Rules (listLookupRules)​

Dedicated to checking values against external or internal risk lists (e.g., Sanctions or High-Risk Countries).

📝 Configuration Examples​

Settings Configuration

Examples

The Three Safety Nets (Fallback Logic)​

:::warning Important migration behavior In V3, resultForNullAnswer defaults to UNDEFINED.

In V2, the effective default behavior was usually "no result for missing answer" (commonly represented by leaving resultForNullAnswer as null in mappings).

This means a V2 configuration migrated to V3 without explicitly setting resultForNullAnswer can start returning UNDEFINED for missing answers, which can change final RBA outcomes.

If you need V2 parity for "missing answer", set resultForNullAnswer: null explicitly per rule. :::

1. resultForNullAnswer​

Trigger Scenario: Data is Missing – Triggered when the system finds no data (null) for the configured fieldPath.

Functional Purpose: Addresses Missing Information. In compliance workflows, "Missing" should usually remain OPEN for manual review rather than defaulting to "No Hit".

Recommended Default: UNDEFINED

For V2 parity (optional): Use null explicitly when you want "no result" for missing answers.

2. resultForUnmappedAnswer​

Trigger Scenario: Logic is False – Triggered when data exists (e.g., "false" or "Option C") but does not match any configured valueMappings or logical conditions.

Functional Purpose: Acts as the "Else" statement. It captures unexpected or "safe" values that weren't explicitly mapped in the rule.

Recommended Default: UNDEFINED

3. resultMappedAnswerResultUnknown​

Trigger Scenario: Data Integrity Error (List Rules Only) – Triggered if a value is found in a list, but that specific list entry has an empty or invalid result.

Functional Purpose: Acts as a System Fail-safe. It flags list corruption or incomplete database entries to the auditor via a high-score alert.

Recommended Default: UNDEFINED

⤴️ Migration Guide: V2 to V3​

The V3 provider moves from a Field-Centric approach to a Rule-Centric approach. You cannot simply copy-paste V2 configurations; you must categorize them into the correct rule buckets.

⚠️ Additional Required Migration Check: resultForNullAnswer​

Besides moving rules to the correct V3 buckets, you must verify null-answer behavior for every rule:

  • V3 default: resultForNullAnswer = UNDEFINED
  • Common V2 behavior: missing answer often produced no parameter result

If your V2 behavior relied on "no result for missing answer", set:

"resultForNullAnswer": null

on each migrated V3 rule where that behavior is required.

Key Changes

  1. Explicit Categorization: You no longer dump everything into a generic fields list. You must place rules into simpleValueRules, listLookupRules, or advancedLogicRules.

  2. No More "Hidden" Logic: In V2, complex logic was hidden inside a directMapping of a generic field. In V3, this explicitly belongs in advancedLogicRules.

⚡ Migration Cheat Sheet Compare how a configuration transforms from V2 to V3 below.

  1. Simple Value Migration

Goal: Map question_pep (true/false) to YES/NO.

❌ V2 (Old) Generic fields list with implicit simple logic.

"fields": [
{
"fieldPath": "individual.questionAnswers.question_pep",
  "mapping": {
    "directMapping": [
      { "answer": true, "parameterResult": "YES" }
    ]
  }
}
]

✅ V3 (New) simpleValueRules

"simpleValueRules": [
{
  "fieldPath": "individual.questionAnswers.question_pep",
  "valueMappings": [
    { "answer": true, "parameterResult": "YES" }
  ],
  "resultForNullAnswer": null, // Add for V2 parity when missing answers should return no result
  "resultForUnmappedAnswer": "NO" // Explicit fallback for 'false'
}
]
  1. List Lookup Migration

Goal: Check Country Code against a specific risk list.

❌ V2 (Old) Generic field with listIdentifier buried in mapping.

"fields": [
{
  "fieldPath": "individual.address.countryCode",
  "mapping": {
    "listIdentifier": "country_risk_check",
    "resultForUnmappedAnswer": "LOW"
  }
}
]

✅ V3 (New) Dedicated listLookupRules list.

"listLookupRules": [
{
  "fieldPath": "individual.address.countryCode",
  "listIdentifier": "country_risk_check",
  "resultForNullAnswer": null, // Add for V2 parity when missing answers should return no result
  "resultForUnmappedAnswer": "LOW"
}
]
  1. Advanced Logic Migration

Goal: Check if a number is within a specific range & client_self_employed field is true

❌ V2 (Old) Not possible to evaluate using multiple field paths

"fields": [
{
  "fieldPath": "company.companyNumber",
  "mapping": {
    "directMapping": [
      {
        "conditionalAnswer": {
          "greaterThan": { "value": 1000 }
        },
        "parameterResult": "HIGH"
      }
    ]
  }
}
]

✅ V3 (New) Explicit advancedLogicRules structure, with support to multiple field paths

"advancedLogicRules": [
{
  "description": "Check company number range",
  "resultForNullAnswer": null, // Add for V2 parity when missing answers should return no result
  "mapping": {
    "directMapping": [
      {
        "parameterResult": "HIGH",
        "conditionalAnswer": {
            "and": [
              { "smallerThan": { "fieldPath": "company.companyNumber", "value": 9999999999 } },
              { "greaterThan": { "fieldPath": "company.companyNumber", "value": 1000 } },
              { "equals": { "fieldPath": "company.metadata.CLIENT_SELF_EMPLOYED", "value": true } }
            ]
        }
      }
    ]
  }
}
]