Creditsafe Monitoring Rescreening Provider

Version 1

🎯 Functional documentation

This rescreening provider only rescreens the dossiers of companies that actually changed.

Creditsafe Global Monitoring keeps a portfolio of companies for the white label. Whenever Creditsafe registers a change on one of those companies (new director, new address, insolvency, ...), it records a notification event. On every run, this provider asks Creditsafe which companies changed since the previous run, looks up the dossiers of those companies, and throws the automation event only for them. Which event that is, is up to you: it is the value you configure in the AUTOMATION_IDENTIFIER setting, for example RESCREENING_AUTOMATION.

Compared to the Basic rescreening provider, which rescreens every dossier matching the dossier filter on every run, this provider is a delta rescreening: far fewer dossiers are touched, and far fewer due diligence provider calls are made.

🧩 This provider never works on its own

Event-based monitoring is a chain of four configuration items. They are configured in different places, but they are one feature: if one of them is missing or misaligned, the whole flow silently stops working.

#	What	Where	What it does	If it is missing
1	Creditsafe party provider (V7)	Provider	Imports the company and stores its Creditsafe identifier (Connect ID)	Companies have no Connect ID, so they can never be registered nor found back
2	Creditsafe monitoring provider	Provider	Holds the portfolio and the connection to Creditsafe Global Monitoring	The two actions fail and this rescreening provider reports an error instead of rescreening
3	CreditsafeMonitoringRegister	Action, e.g. on DOSSIER_APPROVED	Puts the dossier's companies into the portfolio	Nothing is monitored, so Creditsafe never reports a change and nothing is ever rescreened
4	CreditsafeMonitoringDeregister	Action, e.g. on DOSSIER_ARCHIVED	Takes the companies out of the portfolio again	Companies stay monitored (and billed) forever, and keep triggering rescreenings

:::warning Configure all four, pointing at the same monitoring provider The two actions and this rescreening provider each name the Creditsafe monitoring provider they belong to, in their own MONITORING_PROVIDER_IDENTIFIER setting. That is what allows one white label to run several portfolios, each with its own set of four. Configuring the provider without the actions monitors nothing; configuring the actions without the rescreening provider pays for change events nobody looks at; and pointing them at different providers is the quietest failure of all — see the warning under Settings. :::

🔄 How the flow works

1. A company enters a dossier. The advisor (or an automation) selects the company through the Creditsafe party provider. That provider stores the Creditsafe Connect ID on the party.
2. The dossier reaches its final status. The CreditsafeMonitoringRegister action registers the dossier's company parties in the Creditsafe portfolio. From that moment on, Creditsafe watches them. Registering a company that is already in the portfolio is harmless — it is not registered (nor billed) twice.
3. Creditsafe detects a change on a monitored company and records a notification event on the portfolio.
4. This provider runs on its schedule (typically nightly), asks Creditsafe for all notification events in the window, and translates the returned companies back to Harmoney parties and their dossiers.
5. The dossiers are filtered with the DOSSIER_FILTER and, for each remaining dossier, the automation event configured in AUTOMATION_IDENTIFIER is thrown. From here on it behaves like any other rescreening: the actions linked to that event (status transition, due diligence checks, RBA calculation, ...) do the actual work.
6. The dossier is archived. The CreditsafeMonitoringDeregister action removes the companies from the portfolio, but only the ones that are not used by any other dossier that is not yet archived.

The Connect ID is what ties everything together

A company can only be monitored if Harmoney knows its Creditsafe Connect ID. That identifier is written by the Creditsafe party provider when the company is imported, and it is stored in one of two places:

Creditsafe party provider setting	Where the Connect ID is stored	What to configure on the monitoring provider
metadataKeyForExternalRefIdentifier is set	In that metadata field of the party	METADATA_KEY_IDENTIFIER = the same key
metadataKeyForExternalRefIdentifier is empty	In the party's external reference field	Leave METADATA_KEY_IDENTIFIER empty

:::danger Use exactly the same key on both providers The monitoring provider reads the Connect ID from where you tell it to read, without falling back to the other location. A mismatch means: no company is ever registered, and changed companies are never matched back to a party. Nothing fails visibly — it simply does nothing. :::

Companies that were not imported from Creditsafe (no Connect ID) are skipped. They are not an error, they are just not monitored.

⚙️ Configuration

• Implementation class: eu.myharmoney.app.providers.dossier.CreditsafeMonitoringRescreeningProvider

Settings

• MONITORING_PROVIDER_IDENTIFIER (required): the identifier of the Creditsafe monitoring provider whose portfolio the notification events are read from. When the configuration is saved, Harmoney checks that a provider with this identifier exists in the organization.
• AUTOMATION_IDENTIFIER (required): the event thrown for every dossier to rescreen. Link your rescreening actions to this event.
• CRON_SCHEDULE (required): "a b c d e", where a = minute, b = hour, c = day of month, d = month, e = day of week. An '*' means not specified. It also determines the default size of the events window (see below).
• SYSTEM_USER (required): the gateway user shown in the activity tab as the author of the automation.
• SUPPORTED_FSP (required): the financial service providers this rescreening applies to.
• DOSSIER_FILTER (required): only dossiers matching this filter are rescreened, see Dossier Filter. Typically the final statuses, e.g. APPROVED / REJECTED.
• associatedPartyTypes: which associations between the changed company and a dossier are taken into account. Any associated party type is accepted and it defaults to CLIENT when the key is omitted, the same default as the monitoring provider; an empty list is rejected. Keep it aligned with the monitoring provider's setting: resolving an association type that is never registered means waiting for change events that are never raised.
• overruleCachedResultsForDueDiligenceProviders (required): see Due diligence results and caching below. An empty list is allowed and means "always reuse cached results".
• EVENTS_LOOKBACK_DAYS: recovery lever only. Overrides how many days back events are requested (maximum 31), to catch up after an outage. Put it back to empty afterwards: there is no de-duplication of events, so a permanently enlarged window rescreens the same changes over and over.
• EVENTS_OVERLAP_MARGIN_HOURS: how much consecutive windows overlap so no change can fall between two runs. Defaults to 1 hour.

:::danger All three configurations must name the same identifier This provider, the register action and the de-register action must all point at the same monitoring provider. If the actions write to one portfolio while this provider reads events from another, both sides succeed and the result is indistinguishable from a window in which nothing changed. Nothing validates this — only the existence of the named provider is checked at save time. :::

The events window

You do not have to configure the window. It is derived from the CRON_SCHEDULE, extended with the overlap margin:

Schedule	Events requested for
Daily	the last day + 1 hour
Weekly	the last 7 days + 1 hour
Monthly or yearly	the last 31 days + 1 hour

The window is capped at 31 days. This is a safety limit in Harmoney, so that a mistake in the cron schedule can never make the provider request an unbounded range of events.

When a run cannot fetch the changed companies — Creditsafe unreachable, or the named monitoring provider not found — that window is lost, because the next run moves on and never asks for it again. The run logs a failed rescreening event for the white label naming the exact window it could not screen. That is your signal to set EVENTS_LOOKBACK_DAYS once, wide enough to cover the gap, and to clear it again afterwards.

:::note A quiet window logs nothing A white label for which nothing changed, or whose changed companies resolve to no dossier, produces no rescreening event at all. Only white labels with at least one dossier to rescreen get the "started rescreening of N dossiers" event. The absence of that event is normal; a failed rescreening event is the signal that something went wrong. :::

:::tip Keep the schedule and the window in sync If you change the cron schedule to run less frequently, the window follows automatically. If you pause the provider for a while, use EVENTS_LOOKBACK_DAYS once to catch up, then clear it again. :::

Due diligence results and caching

Every due diligence provider caches its results for the number of minutes in its DUE_DILIGENCE_RESULT_EXPIRATION setting. The default is 1380 minutes (23 hours) — deliberately just under a day, because it was designed for a daily rescreening of everything, where a cached result would otherwise block the new check.

:::info Always revisit DUE_DILIGENCE_RESULT_EXPIRATION after configuring this provider With event-based monitoring, that short expiration is no longer needed and only costs money: the rescreening already knows which companies changed, so there is no reason to re-check the unchanged ones every 23 hours.

Recommended configuration:

1. On each due diligence provider, raise DUE_DILIGENCE_RESULT_EXPIRATION to a much longer period (for example one month, 43200 minutes). Unchanged companies then keep reusing their cached result.
2. On this rescreening provider, list the due diligence providers that must deliver fresh data for a changed company in overruleCachedResultsForDueDiligenceProviders. For those providers the cached result of the changed party is invalidated, so the rescreening always performs a real, new check — regardless of the expiration time.

The result: a daily rescreening that only spends provider calls on companies Creditsafe reported as changed. :::

Not every due diligence provider is relevant for a company change. Only list the ones that are, otherwise you pay for fresh checks you did not need.

Automation actions

Like every rescreening provider, this provider only selects dossiers and throws an event. Configure the actions that must run for a rescreened dossier on the event you configured in AUTOMATION_IDENTIFIER. See the Perpetual KYC use case for what such an automation typically contains.

Example

{
    "MONITORING_PROVIDER_IDENTIFIER": "Creditsafe monitoring",
    "AUTOMATION_IDENTIFIER": "RESCREENING_AUTOMATION",
    "CRON_SCHEDULE": "0 4 * * *",
    "SUPPORTED_FSP": "$vault{<client>_SUPPORTED_FSP}",
    "SYSTEM_USER": "$vault{<client>_SYSTEM_USER}",
    "DOSSIER_FILTER": {
        "status": [
            "APPROVED",
            "REJECTED"
        ]
    },
    "associatedPartyTypes": [
        "CLIENT"
    ],
    "overruleCachedResultsForDueDiligenceProviders": [
        "Creditsafe Due Diligence Provider"
    ]
}

Settings: schema

Settings Configuration

Examples