Source-derived document; review findings and open questions with the application owner.

08 — Integration catalogue

Purpose and scope

The integration surface supports the processing, assessment, movement, financial-guarantee, audit, and reporting aspects of import notifications. The system exchanges notification data with persistence repositories, translates stored-procedure result sets for progress views, raises and handles domain events, and exposes report-oriented database views and caches. The evidence establishes several internal integration relationships, but does not provide a complete inventory of deployed endpoints, message brokers, scheduled jobs, or third-party services. E0010E0008E0262

The business purpose of these integrations is to keep the notification record and its related assessment information usable across operational activities. The represented data includes notifications, movements, shipments, facilities, competent authorities, waste codes, carriers, assessments, consent decisions, financial guarantees, comments, audit results, and reporting projections. These are evidenced data shapes and storage mappings; completeness, uniqueness, and end-to-end consistency remain unresolved. E0006E0010E0156

Actors and integration participants

The principal actors visible in the source are:

Provenance gap: This passage has no artifact/source citation.

• External or internal notification users, who create, submit, edit, and comment on notifications and movements.
• Assessment officers, who record consent, refusal, objection, withdrawal, and financial-guarantee decisions.
• Internal users, whose identity and competent-authority context can affect access to notification information and reporting.
• Request handlers and domain services, which orchestrate commands and queries.
• Repositories and the persistence context, which read and write notification, assessment, movement, comment, and guarantee records.
• SQL Server procedures, views, and caches, which provide progress and reporting projections.
• Localization resources, which supply validation and display messages.

Provenance gap: This passage has no artifact/source citation.

The internal-user relationship is directly evidenced by comment-user lookup and audit behavior: comment records yield user IDs, which are resolved to internal users and mapped to full names; status-audit records include the acting user ID. E0010

A competent authority is represented by an explicit enumeration containing England, Scotland, Northern Ireland, and Wales. Notification-number generation also uses a SQL Server sequence name derived from the competent authority. The evidence therefore supports authority-specific numbering as an integration dependency, but does not establish how the authority is selected or whether sequence allocation is concurrency-safe. E0006E0008

Integration relationships

The following diagram shows relationships supported by the supplied implementation evidence. Dashed edges identify links whose downstream implementation or runtime configuration is not available.

Provenance gap: This passage has no artifact/source citation.

flowchart LR
    U[User or assessment officer] --> H[Request handlers]
    H --> D[Domain entities and state machines]
    H --> R[Repositories / persistence context]
    R --> DB[(SQL Server)]
    D -->|domain event| EH[Event handlers]
    EH --> R
    H --> P[Notification progress service]
    P --> SP[uspNotificationProgress]
    SP --> DB
    DB --> V[Reporting views and caches]
    V -. scheduled or operational refresh unknown .-> RC[Reports consumers]
    H -. authorization pipeline not shown .-> A[Identity / access services]

Observed behavior shows handlers calling repositories, mappers, calculators, and SaveChangesAsync(). Most repository Add methods only add to an Entity Framework DbSet; whether persistence occurs immediately or at a later unit-of-work boundary varies by path. E0262E0482

Open question for Harten: the inspected artifacts are the handler and repository analyses in E0262 and E0482. Evidence needed to resolve this is the dependency-registration configuration, unit-of-work implementation, transaction boundary, and representative callers for each repository method.

Provenance gap: This passage has no artifact/source citation.

Notification and assessment integration

Notification submission is orchestrated by SubmitNotificationHandler, which retrieves an assessment, invokes assessment.Submit(progressService), saves changes, and returns the assessment identifier. The assessment state machine is reported to raise an ImportNotificationSubmittedEvent when the submit trigger is fired. The concrete status transition visible in the supplied evidence is from NotificationReceived to AwaitingPayment; Submitted is also represented in the state hierarchy, but should not be treated as the concrete destination without further evidence. E0482E0508

The event-driven boundary is demonstrated by NotificationCreatedEventHandler, which creates a NotificationAssessment and a FinancialGuaranteeCollection, adds both to the context, and saves. SharedUserAdded similarly constructs a shared-user record using the event notification ID, user ID, and current system time before saving. These handlers show internal event consumption rather than an externally demonstrated message-bus integration. E0008E0482

Assessment decisions include consent date ranges and conditions. ConsentHandler invokes the assessment consent operation with a DateRange, conditions, and a consent date, then saves and returns true. The handler therefore integrates the request message with the assessment aggregate and persistence context; validation of date ordering and consent conditions is not visible in the cited handler evidence. E0010E0482

Financial guarantees form a separate but related integration. Creation persists an ImportFinancialGuarantee; separate handlers exist for approval, refusal, and release. Approval carries a reference, refusal carries a reason, and the observed release call carries no additional decision detail. The domain state configuration shows ApplicationReceived progressing to ApplicationComplete, then to Approved or Refused, with Approved progressing to Released; a direct ApplicationComplete to Released path is not evidenced. E0010E0508

Movement and shipment integration

Movement creation integrates notification state, shipment limits, movement counts, consent, financial guarantees, and movement-number generation. The factory is reported to check movement-date validity, maximum movement count, active loads, remaining shipment quantity, Consented notification status, an approved financial guarantee, consent-period validity, and finally movement-number generation. The evidence does not establish that these separate reads and checks are transactionally atomic. E0372

Movement state changes include submission, receipt, completion, rejection, cancellation, and partial rejection. External receipt creates a MovementReceipt; external completion creates a MovementCompletedReceipt. Internal completion checks that the completion date is not before the receipt date, while the supplied evidence does not show the same ordering check on external completion. E0013

A database-side movement integration also exists. uspUpdateExportMovementData updates movement fields within a transaction, including prenotification date, statistics marking, comments, and selected receipt, rejection, partial-rejection, and operation-receipt records. When a movement is received, the procedure requires receipt-related data; when rejected, it requires rejection data and removes incompatible receipt-related records. E0218

Open question for Harten: the inspected artifacts are Movement.cs, MovementFactory.cs, uspUpdateExportMovementData.sql, and the movement repository analysis in E0013, E0372, and E0218. Evidence needed is the application path that invokes the procedure, transaction coordination between ORM and SQL calls, and database constraints governing movement numbers and related rows.

Provenance gap: This passage has no artifact/source citation.

Reporting and progress integration

NotificationProgressService calls [Notification].[uspNotificationProgress] @NotificationId, translates five result sets, and closes the database connection in a finally block. This establishes a raw-SQL integration for progress information. It does not establish the schema or semantic guarantees of all five result sets, nor the behavior if a result set is missing or has an unexpected shape. E0008

The reporting database layer contains views combining export and import notification records. The notification report view uses UNION ALL, exposes notification identity, status, authority, dates, quantities, shipments, consent information, and charges, and uses different join requirements for export and import rows. The export-stats view includes only movements whose status is 3 or 4, converts quantities based on unit identifiers, and derives recovery or disposal codes according to notification type. E0081

The report-cache procedure deletes and repopulates the Freedom of Information, shipments, and producer caches. It also identifies movement-audit records whose user is not present in Person.InternalUser and marks matching shipment-cache rows as actioned by an external user. This is an evidenced transformation, but the trigger or schedule that invokes the cache refresh is not supplied. E0218

Open question for Harten: the inspected artifact is uspUpdateReportCache.sql and the report-view analysis in E0218 and E0081. Evidence needed is the job, deployment, or application call that executes the procedure, together with refresh frequency, failure handling, and report-consumer contracts.

Provenance gap: This passage has no artifact/source citation.

Validation, localization, and error boundaries

Waste-type validation messages exist for Basel/OECD, EWC, H, UN, waste-name, and Y-code validation. The resource designer exposes these messages through ResourceManager.GetString(...), but no validator implementation or conditional logic consuming the keys is included. The messages therefore evidence a localization integration, not enforcement of the corresponding rules. E0010

Waste-code retrieval follows a repository–mapper–handler path: GetAllWasteCodesHandler awaits GetAllWasteCodes(), maps the results to WasteCodeData, and returns a list. The available evidence does not establish filtering, ordering, caching, or uniqueness of returned codes. E0010

Several boundaries have explicit fallback behavior. For example, some missing-record queries return empty data objects or null, while GetNotificationIdByNumberHandler catches Exception around access checks and returns null. This broad catch means database, configuration, or programming failures could also be suppressed; it should not be documented as handling authorization failures only. E0010E0008

Requirements

INT-08-REQ-001 — Persist assessment consent

The system shall accept a consent operation containing a notification identifier, consent validity start and end dates, conditions, and consent date, invoke the assessment consent operation, persist the change, and return a successful result when the operation completes. This requirement is based on observed ConsentHandler behavior; validation rules for the supplied values remain outside the evidence. E0010

INT-08-REQ-002 — Persist financial-guarantee decisions

The system shall support separate financial-guarantee creation, approval, refusal, and release operations. Approval shall carry an approval reference, refusal shall carry a refusal reason, and release shall persist the release operation represented by the handler. The permitted state transitions shall distinguish approval before release unless contrary domain evidence is provided. E0010E0508

INT-08-REQ-003 — Expose progress through the database procedure

The system shall request notification progress by notification identifier through [Notification].[uspNotificationProgress], translate the expected five result sets, and close the database connection after processing, including when processing fails. The result-set schema and failure contract require confirmation. E0008

INT-08-REQ-004 — Refresh report projections

The reporting integration shall refresh the evidenced Freedom of Information, shipment, and producer cache projections from their report sources and apply the external-user audit marking described by uspUpdateReportCache. Invocation schedule, atomicity, and recovery behavior shall be confirmed before treating this as an operational guarantee. E0218

Characterisation scenarios — candidates

INT-08-SC-001 — Consent persistence

Provenance gap: This passage has no artifact/source citation.

• Given an existing notification assessment and a consent request containing a date range and conditions
• When ConsentHandler.HandleAsync processes the request
• Then the assessment consent operation is invoked, changes are saved, and the handler returns true. E0010

INT-08-SC-002 — Progress retrieval

Provenance gap: This passage has no artifact/source citation.

• Given a notification identifier and a database containing the progress procedure
• When NotificationProgressService requests progress
• Then the procedure is called with that identifier, five result sets are translated, and the connection is closed in the completion path. E0008

INT-08-SC-003 — Report-cache refresh

Provenance gap: This passage has no artifact/source citation.

• Given report source rows and matching movement-audit records for external users
• When uspUpdateReportCache executes
• Then the relevant caches are repopulated and matching shipment-cache rows are marked ActionedByExternalUser = 'Y'. E0218