Troubleshooting Enrichment Decisions (Staff/Advanced)

Warning: Advanced Feature

Accessing and interpreting the Enrichment JSON log is an advanced troubleshooting technique primarily intended for use by Zudello implementation staff or trained partners. It requires understanding Zudello's internal data structures and enrichment logic.

When Zudello processes a document, the Enrichment service automatically attempts to link related records (like Suppliers, Items, POs) and apply default coding. Sometimes, these automatic decisions might not be what the user expects. The Enrichment JSON log provides a detailed, step-by-step record of the decisions made during this process, helping staff diagnose why a particular outcome occurred.

Best practices

• Use the Enrichment JSON log when standard troubleshooting (checking document data, supplier/item records, alternatives) doesn't explain the behaviour.
• Focus on the specific enrichment step causing the issue (e.g., Link Supplier, Link Item for line #X).
• Understand the sequence of enrichment steps, as earlier steps influence later ones.
• Correlate the log entries with the actual data on the document and related records at the time of enrichment.

Accessing the Enrichment JSON Log

Accessing this log requires specific staff permissions.

1. Open the relevant transaction document in Zudello.
2. Click the Staff Menu icon (often a wrench or gear icon, visible only to staff) at the top right of the document viewer.
3. Select Enrichment JSON (or similar option) from the menu.
4. A modal or panel will display the JSON log data.

Understanding the Log Structure

The log typically contains an array of entries, where each entry represents a specific run of the Enrichment service for that document. Enrichment might run multiple times (e.g., initially after extraction, again if "Apply Trained Rules" is clicked).

Each run entry contains:

• Timestamp: When the enrichment process started for that run.
• Actions: An object containing key-value pairs, where:
  • Key: The name of the specific enrichment function or step performed (e.g., Link Supplier, Link Item for line #1, Find matching PURCHASING ORDER transactions).
  • Value: An object detailing the outcome of that step:
    • result: The outcome or linked record(s) found (e.g., Supplier Name and UUID, Item Name and UUID, list of matched PO UUIDs, or null/[] if no match).
    • filter_steps: An array of strings showing the database query filters used during that step. This is crucial for understanding why a specific record was (or wasn't) matched.
    • dependency_state: (If applicable) Shows the values of fields used for dependency checks during that step (e.g., the supplier_uuid used when filtering items).

// Simplified Example Structure
[
  {
    "start_time": "2024-04-21T12:00:00Z",
    "actions": {
      "Link Supplier": {
        "result": "Supplier ABC (uuid-abc)",
        "filter_steps": ["company_tax=123456789"],
        "dependency_state": null
      },
      "Link Item for line #1": {
        "result": "Item XYZ (uuid-xyz)",
        "filter_steps": ["sku__iexact='SKU123'"],
        "dependency_state": {"header": {"supplier": "uuid-abc"}}
      },
      "Find matching PURCHASING ORDER transactions": {
        "result": ["PURCHASING ORDER PO987 (uuid-po987)"],
        "filter_steps": ["supplier_id=uuid-abc", "document_number__iexact='PO987'"]
      }
      // ... other steps
    }
  },
  // ... potentially other enrichment runs
]

Common Troubleshooting Scenarios

• Why was this Supplier linked?
  • Find the Link Supplier step.
  • Examine the filter_steps. Did it match on ABN (company_tax), email, phone, or name? Was an alternative used?
  • Compare the filter value with the data on the document and the linked Supplier record.
• Why wasn't a Supplier linked?
  • Find the Link Supplier step.
  • Examine the filter_steps. Did any step use incorrect data extracted from the document?
  • Check the Supplier record in Zudello – does it have the correct ABN, email, phone, or name matching the document?
  • Check Supplier Alternatives – does an alternative exist that should have matched?
• Why was this Item linked to Line X?
  • Find the Link Item for line #X step.
  • Examine filter_steps. Did it match on SKU, alternative, barcode, or description keyword?
  • Check the dependency_state – was it filtering based on the correct Supplier?
  • Compare filter values with the transaction line data and the linked Item record/alternatives.
• Why wasn't the correct PO found for matching?
  • Find the Find matching PURCHASING ORDER transactions step.
  • Examine filter_steps. Was it searching using the correct po_number extracted from the invoice? Was it filtering by the correct supplier_id? Was it checking the correct PO status values (based on Allocation Extension settings)?
  • Check the actual PO record in Zudello – does its document number, supplier, and status match the filter criteria?

Need help?

Interpreting the Enrichment JSON requires familiarity with Zudello's internal processes. If you are unable to diagnose an issue using the log, escalate the problem to the development team via a detailed support ticket, including the document UUID and the relevant sections of the Enrichment JSON log.