Rajapinnan yleiskuvaus
Verkkopalveluita käytetään tapahtuman aloitukseen (BeginActivityV2
) ja päättämiseen (EndActivityV2
) Neptonissa.
Verkkopalvelut on suunniteltu käytettäväksi päätelaitesovelluksissa. Kaikki verkkopalvelun kautta aloitetut ja päätetyt tapahtumat kirjataan kellotettuina tapahtumina, paitsi tapauksissa jolloin päätettävä tapahtuma ei ollut aloitettuna kellotettu.
Verkkopalveluiden autentikoituminen eroaa muista verkkopalveluista sillä tavalla, että onnistuneesti käyttäjätunnuksella ja salasanalla autentikoitunut henkilö voi autentikoitua toisena henkilönä PIN-koodin tai RFID-koodin perusteella. Ensimmäisessä vaiheessa autentikoituneella henkilöllä täytyy olla oikeudet lukea henkilötietoja. Esimerkiksi:
<CallerAuthentication>
<CustomerId>1234</CustomerId>
<Username>PäätelaiteKäyttäjä</Username>
<Password>KuvitteellinenSalasana123</Password>
<PinCode>1234</PinCode> <!-- Päätelaitteella syötetty PIN-koodi -->
</CallerAuthentication>
Jos annetulla PIN-koodilla tai RFID-koodilla ei löydy henkilöä, autentikoituminen epäonnistuu.
Verkkopalvelun WSDL-skeema on julkisesti saatavilla täällä. Rajapinnat ovat yleisellä tasolla kuvattuna täällä.
Kuvauksessa oleva sarake esiintymiskerrat määrittää sen onko jokin tieto pakollinen kutsussa vai ei. Esiintymiskerrat 0, tarkoittaa että kyseistä tietoa ei tarvitse siirtää kutsussa. Esiintymiskerrat 1 tarkoittaa, että tiedon tulee esiintyä kutsussa yhden kerran. Esiintymiskerrat 0..n tarkoittaa, että kyseinen tieto voi esiintyä kutsussa minkä tahansa määrän. Esiintymiskerrat 1..n tarkoittaa että kyseinen tieto tulee olla aineistossa ainakin kerran, mutta voi olla useamminkin.
Lähetettävät tiedot
Taso | Kentän nimi | Muoto | Esiintymiskerrat | Selite |
---|---|---|---|---|
Juuri, SOAP body:n alla |
ParametersForBeginActivityV2 / ParametersForEndActivityV2 | XML element | 1 | |
1 | CallerAuthentication | XML element | 1 | Lisää tietoa autentikoitumisesta täällä |
1 | ActivityTypeId | integer | 1 | Aloitettavan tapahtumatyypin Nepton-tunniste. Käytettävissä vain BeginActivityV2-kutsussa. |
1 | ActivityId | integer | 0..1 |
Huom! Tietoa ei käytetä, päätettävä tapahtuma tunnistetaan automaattisesti. Päätettävän tapahtuman Nepton-tunniste. Käytettävissä vain EndActivityV2-kutsussa. |
1 | BeginDateTime | datetime | 0..1 |
Aloitettavan tapahtuman alkamispäivä ja -aika. Jos tietoa ei anneta, tapahtuman alkamisajaksi annetaan nykyinen aika. Käytettävissä vain BeginActivityV2-kutsussa. |
1 | BeginDateTime | datetime | 0..1 |
Tapahtuman päättymispäivä ja -aika. Jos tietoa ei anneta EndActivityV2-kutsussa, tapahtuman päättymisajaksi annetaan nykyinen aika. Jos tietoa ei anneta BeginActivityV2-kutsussa, tapahtuman aloitetaan ilman päättymisaikaa. |
1 | TerminalId | integer | 0..1 | Päätelaitteen tunniste. Tunnisteena voidaan käyttää itse annettuna tunnisteita, kunhan tunnisteet ovat kokonaislukuja. |
1 | Comment | string | 0..1 | Tapahtumalle kirjattavat huomiot. |
1 | OvertimeBasePartTargetedTo | string | 0..1 | Ylityön perusosan kohdenne tapahtumalle. |
1 | OvertimeIncrementPartTargetedTo | string | 0..1 | Ylityön korotusosan kohdenne tapahtumalle. |
1 | RelatedProjects | XML element | 0..1 | Tapahtumalle kirjattavat projektit. |
2 | ActivityToProjectRelation | XML element | 0..n | |
3 | Id | integer | 0..1 | Projektin yksilöllinen tunniste Neptonissa. Projektin yksilöllinen tunniste tai projektin koodi täytyy antaa. |
3 | Duration | integer | 0..1 | Projektin kesto minuutteina |
3 | Name | string | 0..1 | Projektin nimi. Tietoa ei käytetä. |
3 | Code | string | 0..1 | Projektin koodi. Projektin yksilöllinen tunniste tai projektin koodi täytyy antaa. |
1 | WorkIncrements | XML element | 0..1 | Tapahtumalle kirjattavat työlisät. |
2 | WorkIncrement | XML element | 0..n | |
3 | Index | integer | 1 | Työlisän indeksi |
3 | Value | decimal | 1 | Työlisän arvo minuutteina, yksikköinä tai desimaalina. |
1 | AppendExistingWorkIncrements | boolean | 0..1 | Lisätäänkö kutsussa olevat työlisät tapahtumalla olevien työlisien päälle (true ) vai ei (false ). Oletuksena ei lisätä tapahtumalla olevien päälle. Käytettävissä vain EndActivityV2-kutsussa. |
1 | ExistingExternalIdentifier | XML element | 0..1 |
Huom! Tietoa ei käytetä, päätettävä tapahtuma tunnistetaan automaattisesti. Päätettävän tapahtuman ulkoinen tunniste. Käytettävissä vain EndActivityV2-kutsussa. |
2 | Identifier | string | 1 | Ulkoinen tunniste |
2 | IdentifierType | string | 1 | Ulkoisen tunnisteen tyyppi. Tällä hetkellä ainoa tuettu tyyppi on External |
1 | ExternalIdentifiers | XML element | 0..1 | Tapahtumalle asetettavat ulkoiset tunnisteet. Jos tietoa ei anneta EndActivityV2-kutsussa, ulkoisia tunnisteita ei tyhjennetä. |
2 | ExternalIdentifier | XML element | 1..n | Tapahtumalle asetettava ulkoinen tunniste |
3 | Identifier | string | 1 | Ulkoinen tunniste |
3 | IdentifierType | string | 1 | Ulkoisen tunnisteen tyyppi. Ainoa tuettu tyyppi tällä hetkellä on External . |
Kyselyn esimerkki (BeginActivityV2)
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tyo="http://tyoaika.tyoteho.fi">
<soapenv:Header/>
<soapenv:Body>
<tyo:ParametersForBeginActivityV2>
<CallerAuthentication /> <!-- Autentikoituminen vaaditaan, mutta on jätetty tässä esimerkissä pois -->
<ActivityTypeId>1</ActivityTypeId>
<BeginDateTime>2021-05-28T07:35:34</BeginDateTime>
<TerminalId>418</TerminalId>
<ExternalIdentifiers>
<ExternalIdentifier>
<Identifier>ae2f6c97-104f-49e4-9cff-70951f00234e</Identifier>
<IdentifierType>External</IdentifierType>
</ExternalIdentifier>
</ExternalIdentifiers>
</tyo:ParametersForBeginActivityV2>
</soapenv:Body>
</soapenv:Envelope>
Kyselyn esimerkki (EndActivityV2)
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tyo="http://tyoaika.tyoteho.fi" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Header/>
<soapenv:Body>
<tyo:ParametersForEndActivityV2>
<CallerAuthentication /> <!-- Autentikoituminen vaaditaan, mutta on jätetty tässä esimerkissä pois -->
<TerminalId>418</TerminalId>
<ExternalIdentifiers>
<ExternalIdentifier>
<Identifier xsi:nil="true" /> <!-- Poistetaan ulkoinen tunniste tapahtumalta -->
<IdentifierType>External</IdentifierType>
</ExternalIdentifier>
</ExternalIdentifiers>
</tyo:ParametersForEndActivityV2>
</soapenv:Body>
</soapenv:Envelope>
Vastaus
Taso | Kentän nimi | Muoto | Esiintymiskerrat | Selite |
---|---|---|---|---|
Juuri, SOAP body:n alla |
ReturnValueForBeginActivityV2 / ReturnValueForEndActivityV2 | XML element | 1 | |
1 | ResponseCode | integer | 1 | Käsittelyn tuloksen koodi. Mahdolliset koodit löytyvät täältä. |
1 | ResponseString | string | 0..1 | Koodin kuvaus |
1 | UserId | integer | 0..1 | Autentikoituneen henkilön Nepton-tunniste |
1 | CustomerId | integer | 0..1 | Työajan asiakkuuden Nepton-tunniste |
1 | Locale | string | 0..1 | Henkilön kieli. Tällä hetkellä mahdolliset arvot ovat:
|
1 | StartedActivity / EndedActivity | XML element | 0..1 | Aloitetun / päätetyn tapahtuman tiedot. |
2 | Id | integer | 0..1 | Tapahtuman yksilöllinen tunniste Neptonissa |
2 | UserId | integer | 0..1 | Henkilön yksilöllinen tunniste Neptonissa. Kuuluu henkilölle, jolla tapahtuma on. |
2 | UserFirstName | string | 0..1 | Henkilön etunimi. Kuuluu henkilölle, jolla tapahtuma on. |
2 | UserLastName | string | 0..1 | Henkilön sukunimi. Kuuluu henkilölle, jolla tapahtuma on. |
2 | UserUsername | string | 0..1 | Henkilön käyttäjätunnus. Kuuluu henkilölle, jolla tapahtuma on. |
2 | UserPersonnelNumber | string | 0..1 | Henkilön henkilönumero. Kuuluu henkilölle, jolla tapahtuma on. |
2 | UserSocialSecurityNumber | string | 0..1 | Henkilön henkilötunnus. Kuuluu henkilölle, jolla tapahtuma on. |
2 | ActivityTypeId | integer | 0..1 | Tapahtumatyypin yksilöllinen tunniste Neptonissa. |
2 | ActivityTypeName | string | 0..1 | Tapahtumatyypin nimi. |
2 | ActivityTypeCategoryId | string | 0..1 | Tapahtumatyypin kategorian yksilöllinen tunniste Neptonissa. |
2 | ActivityTypeCategoryName | string | 0..1 | Tapahtumatyypin kategorian nimi. |
2 | ApproverUserId | integer | 0..1 | Tapahtuman hyväksyneen henkilön yksilöllinen tunniste Neptonissa. |
2 | ApproverFirstName | string | 0..1 | Tapahtuman hyväksyneen henkilön etunimi. |
2 | ApproverLastName | string | 0..1 | Tapahtuman hyväksyneen henkilön sukunimi. |
2 | ApproverPersonnelNumber | string | 0..1 | Tapahtuman hyväksyneen henkilön henkilönumero. |
2 | BeginDateTime | dateTime | 0..1 | Tapahtuman alkupäivä ja -aika. Muotona on VVVV-KK-PPTHH:MM:SS , esimerkiksi 2021-02-18T12:30:00 . |
2 | EndDateTime | dateTime | 0..1 | Tapahtuman päättymispäivä ja -aika. Muotona on VVVV-KK-PPTHH:MM:SS , esimerkiksi 2021-02-18T12:30:00 . |
2 | ModifiedDateTime | dateTime | 0..1 | Aika milloin tapahtumaa on viimeksi muutettu. Muotona on VVVV-KK-PPTHH:MM:SS , esimerkiksi 2021-02-18T12:30:00 . |
2 | ModifiedByUserId | integer | 0..1 | Tapahtumaa viimeksi muuttaneen henkilön tunniste Neptonissa. |
2 | ModifiedFromIp | string | 0..1 | IP-osoite mistä tapahtumaa on viimeksi muutettu. |
2 | Comment | string | 0..1 | Tapahtumalle kirjatut huomiot. |
2 | IsClockedEvent | boolean | 0..1 | Onko tapahtuma kellotettu (true ) vai ei (false ). |
2 | IsCreatedWithPinCode | boolean | 0..1 | Onko tapahtuma kellotettu PIN-koodilla (true ) vai ei (false ). |
2 | OvertimeBasePartTargetedTo | string | 0..1 | Ylityön perusosan kohdenne tapahtumalla. |
2 | OvertimeIncrementPartTargetedTo | string | 0..1 | Ylityön korotusosan kohdenne tapahtumalla. |
2 | RelatedProjects | XML element | 0..1 | Tapahtumalle kirjatut projektit. |
3 | ActivityToProjectRelation | XML element | 0..n | |
4 | Id | integer | 0..1 | Projektin yksilöllinen tunniste Neptonissa |
4 | Duration | integer | 0..1 | Projektin kesto minuutteina |
4 | Name | string | 0..1 | Projektin nimi |
4 | Code | string | 0..1 | Projektin koodi |
2 | WorkIncrements | XML element | 0..1 | Tapahtumalle kirjatut työlisät. |
3 | WorkIncrement | XML element | 0..n | |
4 | Index | integer | 1 | Työlisän indeksi |
4 | Value | decimal | 1 | Työlisän arvo minuutteina, yksikköinä tai desimaalina. |
2 | ActivityDetails | XML element | 0..1 | Tapahtuman lisätiedot |
3 | AbsenceDetails | XML element | 0..1 | Poissaolotapahtuman lisätiedot |
4 | CompensationTypeId | integer | 0..1 | Poissaolon korvaustyypin tunniste. Mahdolliset arvot:
|
4 | CompensationTypeName | string | 0..1 | Poissaolon korvaustyypin nimi |
4 | EarnsVacationDays | boolean | 0..1 | Ansaitaanko poissaolosta vuosilomapäiviä (true ) vai ei (false ) |
4 | AbsenceTypeId | integer | 0..1 | Poissaolotyypin tunniste. Poissaolotyypit näkee Työajasta, Työyhteisön asetuksista: Työtunnit > Poissaolotyypit |
4 | AbsenceTypeName | string | 0..1 | Poissaolotyypin nimi |
3 | PlannedWorkDetails | XML element | 0..1 | Suunnitellun työvuoron lisätiedot |
4 | PlannedWorkCalculationUnit | string | 0..1 | Työvuoron toimipisteen laskentayksikkö. Lue toimipisteen lisäyksestä ja laskentayksiköstä täällä. |
4 | PlannedWorkColor | string | 0..1 | Työvuoron toimipisteen suunnittelutason tunnusväri. Tunnusvärin voi asettaa Vuorosuunnittelussa: Toimipisteet > Valitse suunnittelutaso > Suunnittelutason asetukset > Suunnittelutason väri |
4 | PlannedWorkUseForWorkDayLengthCalculations | boolean | 0..1 | Tuleeko työpäivän pituus työvuorosta (true ) vai ei (false ) |
4 | PlannedWorkCanBeCancelledUntil | string | 0..1 | Päivämäärä ja aika, mihin asti varattu vuorotarve on mahdollista perua. Muotona on VVVV-KK-PPTHH:MM:SS , esimerkiksi 2021-02-18T12:30:00 . |
4 | PlannedWorkWorkTimeLimitOffsetStartInMins | integer | 0..1 |
Työvuorosta tulevan sallitun työn aloitusajan aikasiirtymä minuutteina. Arvo lisätään tapahtuman alkuaikaan, jota käytetään sallitun työn aloitusajan asettamiseen. Nolla-arvo asettaa sallitun työn aloitusajan tapahtuman aloitusajaksi. |
4 | PlannedWorkWorkTimeLimitOffsetEndInMins | integer | 0..1 |
Työvuorosta tulevan sallityn työn lopetusajan aikasiirtymä minuutteina. Arvo lisätään tapahtuman loppuaikaan, jota käytetään sallitun työn lopetusajan asettamiseen. Nolla-arvo asettaa sallitun työn lopetusajan tapahtuman lopetusajaksi. |
4 | AssumedLunchInMinutes | integer | 0..1 | Työvuorosta tulevan oletetun ruokatauon pituus minuutteina |
4 | PlannedWorkActivityGroupPublicInfo | string | 0..1 | Työvuoron ryhmän tietoihin annettu julkinen tieto |
3 | SickLeaveDetails | XML element | 0..1 | Sairausloman lisätiedot |
4 | CompensationTypeId | integer | 0..1 | Sairausloman korvaustyypin tunniste. Mahdolliset arvot:
|
4 | CompensationTypeName | string | 0..1 | Sairausloman korvaustyypin nimi |
4 | EarnsVacationDays | boolean | 0..1 | Ansaitaanko poissaolosta vuosilomapäiviä (true ) vai ei (false ) |
4 | SickLeaveTypeId | integer | 0..1 | Sairausloman tyypin tunniste. Mahdolliset arvot:
|
4 | SickLeaveTypeName | string | 0..1 | Sairausloman tyypin nimi |
4 | MedicalCertificateGiven | boolean | 0..1 | Onko lääkärintodistus luovutettu (true ) vai ei (false ) |
4 | SupervisorsPermission | boolean | 0..1 | Onko sairauslomalle esimiehen hyväksyntä lääkärintodistuksen sijaan (true ) vai ei (false ) |
4 | ReasonCode | string | 0..1 | Sairausloman syykoodi |
2 | ExternalIdentifiers | XML element | 0..1 | Tapahtuman ulkoiset tunnisteet |
3 | ExternalIdentifier | XML element | 1..n | Tapahtuman ulkoinen tunniste |
4 | Identifier | string | 1 | Ulkoinen tunniste |
4 | IdentifierType | string | 1 | Ulkoisen tunnisteen tyyppi. Tällä hetkellä ainoa tuettu tyyppi on External |
2 | IsDeleted | boolean | 0..1 | Onko tapahtuma poistettu (true ) vai ei (false ) |
1 | AccrualList | XML element | 0..1 | Lista kertymistä ja niiden arvoista |
2 | Accrual | XML element | 0..n | |
3 | InternalName | string | 1 | Kertymän tunnisteena käytettävä nimi |
3 | Name | string | 1 | Kertymän selkokielinen nimi |
3 | Amount | string | 1 | Kertymän arvo tunteina ja minuutteina, esimerkiksi -02:43 |
3 | ChangeAmount | string | 0..1 | Paljonko kertymän arvo on muuttunut nykyisenä päivänä. Arvo tunteina ja minuutteina, esimerkiksi +00:30 |
1 | CurrentDateTimeUTC | dateTime | 1 | Tämän hetkinen kellonaika UTC-aikavyöhykkeellä. Muotona on VVVV-KK-PPTHH:MM:SS , esimerkiksi 2021-02-18T12:30:00 . |
Vastauksen esimerkki (BeginActivityV2)
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://tyoaika.tyoteho.fi">
<SOAP-ENV:Body>
<ns1:ReturnValueForBeginActivityV2>
<ResponseCode>1000</ResponseCode>
<ResponseString>All clear. No errors.</ResponseString>
<UserId>123456</UserId>
<CustomerId>1234</CustomerId>
<Locale>fi_FI</Locale>
<StartedActivity>
<Id>12345678</Id>
<UserId>123456</UserId>
<UserFirstName>Maija</UserFirstName>
<UserLastName>Meikäläinen</UserLastName>
<UserUsername>maija.meikäläinen</UserUsername>
<UserPersonnelNumber>1111</UserPersonnelNumber>
<ActivityTypeId>1</ActivityTypeId>
<ActivityTypeName>Työ</ActivityTypeName>
<ActivityTypeCategoryId>1</ActivityTypeCategoryId>
<ActivityTypeCategoryName>Työ</ActivityTypeCategoryName>
<BeginDateTime>2021-01-20T09:12:23</BeginDateTime>
<ModifiedDateTime>2021-01-20T09:12:23</ModifiedDateTime>
<ModifiedByUserId>123456</ModifiedByUserId>
<ModifiedFromIp>127.0.0.1</ModifiedFromIp>
<IsClockedEvent>true</IsClockedEvent>
<IsCreatedWithPinCode>false</IsCreatedWithPinCode>
<OvertimeBasePartTargetedTo>balance</OvertimeBasePartTargetedTo>
<OvertimeIncrementPartTargetedTo>uncompensated</OvertimeIncrementPartTargetedTo>
<IsDeleted>false</IsDeleted>
</StartedActivity>
<AccrualList>
<Accrual>
<InternalName>balance</InternalName>
<Name>Saldo</Name>
<Amount>12:32</Amount>
</Accrual>
</AccrualList>
<CurrentDateTimeUTC>2021-01-20T06:12:23</CurrentDateTimeUTC>
</ns1:ReturnValueForBeginActivityV2>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Vastauksen esimerkki (EndActivityV2)
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://tyoaika.tyoteho.fi">
<SOAP-ENV:Body>
<ns1:ReturnValueForEndActivityV2>
<ResponseCode>1000</ResponseCode>
<ResponseString>All clear. No errors.</ResponseString>
<UserId>123456</UserId>
<CustomerId>1234</CustomerId>
<Locale>fi_FI</Locale>
<EndedActivity>
<Id>12345678</Id>
<UserId>123456</UserId>
<UserFirstName>Maija</UserFirstName>
<UserLastName>Meikäläinen</UserLastName>
<UserUsername>maija.meikäläinen</UserUsername>
<UserPersonnelNumber>1111</UserPersonnelNumber>
<ActivityTypeId>1</ActivityTypeId>
<ActivityTypeName>Työ</ActivityTypeName>
<ActivityTypeCategoryId>1</ActivityTypeCategoryId>
<ActivityTypeCategoryName>Työ</ActivityTypeCategoryName>
<BeginDateTime>2021-01-19T09:12:23</BeginDateTime>
<EndDateTime>2021-01-19T17:45:11</EndDateTime>
<ModifiedDateTime>2021-01-20T17:45:11</ModifiedDateTime>
<ModifiedByUserId>123456</ModifiedByUserId>
<ModifiedFromIp>127.0.0.1</ModifiedFromIp>
<IsClockedEvent>true</IsClockedEvent>
<IsCreatedWithPinCode>false</IsCreatedWithPinCode>
<OvertimeBasePartTargetedTo>balance</OvertimeBasePartTargetedTo>
<OvertimeIncrementPartTargetedTo>uncompensated</OvertimeIncrementPartTargetedTo>
<IsDeleted>false</IsDeleted>
</EndedActivity>
<AccrualList>
<Accrual>
<InternalName>balance</InternalName>
<Name>Saldo</Name>
<Amount>13:05</Amount>
<ChangeAmount>+00:33</ChangeAmount>
</Accrual>
</AccrualList>
<CurrentDateTimeUTC>2021-01-20T14:45:11</CurrentDateTimeUTC>
</ns1:ReturnValueForEndActivityV2>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>