Statistikk Skill

Expert knowledge of statistics publishing for issued A1 certificates to the data warehouse.

Quick Reference

Key Components

Component	Location	Purpose
UtstedtA1Service	statistikk/src/main/java/.../utstedt_a1/service/	Creates and sends A1 statistics messages
UtstedtA1EventListener	statistikk/src/main/java/.../utstedt_a1/service/	Listens for vedtak events
UtstedtA1AivenProducer	statistikk/src/main/java/.../utstedt_a1/integrasjon/	Kafka producer for Aiven
UtstedtA1AdminController	statistikk/src/main/java/.../utstedt_a1/api/	Admin endpoint for republishing
UtstedtA1Melding	statistikk/src/main/java/.../utstedt_a1/integrasjon/dto/	Kafka message DTO

Kafka Topics

Topic	Environment	Purpose
teammelosys.melosys-utstedt-a1.v1	prod-gcp	A1 issued statistics
teammelosys.melosys-utstedt-a1.v1-q1	dev-gcp (q1)	A1 issued statistics
teammelosys.melosys-utstedt-a1.v1-q2	dev-gcp (q2)	A1 issued statistics
teammelosys.melosys-utstedt-a1.v1-local	local	A1 issued statistics

Processing Flow

1. VedtakMetadata is saved → VedtakMetadataLagretEvent published
   ↓
2. UtstedtA1EventListener receives event (@Async, @TransactionalEventListener)
   ↓
3. UtstedtA1Service.sendMeldingOmUtstedtA1(behandlingID) called
   ↓
4. Check if a1Produseres(behandlingsresultat) is true
   ↓
5. Build UtstedtA1Melding with:
   - Serienummer: saksnummer + behandlingId
   - Artikkel: Mapped from LovvalgBestemmelse
   - Periode: From lovvalgsperiode
   - UtsendtTilLand: From trygdemyndighetsland
   - TypeUtstedelse: FØRSTEGANG, ENDRING, or ANNULLERING
   ↓
6. Validate against JSON schema (a1-utstedt-schema.json)
   ↓
7. UtstedtA1AivenProducer publishes to Kafka topic

Debugging

For symptom-by-symptom troubleshooting (message not published, wrong article, missing utsendtTilLand, schema validation failures), diagnostic SQL queries, log strings to grep for, and curl/Kafka console-consumer commands for republishing and inspecting the topic, see references/debugging.md.

UtstedtA1Melding Schema

Message Structure

{
  "serienummer": "MEL-123456",
  "saksnummer": "MEL-123",
  "behandlingId": 456,
  "aktorId": "1234567891234",
  "artikkel": "12.1",
  "periode": {
    "fom": "2024-01-01",
    "tom": "2024-12-31"
  },
  "utsendtTilLand": "SE",
  "datoUtstedelse": "2024-01-15",
  "typeUtstedelse": "FØRSTEGANG",
  "meldingOpprettetTidspunkt": "2024-01-15T10:30:00.000Z"
}

Field Descriptions

Field	Type	Required	Description
serienummer	String	Yes	Unique ID: saksnummer + behandlingId
saksnummer	String	Yes	Fagsak saksnummer (MEL-*)
behandlingId	Long	Yes	Treatment ID
aktorId	String	Yes	Person's aktør-ID (13 chars)
artikkel	String	Yes	EU regulation article. On the Java side this is a Lovvalgsbestemmelse value object that serializes (via @JsonValue on getKode()) to the string code on the wire
periode	Object	Yes	A1 validity period (fom/tom)
utsendtTilLand	String	Conditional	ISO-2 country code (for Art. 12)
datoUtstedelse	Date	Yes	Date of issuance/annulment
typeUtstedelse	String	Yes	FØRSTEGANG, ENDRING, ANNULLERING
meldingOpprettetTidspunkt	DateTime	Yes	Message creation timestamp

Artikkel Values

Mapped from EU Regulation 883/2004:

Value	Description
11.3a	Work in one member state (employed or self-employed)
11.3b	Civil servant (tjenestemann)
11.4	Work on a ship under a member state's flag (flaggstatsprinsippet)
11.5	Flight or cabin crew (flyvende/kabinpersonell)
12.1	Posted workers (employees)
12.2	Posted workers (self-employed)
13.1	Work in two or more states (employee)
13.2	Work in two or more states (self-employed)
13.3	Work in two or more states (mixed)
13.4	Civil servants in multiple states
16	Exceptions/agreements

The JSON schema enum (a1-utstedt-schema.json) accepts all values above, including 11.5. The Java Lovvalgsbestemmelse value object (see below) currently only maps 11.3a, 11.3b, 11.4, 12.1, 12.2, 13.1-13.4, and 16 — so a 11.5 value would need to be added to the enum before it can be produced on the wire.

TypeUtstedelse Values

Value	Description
FØRSTEGANG	First-time issuance
ENDRING	Modification of existing A1
ANNULLERING	Annulment of existing A1

Special Handling

UK/Great Britain Cases

For UK-related cases (EFTA Storbritannia convention), messages are sent twice:

1. Once with the GB-specific bestemmelse
2. Once with the standard 883/2004 equivalent

The gate is whether the lovvalgsperiode's bestemmelse is one of the Lovvalgbestemmelser_konv_efta_storbritannia values. When it is, lagMelding builds the article via Lovvalgsbestemmelse.avKonvensjonEftaStorbritannia(...); otherwise via Lovvalgsbestemmelse.av(...). Actual UtstedtA1Service source:

var erStorbritannia = Arrays.stream(Lovvalgbestemmelser_konv_efta_storbritannia.values())
    .anyMatch(bestemmelse -> bestemmelse == lovvalgsbestemmelse);

if (erStorbritannia) {
    sendMeldingOmUtstedtA1(behandlingsresultat); // GB-specific article (avKonvensjonEftaStorbritannia)
}
sendMeldingOmUtstedtA1(behandlingsresultat);     // standard 883/2004 article (av)

UtsendtTilLand Logic

Land is only included for certain articles:

// Land should NOT be sent for:
// - Article 13 (multiple countries, no single destination)
// - Article 11 (unless also 12 - edge case)
private boolean landSkalIkkeSendes(Lovvalgsperiode lovvalgsperiode) {
    return lovvalgsperiode.erArtikkel13()
        || (lovvalgsperiode.erArtikkel11() && !lovvalgsperiode.erArtikkel12());
}

Admin API

Republish Single Treatment

POST /admin/utstedtA1/{behandlingID}/publiserMelding
Authorization: Bearer {token}

Republish Multiple Treatments

POST /admin/utstedtA1/publiserMelding/eksisterendeBehandlinger?fom=2024-01-01
Authorization: Bearer {token}

Response:
{
  "sendteBehandlinger": [123, 456],
  "feiledeBehandlinger": [789]
}

Configuration

Kafka Configuration

kafka:
  aiven:
    a1-utstedt:
      topic: ${KAFKA_AIVEN_UTSTEDT_A1_TOPIC:teammelosys.melosys-utstedt-a1.v1}

Producer Configuration

@Bean
@Qualifier("aivenUtstedtA1")
KafkaTemplate<String, UtstedtA1Melding> aivenKafkaTemplate

JSON Schema Validation

Messages are validated against: utstedt_a1/a1-utstedt-schema.json

Schema enforces:

• Required fields presence
• Field types and formats
• Valid enum values for artikkel and typeUtstedelse
• Date formats (ISO-8601)
• String length limits

Integration Points

Event Source

Triggered by: VedtakMetadataLagretEvent

• Published when vedtak metadata is saved
• Event contains behandlingID

Dependencies

Service	Purpose
BehandlingsresultatService	Fetch behandlingsresultat
LandvelgerService	Get trygdemyndighetsland
VedtakMetadataRepository	Query existing vedtak for republishing

Related Skills

• vedtak: VedtakMetadata triggers statistics
• behandlingsresultat: Source of A1 data
• lovvalg: Lovvalgsperiode and articles
• kodeverk: Land_iso2, Lovvalgbestemmelser enums