Populus poissaolotapahtumien vienti reaaliajassa

Populus poissaolojen vienti -liittymällä poissaolot siirretään reaaliajassa SFTP-palvelimelle Populukseen, kun ne tallennetaan Neptonissa. 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 SFTP-palvelimelle. 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.
• 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. 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.

SFTP-asetuksissa tulee määrittää vähintään SFTP-palvelimen osoite, SFTP-käyttäjätunnus sekä SFTP-salasana (tai public key -autentikointi). 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

Tiedostomuoto

Siirtotiedosto on UTF-8 muotoista puolipisteellä (;) eroteltua tekstimuotoista dataa.

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. Manuaalisesti suoritettu liittymä muodostaa ainoastaan lisäysrivejä ("U").

Mikäli tarkoitus on poistaa rivejä Populuksesta, voidaan manuaalisen suorituksen luomaa tiedostoa muokata korvaamalla "U" -rivit "P" -riveillä.

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.

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.