Gå til innhold

KAI-regler

KAI-regler er en regelmotor for time-registreringer. En regel består av betingelser (IF), handlinger (THEN) og et omfang (WHO). Reglene kjøres som en del av valideringsflyten i Time-modulen, og kan enten validere en registrering (vise advarsel, feil eller blokkere innsending) eller utføre automatisk registrering av timer basert på AI-instruksjon.

Reglene defineres i fanen KAI-regler under Innstillinger → Systeminnstillinger → KAI-administrasjon. Du kan opprette regler fra grunnen, importere ferdige maler, eller la KAI foreslå regler fra historiske data (kai-ml-oppdaging.md).

Tilgang

Hvem Hva trengs
Rolle Administrator (adminPage: true på ruten)
Modul Innstillinger (moduleId 99) — [ActivateService, ModuleGuard]
Autentisering API-endepunktene under api/KAIRules krever [Authorize]

Ruten er definert i setting-routing.module.ts:34, og selve regel-fanen i kai-admin.component.ts:18 (fane-id kaiRules).

Sånn ser siden ut

Fanen viser et søkbart rutenett over alle regler i selskapet. Kolonnene er definert i kai-rules.component.ts:64:

Kolonne Innhold
Status Aktiv eller Inaktiv (badge)
Regelnavn Navn + beskrivelse
Type Validering eller Auto-registrering
Modul Kategoriens modulnavn
Betingelser Antall betingelser på regelen
Omfang Alle ansatte, Ansattgruppe, Individuell ansatt (eller kombinasjon)
Prioritet Heltall (lavere tall = høyere prioritet)
Opprettet Dato/tid
Handlinger Rediger, Aktiver/Deaktiver, Kopier, Slett

Over rutenettet ligger tre knapper (kai-rules.component.html:5):

  • Opprett ny regel — åpner regel-editoren i en sidepanel-drawer.
  • Oppdag regler fra ML — navigerer til KAI ML-oppdaging.
  • Importer maler — åpner mal-katalogen og lar deg velge maler du vil legge inn som aktive regler i selskapet ditt.

Tre nedtrekksfiltre over rutenettet (kai-rules.component.html:53):

  • Modul — filtrer på kategori-modul (AllModules som standard).
  • Type — Validering eller Auto-registrering.
  • Status — Aktiv eller Inaktiv.

regel-fanen med rutenett, knapper og filtre synlig

Regelmodell

Hver regel (RuleDto i kai-rules.service.ts:36) har:

Felt Type Standard Validering
Regelnavn (RuleName) tekst tom Validators.required
Regelnavn engelsk (RuleNameEn) tekst tom –
Beskrivelse (Description) tekst tom –
Beskrivelse engelsk (DescriptionEn) tekst tom –
Kategori (CategoryID) nedtrekk – Validators.required
Regeltype (RuleType) nedtrekk Validation Validators.required
Vanskelighetsgrad (Difficulty) tekst medium –
Mal (IsTemplate) avkrysning false –
Aktiv (IsActive) avkrysning true –
Prioritet (Priority) tall 1 Validators.required, Validators.min(1)

Validering og standardverdier kommer fra FormBuilder-oppsettet i kai-rule-editor.component.ts:66.

Regeltyper

Verdi Visningsnavn Hva regelen gjør
Validation Validering Sjekker time-registreringer mot betingelsene og kjører en handling (advarsel/feil/blokkering/forslag) når de stemmer
Aggregation Aggregering Teller eller summerer føringer per periode (uke/dag, evt. per ansatt) og varsler når aggregatet avviker fra forventet verdi
AutoRegistration Auto-registrering Utfører automatisk registrering av timer basert på AI-instruksjon (se AutoRegister-handling under)

Verdiene kommer fra kai-rule-editor.component.ts:84.

Aggregeringsregler (antall/sum per periode)

En vanlig valideringsregel ser på én føring av gangen. En aggregeringsregel ser på grupper av føringer – f.eks. «hvor mange overordnede vakter er ført denne uka». Brukes til kontroller som ikke kan avgjøres rad for rad:

  • Nøyaktig én overordnet vakt per uke (antall = 1, varsle uker uten vakt).
  • To montørvakter per uke (antall = 2).
  • Minimum ferietimer per dag (sum ≥ 7,5 per ansatt/dag).

Betingelsene (IF) velger hvilke føringer som telles (typisk Lønnsart = en bestemt vaktart). Aggregeringen styres av:

Felt Forklaring
Grupper per Uke / Ansatt + uke / Dag / Ansatt + dag
Aggregat Antall føringer eller Sum av timer
Forventet (operator) =, ≠, <, >, ≤, ≥ – gruppen er gyldig når aggregatet oppfyller dette
Forventet verdi Tallet operatoren sammenlignes mot
Flagg perioder uten treff Ved ukegruppering: uker i perioden uten en eneste matchende føring flagges (f.eks. uke uten vakt)

Ferdige aggregeringsmaler ligger i Timekontroll-katalogen og importeres per selskap (se Slik importerer du maler). Lønnsartkodene i malene er 4-sifret og justeres etter import.

Datofeltet (wrDate) lagres som «ÅÅÅÅMMDD». Regelmotoren tolker dette eksplisitt, slik at ukedag-baserte betingelser (f.eks. «vakt skal være på torsdag») og uke-/dag-grupperingen fungerer.

Betingelser (IF)

En betingelse består av felt, operator og verdi, koblet sammen med logisk operator (OG / ELLER). En regel kan ha flere betingelser, og betingelser med samme GroupIndex evalueres som en gruppe.

Tilgjengelige felt (kai-rules.service.ts:241) — mappet til wv_time_wagereg-tabellen i Time-modulen:

  • Time-registrering: Timekode, Lønnsnummer, Dato, Ukedag, Ansattnummer
  • Timer og tid: Antall timer, Totale timer, Daglige timer, Starttid, Sluttid, Overtid denne uken
  • Prosjekt og kostnadssted: Arbeidsordre, Prosjekt, Avdeling, Aktivitet
  • Beskrivelse: Beskrivelse av registreringen
  • Status og godkjenning: Godkjent, Eksportert, Godkjent av, Kontrollert, Kontrollert av
  • Validering / avledet: Er helligdag, Er helg, Tidsoverlapp, Mangler obligatoriske felt, Antall barn under 12
  • Revisjon: Registrert av, Registrert dato, Endret av, Endret dato

Operatorer (kai-rules.service.ts:252):

Er lik, Er ikke lik, Større enn, Mindre enn, Større enn eller lik, Mindre enn eller lik, Er i listen, Er ikke i listen, Inneholder, Starter med, Starter ikke med.

Standardverdier for ny betingelse (kai-rule-editor.component.ts:341):

  • Operator: equals
  • Logisk operator: AND
  • Felt og verdi: påkrevd (Validators.required)

betingelse-seksjonen med felt-, operator- og verdi-feltene

Handlinger (THEN)

En handling beskriver hva som skal skje når betingelsene er oppfylt. En regel kan ha flere handlinger.

Handlingstyper (kai-rules.service.ts:292):

Verdi Visningsnavn
ShowWarning Vis advarsel
ShowError Vis feil
SuggestCorrection Foreslå rettelse
BlockSubmission Blokker innsending
AutoRegister Utfør automatisk registrering

Alvorlighetsgrad (Severity) — settes per handling (kai-rules.service.ts:305):

Verdi Visning
Error Feil
Warning Advarsel
Info Info

Felter per handling:

Felt Validering Standard
Handlingstype (ActionType) Validators.required ShowWarning
Melding (Message) Validators.required tom
Melding engelsk (MessageEn) – tom
Alvorlighetsgrad (Severity) Validators.required Warning
Foreslått løsning (SuggestedFix) – tom

Standardverdier fra kai-rule-editor.component.ts:384.

Ekstra konfigurasjon for AutoRegister

Når handlingstypen er AutoRegister, lagres tilleggsfelt som JSON i ActionData (kai-rule-editor.component.ts:530):

Felt Standard Beskrivelse
Tidskode (timeCode) – Lønnskode som benyttes ved automatisk registrering
Timer per dag (hoursPerDay) 7.5 Standard antall timer per dag
AI-instruksjon (aiInstruction) tom Fritekst-instruksjon til AI om hvordan registreringen skal håndteres
Hopp over helger (skipWeekends) true Hopper over lørdag/søndag
Bruk AI for å finne AO/prosjekt/avdeling (enableAutoLookup) false AI-basert oppslag fra brukerens fritekst
Fall tilbake til brukerens historikk (fallbackToHistory) true Bruk mest brukte AO/prosjekt/avdeling hvis AI ikke finner verdier
Krev manuell oppføring (requireManualEntry) false Brukeren må alltid angi AO/prosjekt/avdeling manuelt (deaktiverer AI-oppslag)

handlings-seksjonen med AutoRegister valgt og auto-oppslag-feltene utvidet

«Rett opp» og revisjonslogg

En handling kan bære en entydig rettelse i ActionData ({"fix":{"field":"Department","value":"9500"}}). Avvikspanelet i godkjenningsbildet viser da en «Rett opp»-knapp som utfører endringen for deg — låste rader (godkjent/eksportert) hoppes over. Hver utført feltendring skrives til revisjonsloggen (Systemadministrasjon → Revisjonslogg) med handlingen KAI_ACTION_APPLY: én rad per endret felt, med gammel og ny verdi.

Omfang (WHO)

Bestemmer hvilke ansatte regelen gjelder for (kai-rule-editor.component.ts:88):

Verdi Visningsnavn Hva det betyr
AllEmployees Alle ansatte Regelen gjelder alle ansatte i selskapet (standard)
EmployeeGroup Ansattgruppe Velg én eller flere ansattgrupper (multi-select) — regelen gjelder alle medlemmer
Individual Individuell ansatt Velg én eller flere ansatte direkte (multi-select)

Merk: Omfanget styrer hvem regelen gjelder for — ikke hvem som mottar varsler. Varsler vises som del av valideringsflyten i Time-modulen for den berørte registreringen.

Ansattgrupper hentes fra TimeGroup/GetTimeGroup og ansatte fra User/GetSysUserList (kai-rule-editor.component.ts:113).

Slik oppretter du en ny regel

  1. Åpne Innstillinger → Systeminnstillinger → KAI-administrasjon og velg fanen KAI-regler.
  2. Klikk Opprett ny regel. Drawer-en åpnes til høyre med en tom betingelse, handling og omfang.
  3. Fyll inn Regelnavn, velg Kategori og sett Regeltype (Validering eller Auto-registrering).
  4. I Betingelser (IF) — velg felt, operator og verdi. Legg til flere betingelser med Legg til betingelse, og sett OG/ELLER mellom dem.
  5. I Handlinger (THEN) — velg handlingstype, alvorlighetsgrad og skriv melding (på norsk og engelsk). Hvis du valgte AutoRegister, fyll inn AI-konfigurasjonen.
  6. I Omfang (WHO) — velg Alle ansatte, eller velg ansattgrupper / individuelle ansatte fra multi-select.
  7. La Aktiv stå av mens du tester. Sett Prioritet (lavere tall = høyere prioritet).
  8. Klikk Opprett regel.

drawer-en med alle tre seksjoner (IF/THEN/WHO) synlig

Slik lager du en regel med KAI (fritekst)

Slipper du å fylle ut betingelser, handlinger og omfang for hånd:

  1. I KAI-regler-fanen, klikk Lag regel med KAI (lilla knapp med stjerne-ikon). En dialog åpnes.
  2. Velg kategori og skriv en beskrivelse — f.eks. «Varsle hvis det er færre enn 2 montørvakter (8201) i en uke» eller «Ikke tillat lønnsart 6111». Klikk Lag regel med KAI i dialogen.
  3. KAI genererer et regelutkast og åpner det forhåndsutfylt i regel-editoren. Utkastet grunnes på selskapets lønnsarter og den lovlige felt-/operatorlisten, så koder og felt holdes gyldige.
  4. Kontroller og juster utkastet — særlig lønnsartnumre og terskler.
  5. Klikk Lagre. Ingenting lagres før du bekrefter.

KAI kan gjette feil lønnsart eller terskel. Behandle utkastet som et utgangspunkt, ikke en fasit. Prompten som styrer genereringen kan redigeres under KAI-administrasjon → System-prompts (nøkkel KAI.Prompt.RuleGenerationNL).

Slik importerer du maler

  1. Klikk Importer maler i toolbar-en.
  2. Mal-katalogen åpnes i en modal med alle tilgjengelige maler på tvers av moduler.
  3. Huk av malene du vil bruke. Antall valgte vises nederst i modal-en.
  4. Klikk Importer valgte. Maler som allerede er importert hoppes over, og du får en tilbakemelding (Importerte X regler, Y hoppet over).

Slik aktiverer / deaktiverer du en regel

I rutenettet har hver rad en Aktiver/Deaktiver-knapp (pause/play-ikon). Status oppdateres umiddelbart via PATCH /api/KAIRules/{id}/toggle (kai-rules.component.ts:220).

Slik kopierer du en regel

  1. Klikk Kopier-knappen (filer-ikon) på raden.
  2. Modal-en åpnes med foreslått navn <Original> (Kopi).
  3. Endre navnet om nødvendig og klikk Kopier.

Den nye regelen inkluderer alle betingelser, handlinger og omfang fra originalen.

Vanlige problemer

Lagring feiler med «Vennligst fyll ut alle påkrevde felt»

Ett eller flere påkrevde felt mangler verdi. Påkrevd er: Regelnavn, Kategori, Regeltype, Prioritet (≥ 1), samt felt + operator + verdi for hver betingelse og handlingstype + melding + alvorlighetsgrad for hver handling. Sjekk hvilke felt som er rødmarkert i drawer-en (kai-rule-editor.component.ts:447).

Regelen utløses ikke for noen ansatte

Sjekk:

  1. Aktiv-bryteren står på (kolonnen Status viser Aktiv).
  2. Omfang er satt riktig — Individuell ansatt med tomt utvalg fanger ingen.
  3. Time-registreringen treffer betingelsene (riktig felt + operator + verdi).

«Kunne ikke laste regler» / «Kunne ikke laste regel»

Sjekk Nettverk-fanen i browseren — api/KAIRules/all eller api/KAIRules/{id} har trolig svart med feil. Bekreft at du er logget inn som administrator og at modul 99 (Innstillinger) er aktivert for selskapet (kai-rules.component.ts:109).

Import av maler — «hoppet over (allerede importert)»

Maler kan kun importeres én gang per selskap. Hvis du har slettet en importert regel og vil hente den på nytt, må du opprette regelen manuelt eller klone fra en annen aktiv kopi.

Auto-registrering registrerer feil arbeidsordre eller prosjekt

Justér AI-konfigurasjonen på AutoRegister-handlingen:

  • Slå av Bruk AI for å finne arbeidsordre/prosjekt/avdeling hvis brukerne skal angi det manuelt.
  • Slå på Krev manuell oppføring for å deaktivere AI-oppslag helt.
  • Slå av Fall tilbake til brukerens historikk hvis du ikke vil at AI skal gjette basert på tidligere bruk.

Relaterte sider