Populus poissaolotapahtumien vienti reaaliajassa

Populus poissaolojen vienti -liittymällä poissaolot lisätään vientipuskuriin reaaliajassa kun ne tallennetaan Neptonissa. Puskurissa olevat tiedot siirretään valitulla aikavälillä kohdepalvelimelle, josta Populus noutaa tiedot. Liittymä käyttää Populuksen poisto- ja lisäysmerkintöjä ("P" ja "U"). Poissaoloa muokattaessa lähetetään molemmat.

Poisto- ja lisäysmerkinnät jaetaan omiin tiedostoihin. Samassa tiedostossa ei koskaan ole sekä poisto- että lisäysmerkintöjä.

Hyvä tietää

• Työntekijät työntekijänumerolla 0 eivät tule osaksi aineistoa.
• Liittymä käsittelee ainoastaan poissaoloja. Huomaathan tämän, kun teet poimintasääntöä. Esim. työtapahtumia ei käsitellä mutta tapahtumatyyppi, jonka käyttäytymiseksi on valittu "poissaolo", otetaan mukaan (liittymä käsittelee siis tapahtumia, joiden activitytypecategoryid = '2').
• Mikäli poissaolotapahtuma aloitetaan kalenterissa ilman lopetusaikaa, liittymä ei käsittele sitä. Liittymä käsittelee poissaolotapahtuman, kun se lopetetaan ja sille määrittyy lopetusaika.
• Poissaolotapahtuman tallennuksen yhteydessä käsitellään vain kyseinen poissaolotapahtuma ja se viedään puskuriin. Muut saman päivän tapahtumat eivät tule osaksi aineistoa.
• Poissaolotapahtuma siirretään ainoastaan, jos se on uusi, poistettu tai siihen on tehty sellainen muutos, joka koskee aineistossa siirrettävää tietoa. Tarkista aineiston tietueet -kohdasta alta, mitkä tiedot siirretään. Esimerkiksi kommentin lisääminen poissaolotapahtumaan ei muodosta uutta aineistoa.
• Mikäli halutaan siirtää tapahtumat vasta hyväksyttyinä, niin poimintasääntöön tulee lisätä isApproved = 'Y'  
• Poissaolotapahtuman voi tallentaa vaikka liittymän suorittamisessa ilmenisi ongelmia. Esim. virheellinen poimintasääntö tai ongelma SFTP-palvelimella ei estä poissaolotapahtuman tallentamista. Virheestä annetaan käyttäjälle varoitus.
• Jokaista poissaolotapahtumaa ja sääntöjoukkoa kohden muodostetaan oma tiedosto, joka siirretään SFTP-palvelimelle. Mikäli sama poissaolotapahtuma muodostaa aineistoa kahdessa eri sääntöjoukossa, luodaan kaksi eri tiedostoa.
• Poistettu poissaolotapahtuma tai muokatun poissaolotapahtuman edellinen versio muodostuu aineistolle poistomerkinnällä "P".
• Uusi tapahtuma tai muokatun poissaolotapahtuman viimeisin versio muodostuu aineistolle lisäysmerkinnällä "U".
• Poissaolotapahtuman muokkaus muodostaa kaksi riviä. Ensimmäisellä rivillä on poissaolon ennen muokkausta ollut versio tunnisteella ”P”. Jälkimmäisellä rivillä on poissaolon päivitetty versio tunnisteella “U". Ensimmäinen ja jälkimmäinen rivi luodaan omiin tiedostoihin.
• Liittymää varten on mahdollista määritellä useampi sääntöjoukko. Mikäli liittymälle on määritelty useita sääntöjoukkoja, tapahtuman tallennus voi kestää hieman kauemmin.
• Mikäli poissaolotapahtumia poistetaan henkilön kalenterista massatoimintojen kautta, muodostuvat poistettavat rivit yhteen tiedostoon, vaikka poissaolotapahtumia olisi useampi. Poissaolotapahtumia kopioidessa jokaista tapahtumaa kohden muodostuu oma tiedosto.

Määrittäminen

1. Henkilöiden tunnusten määrittäminen

Henkilötunnisteet voidaan määrittää kohdassa Työsuhde > Henkilön tiedot > Tunnisteet.

2. Kohdepalvelimen lisäys

Jos liittymälle ei vielä ole kohdepalvelinta, lisää se työyhteisön asetuksista kohdasta Liittymät > Liittymien kohdepalvelimet. Katso Työajan vientiliittymien kohdepalvelimet yleiset ohjeet kohdepalvelimen lisäykseen ja kohdepalvelimen SFTP-asetuksien asetukseen.

Kohdepalvelimen SFTP-asetuksissa tulee määrittää vähintään SFTP-palvelimen osoite, SFTP-käyttäjätunnus sekä SFTP-salasana (tai public key -autentikointi)

3. Liittymän asetukset

Liittymän käyttöönottoa varten tulee määrittää sääntöjoukko, jolla muodostetaan poissaoloaineisto. Sääntöjoukon asetuksissa valitaan viennin tiedostomuodoksi Populus poissaolojen vienti.

Valitse liittymälle kohdepalvelin, jonka lisäsit kohdassa 2.

Vientitiedoston nimeen tulee lisätä tarkka aikaleima [timestamp-ms], kuten alla olevassa esimerkissä. Mikäli aikaleimaa ei käytetä, jokaisella tiedostolla on sama nimi ja ne ylikirjoittavat toisensa.

Vientitiedoston nimeen on myös mahdollista lisätä konteksti, eli onko tiedosto poisto- vai lisäysmerkinnät sisältävä tiedosto. Mikäli tämä lisätään, on tärkeää, että se on aikaleiman jälkeen. Esimerkiksi:

nep-poissaolot-[timestamp-ms]-[context].csv

Tiedostonimet yllä olevalla esimerkillä olisivat seuraavan muotoiset:

• Poistomerkinnöille: nep-poissaolot-1741348913396-P.csv
• Lisäysmerkinnöille: nep-poissaolot-1741348913396-U.csv

4. Vientitiedoston jakaminen

Vientitiedoston osiin jakaminen -kohdan alla olevia asetuksia voidaan käyttää tämän liittymän kanssa, mutta reaaliaikaisissa siirroissa tähän liittyy eräs huomio. Jokainen yksittäinen reaaliaikainen siirto poimii hyvin pienen määrän dataa. Useimmilla ryhmittelyperusteilla tämä pieni datamäärä ei enää jakaudu pienempiin osiin, vaan siirrosta muodostuu edelleenkin vain yksi tiedosto. Tiedoston nimeen liitettään kuitenkin määritetty ryhmittelyperuste (esim. maksuryhmä). Tätä määritystä noudettaisiin myös manuaalisesti käynnistetyissä siirroissa, joissa todennäköisesti muodostuisi useampi tiedosto suuremman datamäärän vuoksi.

Kun nämä asetukset ovat käytössä, järjestelmä pilkkoo tiedot ensin tämän määrityksen mukaan ja sen jälkeen jakaa vielä lisäys- ja poistomerkinnät omiin tiedostoihinsa. 

Tarkemmat tiedot näistä asetuksista löydät täältä. 

5. Viennin ajastus kohdepalvelimelle

Viimeisenä kohdepalvelimen puskurille tarvitsee määrittää viennin ajastus. Tästä voit lukea lisää artikkelista Työajan vientiliittymien kohdepalvelimet.

Tiedostomuoto

Siirtotiedosto on UTF-8 muotoista puolipisteellä (;) eroteltua tekstimuotoista dataa. Rivinvaihto on LF. Siirtotiedoston lopussa on yksi tyhjä rivi.

Aineiston tietueet

SELECT *,
CASE WHEN :integrationContext = 'P'
  THEN 'D'
  ELSE 'N'
END AS RowContext
FROM UserSalaryData

Alla olevat aineistot kuvastavat muokattua poissaoloa. Yhden päivän pituinen poissaolo on muokattu kahden päivän pituiseksi. Edellisestä versiosta luodaan poistorivi ("P") ja uudesta version lisäysrivi ("U").

418;P;1234;707;1918;Meikäläinen Matti;;20200102;9090;20250113;20250113;;;;;;

418;U;1234;707;1918;Meikäläinen Matti;;20200102;9090;20250113;20250114;;;;;;

Liittymän suorittaminen tapahtuman tallentamisen yhteydessä

Alla olevassa esimerkissä on kalenterinäkymässä kopioitu poissaolotapahtuma viidelle päivälle.

Tallennuksen yhteydessä SFTP-palvelimelle muodostuu jokaisesta tapahtumasta oma tiedosto, jossa on sääntöjoukon muodostama aineisto. Huomaathan, että on tärkeää määrittää tapahtuman nimeen tarkka aikaleima [timestamp-ms], jotta tiedostot eivät ylikirjoita toisiaan.

Liittymän suorittaminen manuaalisesti

Liittymän voi suorittaa manuaalisesti kohdassa Hallinta > Liittymät > Populus poissaolojen vienti. Tämä voi olla tarpeellista esimerkiksi silloin, kun halutaan ajaa tietyn aikavälin aineisto kokonaan uudelleen tai poistaa se. 

Rivin ja tiedoston tyyppi on mahdollista valita Merkintä-pudotusvalikosta. Esimerkiksi valinta "Poistettu" luo poistoon tarkoitetun tiedoston, jonka riveillä on poistomerkintä "P".

Alla olevassa esimerkissä käytetään aiemmin luotua poimintasääntöä "Populus poissaolot". Poimintasääntö on pakollinen.

Rivityypin ohittaminen poimintasäännössä

Joskus saattaa olla tarpeellista ohittaa "P" tai "U" -rivien muodostuminen, kun käsitellään tiettyjä poissaolotyyppejä. Tätä varten poimintasäännössä voidaan käyttää kolmea eri muuttujaa:

1. :integrationContext - konteksti, jossa liittymää suoritetaan ("P" tai "U")
2. :integrationContextForDeletedOrEditedActivities - Rivin "P" muodostus
3. :integrationContextForNewActivities - Rivin "U" muodostus

Alla oleva esimerkki kuvaa yksinkertaistetusti, kuinka isyysvapaalle muodostetaan ainoastaan lisäysmerkinnät "U", mutta poiston tai muokkauksen yhteydessä ei muodosteta poistomerkintää "P".

SELECT *, SUM(Amount) AS OverrideAmount, 
MIN(SalaryRenderingDate) As OverrideStartDatetime, 
MAX(SalaryRenderingDate) AS OverrideEndDatetime,
CASE 
WHEN AbsenceTypeId = 11 THEN 'KERTAUS' --Kertausharjoitukset
WHEN AbsenceTypeId = 3 THEN 'ISYYSVAPAA' -- Isyysvapaa
ELSE
'MUU VAPAA'
END AS OverrideSalaryCode
FROM UserSalaryData 
WHERE CompensationType = 'BasicTime'
AND 
AbsenceTypeId IS NOT NULL 
AND 
(AbsenceTypeId != 3 OR :integrationContext != :integrationContextForDeletedOrEditedActivities) -- Lähetä ainostaan U-rivit isyysvapaalle
GROUP BY ActivityId

Kun kalenteriin lisätään uusi isyysvapaa, muodostetaan aineisto, joka sisältää isyysvapaan lisäysmerkinnällä "U". Mikäli isyysvapaata muokataan, muodostetaan uusi aineisto lisäysmerkinnällä "U", mutta edellistä versiota poissaolosta ei muodosteta poistomerkinnällä "P". Mikäli isyysvapaaa poistetaan kokonaan, ei aineistoa muodosteta.

Mikäli kalenteriin lisätään kertausharjoitukset (tai mikä tahansa muu poissaolo), se käsitellään liittymän normaalin toimintatavan mukaisesti.

Kuluvan päivän poissaolokirjauksen poimintasäännön ehto

Tilanteessa, jossa kuluvalle päivälle kirjataan poissaolo, tietokantatauluun muodostuu tieto "istimeborrowedfrombalance = 'Y'. Tämä aiheuttaa tilanteen, jossa hyväksymätön poissaolo siirtyy aiheettomasti eteenpäin vientipuskuriin ja edelleen Populukseen. Tämän tiedon muodostuminen on tarkoituksenmukaista. 

Tästä syystä poissaolojen poimintasääntöön tulee lisätä ehto istimeborrowedfrombalance = 'N', jotta kuluvan päivän poissaolokirjaukset eivät siirry ennenaikaisesti ja aiheettomasti liittymällä ennen niiden hyväksyntää. 

Ongelmatilanteet

Poissaolojen lisäys ja poistaminen Populuksesta

Mikäli Populuksesta halutaan kerralla poistaa suurempi määrä sinne vietyjä poissaoloja tietyllä ajanjaksolla, voi sen tehdä suorittamalla liittymän manuaalisesti. Manuaalista liittymän suoritusta voi käyttää samalla tavalla myös poissaolojen lisäämiseen.

Asetusmuutokset

Palkka-aineistoon vaikuttavia asetusmuutoksia ei ole suositeltavaa tehdä jälkikäteen. Esimerkiksi työpäivän pituuden muuttaminen päiväkohtaisesti kalenterinäkymässä voi muuttaa myös palkallisia poissolopäiviä. Tällaisia muutoksia tehdessä liittymää ei suoriteta ja Populukseen jää sinne mahdollisesti aiemmin viety tieto poissaolojen päivistä. Tällaisessa tilanteessa tulee toimia seuraavasti:

• Poista Populukseen aiemmin luotu poissaolo.
• Poista Neptonista nykyinen poissaolo. Tämä lähettää "P" -rivin, jolle ei ole vastinetta Populuksessa.
• Lisää poissaolo uudelleen. Tämä luo "U" -rivin muodostaen aineiston käyttäen nykyisiä asetuksia.