Timecard Soap API

Latest revision as of 03:37, 13 September 2024

[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