Timecard Soap API

From
Revision as of 04:17, 7 November 2005 by Philipc (Talk)

Jump to: navigation, search

Contents

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

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

OverTimeBean

HoursPeriodBean

  • boolean applicable
  • hours as int
  • mins as int

OrganizationDetailsBean

  • Name
  • Description
  • AccountNumber
  • ContactName
  • ContactWorkPhone
  • ContactMobilePhone
  • ContactEmailAddress
  • Address1
  • Address2
  • Address3
  • Address4
  • Locale
Retrieved from "http://econz.org/index.php?title=Timecard_Soap_API&oldid=1615"
Personal tools
MediaWiki Appliance - Powered by TurnKey Linux