BeginActivityV2 & EndActivityV2

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

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

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>