Timecard Soap API

From
(Difference between revisions)
Jump to: navigation, search
(Fix links)
(→‎Schedule Related Methods)
 
(10 intermediate revisions by one user not shown)
Line 175: Line 175:
 
|[[UserIDBean]]
 
|[[UserIDBean]]
 
|Returns array of OverTimeRuleBean.
 
|Returns array of OverTimeRuleBean.
 +
|}
 +
 +
===Schedule Related Methods===
 +
 +
{| border=1
 +
!Returns
 +
!Method
 +
!Parameters
 +
!Description
 +
|---- bgcolor=#EDEDFF
 +
| AddScheduleResult
 +
| addSchedule
 +
| [[UserIDBean]], [[#ScheduleDetails | ScheduleDetails]]
 +
| Adds a new schedule into the Timecard system, with the given details
 +
|---- bgcolor=#EDEDFF
 +
| GetScheduleResult (contains [[#ScheduleDetails | ScheduleDetails]])
 +
| getSchedule
 +
| [[UserIDBean]], schedulePk
 +
| Query the details of given schedule
 +
|---- bgcolor=#EDEDFF
 +
| DeleteScheduleResult
 +
| deleteSchedule
 +
| [[UserIDBean]], schedulePk
 +
| Remove given schedule from system
 
|}
 
|}
  
Line 315: Line 339:
 
|---- bgcolor=#EDEDFF
 
|---- bgcolor=#EDEDFF
 
|UpdateTaskResult
 
|UpdateTaskResult
−
|[http://eservicewebtest.econz.com/SOAP/timecard_wsdl_doc.html#op.N69826 updateTaskDetails]
+
|[https://services.w3.org/xslt?xslfile=http://tomi.vanek.sk/xml/wsdl-viewer.xsl&xmlfile=https://eservicewebtest.econz.com/axis/services/timecard1Soap?wsdl&transform=Submit#op.d1e1874 updateTaskDetails]
 
|UserIDBean, taskName, taskDetails
 
|UserIDBean, taskName, taskDetails
 
|Sets/updates the task details.
 
|Sets/updates the task details.
Line 365: Line 389:
 
|Remove the rateCode specified for the provided userPK/taskName combination
 
|Remove the rateCode specified for the provided userPK/taskName combination
 
|}
 
|}
 +
 +
----
  
 
=== Main Data Type Definitions ===
 
=== Main Data Type Definitions ===
Line 1,018: Line 1,044:
 
|N/A
 
|N/A
 
|Value entered for the custom field.
 
|Value entered for the custom field.
 +
|}
 +
 +
 +
-----
 +
 +
====ScheduleDetails====
 +
{| border=1
 +
!Name
 +
!Type
 +
!Required
 +
!Description
 +
|---- bgcolor=#EDEDFF
 +
| description
 +
| String
 +
| Yes
 +
| Schedule name/description
 +
|---- bgcolor=#EDEDFF
 +
| start
 +
| [[DateTime]]
 +
| Yes
 +
| Start time/date of schedule
 +
|---- bgcolor=#EDEDFF
 +
| end
 +
| [[DateTime]]
 +
| Yes
 +
| End time/date of schedule
 +
|---- bgcolor=#EDEDFF
 +
| colourHex
 +
| String
 +
| Yes
 +
| Colour of schedule (for display on web-scheduler). E.g. #666666
 +
|---- bgcolor=#EDEDFF
 +
| isRepeat
 +
| Boolean
 +
| Yes
 +
| Determines if this schedule repeats on an interval (repeatFrequency)
 +
|---- bgcolor=#EDEDFF
 +
| repeatOnlyWeekdays
 +
| Boolean
 +
| Yes
 +
| Determines if the repeat frequency will include on weekdays or not. Unused when isRepeat is false and/or repeatFrequency not Week
 +
|---- bgcolor=#EDEDFF
 +
| repeatFrequency
 +
| String
 +
| No
 +
| Day, Week
 +
|---- bgcolor=#EDEDFF
 +
| repeatDays
 +
| [[#RepeatDays | RepeatDays]]
 +
| No
 +
| Used with repeatFrequency Day
 +
|---- bgcolor=#EDEDFF
 +
| endRepeat
 +
| [[DateTime]]
 +
| No
 +
| Used with isRepeat to determine end date
 +
|---- bgcolor=#EDEDFF
 +
| fieldDeviceList
 +
| ArrayOfString
 +
| Yes
 +
| List of user PKs to assign to schedule
 +
|---- bgcolor=#EDEDFF
 +
| taskList
 +
| ArrayOfString
 +
| Yes
 +
| List of task names to allocate to schedule
 +
|---- bgcolor=#EDEDFF
 +
| notes
 +
| String
 +
| Yes
 +
| Additional notes
 +
|}
 +
 +
====RepeatDays====
 +
{| border=1
 +
!Name
 +
!Type
 +
!Required
 +
!Description
 +
|---- bgcolor=#EDEDFF
 +
| mo
 +
| Boolean
 +
| No
 +
| Monday repeat
 +
|---- bgcolor=#EDEDFF
 +
| tu
 +
| Boolean
 +
| No
 +
| Monday repeat
 +
|---- bgcolor=#EDEDFF
 +
| we
 +
| Boolean
 +
| No
 +
| Monday repeat
 +
|---- bgcolor=#EDEDFF
 +
| th
 +
| Boolean
 +
| No
 +
| Monday repeat
 +
|---- bgcolor=#EDEDFF
 +
| fr
 +
| Boolean
 +
| No
 +
| Monday repeat
 +
|---- bgcolor=#EDEDFF
 +
| sa
 +
| Boolean
 +
| No
 +
| Monday repeat
 +
|---- bgcolor=#EDEDFF
 +
| su
 +
| Boolean
 +
| No
 +
| Monday repeat
 
|}
 
|}

Latest revision as of 03:37, 13 September 2024

Contents

[edit] The Timecard SOAP API

The Timecard SOAP API is similar to the EService Soap API, in that it provides methods for retrieving, updating, and deleting data stored on the Econz Timecard servers.

The API is published separately at the moment, as another interface for linking into the Timecard server, although there is some progress on integrating the two products together in a future release.

[edit] The Interface Definition

Below is a summary of the important functions that make up the Timecard API (a full java doc style specification can be found here and even better the latest auto generated SOAP doc is available here and here is the wsdl). Each function is called, passing in at least one parameter, a UserIDBean. This bean contains the user name and password of a previously registered Timecard User, with administrative rights. This ensures only authorised users are able to access the interface.

[edit] Timecard User Management Functions

Method Summary
createUser Creates a new user based on the user data passed in.
getUserDetail Gets all the details of a specified user.
getUserDetailByLoginID Gets all the details of the user as specified by their Login ID (user name).
getUserDetails Gets all the details for all the users (returns an array of UserBean).
getUserSummaries Returns a list of all users (including managers).
getManagerSummaries Returns a list of just the managers.
updateUser Updates a particular user with new details.
updateUserPassword Updates a user's password.
deleteUser Deletes an existing user.
getUnsynchronisedUsers Retrieves all users who have not previously been synchronised and acknowledged, and all users that have changed since their last synchronisation.
ackUserSynchronisation Acknowledges that synchronisation has been performed on the selected users.

[edit] Timecard Field Device Management Functions

Method Summary
createFieldDevice Creates a new field device based on the field device data passed in.
getFieldDeviceDetail Gets the full set of details for a specified field device.
getFieldDeviceDetails Gets the full set of details for all specified field devices.
getFieldDeviceDetailsUpdatedSince Gets the full set of details for all field devices that have been updated since the specified date and time.
updateFieldDevice Updates a field device with new details.
deleteFieldDevice Marks a field device as deleted.
getFieldDevicePKForName Gets the primary key of a field device, based on the name passed in.
getFieldDevicePKForDeviceID Gets the primary key of a field device, based on the device id passed in.

[edit] Timecard functions to Retrieve Raw Event Data

Returns Method Parameters Description
Array of EventBean getUserEvents UserIDBean, userPrimaryKey, start date, end date For a given user in a selected period, retrieves clock in/out dates and times and task descriptions.
GetLastUserEventsResult getLastUserEvents UserIDBean Retrieves last user events (including GPS location info if available).
GetUserGPSResult getUserGPS UserIDBean, userPK, start date, end date Retrieves user GPS locations for the given time period.
GetGpsEventsResult getGPSEvents UserIDBean, userPK, teamPK, startDate, endDate Retrieves user event info with timezone of the event as recorded by the phone.
Array of EventBean getAllUserEvents UserIDBean, start date, end date Retrieves clock in/out dates and times and task descriptions for all users in a selected period.
Array of EventBean getUnsynchronizedUserEvents UserIDBean, synchronisationID, createdOnOrAfter Retrieves array of EventBean (detailed further below) that have not previously been synchronized and acknowledged and all events that have changed since their last synchronization.
return ackUserEventSynchronization UserIDBean, UserEventSynchronizationBean Acknowledges that synchronization has been performed on the selected events.

[edit] Methods to Retrieve Processed Data

Returns Method Parameters Description
HourBreakdownBean getUserHoursSummary UserIDBean, UserPrimaryKey, start, end Gets the hourly breakdown for a single user.
Array of HourBreakdownBean getHourSummaries UserIDBean, start, end Hourly breakdowns for all users in the given time period.
Array of DetailedHourBreakdownBean getDetailedUserHourSummary UserIDBean, UserPrimaryKey, start, end, showUserTZFlag Gets the hourly breakdown, adhering to the IDI specification, for a single user.
Array of DetailedHourBreakdownBean getDetailedHourSummaries UserIDBean, start, end, showUserTZFlag Hourly breakdowns, adhering to the IDI specification, for all users in the given time period.
Array of DetailedHourBreakdownBeanWithRateCode getDetailedUserHourSummaryWithRateCode UserIDBean, UserPrimaryKey, start, end, showUserTZFlag Gets the hourly breakdown, adhering to the IDI specification, for a single user. Provided results include a customer specified rate code for the associated task/device combination. This method does not return an additional row if worker time covers two days(eg night shift). The getDetailedUserHourSummary method returns two rows for this scenario for easy daily overtime calculation.
Array of DetailedHourBreakdownBeanWithRateCode getDetailedHourSummariesWithRateCode UserIDBean, start, end, showUserTZFlag Hourly breakdowns, adhering to the IDI specification, for all users in the given time period. Provided results include a customer specified rate code for the associated task/device combination. This method does not return an additional row if worker time covers two days(eg night shift). The getDetailedHourSummaries method returns two rows for this scenario for easy daily overtime calculation.
Array of DetailedHourBreakdownBeanWithRateCodeAndPremiumPay getDetailedHourSummariesWithRateCodeAndPremiumPay UserIDBean, start, end, showUserTZFlag Hourly breakdowns, adhering to the IDI specification, for all users in the given time period. Provided results include a customer specified rate code for the associated task/device combination as well as an indication as to whether Premium Pay is due. This method does not return an additional row if worker time covers two days(eg night shift). The getDetailedHourSummaries method returns two rows for this scenario for easy daily overtime calculation.
Array of Strings getUserTypes UserIDBean Returns array of UserType Names (FYI - The 'Operations Manager' user type has a PK of 9).
Array of OverTimeRuleBean getOvertimeRulesBean UserIDBean Returns array of OverTimeRuleBean.

[edit] Schedule Related Methods

Returns Method Parameters Description
AddScheduleResult addSchedule UserIDBean, ScheduleDetails Adds a new schedule into the Timecard system, with the given details
GetScheduleResult (contains ScheduleDetails) getSchedule UserIDBean, schedulePk Query the details of given schedule
DeleteScheduleResult deleteSchedule UserIDBean, schedulePk Remove given schedule from system

[edit] Retrieving and updating Organisation Details

Returns Method Parameters Description
OrganisationDetailsBean getOrganisationDetail UserIDBean Returns all details from admin screen (including standard open hours).
updateOrganisationDetailResult updateOrganisationDetail UserIDBean, OrganisationDetailsBean Updates all details on admin screen (including standard open hours).

[edit] Various Maintenance Functions

Returns Method Parameters Description
sendMessageToUserResult sendMessageToUser UserIDBean, userPrimaryKey, messageString Sends a string message to the specified user.
wakeFieldDeviceResult wakeFieldDevice UserIDBean, userPrimaryKey Sends a message to the phone, which forces the application to start and connect to the server.
getTeamListResponse getTeamList UserIDBean Returns the list of teams.
createNewTeamResult createNewTeam UserIDBean, teamName, teamLeaderUserPrimaryKey Creates a new team with the specified user as the team leader.
deleteTeamResult deleteTeam UserIDBean, teamName Deletes the specified team. Members of this team should be reallocated to existing teams.
addUserToTeamResult addUserToTeam UserIDBean, teamName, userPrimaryKey Adds the specified user to the specified team. Note that each user can only belong to one team.
removeUserFromTeamResult removeUserFromTeam UserIDBean, teamName, userPrimaryKey Removes the user from the team specified.
sendMessageToTeamResult sendMessageToTeam UserIDBean, teamName, messageString Sends a string message to all users in the specified team.
wakeTeamFieldDevicesResult wakeTeamFieldDevices UserIDBean, teamName Sends a message to all phone devices, which forces the application to start and connect to the server.
AddTasksToTeamResult addTasksToTeam UserIDBean, teamName, tasks Add a list of tasks to the given team.
DeleteTasksFromTeamResult deleteTasksFromTeam UserIDBean, teamName, tasks Remove a list of tasks from the given team.
AddSubTasksToTaskResult addSubTasksToTaskAndTeam UserIDBean, teamName, taskName, subTasks Add a list of subTasks to the given team's task.
DeleteSubTasksFromTaskResult deleteSubTasksFromTask UserIDBean, teamName, taskName, subTasks Delete a list of subTasks from the given team's task.
DeleteTasksFromAllTeamsResponse deleteTasksFromAllTeams UserIDBean, tasks Delete a list of tasks from all teams.
Array of strings getSubtasksForTaskAndTeam UserIDBean, teamName taskName Gets the sub tasks list from the server for a given task and team.
Array of strings getTasksForTeam UserIDBean, teamName Gets the tasks/customers list from the server for a given team.
Array of strings getTaskList UserIDBean Gets the tasks/customers list from the server.
AddNewTaskResult addNewTask UserIDBean, taskName Adds a new task/customer to the server list.
AddNewTaskResult addTaskWithAddress UserIDBean, DetailedTaskWithAddress Adds a new task/customer to the server list with custom fields and address information included.
AddNewTaskResult addTaskForManager UserIDBean, managerPK, DetailedTaskWithAddress Adds a new task/customer to the server list (with custom fields and address information included) and associate it with the specified Manager's UserPK.
UpdateTaskResult updateTaskManager UserIDBean, taskName, managerPK Updates the 'TaskManager' (i.e. specifically a user who is a 'Manager' type) associated with the given Task (specified by the taskName).
UpdateTaskResult updateTaskStartEnd UserIDBean, taskID, start, end Sets/updates the time period visibility of the given task. The task will be visible on mobile devices from the given start date to the given end date.
UpdateTaskResult updateTaskDetails UserIDBean, taskName, taskDetails Sets/updates the task details.
removeTaskResult removeTask UserIDBean, taskName Remove task/customer from the server.
UpdateTaskResult renameTask UserIDBean, oldTaskName, newTaskName Update the task/customer name.
addSubtaskToTask addSubtaskToTask UserIDBean, taskName, subTaskName Add a new subtask to an existing task in the server list.
addSubtasksToTask addSubtasksToTask UserIDBean, taskName, subTaskNames Add new list of subtasks to an existing task in the server list.
deleteSubtask deleteSubtask UserIDBean, taskName, subTaskName Remove subtask with the provided name from the task with the name provided from the server list.
getSubtaskList getSubtaskList UserIDBean, taskName Get a list of subtasks for the task with the provided name from the server list.
setFieldWorkerUnionCode setFieldWorkerUnionCode UserIDBean, userPK, unionCode Associte the specified unionCode for the provided userPK. The unionCode specified needs to be defined in the Manage Unions Page in the Timecard Website.
addRateCode addRateCode UserIDBean, userPK, taskName, rateCode Associate the specified rateCode for the provided userPK/taskName combination
deleteRateCode deleteRateCode UserIDBean, userPK, taskName Remove the rateCode specified for the provided userPK/taskName combination

[edit] Main Data Type Definitions

[edit] EventBean

Name Type Size Required Description
whenOccured Calendar N/A N/A The date and time at which a clock in, clock out, start break, end break start task or end task event occurred
eventID String 9 N/A Unique identifier for the event
eventType Enumerated String 9 N/A One of the following: CLOCK_IN, CLOCK_OUT, TASK_START, TASK_END, BREAK_START, BREAK_END.
userName String 25 N/A The name of the user who generated the event.
deviceID String 30 N/A Device ID of the user who generated the event (unique identifier for the device).
userPK String 9 N/A Unique identifier for the user.
userType String 50 N/A Describes the type of user.

[edit] TaskEventBean extends EventBean

Name Type Size Required Description
taskName String 50 N/A The task name associated with the TASK_START or TASK_END event.

[edit] HourBreakdownBean

Name Type Size Required Description
userType String 50 N/A Describes the type of user.
userName String 25 N/A The name of the user who generated the event.
deviceID String 30 N/A Device ID of the user who generated the event (unique identifier for the device).
userName String 25 N/A The name of the user who generated the event.
normalHours Int 0-24 N/A The hours component of a normal working day.
normalMinutes Int 0-59 N/A The minutes component of a normal working day.
normalSeconds Int 0-59 N/A The seconds component of a normal working day.
overTimeHours Int 0-24 N/A The hours component of overtime in excess of a normal working day.
overTimeMinutes Int 0-59 N/A The minutes component of overtime in excess of a normal working day.
overTimeSeconds Int 0-59 N/A The seconds component of overtime in excess of a normal working day.
extraHours Int 0-24 N/A The hours component of extra time in excess of overtime and the normal working day.
extraMinutes Int 0-59 N/A The minutes component of overtime in excess of overtime and the normal working day.
extraSeconds Int 0-59 N/A The seconds component of overtime in excess of overtime and the normal working day.

[edit] DetailedHourBreakdownBean

Name Type Size Required Description
userPrimaryKey String 9 N/A User Primary Key in Timecard.
userType String 50 N/A Describes the type of user.
userName String 25 N/A The name of the user who generated the event.
deviceID String 30 N/A Device ID of the user who generated the event (unique identifier for the device).
dateStart DateTime N/A N/A The date/time of the start event.
dateEnd DateTime N/A N/A The date/time of the end event.
timezone String 25 N/A The timezone of the user who generated the event.
startEvent String 25 N/A The start event type.
endEvent String 25 N/A The end event type.
teamName String 50 No The team name that the user belongs to.
taskName String 50 No The task that the event belongs to.
subtaskName String 50 No The subtask that the event belongs to.
normalHours Int 0-24 N/A The hours component of a normal working day.
normalMinutes Int 0-59 N/A The minutes component of a normal working day.
normalSeconds Int 0-59 N/A The seconds component of a normal working day.
overTimeHours Int 0-24 N/A The hours component of overtime in excess of a normal working day.
overTimeMinutes Int 0-59 N/A The minutes component of overtime in excess of a normal working day.
overTimeSeconds Int 0-59 N/A The seconds component of overtime in excess of a normal working day.
extraHours Int 0-24 N/A The hours component of extra time in excess of overtime and the normal working day.
extraMinutes Int 0-59 N/A The minutes component of overtime in excess of overtime and the normal working day.
extraSeconds Int 0-59 N/A The seconds component of overtime in excess of overtime and the normal working day.
customFields Array of CustomField N/A N/A The custom fields that are belong to this task.

[edit] DetailedHourBreakdownBeanWithRateCode

Name Type Size Required Description
userPrimaryKey String 9 N/A User Primary Key in Timecard.
userType String 50 N/A Describes the type of user.
userName String 25 N/A The name of the user who generated the event.
deviceID String 30 N/A Device ID of the user who generated the event (unique identifier for the device).
dateStart Date N/A N/A The date/time of the start event.
dateEnd Date N/A N/A The date/time of the end event.
timezone String 25 N/A The timezone of the user who generated the event.
startEvent String 25 N/A The start event type.
endEvent String 25 N/A The end event type.
teamName String 50 No The team name that the user belongs to.
taskName String 50 No The task that the event belongs to.
subtaskName String 50 No The subtask that the event belongs to.
normalHours Int 0-24 N/A The hours component of a normal working day.
normalMinutes Int 0-59 N/A The minutes component of a normal working day.
normalSeconds Int 0-59 N/A The seconds component of a normal working day.
overTimeHours Int 0-24 N/A The hours component of overtime in excess of a normal working day.
overTimeMinutes Int 0-59 N/A The minutes component of overtime in excess of a normal working day.
overTimeSeconds Int 0-59 N/A The seconds component of overtime in excess of a normal working day.
extraHours Int 0-24 N/A The hours component of extra time in excess of overtime and the normal working day.
extraMinutes Int 0-59 N/A The minutes component of overtime in excess of overtime and the normal working day.
extraSeconds Int 0-59 N/A The seconds component of overtime in excess of overtime and the normal working day.
rateCode String 50 N/A Customer specified Rate Code setup for the provided device & task combination.
customFields Array of CustomField N/A N/A The custom fields that are belong to this task.

[edit] OverTimeRuleBean

Name Type Size Required Description
userTypeAppliedTo String 50 N/A User type this is applied to.
startDate Calendar N/A N/A When the overtime rule starts
endDate Calendar N/A N/A When the overtime rule ends. This may be null if there is no definite end date for the rule.
includeBreakInTimeWorked boolean N/A N/A Defines if break time should be included in time worked calulations
overTimeRule OverTimeBean N/A N/A Which overtime rule
extraTimeRule OverTimeBean N/A N/A Which extratime rule

[edit] OverTimeBean

Name Type Size Required Description
applicable boolean N/A N/A Determines if this overtime information is applicable or not.
hoursPerDay HoursPeriodBean N/A N/A Defines the limit of normal work per day (anything over this is considered as a form of overtime or extratime).
hoursPerWeek HoursPeriodBean N/A N/A Defines the limit of normal work per week (anything over this is considered as a form of overtime or extratime).

[edit] HoursPeriodBean

Name Type Size Required Description
applicable boolean N/A N/A Determines if this hours period information is applicable or not.
hours Int 0-168 N/A Number of hours in this period.
minutes Int 0-59 N/A Numberof minutes in this period.

[edit] OrganisationDetailsBean

Name Type Size Required Description
name String 25 N/A The name of the organisation.
description String 50 N/A The description of the organisation.
accountNumber String 25 N/A The account number of the organisation.
contactName String 30 N/A The name of the contact person for the organisation.
contactWorkPhone String 30 N/A The contact person's work number.
contactMobilePhone String 30 N/A The contact person's mobile number.
contactEmailAddress String 30 N/A The contact person's email address.
address1 String 200 N/A Address line 1 for the organisation (street address)
address2 String 30 N/A Address line 2 for the organisation (suburb/town)
address3 String 30 N/A Address line 3 for the organisation (city)
address4 String 30 N/A Address line 4 for the organisation (state/region)
locale String 10 N/A Locale of the organisation (made up of language, country and variant codes - see java doc for more info)

[edit] CustomField

Name Type Size Required Description
name String 25 N/A Name of the custom field set up in timecard.
value String 500 N/A Value entered for the custom field.


[edit] ScheduleDetails

Name Type Required Description
description String Yes Schedule name/description
start DateTime Yes Start time/date of schedule
end DateTime Yes End time/date of schedule
colourHex String Yes Colour of schedule (for display on web-scheduler). E.g. #666666
isRepeat Boolean Yes Determines if this schedule repeats on an interval (repeatFrequency)
repeatOnlyWeekdays Boolean Yes Determines if the repeat frequency will include on weekdays or not. Unused when isRepeat is false and/or repeatFrequency not Week
repeatFrequency String No Day, Week
repeatDays RepeatDays No Used with repeatFrequency Day
endRepeat DateTime No Used with isRepeat to determine end date
fieldDeviceList ArrayOfString Yes List of user PKs to assign to schedule
taskList ArrayOfString Yes List of task names to allocate to schedule
notes String Yes Additional notes

[edit] RepeatDays

Name Type Required Description
mo Boolean No Monday repeat
tu Boolean No Monday repeat
we Boolean No Monday repeat
th Boolean No Monday repeat
fr Boolean No Monday repeat
sa Boolean No Monday repeat
su Boolean No Monday repeat
Retrieved from "http://econz.org/index.php?title=Timecard_Soap_API&oldid=2231"
Personal tools
MediaWiki Appliance - Powered by TurnKey Linux