Interface overview
The web service is used to retrieve event information from Nepton. The web service also returns events for deactivated people (those deleted in Nepton using the Remove User function) when a user filter (e.g. personal identification number) is included in the query.
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 the previous version (GetActivitiesV4)
New features and fields
-
Events can be filtered with person's external identifiers
- FilterByUserPersonExternalIdentifiers - element added to the request
- FilterByUserPersonExternalIdentifiers contains PersonExternalIdentifier - elements
- PersonExternalIdentifier - element contains elements Identifier and FieldName
Sent data
| Level | Field name | Format | Occurences | Description |
|---|---|---|---|---|
| Root, below SOAP body |
ParametersForGetActivitiesV5 | XML element | 1 | |
| 1 | CallerAuthentication | XML element | 1 | More information about authentication here. |
| 1 | FilterByUserIds | XML element | 0..1 | Filtering based on users' unique Nepton IDs. |
| 2 | UserId | integer | 1..n | One user's unique Nepton ID. |
| 1 | FilterByUserNames | XML element | 0..1 | Filtering based on person's usernames. |
| 2 | UserName | string | 1..n | One person's username. |
| 1 | FilterByUserPersonnelNumbers | XML element | 0..1 | Filtering based on person's personnel numbers. |
| 2 | PersonnelNumber | string | 1..n | One person's personnel number. |
| 1 | FilterByUserPersonExternalIdentifiers | XML element | 0..1 | Filtering based on persons' external identifiers |
| 2 | PersonExternalIdentifier | string | 1..n | External identifier information of person |
| 3 | Identifier | string | 1 | External identifier value |
| 3 | FieldName | string | 1 |
External identifier field name. Supported values: ExternalIdentifier1 |
| 1 | FilterByActivityTypeIds | XML element | 0..1 |
Filtering based on event types' unique Nepton IDs. If you want to search for all event types, this element is omitted. |
| 2 | ActivityTypeId | integer | 1..n |
The identifier of a single event type. The ActivityTypeId can be checked in SQL by adding ActivityTypeId AS Aid to the SELECT clause. This will add the Aid column, where the Id is displayed. If the Id is not found, an empty query is returned. |
| 1 | FilterByExternalIdentifiers | XML element | 0..1 | Filtering based on event types' external IDs. |
| 2 | ExternalIdentifier | XML element | 1..n | External ID of a single event. |
| 3 | Identifier | string | 1 | External identifier |
| 3 | IdentifierType | string | 1 | Type of external identifier. At the moment the only supported type is External
|
| 1 | FilterPeriodBeginDateTime | dateTime | 0..1 | Filtering for events, that start after given date and time. Format is VVVV-KK-PPTHH:MM:SS, for example 2021-02-18T12:30:00. |
| 1 | FilterPeriodEndDateTime | dateTime | 0..1 | Filtering for events, that end before given date and time. Format is VVVV-KK-PPTHH:MM:SS, for example 2021-02-18T12:30:00. |
| 1 | FilterModifiedBeginDateTime | dateTime | 0..1 | Filtering for events, that have last been modified after given date and time. Format is VVVV-KK-PPTHH:MM:SS, for example2021-02-18T12:30:00. |
| 1 | FilterModifiedEndDateTime | dateTime | 0..1 | Filtering for events, that have last been modified before given date and time. Format is VVVV-KK-PPTHH:MM:SS, for example 2021-02-18T12:30:00. |
| 1 | FilterIsApproved | boolean | 0..1 | Filtering for events that are approved (true) or are not approved (false). |
| 1 | IncludeDeleted | boolean | 0..1 | Whether deleted evets are included (true) or not (false). By default deleted events are not included. |
| 1 | OrderResultsFirstBy | string | 0..1 |
The primary sorting criteria for events. The following values are supported:
|
| 1 | OrderResultsSecondBy | string | 0..1 | A secondary sorting criteria for events. The supported criteria are the same as the primary sorting criterion. |
| 1 | OrderResultsThirdBy | string | 0..1 | A third sorting criteria for events. The supported criteria are the same as the primary sorting criterion. |
Call example
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tyo="http://tyoaika.tyoteho.fi">
<soapenv:Header/>
<soapenv:Body>
<tyo:ParametersForGetActivitiesV5>
<CallerAuthentication /> <!-- Autentikoituminen vaaditaan, mutta on jätetty tässä esimerkissä pois -->
<FilterByActivityTypeIds>
<ActivityTypeId>1</ActivityTypeId>
</FilterByActivityTypeIds>
<FilterByExternalIdentifiers>
<ExternalIdentifier>
<Identifier>c2d816bc-bf67-11eb-8529-0242ac130003</Identifier>
<IdentifierType>External</IdentifierType>
</ExternalIdentifier>
<ExternalIdentifier>
<Identifier>4a700e90-c754-4d1d-ac9a-bfdc011fc2c1</Identifier>
<IdentifierType>External</IdentifierType>
</ExternalIdentifier>
</FilterByExternalIdentifiers>
<FilterByUserPersonExternalIdentifiers>
<PersonExternalIdentifier>
<Identifier>EMP-12345</Identifier>
<FieldName>ExternalIdentifier1</FieldName>
</PersonExternalIdentifier>
<PersonExternalIdentifier>
<Identifier>EMP-67890</Identifier>
<FieldName>ExternalIdentifier1</FieldName>
</PersonExternalIdentifier>
</FilterByUserPersonExternalIdentifiers>
<FilterPeriodBeginDateTime>2021-01-01T00:00:00</FilterPeriodBeginDateTime>
<FilterPeriodEndDateTime>2021-01-31T23:59:59</FilterPeriodEndDateTime>
<IncludeDeleted>false</IncludeDeleted>
<OrderResultsFirstBy>ActivityBeginDatetime</OrderResultsFirstBy>
</tyo:ParametersForGetActivitiesV5>
</soapenv:Body>
</soapenv:Envelope>
Response
| Level | Field name | Format | Occurances | Description |
|---|---|---|---|---|
| Root, below SOAP body |
ReturnValueForGetActivitiesV5 | XML element | 1 | |
| 1 | ResponseCode | integer | 1 | Result code. See list of response codes here. |
| 1 | ResponseString | string | 1 | Response description |
| 1 | ActivityList | XML element | 1 | |
| 2 | Activity | XML element | 0..n | |
| 3 | Id | integer | 0..1 | Unique identifier for event. This remains unchanged even if event is modified. |
| 3 | UserId | integer | 0..1 | Person's unique identifier in Nepton. Belongs to the person that the event is marked for. |
| 3 | UserFirstName | string | 0..1 | Person's first name. Belongs to the person that the event is marked for. |
| 3 | UserLastName | string | 0..1 | Person's last name. Belongs to the person that the event is marked for. |
| 3 | UserUsername | string | 0..1 | Person's user name. Belongs to the person that the event is marked for. |
| 3 | UserPersonnelNumber | string | 0..1 | Person's personnel number. Belongs to the person that the event is marked for. |
| 3 | PersonExternalIdentifiers | xml element | 0..n | List of person's external identifiers. Belongs to the person that the event is marked for. |
| 4 | PersonExternalIdentifier | xml element | 0..1 | Person external identifier info |
| 5 | Identifier | string | 1 | Person's external identifier value |
| 5 | FieldName | string | 1 |
Person's external identifier type name. Supported values: ExternalIdentifier1 |
| 3 | UserSocialSecurityNumber | string | 0..1 | Person's social security number. Belongs to the person that the event is marked for. |
| 3 | ActivityTypeId | integer | 0..1 | Identifier for the event type in Neptonissa. |
| 3 | ActivityTypeName | string | 0..1 | Name of the event type. |
| 3 | ActivityTypeCategoryId | string | 0..1 | Event type category identifier in Nepton. |
| 3 | ActivityTypeCategoryName | string | 0..1 | Event type category name. |
| 3 | ApproverUserId | integer | 0..1 | Unique identifier in Nepton for the person who has approved the event. |
| 3 | ApproverFirstName | string | 0..1 | First name of the person who has approved the event. |
| 3 | ApproverLastName | string | 0..1 | Last name of the person who has approved the event. |
| 3 | ApproverPersonnelNumber | string | 0..1 | Personnel number of the person who has approved the event. |
| 3 | BeginDateTime | dateTime | 0..1 | Event begin date and time. Format is YYYY-MM-DDTHH:MM:SS, e.g 2021-02-18T12:30:00. |
| 3 | EndDateTime | dateTime | 0..1 | Event end date and time. Format is YYYY-MM-DDTHH:MM:SS, e.g 2021-02-18T12:30:00. |
| 3 | ModifiedDateTime | dateTime | 0..1 | Date and time when event was last modified. Format is YYYY-MM-DDTHH:MM:SS, e.g 2021-02-18T12:30:00. |
| 3 | ModifiedByUserId | integer | 0..1 | Tapahtumaa viimeksi muuttaneen henkilön tunniste Neptonissa. |
| 3 | Comment | string | 0..1 | Notes added to the event. |
| 3 | IsClockedEvent | boolean | 0..1 | Is the event clocked in real time (true) or not (false). |
| 3 | IsCreatedWithPinCode | boolean | 0..1 | Is event recorded with a PIN-code (true) or not (false). |
| 3 | OvertimeBasePartTargetedTo | string | 0..1 | Event's overtime base part target. |
| 3 | OvertimeIncrementPartTargetedTo | string | 0..1 | Event's overtime increment part target. |
| 3 | RelatedProjects | XML element | 0..1 | Event's projects. |
| 4 | ActivityToProjectRelation | XML element | 0..n | |
| 5 | Id | integer | 0..1 | Unique identifier of project in Neptonissa |
| 5 | Duration | integer | 0..1 | Project duration in minutes. |
| 5 | Name | string | 0..1 | Project name. |
| 5 | Code | string | 0..1 | Project code. |
| 3 | WorkIncrements | XML element | 0..1 | Supplements recorded for the event. |
| 4 | WorkIncrement | XML element | 0..n | |
| 5 | Index | integer | 1 | Index of the supplement. |
| 5 | Value | decimal | 1 | Supplement value in minutes, units or decimals. |
| 3 | ActivityDetails | XML element | 0..1 | Additional details for event |
| 4 | AbsenceDetails | XML element | 0..1 | Details of an absence type event. |
| 5 | CompensationTypeId | integer | 0..1 |
Absence compensation identifier. Possible values:
|
| 5 | CompensationTypeName | string | 0..1 | Absence compensation type name. |
| 5 | EarnsVacationDays | boolean | 0..1 | Does absence earn annual leave days (true) or not (false). |
| 5 | AbsenceTypeId | integer | 0..1 | Absence type identifier. You can see absence type identifiers in Worktime settings Work hours > Absence types. |
| 5 | AbsenceTypeName | string | 0..1 | Absence type name. |
| 4 | PlannedWorkDetails | XML element | 0..1 | Details of planned work event. |
| 5 | PlannedWorkCalculationUnit | string | 0..1 | Calculation unit of the location of the planned shift. Read more about adding locations and calculation units here. |
| 5 | PlannedWorkColor | string | 0..1 | Colour highlight for the location of the planned shift. You can set the colour in Planning > Locations > Select location > Location settings > Location colour. |
| 5 | PlannedWorkUseForWorkDayLengthCalculations | boolean | 0..1 | Does work day length come from the planned shift (true) or not(false) |
| 5 | PlannedWorkCanBeCancelledUntil | string | 0..1 | Date until planned work event that has been reserved can be cancelled. Format is YYYY-MM-DDTHH:MM:SS, e.g. 2021-02-18T12:30:00. |
| 5 | PlannedWorkWorkTimeLimitOffsetStartInMins | integer | 0..1 | Time offset in minutes for the allowed work start time from the work shift. The value is added to the event's start time, which is used to set the allowed work start time. A zero value sets the allowed work start time to the event's start time. |
| 5 | PlannedWorkWorkTimeLimitOffsetEndInMins | integer | 0..1 | Time offset in minutes for the allowed work end time from the work shift. The value is added to the event's end time, which is used to set the allowed work end time. A zero value sets the allowed work end time to the event's end time. |
| 5 | AssumedLunchInMinutes | integer | 0..1 | Assumed lunch that is set in the planned shift in minutes. |
| 5 | PlannedWorkActivityGroupPublicInfo | string | 0..1 | Public info set in the planned shift group info. |
| 4 | SickLeaveDetails | XML element | 0..1 | Details for a sick leave type event. |
| 5 | CompensationTypeId | integer | 0..1 |
Sick leave compensation type. Possible values:
|
| 5 | CompensationTypeName | string | 0..1 | Sick leave compensation type name |
| 5 | EarnsVacationDays | boolean | 0..1 | Does sick leave earn annual leave days (true) or not (false) |
| 5 | SickLeaveTypeId | integer | 0..1 |
Sick leave type identifier. Possible values:
|
| 5 | SickLeaveTypeName | string | 0..1 | Sick leave type name |
| 5 | MedicalCertificateGiven | boolean | 0..1 | Has medical certificate been received (true) or not (false) |
| 5 | SupervisorsPermission | boolean | 0..1 | Has permission of supervisor instead of medical certificate (true) or not (false) |
| 5 | ReasonCode | string | 0..1 | Sick leave reason code |
| 3 | ExternalIdentifiers | XML element | 0..1 | External identifiers for event |
| 4 | ExternalIdentifier | XML element | 1..n | External identifier information for event |
| 5 | Identifier | string | 1 | Event external identifier value |
| 5 | IdentifierType | string | 1 | Event external identifier type |
| 3 | ResetValue | decimal | 0..1 | The accrual and annual leave reset value in minutes. |
| 3 | ChangeValue | decimal | 0..1 | The accrual and annual leave change value in minutes. |
| 3 | IsDeleted | boolean | 0..1 | Has event been deleted (true) or not (false) |
Response example
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tyo="http://tyoaika.tyoteho.fi">
<SOAP-ENV:Body>
<tyo:ReturnValueForGetActivitiesV5>
<ResponseCode>1000</ResponseCode>
<ResponseString>All clear. No errors.</ResponseString>
<ActivityList>
<Activity>
<Id>12345678</Id>
<UserId>9001</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-19T08:00:00</BeginDateTime>
<EndDateTime>2021-01-19T16:00:00</EndDateTime>
<ModifiedDateTime>2021-01-20T09:12:23</ModifiedDateTime>
<ModifiedByUserId>9001</ModifiedByUserId>
<ModifiedFromIp>127.0.0.1</ModifiedFromIp>
<Comment>Työtapahtuma</Comment>
<IsClockedEvent>false</IsClockedEvent>
<IsCreatedWithPinCode>false</IsCreatedWithPinCode>
<OvertimeBasePartTargetedTo>salary</OvertimeBasePartTargetedTo>
<OvertimeIncrementPartTargetedTo>salary</OvertimeIncrementPartTargetedTo>
<RelatedProjects>
<ActivityToProjectRelation>
<Id>12345</Id>
<Duration>450</Duration>
<Name>Asiakaspalvelu</Name>
<Code>ASPA</Code>
</ActivityToProjectRelation>
</RelatedProjects>
<IsDeleted>false</IsDeleted>
</Activity>
</ActivityList>
</tyo:ReturnValueForGetActivitiesV5>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>