Overview
This article contains documentation for the User Status web service, all related API calls, and possible errors.
You can use Ctrl+F to search for the required method or error message.
For more information about all available Web Services and corresponding methods, refer to the Introduction to Web Services article.
Information
This web service includes the following methods:
getTimesheets
(SvDate start, SvDateHolder end)
Description
This web service allows the retrieval of all timesheets completed by all workers in a company within a date range. The start and end dates must be specified in UTC. A timesheet is only created when a shift is completed. For example, a shift starts when a user performs a Start Shift and ends once a Start Break or End Shift action is performed. The timesheet cannot be retrieved until the shift is complete or closed.
Method Signature
|
Ordinal |
DataType |
Required |
Description |
|---|---|---|---|
|
start |
SvDate |
Yes |
The starting time of the search range. The start date is inclusive. |
|
end |
SvDateHolder |
Yes |
The ending time of the search range in UTC. The end date is exclusive. The end date is adjusted if the date passed to the web service is later than the current database time. The current database time is then returned to the caller. |
|
Return Result |
SvTimesheet[] |
Yes |
For each timesheet that is found, a fully populated SvTimesheet object will be returned. If no timesheets are found, an empty array is returned. |
SvTimesheet
|
Field |
DataType |
Comments |
|---|---|---|
|
timecardName |
String |
The shift name. Is one of the following: On Duty, On Break, Off Duty, Logged In |
|
workerName |
String |
The name of the worker who's timesheet it is. |
|
startDate |
SvDate |
Timestamp of when the shift was started |
| endDate | SvDate |
Timestamp of when the shift was ended. Can be null if the shift has not ended. |
Validation Errors
“The start date cannot be null.” – thrown if the start date is null
“The end date cannot be null.” – thrown if the end date is null
“The end date must be after the start date.” – thrown if the start date is after the end date.
“You are only allowed to query for 7 days of data at a time.” – thrown if an attempt is made to query for more than 7 days of data.
getTimesheetsByWorkerName
(String workerName, SvDate start, SvDateHolder end)
Description
This web service allows the retrieval of all timesheets completed by a specified worker within a date range.
Method Signature
|
Ordinal |
DataType |
Required |
Description |
|---|---|---|---|
|
workerName |
String |
Yes |
The username of the worker whose timesheets are required. |
|
start |
SvDate |
Yes |
The starting time of the search range. The start date is inclusive. |
|
end |
SvDateHolder |
Yes |
The ending time of the search range. The end date is exclusive. The end date is adjusted if the date passed to the web service is later than the current database time. This value is then returned to the caller. |
|
Return Result |
SvTimesheet[] |
Yes |
For each timesheet that is found, a fully populated SvTimesheet object will be returned. If no timesheets are found, an empty array is returned. |
SvTimesheet
|
Field |
DataType |
Comments |
|---|---|---|
|
timecardName |
String |
The shift name. Is one of the following: On Duty, On Break, Off Duty, Logged In |
|
workerName |
String |
The name of the worker who's timesheet it is. |
|
startDate |
SvDate |
Timestamp of when the shift was started |
|
endDate |
SvDate |
Timestamp of when the shift was ended. Can be null if the shift has not ended. |
Validation Errors
“The start date cannot be null.” – thrown if the start date is null
“The end date cannot be null.” – thrown if the end date is null
“The end date must be after the start date.” – thrown if the start date is after the end date.
“You are only allowed to query for 7 days of data at a time.” – thrown if an attempt is made to query for more than 7 days of data.
“The worker name cannot be null.” – Thrown if the workerName is null or blank.
“Could not find a worker with the username.” – Thrown if the worker corresponding to the input workerName cannot be found.
GetTimecardActions
(SvDate start, SvDateHolder end)
Description
The getTimecardActions service method provides the ability to retrieve timecard information over a specified time range. Only timecard data which was actually received by the system during the time range is returned. Thus, due to network latency or cell coverage issues between the mobile device and the server, this may result in SvUserAction objects being returned that have an excutionDateTime earlier than the startDate of the query. Form data is included within the SvUserAction object if a form was associated with the timecard. Note that login and logout actions are also returned as timecard data.
Method Signature
|
Ordinal |
DataType |
Required |
Description |
|---|---|---|---|
|
startDate |
SvDate |
Yes |
Starting date for the range to check for changes. Starting date is inclusive. |
|
endDate |
SvDateHolder |
Yes |
Ending date for the range to check for changes. Ending date is exclusive. |
|
Return Result |
SvUserAction[] |
Yes |
An array of SvUserAction objects. An empty array is returned if no timecards are found. |
Validation Errors
“The start date cannot be null.” – thrown if the start date is null
“The end date cannot be null.” – thrown if the end date is null
“The end date must be after the start date.” – thrown if the start date is after the end date.
“You are only allowed to query for 7 days of data at a time.” – thrown if an attempt is made to query for more than 7 days of data.
“Media size exceeded max allowed bytes of 524288000.” – thrown if total size of all the images returned in a single API call exceeds 500 MB. Reduce date range and try again.
GetTimecardActionsByWorkerName
(String workerName, SvDate start, SvDateHolder end)
Description
The getTimecardActionByWorkerName service method provides the ability to retrieve timecard information for a specific worker over a specified time range. Only timecard data which was actually received by the system during the time range is returned. Thus, due to network latency or cell coverage issues between the mobile device and the server, this may result in SvUserAction objects being returned that have an excutionDateTime earlier than the startDate of the query. Form data is included within the SvUserAction object if a form was associated with the timecard.
Method Signature
|
Ordinal |
DataType |
Required |
Description |
|---|---|---|---|
|
workerName |
String |
Yes |
The username of the worker whose timecards are to be returned. |
|
startDate |
SvDate |
Yes |
Starting date for the range to check for changes. Starting date is inclusive |
|
endDate |
SvDateHolder |
Yes |
Ending date for the range to check for changes. Ending date is exclusive. |
|
Return Result |
SvUserAction[] |
Yes |
An array of SvUserAction objects. An empty array is returned if no timecards are found. |
Validation Errors
“The start date cannot be null.” – thrown if the start date is null
“The end date cannot be null.” – thrown if the end date is null
“The end date must be after the start date.” – thrown if the start date is after the end date.
“You are only allowed to query for 7 days of data at a time.” – thrown if an attempt is made to query for more than 7 days of data.
“The worker name cannot be null.” – Thrown if the workerName is null or blank.
“Could not find a worker with the username.” – Thrown if the worker corresponding to the input workerName cannot be found.
“Media size exceeded max allowed bytes of 524288000.” – thrown if total size of all the images returned in a single API call exceeds 500 MB. Reduce date range and try again.
GetUpdatedTimecardActions
(SvDate start, SvDateHolder end)
Description
This API works similar to getTimecardActions. The API returns the timecard actions created or edited during the specified time range. The response includes an additional property actionId which can be used to uniquely identify a timecard action. Form data is included within the SvUserActionUpdate object if a form was associated with the timecard. The excutionDateTime in SvUserActionUpdate might be earlier than the start date some time due to network latency or cell coverage issues between the mobile device and the server. Note that login and logout actions are also returned as timecard data.
Method Signature
|
Ordinal |
DataType |
Required |
Description |
|---|---|---|---|
|
startDate |
SvDate |
Yes |
Starting date for the range to check for changes. Starting date is inclusive. |
|
endDate |
SvDateHolder |
Yes |
Ending date for the range to check for changes. Ending date is exclusive. |
|
Return Result |
SvUserActionUpdate[] |
Yes |
An array of SvUserActionUpdate objects. An empty array is returned if no timecards are found. |
Validation Errors
“The start date cannot be null.” – thrown if the start date is null
“The end date cannot be null.” – thrown if the end date is null
“The end date must be after the start date.” – thrown if the start date is after the end date.
“You are only allowed to query for 7 days of data at a time.” – thrown if an attempt is made to query for more than 7 days of data.
“Media size exceeded max allowed bytes of 524288000.” – thrown if total size of all the images returned in a single API call exceeds 500 MB. Reduce date range and try again.
GetUpdatedTimecardActionsByWorkerName
(String workerName, SvDate start, SvDateHolder end)
Description
This API works similar to getTimecardActionsByWrokerName. The API returns the timecard actions created or edited during the specified time range for a given worker. The response includes an additional property actionId which can be used to uniquely identify a timecard action. Form data is included within the SvUserActionUpdate object if a form was associated with the timecard. The excutionDateTime in SvUserActionUpdate might be earlier than the start date some time due to network latency or cell coverage issues between the mobile device and the server. Note that login and logout actions are also returned as timecard data.
Method Signature
|
Ordinal |
DataType |
Required |
Description |
|---|---|---|---|
|
workerName |
String |
Yes |
The username of the worker whose timecards are to be returned. |
|
startDate |
SvDate |
Yes |
Starting date for the range to check for changes. Starting date is inclusive. |
|
endDate |
SvDateHolder |
Yes |
Ending date for the range to check for changes. Ending date is exclusive. |
|
Return Result |
SvUserActionUpdate [] |
Yes |
An array of SvUserActionUpdate objects. An empty array is returned if no timecards are found. |
Validation Errors
“The start date cannot be null.” – thrown if the start date is null
“The end date cannot be null.” – thrown if the end date is null
“The end date must be after the start date.” – thrown if the start date is after the end date.
“You are only allowed to query for 7 days of data at a time.” – thrown if an attempt is made to query for more than 7 days of data.
“The worker name cannot be null.” – thrown if the workerName is null or blank.
“Could not find a worker with the username.” – thrown if the worker corresponding to the input workerName cannot be found.
“Media size exceeded max allowed bytes of 524288000.” – thrown if total size of all the images returned in a single API call exceeds 500 MB. Reduce date range and try again.
GetUserForms
(SvDate start, SvDateHolder end)
Description
The getUserForms service method allows the download of user forms both adhoc forms and those forms associated with a timecard action. Only forms which were actually received by the system during the time range are returned. Thus, due to network latency or cell coverage issues between the mobile device and the server, this may result in SvUserAction objects being returned that have an excutionDateTime earlier than the startDate of the query. There are multiple overloaded versions of this method.
Method Signature
|
Ordinal |
DataType |
Required |
Description |
|---|---|---|---|
|
startDate |
SvDate |
Yes |
Starting date for the range to check for changes. Starting date is inclusive. |
|
endDate |
SvDateHolder |
Yes |
Ending date for the range to check for changes. Ending date is exclusive. |
|
Return Result |
SvUserAction[] |
Yes |
An array of SvUserAction objects. An empty array is returned if no forms are found. |
Validation Errors
“The start date cannot be null.” – thrown if the start date is null
“The end date cannot be null.” – thrown if the end date is null
“The end date must be after the start date.” – thrown if the start date is after the end date.
“You are only allowed to query for 7 days of data at a time.” – thrown if an attempt is made to query for more than 7 days of data.
“Media size exceeded max allowed bytes of 524288000.” – thrown if total size of all the images returned in a single API call exceeds 500 MB. Reduce date range and try again.
GetUserFormsByWorkerName
(String workerName, SvDate start, SvDateHolder end)
Description
The getUserFormsByWorkerName service method allows the download of adhoc forms and forms associated with a timecard action. Only forms which were actually received by the system during the time range are returned. Thus, due to network latency or cell coverage issues between the mobile device and the server, this may result in SvUserAction objects being returned that have an excutionDateTime earlier than the startDate of the query.
Method Signature
|
Ordinal |
DataType |
Required |
Description |
|---|---|---|---|
|
workerName |
String |
Yes |
Only forms for this worker will be retrieved. |
|
startDate |
SvDate |
Yes |
Starting date for the range to check for changes. Starting date is inclusive. |
|
endDate |
SvDateHolder |
Yes |
Ending date for the range to check for changes. Ending date is exclusive. |
|
Return Result |
SvUserAction[] |
Yes |
An array of SvUserAction objects. An empty array is returned if no forms are found. |
Validation Errors
“The start date cannot be null.” – thrown if the start date is null
“The end date cannot be null.” – thrown if the end date is null
“The end date must be after the start date.” – thrown if the start date is after the end date.
“You are only allowed to query for 7 days of data at a time.” – thrown if an attempt is made to query for more than 7 days of data.
“The worker name cannot be null.” – thrown if the workerName is null or blank.
“Could not find a worker with the username.” – thrown if the worker corresponding to the input workerName cannot be found.
“Media size exceeded max allowed bytes of 524288000.” – thrown if total size of all the images returned in a single API call exceeds 500 MB. Reduce date range and try again.
GetUserFormsByFormName
(String formName, SvDate start, SvDateHolder end)
Description
The getUserFormsByFormName service method allows the download of adhoc forms and forms associated with a timecard action. Only forms which were actually received by the system during the time range is returned. Thus, due to network latency or cell coverage issues between the mobile device and the server, this may result in SvUserAction objects being returned that have an excutionDateTime earlier than the startDate of the query.
Method Signature
|
Ordinal |
DataType |
Required |
Description |
|---|---|---|---|
|
formName |
String |
Yes |
Only instances of the specified form will be returned. |
|
startDate |
SvDate |
Yes |
Starting date for the range to check for changes. Starting date is inclusive. |
|
endDate |
SvDateHolder |
Yes |
Ending date for the range to check for changes. Ending date is exclusive. |
|
Return Result |
SvUserAction[] |
Yes |
An array of SvUserAction objects. An empty array is returned if no forms are found. |
Validation Errors
“The start date cannot be null.” – thrown if the start date is null
“The end date cannot be null.” – thrown if the end date is null
“The end date must be after the start date.” – thrown if the start date is after the end date.
“You are only allowed to query for 7 days of data at a time.” – thrown if an attempt is made to query for more than 7 days of data.
“The form name must be populated” – Returned if the form name is blank.
“Could not find an active form with form name = <formName>” – Returned if a form with the submitted form name cannot be found in the Field Force Manager system.
“Media size exceeded max allowed bytes of 524288000.” – thrown if total size of all the images returned in a single API call exceeds 500 MB. Reduce date range and try again.
submitUserAction
(SvUserAction userAction)
Description
This service allows a user action to be submitted. The SvUserAction object must have a workerName value of a worker that is in the Field Force Manager system. The actionName must be one of the valid actions: 'Login', 'Exit', 'Start Shift', 'End Shift', 'Start Break', 'End Break'. At this time, form data cannot be submitted through this method. This method requires that the specified worker must be associated with a device in the Field Force Manager system.
Method Signature
|
Ordinal |
DataType |
Required |
Description |
|---|---|---|---|
|
userAction |
SvUserAction |
Yes |
The user action that has been executed. A non-zero result code will be returned within the SvResult object if the actionName, dateTime or workerName is empty or null or the actionName is not one of a set of defined values. |
|
Return Result |
SvResult |
Yes |
A result object that indicates if the operation was successful. Any error codes or error messages will be returned here. |
Validation Errors
"The worker name cannot be null." – Returned if the workerName field on the SvUserAction object is null or blank.
"Could not find a worker with the username: <username>” – Returned if the worker specified cannot be found.
"The execution datetime must be populated in the SvUserAction object." – Returned if the dateTime field on the SvUserAction object is null or blank.
"The action name must be populated in the SvUserAction object." – Returned if the actionName field on the SvUserAction object is null or empty.
"Unrecognized action name. The action name must be one of: 'Login', 'Exit',
'Start Shift', 'End Shift', 'Start Break', 'End Break' " – Returned if an invalid value is entered for the action name.
"A device could not be found for the input worker." – Returned if the worker is not associated with a device in the Field Force Manager system.