Arkivering fra Elektronisk Stoffkartotek (IOM-725)

Innledning

Dette integrasjonsprosjektet automatiserer overføringen av HMS-dokumentasjon fra Workplace Safety (Elektronisk Stoffkartotek) til organisasjonens sentrale arkivløsning, Public 360. Løsningen er utviklet som en MuleSoft scheduler-drevet integrasjonsapplikasjon med navnet workplacesafety-p360-archiver, som orkestrerer forretningslogikk og datatransformasjon mellom fagsystemet og arkivet ved bruk av Public 360s Simple Integration Framework (SIF) API.

Gjennom bruk av standardiserte metadata-mappings definert av Sikt og Arbeidsutvalget (AU) for dokumentasjonsforvaltning, sørger integrasjonen for at tre spesifikke dokumenttyper — ferdigstilte substitusjonsvurderinger, registrerte eksponeringer med tilhørende sikkerhetsdatablader (SDS), og gjennomførte risikovurderinger — blir arkivert med korrekt juridisk og vitenskapelig kontekst. Teknisk realiseres dette ved å utnytte Public 360s Simple Integration Framework (SIF) API for automatisert opprettelse av saker og dokumentjournalføring.

Nøkkel info

Denne tabellen oppsummerer de arkitektoniske valgene for workplacesafety-p360-archiver, der S3 fungerer som et sikkert lagringspunkt for binærdata under prosessering, mens selve arkivreferansen (Source of Truth) forblir i Public 360.

Bakgrunn

Hovedformålet med løsningen er å sikre etterlevelse av norske regulatoriske krav, herunder Arkivloven og Noark 5-standarden. Digital transformasjon av kjemikaliehåndtering krever at data forblir tilgjengelige, autentiske og brukbare over svært lang tid. Dette er spesielt kritisk for eksponeringsregistre, hvor det foreligger et lovmessig krav om 60 års bevaringstid for å sikre dokumentasjonens integritet over generasjoner, for eksempel ved spørsmål om yrkessykdom.

Interessenter

Prosjektet er et samarbeid mellom flere sentrale aktører for å sikre standardisering i sektoren:

• Sikt (Kunnskapssektorens tjenesteleverandør): Koordinerer anskaffelse og standardisering av systemene.

• Arbeidsutvalget (AU) for dokumentasjonsforvaltning: Har definert de spesifikke metadata-mappingene som integrasjonen må følge for å sikre juridisk gyldighet.

• Lokale HMS-ansvarlige: Ansvarlige for datakvalitet i kildesystemet (Workplace Safety).

• Dokumentasjonsforvaltere: Mottakere av arkivverdig materiale i Public 360.

Brukerhistorie

Som organisasjon har vi behov for automatisk og sikker arkivering av HMS-dokumentasjon for å redusere manuelt arbeid og sikre juridisk etterlevelse. Løsningen dekker tre separate og uavhengige behov:

1. Jobb 1: Arkivering av registrerte eksponeringer med tilhørende sikkerhetsdatablader (SDS) for å ivareta ansattes rettigheter.

2. Jobb 2: Arkivering av ferdigstilte substitusjonsvurderinger for å dokumentere utfasing av farlige kjemikalier.

3. Jobb 3: Arkivering av gjennomførte risikovurderinger for å dokumentere virksomhetens forebyggende sikkerhetsarbeid.

Systemer/tjenester

Integrasjonsløsningen workplacesafety-p360-archiver fungerer som det sentrale bindeleddet mellom fagsystemet for kjemikaliehåndtering og organisasjonens arkivløsning. Løsningen består av følgende komponenter:

• Workplace Safety (WPS / Elektronisk Stoffkartotek): Fungerer som kildesystem (Source). Systemet forvalter data om kjemikalier, sikkerhetsdatablader (SDS) og gjennomførte vurderinger. Data hentes ut via Workplace Safety API (kilde for rådata om eksponeringer og kjemikalier), som gir tilgang til moduler for substitusjon, risikovurdering og eksponeringslogger.

• Public 360 (P360): Fungerer som målsystem (Target) for arkivering. Integrasjonen kommuniserer med P360 gjennom Simple Integration Framework (SIF) API (mottaker for journalføring). Dette rammeverket muliggjør automatisert opprettelse av saker og dokumentjournalføring i henhold til Noark-standarden. En teknisk nøkkelfunksjon er bruken av "recno" (record numbers) for å identifisere korrekte dokumentkategorier og statuser i arkivet.

• Amazon S3: Fungerer som midlertidig lagringsplass og backup for binærdata under prosessering.

• PdfGenerator (Java): En egendefinert Java-komponent basert på 'openhtmltopdf' som transformerer JSON-data til statiske PDF-filer for langvarig lagring.

• MuleSoft workplacesafety-p360-archiver: Selve integrasjonsmotoren, utviklet som en scheduler-drevet integrasjonsapplikasjon (Mule 4.9.17, samme som CloudHub-prod). Dets oppgave er å orkestrere prosessen: hente data fra Workplace Safety (via workplacesafety-ext-konnektoren), transformere metadata og filer (Base64-koding) via DataWeave, og utføre de nødvendige kallene mot P360 SIF API i riktig rekkefølge. API-et håndterer også logikk for feilhåndtering, spesielt viktig siden SIF API kan returnere HTTP 200 selv om en operasjon har feilet internt.

Detaljert liste av alle involverte systemer/tjenester — hva utveksler data? Fra hvor / til hvor?

Flytdiagram — Jobb 1

Diagrammet under viser hvordan komponentene fra tabellen over kalles i tid for én iterasjon av Jobb 1, fra scheduler-trigger via Workplace Safety og S3 til arkivering i Public 360, med audit-spor til oai-db og betinget feilrapport til Slack.

Data-flow 'Entity Relationship Diagram' (ERD) — Jobb 1

Diagrammet under viser hvordan datastrukturene transformeres fra Workplace Safety-eksponeringen via S3-mellomlagring til Public 360-saker og dokumenter, samt hvordan ConfigDbOrg leverer default-verdier og AuditInfoMap akkumulerer status på tvers av stegene.

Tilgangsstyring og logging

• Autentisering: Workplace Safety: OAuth 2.0 client-credentials per institusjon mot WPS' IdentityServer (https://auth-{institusjon}.workplacesafety.no/connect/token). Reelle scopes (per WPS-kontaktperson): exposure, sds, substitution, risk_assessments — bestilles per jobb. Per-institusjon klient-credentials (clientId og clientSecret) lagres kun i Sikts KeyService og hentes ut av workplacesafety-ext-konnektoren ved kjøretid; ingen WPS-credentials lagres i selve appens secure properties. Per-institusjon URL-er for token- og API-endepunkt lagres som felter (identityBaseUrl, apiBaseUrl) i configDb.orgs[i].ArkivWorkplacesafety[env], sammen med KeyService-instans-ID-en (instance); konnektorens operasjoner mottar disse per kall, ingen URL-er er hardkodet i appens konfig. P360 (via UH-arkiv-gatewayen): API-nøkkel-autentisering med X-Gravitee-Api-Key. Interne datastores (configDb, oai-db) bruker username/password fra Mule secure properties (secure2.properties med ${action} som dekrypteringsnøkkel).

• Logging: All aktivitet logges med en unik correlationId for å kunne spore en melding fra kilde til mål. Loggformat følger konvensjonen LEVEL [flow/step] action — key=val. Next: <hint>, slik at hver linje sier hva som skjer, hvilke nøkkelverdier som er involvert, og hva som forventes å skje videre. ERROR-linjer inkluderer i tillegg State: (hva fullførte før feilen) og Next: (recovery-handling) for raskere feilsøking.

• Audit-spor: Flyten skriver auditInfoMap til Sikts oai-db audit-tabell ved slutten av hver iterasjon, både ved suksess og feil. Kildesystemet (Workplace Safety) oppdateres ikke fra denne integrasjonen.

Forretningsregler

Mapping

Integrasjonen workplacesafety-p360-archiver benytter følgende logikk ved opprettelse av sak for eksponering:

Verdiene under er default-verdier per organisasjon, hentet fra configDb-noden ArkivWorkplacesafety.${mule_env}. De kan variere mellom tenants og overstyres per org.

• Tittel-generering: Sakstittelen bygges dynamisk ved å kombinere stoffnavn fra kildesystemet, år/måned for eksponering, og fritekst fra fagsystemets tittelfelt for å sikre unik identifikasjon.

• Arkivklassifisering: Alle eksponeringssaker klassifiseres med primærkode a.f.05 (Føre tilsyn med helse, miljø og sikkerhet) i arkivdel 3-integrasjon øvrig.

• Tilgangsbegrensning: På grunn av personopplysningsvern skjermes saken med tilgangskode U.off og hjemmel Offl § 13, og tilgang begrenses til gruppen Integrasjon stoffkartoteket.

• Mapping for eksponering (Jobb 1):

  • Tittel: {Substansnavn} - {ÅÅÅÅ MM} - {Tittelfelt}.

  • Skjerming: Alle eksponeringssaker merkes med tilgangskode U.off og hjemmel Offl § 13 jfr Fvl § 13.1.

  • Arkivkode: Benytter primærklassifisering a.f.05 (Helse, miljø og sikkerhet).

  • Kontakt-kort: Ikke implementert maskinelt. P360-saken skal lenkes til riktig kontakt (eksponert person) via et kontakt-kort, men dette krever oppslag på fødselsnummer som Sikt ikke har tilgang til i denne integrasjonskonteksten. Saker arkiveres dermed uten utfylt kontakt-kort, og må behandles manuelt for fullstendig arkiv-leveranse. Se "Pause-status og blokkerere".

• Datoformat: WPS returnerer exposureDate som MM/dd/yyyy (US-format), mens andre dato-felt i samme respons kommer som ISO-8601 — inkonsistens er rapportert til WPS via Jira-kommentar. Flyten parser exposureDate som MM/dd/yyyy og konverterer til arkivvennlig yyyy MM for sakstittelen. Spesialtegn som er ulovlige i P360-filnavn (< > : " / \\ | ? *) strippes fra tittel før den brukes som filnavn.

Behandlingstid/responstid og volum

• Volum: Estimert lavt volum per natt (typisk under 100 elementer per organisasjon).

• Frekvens: Nattlig batch-kjøring for å minimere belastning på API-ene i arbeidstiden.

Feilhåndtering, konsekvenser av feil og overordnet risikoanalyse

• SIF API Validering: SIF API kan returnere HTTP 200 med status: "success" selv når enkelte dokumentopplastinger har feilet (kun sak-opprettelsen lyktes). Flyten overstyrer derfor auditInfoMap.docsToP360.status til "error" dersom failedDocs > 0, slik at audit-loggen og Slack-varslingen ser den faktiske feilen. Original gateway-status bevares i gatewayStatus for sporbarhet.

• Slack-trigger på alle feilstier (K2): auditInfoMap sub-flowen sjekker datafilToS3.status, docsToP360.status og toppnivå auditInfoMap.status — slik at SIF-stille-feil-stien (200 + failedDocs > 0) faktisk fyrer Slack-alarm. Tidligere ble bare datafilToS3.status sjekket, og overstyringen i punktet over hadde derfor ingen Slack-effekt.

• Try på tenant- og item-nivå (K3): WPS-toppkallet er pakket i <try>/<on-error-continue> — ved KeyService- eller WPS-utfall fyrer én Slack-alarm per tenant og foreach hopper, slik at flyten fortsetter til neste org i stedet for å stoppe Jobb 1. Hvert item inni foreach er pakket i tilsvarende <try> — uventede feil i sub-flowene (PDF, S3, P360-retry uttømt) registreres som status: "error" i audit, fyrer Slack via K2, og foreach fortsetter til neste item.

• Graciøs WPS SDS-degradering: WPS SDS-API har observert intermittente HTTP 5xx (transient WPS-side-feil, edge-cases på productId, etc.). Sub-flowen vedleggToS3 har en egen <try> rundt SDS-metadata-oppslag og SDS-nedlasting med on-error-continue som lister alle WPS-connector-feiltyper eksplisitt. Ved enhver WPS-feil settes sdsAvailable=false og item-en arkiveres uten SDS-vedlegg. Eksponeringen selv er arkiveringspliktig (60 års bevaringstid) og bør lagres til P360 uavhengig av om SDS-vedlegget kan hentes — vedlegget kan re-arkiveres senere når WPS er friskt. S3- og file:write-feil propagerer fortsatt opp til item-level try (de indikerer bredere infrastrukturproblem).

• Retry-mekanisme: SIF-kallet i docsToP360 har <until-successful> med maxRetries=3, millisBetweenRetries=5000 (totalt ~15 s worst-case per item). Ved tekniske feil (nettverk/timeout) forsøkes på nytt umiddelbart; vedvarende feil propagerer til item-level try beskrevet over.

Kommentarer

• PDF/A: Det bør vurderes å oppgradere PDF-generatoren til å produsere PDF/A-standard for å garantere lesbarhet i hele 60-årsperioden.

• IntArk: Sikt-fellestjenesten IntArk benyttes ikke i denne integrasjonen — P360-trafikk går via UH-IT-gatewayen gw-sikt.intark.uh-it.no (UH-IT sin Gravitee-baserte API-gateway, ikke Sikts IntArk-tjeneste). Status for Sikt-IntArk som fellestjeneste er ikke verifisert i denne dokumentasjonen.

• Kontakt-kort og fnr-tilgang: P360-arkivposter for eksponering bør normalt inneholde et kontakt-kort som lenker saken til den eksponerte personen. Dette krever fødselsnummer-oppslag som Sikt ikke har tilgang til i denne integrasjonskonteksten. Behandling som mulig retning videre: enten skaffe en autorisert kanal for fnr-oppslag (krever rettslig grunnlag/avtale med institusjonene), eller akseptere at kontakt-kortet fylles ut manuelt i en etterprosess. Se "Pause-status og blokkerere".

Relaterte ressurser

• Jira: IOM-725 — overordnet migrerings- og utviklingsticket

• Jira: IOM-811 — migrering fra CloudHub 1.0 til Docker og Platon

• Confluence: Migrering fra CloudHub 1.0 til Docker — tekniske notater — A-til-Å teknisk dokumentasjon av CE/Docker-migreringen (gotchas, Dockerfile, neste steg mot Platon)

• Miro-board (Agata): https://miro.com/app/board/uXjVJhoc7pg=/