TerminalLoginV2

Interface overview

The webservice is used to retrieve a person's current status from Nepton. The web service is designed to be used in terminal applications, to show for example the following user related information:

• Ongoing event registration
• Projects that can be registered for events
• Which projects are used by default when starting a new event
• Is registering a project for an event mandatory or not
• Work supplements that can be registered for events
• Default overtime target for work events
• Event typess that can be registered
• Person's accruals and their balances

Authentication in the web service differs from other web services in that a person who has successfully authenticated with a username and password can authenticate as another person based on a PIN code or RFID code. In the first step, the authenticated person must have the rights to view personal data. For example:

<CallerAuthentication>
  <CustomerId>1234</CustomerId>
  <Username>PäätelaiteKäyttäjä</Username>
  <Password>KuvitteellinenSalasana123</Password>
  <PinCode>1234</PinCode> <!-- Pin code given on terminal -->
</CallerAuthentication>

If the person cannot be found with the provided PIN code or RFID code, authentication will fail.

The WSDL schema of the web service is publicly available here. The interfaces are described in general here.

The occurrences column in the description determines whether a piece of information is mandatory in the call or not. Occurrences 0 means that the information in question does not need to be passed in the call. Occurrences 1 means that the information must appear once in the call. Occurrences 0..n means that the information in question can appear any number of times in the call. Occurrences 1..n means that the information in question must appear in the data at least once, but can appear more often.

Changes from previous version (TerminalLogin)

Structural changes

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

Obsolete elements

The following elements were previously in the response twice, first under the OngoingActivity element and the second time under the ActivityDetails element:

• PlannedWorkCalculationUnit

• PlannedWorkColor

• PlannedWorkUseForWorkDayLengthCalculations

• PlannedWorkCanBeCancelledUntil

• PlannedWorkWorkTimeLimitOffsetStartInMins

• PlannedWorkWorkTimeLimitOffsetEndInMins

• PlannedWorkActivityGroupPublicInfo

From now on, these elements will only be found under the ActivityDetails element.

RelatedActivityId was already reported as deprecated in the previous version, but now this element has been technically removed from the response.

New features and elements

• The response contains the personnel number for the person in the event (UserPersonnelNumber element)
• The response contains the personnel number for the approver of the event (ApproverPersonnelNumber element)
• The response contains the external identifiers for the event (ExternalIdentifiers element)

Sent Data

Call example

<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> <!-- RFID code read on the terminal -->        
      </CallerAuthentication>
    </tyo:ParametersForTerminalLoginV2>
  </soapenv:Body>
</soapenv:Envelope>

Response

<StartDate xsi:nil="true" />

<EndDate xsi:nil="true" />

<ParentProjectId xsi:nil="true" />

<ParentProjectCode xsi:nil="true" />

Response example

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