Henkilötietojen tuonti - Sympa API

Hakemalla henkilötietoja Sympa API:sta saadaan henkilötiedot päivitettyä Neptoniin useita kertoja päivässä. Sympa API:sta voidaan tuoda myös tiedot tulevista henkilötietojen muutoksista etukäteen.

Lisätietoa: Henkilötietojen tuonti voimassa alkaen ja päättyen -tiedolla

Käyttöönotto

Henkilötietojen siirto Sympan APIa hyödyntäen otetaan käyttöön määrittelemällä Sympaan tuotavan tiedon poimintasäännöt ja Neptoniin henkilötietojen noudon ajastus. Sympan poimintasäännöt määrittelee Sympan asiantuntija vakioidulla tavalla. Henkilötietojen noudon ajastuksen voit tehdä seuraavilla ohjeilla.

Ajastuksen määritys

Käytä ajastetun tehtävän määrityksessä seuraavia valintoja. Lisäohjeet ajastettujen tehtävien lisäämisestä täältä.

• Merkistökoodaus: UTF-8
• Tiedoston tyyppi: JSON
• Henkilötuonnin tyyppi: Sympa HR Integraatio API
• Autentikaatiotyyppi: Perus HTTP-autentikointi
• REST API osoite: Sympan antama osoite
• Parametri 1: Käyttäjätunnus - Nimi: "username", Arvo: "SympaltaSaatu_API_KEY"
• Parametri 2: Salasana - Nimi: "password", Arvo: "SympaltaSaatu_Salainen_Avain"
• Ajastus: Suosittelemme kerran päivässä klo 00:15 - 01:00 välillä.

Siirrettävän tietomäärän rajoittaminen

Liittymän määrittelyssä on mahdollista rajata haettavaa tietoa. Tiedon rajaukset tehdään pääsääntöisesti Sympan puolella tiedon poiminnassa, mutta etenkin liittymän käyttöönottoprojektin aikana voi olla hyödyllistä rajata siirrettävää sisältöä. Tällä voidaan varmistua siirrettävän sisällön oikeellisuudesta, ennen kuin liittymässä siirretään tieto kaikkien työntekijöiden osalta.

Tiedon tuontia voidaan rajata ajastuksen määrityksen yhteydestä löytyvälllä, REST API -osoitteen komennoilla. Niissä komennoissa, joissa voidaan määritellä kentän nimi, voidaan käyttää mitä tahansa liittymän kentistä. Käytettävissä ovat seuraavat rajauksena käytettävät komennot. 

$top
$skip
$orderby
$filter

Esimerkiksi, jos halutaan palauttaa liittymästä 5 henkilöä järjestettynä sukunimellä niin REST API -osoitteen komentoon lisätään hipsujen sisällä oleva teksti "/?$orderby=Sukunimi&$top=5". Tällöin määrittely REST API - osoitteeksi olisi 

Alla on kuvattuna toiminnoittain komentojen käyttö

Top
The query $top=XX will return the first XX matches to the query.
Example:/?$top=200
Skip
The query $skip=XX will leave out the first XX matches to the query.
Example: /?$skip=10
Example: /?$skip=10&$top=10

Order by
The query $orderby=somealias, someotheralias desc will sort the result set, primarily by the alias “somealias”, ascending, and
secondarily by the alias “someotheralias”, descending.
Example: /?$orderby=id
Example: /?$orderby=id desc
Example: /?$orderby=surname,age desc

Filter
The following subset of OData filters are supported by the API.

Filter examples by field type

• All the field types can be filtered by null or by text
  api/testinterface?$filter=not (email eq null)
  api/testinterface?$filter=name eq 'no values'
• Numeric field
  eq =equal, gt=greater than, lt = less than, ge=greater than or equal to, le=less than or equal to
  /?$filter=not (number eq null)
  /?$filter=number ge 0
  decimal number as filter
  /?$filter=number ge 1.14d
• Dates
  eq =equal, gt=greater than, lt = less than, ge=greater than or equal to, le=less than or equal to
  /?$filter=not (date eq null)
  /?$filter=birthday gt 1980-12-17
  between api/testinterface?$filter=(date gt 2020-02-29) and (date lt 2020-03-02)
• Timestamps
  Datacard's created and modified timestamps can also be used as filter.
  /?$filter=(modified gt 2015-12-31T23:59:59Z)
  Special case: If you don't specify the time, the timestamp is interpreted as T00:00:00, e.g:
  /?$filter=(created le 2014-01-01)
  comparison is done with timestamp 2014-01-01T00:00:00
  A good idea would be to always specify the time with the as a DateTime attribute.
  Note: Datacard's empty created date is shown "0001-01-01T00:00:00" but empty modified date is shown as "null"
• Identification field
  Identification field can be used in filter as the "raw" numeric value, not the formatted value
  e.g. /?$filter=sympaID eq '123'
  Using values that are not numbers (e.g. sympaID eq 'a123') will give an error ("message": "Error with SQM query:
  MissingFilterField")

Kentät ja kenttäryhmät

Henkilötietojen tuonnissa voi käyttää kaikkia yleisen henkilötuonnin kenttiä. Myös henkilön lisätietokentät saadaan tuotua, kun kentän nimi API:n datassa vastaa kentän nimeä Neptonissa. Voimassaoloja tukevat kentän arvot voidaan siirtää voimassaolotiedoilla siirtämällä ne osana mitä tahansa kenttäryhmää, mutta suosittelemme käyttämään alla mainittuja kenttäryhmiä näiden kenttien osalta. Kaikki kentät eivät tällä hetkellä tue voimassaoloaikojen tallennusta, vaikka ne siirretään kenttäryhmissä voimassaolotiedoin. Tässä tapauksessa vain tuontihetkellä voimassaolevat tiedot tallennetaan - ks. tarkemmin kunkin kentän kuvauksesta. Kentät jotka tuodaan API:n datassa ilman voimassaolotietoja, tallennetaan ilman voimassaoloja tuonnin säännöin.

Alla luetellut kentät on siirrettävä osana kenttäryhmää, sillä ne sisältävät tiedon päättelyä.

Huom! Jos samaa kenttäryhmää tuodaan useammassa eri liittymässä, vain viimeisimmän tiedot jäävät voimaan, kaikki aiemmat rivit poistetaan.

Näiden kenttäryhmien lisäksi voidaan käyttää lisätieto-taulukoita. Näitä taulukoita on 10 kpl ja niiden nimi on Lisatieto{1}_TAULUKKO, jossa aaltosulkeissa korvataan se taulukko jota täytetään. Näihin taulukoihin voidaan lisätä mitä tahansa sellaista tietoa, joiden voimassaolo on kaikille taulukkoon lisätyille tiedoille yhteinen. Esimerkiksi henkilön kuukausipalkan voisi tuoda sanomassa lisäämällä sinne taulukon 

          "Lisatieto1_TAULUKKO": [
                {
                    "Voimassa alkaen": "2020-06-02",
                    "Voimassa päättyen": null,
                    "Kuukausipalkka": "2700"
                 }
            ],

Mikäli Sympan tiedoissa kuukausipalkka sekä tehtävänimike jakaisivat saman voimassaolon, niin taulukko olisi seuraavanlainen

          "Lisatieto1_TAULUKKO": [
                {
                    "Voimassa alkaen": "2020-06-02",
                    "Voimassa päättyen": null,
                    "Kuukausipalkka": "2700",                    
                    "Ammattinimike": "Hitsaaja"
                 }
            ],

Voimassaoloaikojen päiväyksen muoto

"Voimassa alkaen"- ja "Voimassa päättyen"-kenttissä käytetään päivämäärämuotoa "YYYY-MM-DD".

Vakioitu liittymä

Tämän ohjeen alussa mainitun vakioidun Sympa API liittymän kohdalla, siirretään vakiomutoinen siirtoainesto. Alla vakioidun liittymän siirtoaineiston kentät.

Vakioidun liittymän aineistoesimerkki

{
    "@odata.context": "https://api.az-sympa.com/api/$metadata#NeptonKaikkiTiedot",
    "value": [
        {
            "Henkilönumero": "123",
            "Kutsumanimi": "Erkki",
            "Etunimet": "Erkki Esko Eemeli",
            "Sähköposti": "maili@maili.com",
            "Puhelinnumero": "040 456 7890",
            "Ensisijainen esimies": "Esimerkki",
            "IBAN": "FI0453260051234567",
            "Katuosoite": "Katu 1",
            "Postinumero": "00000",
            "Postitoimipaikka": "Turku",
            "RFID-tunniste": "ABCDE123456",
            "Yksiköt": "Tuotekehitys",
            "Rooli": "Työntekijä",
            "Työajan roolit": "Työntekijät",
            "Käyttäjätili käytössä": "Kyllä",
            "_FilterLiiketoimintayksikko": "3",
            "_TESTUSER": false,
            "Työsuhde_TAULUKKO": [
                {
                    "Voimassa alkaen": "2020-06-02",
                    "Voimassa päättyen": "2020-10-13",
                    "Ammattinimike": "Testaaja",
                    "Työaika prosentteina": 80.0,
                    "Työajan asetusryhmä": "1234"
                },
                {
                    "Voimassa alkaen": "2020-10-14",
                    "Voimassa päättyen": null,
                    "Ammattinimike": "Ohjelmistokehittäjä",
                    "Työaika prosentteina": 100.0,
                    "Työajan asetusryhmä": "2456"
                }
            ],
            "Kustannuspaikka_TAULUKKO": [
                {
                    "Voimassa alkaen": "2020-06-02",
                    "Voimassa päättyen": null,
                    "Oletuskustannuspaikka": "103"
                    "Toimipiste": "Kamppi"
                }
            ],
            "Organisaatio_TAULUKKO": [
                {
                    "Voimassa alkaen": "2020-06-02",
                    "Voimassa päättyen": null,
                    "Organisaatiotaso1Nimi": "Ohjelmistotalo Oy",
                    "Organisaatiotaso2Nimi": "Turku",
                    "Organisaatiotaso3Nimi": "Tuotekehitys",
                    "Organisaatiotaso1Koodi": "10",
                    "Organisaatiotaso2Koodi": "120",
                    "Organisaatiotaso3Koodi": "1500"
                }
            ],
            "Toissijaiset_esimiehet_TAULUKKO": [
                {
                    "Voimassa alkaen": "2020-09-15",
                    "Voimassa päättyen": "2022-01-01",
                    "Toissijaiset esimiehet": "1234"
                },
                {
                    "Voimassa alkaen": "2016-01-01",
                    "Voimassa päättyen": null,
                    "Toissijaiset esimiehet": "4321"
                }
            ],
            "Asetusryhmä_TAULUKKO": [
                {
                    "Voimassa alkaen": "2020-06-02",
                    "Voimassa päättyen": null,
                    "Työajan asetusryhmä": "Liukuva työaika"
                }
            ]         }
    ]
}

Kenttien arvojen tuonti ilman voimassaolotietoja

Mikäli siirrettävässä aineistossa ei määritellä tiedon voimassaoloja niin tuotava tieto käsitellään ilman voimassaoloja. Alla aineistoesimerkki siirrosta ilman voimassaolotietojen tuontia.

{
    "@odata.context": "https://api.az-sympa.com/api/$metadata#NeptonKaikkiTiedot",
    "value": [
        {
            "Henkilönumero": "123",
            "Käyttäjätunnus": "esko.esimerkki@yritys.fi",
            "Sukunimi": "Esimerkki",
            "Etunimi": "Esko",
            "Sähköposti": "esko.esimerkki@yritys.fi",
            "Ensisijainen esimies": "21",
            "Käyttäjätili käytössä": "Kyllä"
        }
    ]
}

Kenttien arvojen tuonti voimassaolotiedoilla

Sympa API henkilötuonti tukee voimassaolojen siirtämistä osalle kentistä. Kun voimassaoloja tukeva kenttä, siirretään kenttäryhmän kenttänä, voidaan sille määritellä voimassaolot kenttäryhmän tiedoissa.

Tiedon tuonnissa kentät saavat voimassaolon kenttäryhmän 'Voimassa alkaen' ja 'Voimassa päättyen' kenttien mukaan. Katso lisätiedot voimassaolotietojen siirrosta täältä. Voimassaolovälit siirretään kenttäryhmien riveinä. Kenttäryhmän kentät voidaan myös halutessa, tuoda ilman voimassaolotietoja. Mikäli kenttäryhmä siirretään tyhjänä ilman yhtäkään riviä, kenttäryhmän kaikkien kenttien kaikki arvot poistetaan Neptonista. Alla aineistoesimerkki siirrosta voimassaolotiedoilla kenttäryhmän avulla.

{
    "@odata.context": "https://api.az-sympa.com/api/$metadata#NeptonKaikkiTiedot",
    "value": [
        {
            "Henkilönumero": "123",
            "Sukunimi": "Esimerkki",
            "Etunimi": "Esko",
            "Työsuhde_TAULUKKO": [
                {
                    "Voimassa alkaen": "2020-06-02",
                    "Voimassa päättyen": "2020-10-13",
                    "Ammattinimike": "Myyjä",
                    "Työaika prosentteina": 80.0,
                    "Työajan asetusryhmä": "1234"
                },
                {
                    "Voimassa alkaen": "2020-10-14",
                    "Voimassa päättyen": null,
                    "Ammattinimike": "Myyntipäällikkö",
                    "Työaika prosentteina": 100.0,
                    "Työajan asetusryhmä": "2456"
                }
            ]
        }
    ]
}

Lisätietoja tuonnista

Nepton hakee henkilötiedot kutsumalla Sympa API:a. Sympa palauttaa henkilötiedot JSON-muodossa, noudattaen sisällön rakenteen osalta OData Versio 4 standardia. Tiedon poiminnan sisältö ja hakurajaukset määritellään Sympan käyttöliittymässä.