Compliance Case Insight

---
title: Compliance Case Insight
audience: Business stakeholders, compliance officers
voice: business
version: 1.0
last_updated: 2024-06-15
---

## What it is

The Compliance Case Insight widget provides a comprehensive, FirstAML-driven view of active AML/KYC cases within the Innovation Hub. It renders seamlessly on both client work items and compliance cycle work items, preserving FirstAML's PASS/FAIL/MATCH semantics while adding actionable insights like next steps and risk signals.

## Why it exists

Compliance officers previously had to switch between Sharedo and FirstAML to review case status, verify individual results, and determine next actions. This widget eliminates context-switching by surfacing FirstAML's detailed results directly within Sharedo, with a consistent display of case status, risk signals, and individual-level details.

## How it helps

- **Reduce review time** by showing the most critical cases at a glance (attention required badge)
- **Accelerate next steps** with clear, per-individual action suggestions (e.g., 'Sanctions match — escalate')
- **Eliminate context-switching** by keeping compliance review within Sharedo
- **Improve case accuracy** with real-time freshness indicators and auto-refresh
- **Enable bulk refresh** for multiple compliance cycles from a single action

## What it costs

This widget requires a FirstAML integration and a properly configured compliance work item structure. The initial setup involves:

- Configuring the FirstAML result field on work items
- Setting up the compliance cycle work type structure
- Enabling the ODS upsert feature (optional, requires additional configuration)

All configuration is done through the widget designer interface and requires no developer intervention.

## Where it fits

The Compliance Case Insight widget fits naturally on:

- Compliance cycle work items (where the case is actively being reviewed)
- Client work items (where the case is being managed as part of client engagement)

It integrates with Sharedo's existing compliance workflow, enhancing the user experience without disrupting established processes.

Architecture

The widget is built on the Foundry SDK (@alterspective-engine/foundry), with a component-based structure:

• src/index.ts: Main widget implementation, handles data fetching, state management, and rendering
• src/designer-model.ts: Handles designer state and configuration validation
• src/firstaml-adapter.ts: Transforms FirstAML payload into widget-friendly data
• src/ods-upsert-runner.ts: Orchestrates ODS upsert operations
• src/ods-upsert.ts: Plans ODS upsert operations
• src/sync-targets.ts: Resolves structured sync targets to concrete work items

Key APIs

Public APIs (used by widget)

• GET /api/v1/public/workItem/{id}/attributes (fetch work item attributes)
• POST /api/v1/public/workItem/{id}/attributes (write work item attributes)
• POST /api/v1/public/workItem/findByQuery (find work items by query)
• POST /api/plugin/firstaml/graphql (FirstAML GraphQL API)

Internal APIs (not public)

• POST /api/ods/_search (ODS search)
• POST /api/ods (ODS create)
• POST /api/ods/{id}/aspectData (write AML aspect)
• POST /api/v1/public/workItem/{id}/participants (add participants)

Notable Patterns

1. Type-anchored sync targets (syncTargets): Resolves to concrete work items based on work type system name (e.g., null = host, client = parent client work item)
2. Per-row ODS upsert flow: User chooses to link or create for each individual, with role selection per target work item
3. Auto-polling: Only when case is in progress or ready for review
4. Cycle comparison: Optional feature to show changes between current and previous compliance cycles
5. Structured configuration: syncTargets replaces legacy flat fields for better flexibility

Caveats

• ODS upsert requires configuration: The allowOdsUpsert flag must be enabled, and participant roles must be configured
• FirstAML integration is required: The widget depends on FirstAML being configured and the result field being populated
• Legacy fields deprecated: participantRoleIndividual and participantRoleOrganisation are deprecated in favor of syncTargets

Designer Save Contract — this.blade, not this.configuration.blade (v0.1.1)

wireBladeConfigBridge() must read the OOB AddEditWidgetBlade's configurationJson observable via this.blade.model.configurationJson, never this.configuration.blade.model. Foundry's BaseWidget constructor deep-clones configuration (structuredClone, falling back to JSON.parse(JSON.stringify(...)) when it throws on the KO-observable function), which silently drops configurationJson — so reading from the clone makes the bridge a permanent no-op: designer edits never reach the blade's Save button, and reopening the config shows stale values with no error. this.blade is BaseDesigner's own un-cloned reference to the same constructor argument and is the only supported way to reach the blade's live model until Foundry FR-99 (alterspective-foundry#156) ships a dedicated helper. Same root cause and fix as alt-global-shared-widget-related-work-tasks (PR #121).

How it's built

Git is the single source of truth — the component lives at widgets/alt-global-shared-widget-compliance-case-insight. Deployment is to the Sharedo IDE; the manifest defines how the platform loads it.

# Using the Compliance Case Insight Widget

## Placement

Place the widget on:
- **Compliance cycle work items** (default placement)
- **Client work items** (with `hostMode: client` configuration)

## Configuration

The widget is fully configurable through the designer interface:

### Data Source Configuration

| Field | Description | Default |
|-------|-------------|---------|
| Compliance result field name | Sharedo work-item attribute holding FirstAML JSON payload | `alt-fo-shared-form-compliance-case-result` |
| Host mode | How to interpret the host work item (auto, compliance, client) | `auto` |
| Provider | Provider identity (typically `firstaml`) | `firstaml` |
| Client compliance work type | Work type for compliance cycles (used for fallback) | `alt-global-shared-process-client-compliance` |
| Client current-cycle field | Composer-path attribute on client work item holding current cycle ID | `currentComplianceCycleRef` |
| Max child cycles to inspect | How many cycles to check when falling back to child cycles | `10` |

### Status Mapping

| Field | Description | Default |
|-------|-------------|---------|
| Review-ready statuses | FirstAML statuses that map to 'ready for review' | `READY_FOR_REVIEW` |
| Completed statuses | FirstAML statuses that count as 'case finished' | (empty) |
| Attention statuses | FirstAML statuses that trigger 'attention required' badge | (empty) |
| Treat any individual FAIL as attention required | When enabled, a single FAIL flips case badge to red | `true` |

### Display Configuration

| Field | Description | Default |
|-------|-------------|---------|
| Widget title | Title displayed inside the widget (not the sharedo chrome) | `Compliance Insight` |
| Show inner widget title | When enabled, shows title inside the widget body | `false` |
| Show individuals list | Whether to show the list of individuals in the case | `true` |
| Show individual details | When enabled, allows expanding individual rows for more detail | `true` |
| Show per-row next-action hint | Shows a short action suggestion next to each individual | `true` |
| Show severity ring on individual cards | Shows a colored left border derived from risk signals | `true` |
| Show case documents drawer | Shows FirstAML's case-level PDFs (reports, manifests) | `true` |

### ODS Upsert Configuration (Optional)

| Field | Description | Default |
|-------|-------------|---------|
| Allow ODS upsert | When enabled, users can link FirstAML individuals to ODS records | `false` |
| AML aspect key | Key under which AML integration metadata is stored on ODS records | `alt-aml-integration` |
| Participant role — individual | Role system name for individual records | `alt-fo-shared-role-client` |
| Participant role — organisation | Role system name for organisation records | `alt-fo-shared-role-client` |
| Also add upserted ODS records to parent Client | When enabled, adds records to parent client work item | `true` |
| Where to sync | Configures where to add ODS records (host + parent client) | (default: host only) |

## Where to Sync Configuration

The 'Where to sync' field is a structured editor with:

- **Target work type**: Select work type system name (e.g., `client`) or leave empty for host
- **Individual role**: Role for individual records (e.g., `Client Contact`)
- **Organisation role**: Role for organisation records (e.g., `Client`)
- **Required**: When enabled, missing role blocks the link

This replaces the legacy `participantRoleIndividual`/`participantRoleOrganisation` fields and allows for per-target role configuration.

## Bulk Refresh

The widget supports bulk refresh of multiple compliance cycles:

1. Click the 'Refresh all' button
2. The widget will refresh all cycles and show progress
3. Click the 'Refresh this cycle' button to refresh the current cycle only

Bulk refresh requires that the FirstAML result field is configured on all work items.

How to use it

Add Compliance Case Insight to a portal page via the Sharedo Portal Designer (it appears under Alterspective / Insight). Configure it via the designer cog on the placed widget.

For the authoritative configuration fields and behaviour, see the component's designer help panel and the source linked in the footer.