Timecard Soap API

Revision as of 02:42, 7 November 2005

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

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.

The Interface Definition

Below are listed the various functions that make up the timecard API. Each function is called, passing in at least one parameter, a UserIDBean. This bean contains the user name and password of a previously registered EService User, with administrative rights. This ensures only authorised users are able to access the interface.

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

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.

Timecard functions to Retrieve Raw Event Data

Returns	Method	Parameters	Description
Array of #EventObjectBean	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.
Array of #EventObjectBean	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 #EventObjectBean	getUnsynchronizedEvents	UserIDBean, synchronisationID, createdOnOrAfter	Retrieves array of #EventObjectBean (detailed further below) that have not previously been synchronized and acknowledged and all events that have changed since their last synchronization.
return	ackEventSynchronization	UserIDBean, EventSynchronizationBean	Acknowledges that synchronization has been performed on the selected events.

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 Strings	getUserTypeNames	UserIDBean	Returns array of UserType Names.
Array of #OverTimeRuleBean	getOvertimeRulesBean	UserIDBean	Returns array of OverTimeRuleBean.

Retrieving and updating Organization Details

Returns	Method	Parameters	Description
#OrganizationDetailsBean	getOrganizationDetail	UserIDBean	Returns all details from admin screen (including standard open hours).
updateOrganizationDetailResult	updateOrganizationDetail	UserIDBean, #OrganizationDetailsBean	Updates all details on admin screen (including standard open hours).

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.
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.
Array of strings	getTaskList	UserIDBean	Gets the tasks/customers list from the server.
addNewTaskResult	addNewTask	UserIDBean, taskString	Adds a new task/customer to the server list.
removeTaskResult	removeTask	UserIDBean, taskString	Remove task/customer from the server.

Main Data Type Definitions

EventObjectBean

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.

TaskEventBean extends EventObjectBean

Fields :

Task ID

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.

OverTimeRuleBean

UserType Applies to
Start date
End Date (may be indefinite, need constant for that !) not null !!!
boolean for include break in time worked
Overtime rule as #OverTimeBean
ExtraTime rule as #OverTimeBean

OverTimeBean

boolean applicable
hours per day as #HoursPeriodBean
hours per Week as #HoursPeriodBean

HoursPeriodBean

boolean applicable
hours as int
mins as int

OrganizationDetailsBean

Name
Description
AccountNumber
ContactName
ContactWorkPhone
ContactMobilePhone
ContactEmailAddress
Address1
Address2
Address3
Address4
Locale

@@ Line 210: / Line 210: @@
 ==== EventObjectBean ====
-Fields :
 {| border=1