TerminalLoginV2

Rajapinnan yleiskuvaus

Verkkopalveluita käytetään henkilön nykytilan hakemiseen Neptonista. Verkkopalvelu on suunniteltu käytettäväksi päätelaitesovelluksissa, esimerkiksi näyttämään seuraavat henkilöä koskevat tiedot:

• Avoimena oleva tapahtumakirjaus
• Projektit, joita voi tapahtumille kirjata
• Mitä projekteja käytetään oletuksena uuden tapahtuman aloituksessa
• Onko projektin kirjaaminen tapahtumalle pakollista vai ei
• Tapahtumille kirjattavissa olevat työlisät
• Ylityön oletuskohdenne työtapahtumilla
• Kirjattavissa olevat tapahtumatyypit
• Henkilön kertymät ja niiden saldot

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 (TerminalLogin)

Rakenteelliset muutokset

<tyo:ParametersForTerminalLogin>
  ...
</tyo:ParametersForTerminalLogin>

<tyo:ParametersForTerminalLoginV2>
  ...
</tyo:ParametersForTerminalLoginV2>

<tyo:ReturnValueForTerminalLogin>
  ...
</tyo:ReturnValueForTerminalLogin>

<tyo:ReturnValueForTerminalLoginV2>
  ...
</tyo:ReturnValueForTerminalLoginV2>

<OngoingActivity>
  <BeginDateTime>2020-01-01 12:00:00</BeginDateTime>
  <EndDateTime>2020-01-01 14:00:00</EndDateTime>
  <ModifiedDateTime>2020-01-01 16:00:00</ModifiedDateTime>
</OngoingActivity>

<OngoingActivity>
  <BeginDateTime>2020-01-01T12:00:00</BeginDateTime>
  <EndDateTime>2020-01-01T14:00:00</EndDateTime>
  <ModifiedDateTime>2020-01-01T16:00:00</ModifiedDateTime>
</OngoingActivity>      

Poistuneet elementit

Aiemmassa versiossa vastaus sisälsi seuraavat elementit kahdesti, ensin OngoingActivity-elementin alla ja sitten myös ActivityDetails-elementin alla:

• PlannedWorkCalculationUnit

• PlannedWorkColor

• PlannedWorkUseForWorkDayLengthCalculations

• PlannedWorkCanBeCancelledUntil

• PlannedWorkWorkTimeLimitOffsetStartInMins

• PlannedWorkWorkTimeLimitOffsetEndInMins

• PlannedWorkActivityGroupPublicInfo

Nämä löytyvät jatkossa ainoastaan ActivityDetails-elementin alta.

Seuraava elementti oli merkitty vanhentuneeksi jo aiemmassa versiossa ja on nyt poistettu vastauksesta:

• RelatedActivityId

Uudet ominaisuudet ja elementit

• Rajapintavastaus sisältää henkilönumeron tapahtuman henkilölle (UserPersonnelNumber-elementti)
• Rajapintavastaus sisältää henkilönumeron tapahtuman hyväksyjälle (ApproverPersonnelNumber-elementti)
• Rajapintavastaus sisältää tapahtuman ulkoiset tunnisteet (ExternalIdentifiers-elementti)

Lähetettävät tiedot

Kyselyn esimerkki

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tyo="http://tyoaika.tyoteho.fi">
  <soapenv:Header/>
  <soapenv:Body>
    <tyo:ParametersForTerminalLoginV2>
      <CallerAuthentication>
        <CustomerId>1234</CustomerId>
        <Username>PäätelaiteKäyttäjä</Username>
        <Password>KuvitteellinenSalasana123</Password>
        <RFID>2893789127981239</RFID> <!-- Päätelaitteella luettu RFID-koodi -->        
      </CallerAuthentication>
    </tyo:ParametersForTerminalLoginV2>
  </soapenv:Body>
</soapenv:Envelope>

Vastaus

<StartDate xsi:nil="true" />

<EndDate xsi:nil="true" />

<ParentProjectId xsi:nil="true" />

<ParentProjectCode xsi:nil="true" />

Vastauksen esimerkki

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://tyoaika.tyoteho.fi" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <SOAP-ENV:Body>
    <ns1:ReturnValueForTerminalLoginV2>
      <ResponseCode>1000</ResponseCode>
      <ResponseString>All clear. No errors.</ResponseString>
      <UserId>123456</UserId>
      <CustomerId>1234</CustomerId>
      <Username>matti.meikäläinen</Username>
      <FirstName>Matti</FirstName>
      <LastName>Meikäläinen</LastName>
      <Locale>fi_FI</Locale>
      <AvailableProjects>
        <Project>
          <Id>9001</Id>
          <Name>Asiakaspalvelu</Name>
          <Deleted>false</Deleted>
          <Active>true</Active>
          <Code>ASPA01</Code>
          <TypeInternalName>project_work</TypeInternalName>
          <Description>Asiakaspalvelutyö</Description>
          <StartDate xsi:nil="true" />
          <EndDate xsi:nil="true" />
          <ParentProjectId xsi:nil="true" />
          <ParentProjectCode xsi:nil="true" />
        </Project>
      </AvailableProjects>
      <ProjectsToContinue>
        <ProjectToContinue>
          <Id>9001</Id>
          <Name>Asiakaspalvelu</Name>
          <Code>ASPA01</Code>
        </ProjectToContinue>
      </ProjectsToContinue>
      <OnGoingActivity>
        <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>
        <ModifiedDateTime>2021-01-19T09:12:23</ModifiedDateTime>
        <ModifiedByUserId>123456</ModifiedByUserId>
        <ModifiedFromIp>127.0.0.1</ModifiedFromIp>
        <IsClockedEvent>true</IsClockedEvent>
        <IsCreatedWithPinCode>false</IsCreatedWithPinCode>
        <OvertimeBasePartTargetedTo>balance</OvertimeBasePartTargetedTo>
        <OvertimeIncrementPartTargetedTo>uncompensated</OvertimeIncrementPartTargetedTo>
        <RelatedProjects>
          <ActivityToProjectRelation>
            <Id>9001</Id>
            <Duration>333</Duration>
            <Name>Asiakaspalvelu</Name>
            <Code>ASPA01</Code>
          </ActivityToProjectRelation>
        </RelatedProjects>
        <IsDeleted>false</IsDeleted>
      </OnGoingActivity>
      <ProjectMandatory>true</ProjectMandatory>
      <DefaultOvertimeBasePartTargetedTo>balance</DefaultOvertimeBasePartTargetedTo>
      <DefaultOvertimeIncrementPartTargetedTo>uncompensated</DefaultOvertimeIncrementPartTargetedTo>
      <ActivityTypes>
        <ActivityType>
          <Id>1</Id>
          <InternalName>Work</InternalName>
          <TranslatedName>
            <Locale>fi_FI</Locale>
            <Name>Työ</Name>
          </TranslatedName>
          <TranslatedName>
            <Locale>en_US</Locale>
            <Name>Work</Name>
          </TranslatedName>
          <CanAssignWorkIncrements>true</CanAssignWorkIncrements>
          <CanHaveRelatedProjects>true</CanHaveRelatedProjects>
          <CategoryInternalName>work</CategoryInternalName>
          <TranslatedCategoryName>
            <Locale>fi_FI</Locale>
            <Name>Työ</Name>
          </TranslatedCategoryName>
          <TranslatedCategoryName>
            <Locale>en_US</Locale>
            <Name>Work</Name>
          </TranslatedCategoryName>
          <BeginDateTimeInput>disabled</BeginDateTimeInput>
          <EndDateTimeInput>disabled</EndDateTimeInput>
        </ActivityType>
      </ActivityTypes>
      <AccrualList>
        <Accrual>
          <InternalName>balance</InternalName>
          <Name>Saldo</Name>
          <Amount>13:05</Amount>
        </Accrual>
      </AccrualList>
      <CurrentDateTimeUTC>2021-01-20T14:45:11</CurrentDateTimeUTC>
    </ns1:ReturnValueForTerminalLoginV2>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>