English (United Kingdom)
Palvelun tila: -
  1. Nepton Support
  2. Palvelun käyttö
  3. Liittymät
  4. Sovellusliittymät (API)
  5. API esimerkit ja metodi-kuvaukset

BeginActivityV2

  • Päivitetty

Rajapinnan yleiskuvaus

Verkkopalvelua käytetään tapahtuman aloitukseen Neptonissa

Verkkopalvelu on suunniteltu käytettäväksi päätelaitesovelluksissa. Kaikki verkkopalvelun kautta aloitetut tapahtumat kirjataan kellotettuina tapahtumina.

Verkkopalvelun 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.

Muutokset aiempaan versioon nähden (BeginActivity)

Rakenteelliset muutokset

Vanha Uusi Lisätiedot 
<tyo:ParametersForBeginActivity>
  ...
</tyo:ParametersForBeginActivity>
 
<tyo:ParametersForBeginActivityV2>
  ...
</tyo:ParametersForBeginActivityV2>
 Kutsun juurielementin nimi muuttunut 
<tyo:ReturnValueForBeginActivity>
  ...
</tyo:ReturnValueForBeginActivity>
 
<tyo:ReturnValueForBeginActivityV2>
  ...
</tyo:ReturnValueForBeginActivity>
 Vastauksen juurielementin nimi muuttunut 
<StartedActivity>
  <BeginDateTime>
    2020-01-01 12:00:00
  </BeginDateTime>
  <EndDateTime>
    2020-01-01 14:00:00
  </EndDateTime>
  <ModifiedDateTime>
    2020-01-01 16:00:00
  </ModifiedDateTime>
</StartedActivity>
 
<StartedActivity>
  <BeginDateTime>
    2020-01-01T12:00:00
  </BeginDateTime>
  <EndDateTime>
    2020-01-01T14:00:00
  </EndDateTime>
  <ModifiedDateTime>
    2020-01-01T16:00:00
  </ModifiedDateTime>
</StartedActivity>
 Vastauksessa päivämäärä ja aika -elementit ovat nyt datetime-tyyppisiä, mikä vaikuttaa hieman päivämääräformaattiin (BeginDateTime, EndDateTime, ModifiedDateTime)

Poistuneet elementit

Seuraavat elementit olivat aiemmin vastauksessa kahteen kertaan, ensin Activity-elementin alla ja toisen kerran PlannedWorkDetails-elementin alla:

  • PlannedWorkCalculationUnit

  • PlannedWorkColor

  • PlannedWorkUseForWorkDayLengthCalculations

  • PlannedWorkCanBeCancelledUntil

  • PlannedWorkWorkTimeLimitOffsetStartInMins

  • PlannedWorkWorkTimeLimitOffsetEndInMins

  • PlannedWorkActivityGroupPublicInfo

Jatkossa kyseiset elementit löytyvät ainoastaan PlannedWorkDetails-elementin alta.

RelatedActivityId oli ilmoitettu jo aiemman version kohdalla käytöstä poistetuksi, mutta nyt kyseinen elementti on teknisesti poistettu vastauksesta

Uudet ominaisuudet ja elementit

  • Mahdollisuus määrittää tapahtumalle ulkoisia tunnisteita

    • Lisätty ExternalIdentifiers-elementti kutsuun

    • Lisätty ExternalIdentifiers-elementti vastaukseen
  • Vastaus sisältää tiedon tapahtuman henkilön henkilönumerosta
    • Lisätty UserPersonnelNumber-elementti
  • Vastaus sisältää tiedon tapahtuman hyväksyjän henkilönumerosta
    • Lisätty ApproverPersonnelNumber-elementti

Lähetettävät tiedot

TASO

KENTÄN NIMI

MUOTO

ESIINTYMISKERRAT

SELITE

0

ParametersForBeginActivityV2

XML element

1

Juurielementti,
SOAP body:n alla

1

CallerAuthentication

XML element

1

Lisää tietoa autentikoitumisesta täällä

1

ActivityTypeId

integer

1

Aloitettavan tapahtumatyypin Nepton-tunniste. Tapahtumatyyppien listaus on mahdollista lukea API:n kautta. Lue lisää täältä

1

BeginDateTime

datetime

0..1

Aloitettavan tapahtuman alkamispäivä ja -aika. Tieto annetaan muodossa VVVV-KK-PPTHH:MM:SS, esimerkiksi 2021-02-18T12:30:00.

Jos tietoa ei anneta, tapahtuman alkamisajaksi annetaan nykyinen aika.

1

EndDateTime

datetime

0..1

Tapahtuman päättymispäivä ja -aika. Tieto annetaan muodossa VVVV-KK-PPTHH:MM:SS, esimerkiksi 2021-02-18T12:30:00.

Ei pakollinen. Tapahtuma voidaan sulkea toisella metodilla

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

Kertymä, johon ylityön perusosa asetetaan. Katso mahdolliset arvot täältä

1

OvertimeIncrementPartTargetedTo

string

0..1

Kertymä, johon ylityön korotettu osa asetetaan. Katso mahdolliset arvot täältä

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

ExternalIdentifiers

XML element

0..1

Tapahtumalle asetettavat ulkoiset tunnisteet

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

<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>

Vastaus

TASO

KENTÄN NIMI

MUOTO

ESIINTYMISKERRAT

SELITE

0

ReturnValueForBeginActivityV2

XML element

1

Juurielementti,
SOAP body:n alla

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. Katso tuetut kielet ja niiden koodit täältä

1

StartedActivity

XML element

0..1

Aloitetun 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:

  • 1 - palkallinen

  • 2 - palkaton

  • 3 - vähennetty palkka

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

PlannedWorkCalculationUnitBeginActivity

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:

  • 1 - palkallinen

  • 2 - palkaton

  • 3 - vähennetty palkka

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:

  • 1 - sairas

  • 2 - lapsi sairas

  • 3 - työtapaturma

  • 4 - työmatkatapaturma

  • 5 - vapaa-ajan tapaturma

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

<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>