Yleiskuvaus

Työaikaintegraatio on toteutettu kaksisuuntaisen integraation tarjoavana rajapintana, johon Titania järjestelmä tuo työaikasuunnitelmia ja hakee toteumia. Tietojen tuonti ja haku tehdään yksikkö kerrallaan.

Työaikakirjaukset

Henkilökunnan työvuorosuunnitelmat siirretään eVakasta Titaniaan manuaalisesti työvuorosuunnittelijan toimesta. Työvuorosuunnitelmat näkyvät eVakan selaimessa henkilökunta-sivulla henkilön ylärivillä. Työvuorosuunnitelmaa ei voi muokata eVakassa. Työntekijän kirjautuessa ryhmään, eVaka aloittaa luomaan työtoteumaa. Mikäli sisään- tai uloskirjautumisessa on yli 5 minuutin poikkeama, eVaka kysyy syykoodia poikkemalle. Kunnilla voi olla erilaisia käytänteitä liittyen itse Titanian käyttöön.

Syykoodit ovat seuraavat:

• Läsnä - lasketaan käyttöasteeseen
• Ylityö - lasketaan käyttöasteeseen
• Perusteltu muutos - lasketaan käyttöasteeseen
• Työasia - ei lasketa käyttöasteeseen, mutta kerryttää työaikaa
• Koulutus - ei lasketa käyttöasteeseen, mutta kerryttää työaikaa

Työaikaleimaukset haetaan eVakasta Titaniaan manuaalisesti Titanian toiminnanohjausliittymästä.

Virheraportti

Titaniasta tuotu työvuorosuunnitelma tarkistetaan ristiriitojen varalta. Jos ristiriitoja löytyy, ne tallennetaan virheraporttiin, eikä työvuorosuunnitelmia tallenneta. Virheraportilla näytetään jokainen työvuorosuunnitelmien tuontiyritys ja siihen liittyvät ristiriidat.

Virheraportin rivit tyhjennetään ajastettuna ajona 30 päivää tuonnin jälkeen. Lisäksi yksittäinen rivi voidaan poistaa suoraan raportilta.

Titania käyttöönotto

Titania on mahdollista integroida eVakaan HTTP-APIn avulla, jossa eVaka toimii serverinä ja Titania clientinä. Rajapinta on RESTillä ja käyttää JSON-koodattuja pyyntöjä ja vastauksia.

Integraatio koostuu kahdesta osasta:

• työaikatapahtumien (=henkilökunnan läsnäolosuunnitelmien) päivittäminen eVakaan
• leimattujen työaikatapahtumien (=henkilökunnan läsnäolojen) hakeminen eVakasta

Titania käyttää eVakassa juoksevaa työntekijän numeroa, jonka se tallentaa esim. EntraID:stä. Titaniassa pitää olla sama numero tulevalla työvuorosuunnitelmalla, jotta työvuorosuunnitelmat ja toteumat synkronoituvat oikein.

Autentikaatio

HTTP Basic autentikaatio käytössä: Authorization: Basic base64(user:pass)

Virheenkäsittely

HTTP-vastauksen tilakoodeja käytetään virheen ilmaisemiseen (taulukko englanniksi):

HTTP status code	Description
400	Bad Request Request body is incorrect, for example a required field is missing
401	Unauthorized Authentication header is not provided or it is incorrect
403	Forbidden Authentication header is correct but the user doesn't have valid permissions
404	Not Found Request URL is incorrect
405	Method Not Allowed Request method is incorrect, for example PUT was given but POST was expected
415	Unsupported Media Type Request Content-Type header is incorrect, only application/json is supported

Titanian endpointit

Työaikatapahtumien päivitys (taulukko englanniksi)

PUT /api/internal/integration/titania/working-time-events

Request	Response
json schema	-
example	{"message": "OK"}

Esimerkki (kun käytetään lokaalia ympäristöä):

curl \
-u titania:titania \
-X PUT \
-H "Content-Type: application/json" \
-d @titania-update-request-valid-example-data.json \
http://localhost:9099/api/internal/integration/titania/working-time-events

Virheet:

• Tuntematon työntekijänumero (400 Bad Request)
• Pyynnön sisältää työntekijänumeron, jota ei löydy eVakan tietokannasta.

Esimerkki vastauksesta:

{
"detail": [
{
"errorcode": "101",
"message": "Unknown employee number: 176716"
}
],
"faultactor": "/integration/titania/working-time-events",
"faultcode": "Server",
"faultstring": "multiple"
}

Tapahtuman päivämäärä on annetun ajanjakson ulkopuolella (400 Bad Request) Pyyntö sisältää tapahtumapäivämäärän, joka on annetun ajanjakson ulkopuolella.

Esimerkki vastauksesta:

{
"detail": [
{
"errorcode": "102",
"message": "Event date 2019-06-12 is out of period (2020-01-01 - 2020-12-31)"
}
],
"faultactor": "/integration/titania/working-time-events",
"faultcode": "Server",
"faultstring": "multiple"
}

Nouda leimattuja työaikatapahtumia

POST /api/internal/integration/titania/stamped-working-time-events

Request	Response
json schema	-
example	{"message": "OK"}

Esimerkki (kun käytetään lokaalia ympäristöä):

curl \
-u titania:titania \
-X POST \
-H "Content-Type: application/json" \
-d @titania-get-request-valid-example-data.json \
http://localhost:9099/api/internal/integration/titania/stamped-working-time-events

Ympäristömuuttujat / Spring propertyt

• titaniaErrorsReport = true Näytetään Titanian virheraportti - FeatureFlags
• EVAKA_TITANIA_USERNAME Titanian käyttäjänimi AWS Secure String
• EVAKA_TITANIA_PASSWORD Titanian salasana AWS Secure String