Xora APIs Application Integration Guide Xora Inc. 501 Ellis Street Mountain View, CA 94043 www.xora.com [email protected] Version 4.0
Xora APIs Application Integration Guide
Xora Inc.
501 Ellis Street
Mountain View, CA 94043
www.xora.com
Version 4.0
Legal Information
Legal Information
The information from or through this publication is provided “as-is,” “as available,” and all warranties, express or implied, are disclaimed (including but not limited to the disclaimer of any implied warranties of merchantability and fitness for a particular purpose). No representations, warranties or guarantees whatsoever are made as to the accuracy, adequacy, reliability, current ness, completeness, suitability or applicability of the information to a particular situation. The information may contain errors, problems or other limitations. In no event shall Xora, Inc. be liable for any direct, indirect, special, incidental, or consequential damages (including damages for loss of business, loss of profits, litigation, or the like), whether based on breach of contract, breach of warranty, tort (including negligence), product liability or otherwise, even if advised of the possibility of such damages. The entire risk arising out of the use of this information remains with recipient.
Any redistribution or reproduction of any materials or information contained herein is strictly prohibited. This publication and the information may be used solely for personal, informational, non-commercial purposes, and may not be modified or altered in any way. Recipient may not remove any copyright or other proprietary notices contained in the documents and information.
Xora Platform is a trademark of Xora, Inc. Other company names, brand names or product names mentioned herein may be trademarks and/or registered trademarks of their respective owners and companies.
This product includes software developed by the Apache Software Foundation (http://www.apache.org/).
Patent pending.
All rights reserved. Xora, Inc. © 2000-2006
Confidential Xora API V 4.0 - Application Integration Guide
Contents
Contents
1 About this Guide .................................................................................................................... 1 1.1 Organization of this Guide................................................................................................. 1 1.2 Intended Audience ............................................................................................................ 1 1.3 Terminology ...................................................................................................................... 1
2 Xora API - An Introduction .................................................................................................... 2 2.1 Customize, Integrate, and Extend your Solutions............................................................. 2 2.2 What’s New in Version 4.0 ................................................................................................ 2
3 Getting Started with Xora API ............................................................................................... 5 3.1 Prerequisites to use Xora APIs ......................................................................................... 5 3.2 Setting up the Environment with Java using Apache Axis................................................ 5
4 API - Architecture ................................................................................................................... 7 4.1 Points to Remember ......................................................................................................... 7 4.2 Validation Mechanism....................................................................................................... 7
5 Xora APIs ................................................................................................................................ 8 6 Time Services ....................................................................................................................... 11
6.1 getTimeEntries ................................................................................................................ 11 6.2 getShiftFlexFieldEntries .................................................................................................. 13
7 User Management Services ................................................................................................ 16 7.1 createUsers..................................................................................................................... 16 7.2 updateUserInfo................................................................................................................ 19 7.3 getUserInfo...................................................................................................................... 21 7.4 updateUsersPassword.................................................................................................... 24 7.5 createTeams ................................................................................................................... 26 7.6 updateTeams .................................................................................................................. 28 7.7 deleteTeams ................................................................................................................... 31 7.8 addUsersToTeam ........................................................................................................... 32 7.9 removeUsersFromTeam ................................................................................................. 34 7.10 getTeams ........................................................................................................................ 36 7.11 highlightUser ................................................................................................................... 38
8 Location Services................................................................................................................. 41 8.1 createLandmarks ............................................................................................................ 41 8.2 deleteLandmarks............................................................................................................. 44 8.3 getGeofenceActivity ........................................................................................................ 46
Confidential Xora API V 4.0 - Application Integration Guide Page 1
Contents
8.4 getLocationEntries .......................................................................................................... 48 8.5 getLatestLocation............................................................................................................ 51
9 Job Services ......................................................................................................................... 54 9.1 createScheduledJobs...................................................................................................... 54 9.2 updateScheduledJobs..................................................................................................... 59 9.3 cancelScheduledJobs ..................................................................................................... 63 9.4 getScheduledJobDetails ................................................................................................. 65 9.5 getScheduledJobState .................................................................................................... 67 9.6 getJobEntries .................................................................................................................. 70 9.7 getJobFlexFieldEntries.................................................................................................... 72 9.8 changeJobAssignment.................................................................................................... 74 9.9 getJobDetails .................................................................................................................. 77 9.10 getJobsCustomStatusEntries.......................................................................................... 79
10 Utility Services .................................................................................................................. 82 10.1 isCredentialValid ............................................................................................................. 82 10.2 getMediaDetails............................................................................................................... 84
11 Project APIs....................................................................................................................... 86 Appendix ...................................................................................................................................... 87
Request Parameters .................................................................................................................. 87 Response Parameters ............................................................................................................. 101 Throttling Requirements........................................................................................................... 121
.............................................................................................................................. 122 Error Codes
............................................................................................ 124 Event ID / Xora API ID Illustration
Confidential Xora API V 4.0 - Application Integration Guide Page 2
About this Guide
1 About this Guide
This guide provides complete information on Xora Application Programming Interface (Xora API) that are used to exchange data between Xora server and the client applications / systems. In addition to the information on each Xora API, this guide also provides sample Java code for the respective Xora APIs.
For more information about the Xora Web Application or the Xora Phone Application please refer http://help.xora.com.
1.1 Organization of this Guide This guide is organized into the following chapters:
Chapter Description
Xora API – An Introduction
Provides introduction to Xora APIs, use cases, and information on what’s new in version 4.0.
Getting Started with Xora API
Provides prerequisite information to use Xora APIs and how to quickly set up your Xora API development environment.
Xora API - Architecture
Provides an overview on Xora API architecture that includes validations and the associated data flow.
Xora APIs Provides the list of Xora APIs along with request and response parameters, error codes, throttling rules, and sample Java codes.
Appendix Provides a list of properties and its details for each Xora API.
In addition, it also provides the throttling requirements and error codes.
1.2 Intended Audience This guide is designed for Xora partners / customers who intend to integrate Xora GPS TimeTrack with their existing applications / systems using the Xora APIs.
Confidential Xora API V 4.0 - Application Integration Guide Page 1
About this Guide
1.3 Terminology Following are some of the terms that you must be familiar with before implementing Xora APIs:
Term Description
Boolean Boolean is a data type used to signify either “True” or “False” for the respective parameter.
External Id A unique identifier (job number) that binds a job in the customer system to the job in the Xora system.
All jobs created using the Xora APIs need to have a unique external id.
Credentials A complex data-type comprising of the Xora Account Id, the user name, the password, and the user agent.
The credential is used to validate a request.
DatetimeRange A complex data-type comprising of two date fields – A FromDate and a ToDate.
Date range is always in the GMT time zone. The data returned for the given date and time range, is the data, which is received on the Xora server during that time period.
Throttling A set of rules defined by Xora to control the access of the APIs.
Confidential Xora API V 4.0 - Application Integration Guide Page 1
Xora API - An Introduction
2 Xora API - An Introduction
Xora Application Programming Interface (Xora API) provides a standard means of interoperating between different software applications, running on a variety of platforms, and/or frameworks.
The Xora APIs allow integration of any external application with the Xora Server.
Note
This integration is also accomplished using the Xora Data Shuttle (XDS) client. However, this guide provides an overview of Xora APIs only. To integrate external application with the Xora Server through XDS client, please refer XDS Guide at http://help.xora.com.
2.1 Customize, Integrate, and Extend your Solutions
Seamlessly Integrate into existing Payroll System
Using Xora APIs, partners can integrate their customer’s Job / Shift Start and End times from Xora GPS TimeTrack with their applications / systems. This eliminates manual entry of Job / Shift Start and End times into multiple systems, thus reducing the probability of error and the workload.
Integrate into existing billing / invoice application to capture job costing information for accounts receivables
Using Xora APIs, partners can provide their customers with the capability of importing job details like Job Number, Duration, Start and End Times and so on.
Seamlessly Dispatch Jobs to Mobile Employees from Existing Scheduling / Dispatch System
Using Xora APIs, partners can now seamlessly integrate the Xora GPS TimeTrack to customers existing scheduling / dispatch system. This will allow them to dispatch jobs to employee’s phones and also import complete job information.
For example: Job Location, Duration, Scheduled Start and End times, and so on into the system.
2.2 What’s New in Version 4.0
2.2.1 New Xora APIs
The following Xora APIs have been added to version 4.0 to provide more flexibility for integration of external application with the Xora server:
♦ createUsers
♦ updateUsersPassword
♦ createTeams
♦ updateTeams
♦ deleteTeams
Confidential Xora API V 4.0 - Application Integration Guide Page 2
Xora API – An Introduction
♦ addUsersToTeam
♦ removeUsersFromTeam
♦ getTeams
♦ getLatestLocation
♦ getScheduledJobDetails
♦ getJobDetails
2.2.2 Updated Xora APIs
The following Xora APIs have been updated from version 3.0 to version 4.0:
Xora API Updated in 4.0
getScheduledJobIds Removed. Merged in getScheduledJobDetails API.
getScheduledJobDetailsByIds Removed. Merged in getScheduledJobDetails API.
getJobIds Removed. Merged in getJobDetails API.
getJobDetailsByIds Removed. Merged in getJobDetails API.
2.2.3 WSDL
In Version 4.0, the Web Service Description Language (WSDL) is split according to the services offered by Xora. This helps you to navigate to the required Xora API more efficiently.
The services are categorised into the following:
♦ XoraTimeTrackTimeServices40
End Point: https://apps2.xora.com/xoraapps/services/XoraTimeTrackTimeServices40?wsdl
♦ XoraTimeTrackUserManagementServices40
End Point: https://apps2.xora.com/xoraapps/services/XoraTimeTrackUserManagementServices40?wsdl
♦ XoraTimeTrackLocationServices40
End Point: https://apps2.xora.com/xoraapps/services/XoraTimeTrackLocationServices40?wsdl
♦ XoraTimeTrackJobServices40
End Point:
https://apps2.xora.com/xoraapps/services/XoraTimeTrackJobServices40?wsdl
♦ XoraTimeTrackUtilityServices40
End Point: https://apps2.xora.com/xoraapps/services/XoraTimeTrackUtilityServices40?wsdl
Confidential Xora API V 4.0 - Application Integration Guide Page 3
Xora API - An Introduction
2.2.4 Pagination
Pagination is a process of organizing the large set of data in to a sequence of pages of smaller size. That means, whenever you call a Xora API, Pagination would split the results into “pages” and return one page at a time.
You can download the data in subsequent calls by passing the page number. This process reduces the response time and hence reduces the processing time (SOAP message) of the server.
Pagination is implemented for the following Xora APIs:
♦ getUserInfo
♦ getJobEntries
♦ getJobFlexFieldEntries
♦ getJobsCustomStatusEntries
♦ getLocationEntries
♦ getGeofenceActivity
♦ getTimeEntries
♦ getShiftFlexFieldEntries
Confidential Xora API V 4.0 - Application Integration Guide Page 4
Xora API – An Introduction
3 Getting Started with Xora API
3.1 Prerequisites to use Xora APIs To use the Xora API’s you will need at least a Business Plus license. In addition, the following APIs need Gold user licenses:
♦ getJobsCustomStatusEntries
♦ getShiftFlexFieldEntries
3.2 Setting up the Environment with Java using Apache Axis
3.2.1 Downloading and Running the Sample Java Code
The examples used in this manual use the Apache Axis classes to generate the client classes. The Apache Axis jars are included in the download for convenience.
The downloaded archive also contains an Apache ANT build file. You must install ANT in your local environment to execute the Sample Java Code.
Tip The easiest way to get started on Xora API’s is to run through sample Java codes in this document.
To run the sample Java code, follow these steps:
1. Download the sample Java code from the URL. (http://apps2.xora.com/xoraapps/downloads/webservices/ver3/WebservicesV3.zip)
2. Extract the contents of the archive to a local folder.
3. Go through the SampleClient under source\com\xora\services. The class com.xora.services.XoraClient30 contains wrapper for accessing the XAPIs. For more information, please refer docs\wrapper docs\index.html.
The lib folder contains all the jars including Axis and XoraClient jars.
The bin folder contains a batch file, which compiles and runs the Sample Client.
The Sample Folder has all the input sample data files.
4. Run the SampleClient.bat file from the command prompt (or double click the bat file). The file compiles and runs the SampleClient.
3.2.2 Running the Sample Application
This section explains how to run createScheduledJobs() API for instance.
To run an API, follow these steps:
1. Enter the choice of the API you wish to access.
For example: Enter 1 for CreateScheduledJobs()
2. Enter the credential text file’s path. (Sample credential file is in sample/credential.txt)
3. Enter the Scheduled Jobs text file’s path. (Sample ScheduledJob file is in sample/job30.txt)
Confidential Xora API V 4.0 - Application Integration Guide Page 5
Getting Started with Xora API
4. Enter the FlexField text file’s path. (Sample FlexField file is in sample/flex.txt)
5. Enter ‘y’ if allOrNothing value is True. Enter ‘n’ if allOrNothing value False.
6. The Call will be made and the status of all the scheduled jobs will be printed in the console.
3.2.3 Sample Data Files Structure
Credential.txt
This file contains the credentials required to authenticate the user. This file has the data in the following format:
CustomerId;username;Password;userAgent(optional);
Note Leave space if there is no userAgent.
Job30.txt
This file contains the jobs that need to be created. Each line of the file represents a scheduled job. Each scheduled job must be in the following format:
ExternalID;jobNumber;jobDescription;startTime;endTime;availableFrom;availableTo; address1;address2;city;state;postalCode;contactName;contactPhone;lat;lon;sendSms; userId; isAlwaysAvailable;
Note 1. Leave space if there is no value for any of the above parameters. 2. Date must be in “dd-mm-yyyy hh:mm:ss” format.
Flex.txt
This file contains the flexfields associated with the job. Each line of the file represents the FlexFieldDefinition bean. Flexfields must be in the following format:
ExternalId;defaultValue;eventId;fieldname;isMandatory;isMultiSelect;value1;value2;.;valueN;
CreateLandmark.txt
This file contains the details of the Landmarks that need to be created. Each line contains the details of a single landmark. LandmarkDetails should be in the following format:
LandmarkName;address1;address2; city;state;zip;latitude;longitude;zoomLevel;distance; iconIdentifier;
Confidential Xora API V 4.0 - Application Integration Guide Page 6
API - Architecture
4 API - Architecture
The APIs allows integration of any external application with the Xora Server.
This integration is also accomplished using the Xora Data Shuttle (XDS) client. However, this guide provides an overview of the Xora APIs only. To integrate external application with the Xora Server through XDS client, please refer XDS Guide at http://help.xora.com.
4.1 Points to Remember ♦ By default, API’s calls are throttled for 15 minutes.
For example: getLocationEntries Xora API can be called once in 15 minutes. Any violation to this rule would result in the request being rejected by the Xora server.
♦ Time comparisons are done using the actual received time at the Xora server. The data returned for the given date and time range, is the data, which is received on the Xora server during that time period.
♦ Some overlap of a few seconds between subsequent calls to the Get APIs is recommended, since the precision is only up to a few seconds. For example, if client queries for data between T1 to T2, next call must be (T2-1 second) to T3, assuming time T1 < T2 < T3. This minimal overlap in seconds ensures completeness of data.
Note If the time overlap between subsequent get calls is substantial to the effect of a few minutes, then the Xora server may entirely reject the request.
♦ All the requests and responses are mapped to userIds. For mapping the userIds to the phone numbers and names (FirstName, LastName), you must call getUserInfo API at least once.
♦ Also remember to pass the userIds for all post calls.
♦ All the non-Java clients must convert the timestamps to GMT before sending to the Xora server.
♦ Data cannot be queried for more than a period of seven days.
4.2 Validation Mechanism This section provides the validation mechanism for the APIs. They are:
♦ The credentials passed to the APIs determine the phone users for whom the data will be returned. For example, a Team Leader credential will only return user data for users belonging to that team.
Confidential Xora API V 4.0 - Application Integration Guide Page 7
Xora APIs
5 Xora APIs
Xora APIs are categorized into the following services. Click on the links to view the more information on the required services.
♦ Time Services
♦ User Management Services
♦ Location Services
♦ Job Services
♦ Utility Services
Further, each API is divided into the following sections:
♦ Overview
This section provides an overview of the Xora API with an example.
♦ Request Parameters
This section provides list of parameters used to pass the information into Xora server for you to retrieve respective data. For complex parameters, the property information is linked to the respective sections in the Appendix.
♦ Response Parameters
This section provides list of parameters that are returned from the Xora server based on the information passed.
♦ Error Codes
This section provides the list of error codes and the respective error message that are specific to that particular API.
♦ Throttling Rules
This section provides the list of throttling rules that are specific to that particular API.
♦ Status Message (If Any)
This section provides the list status messages that are specific to that particular API.
♦ Sample Java Code
This section is very important and provides sample Java code for that particular API and how it can be used to make calls to create, update, delete, or get the respective data.
Click on the respective API for detailed information.
Time Services
API Name API Description
getTimeEntries This API is used to retrieve all the shift data and their location that were received by the Xora server during the specified time range.
Confidential Xora API V 4.0 - Application Integration Guide Page 8
Xora APIs
getShiftFlexFieldEntries This API is used to retrieve all the Job Flex Fields that were created in the Xora server during the specified time range.
User Management Services
createUsers This API is used to create new users in Xora TimeTrack web application.
updateUserInfo This API is used to update the existing user information such as Employee Number, First Name, Last Name, Time Zone, and Shift Type.
In addition, this API returns the status confirming the success or failure of the updated information.
getUserInfo This API is used to retrieve the user information such as User ID, Employee Number, Team Name, and Team ID.
updateUsersPassword This API is used to update the existing user password associated to the respective user IDs.
createTeams This API is used to create teams.
updateTeams This API is used to update the existing team information.
deleteTeams This API is used to delete teams.
addUsersToTeam This API is used to add users to teams.
removeUsersFromTeam This API is used to remove users from teams.
getTeams This API is used to retrieve team IDs.
highlightUser This API is used to append a text to a given user when the user is viewed on the map.
Note This API is not available for all the customers.
Location Services
createLandmarks This API is used to create landmarks.
Note This API is not available for all the customers.
deleteLandmarks This API is used to delete landmarks.
Note This API is not available for all the customers.
Confidential Xora API V 4.0 - Application Integration Guide Page 9
Xora APIs
getGeofenceActivity This API is used to retrieve the user activities and violations with respect to the defined Geofences that were created in the Xora server during the specified time range.
getLocationEntries This API is used to retrieve the location data that were created in the Xora server during the specified time range.
getLatestLocation This API is used to retrieve the last / latest location of a user.
Job Services
createScheduledJobs This API is used to create jobs in the Xora application. The Jobs are dispatched to the users identified by the userId.
updateScheduledJobs This API is used to update scheduled jobs and also manages to reassign jobs.
cancelScheduledJobs This API is used to cancel the Scheduled Jobs.
getScheduledJobDetails This API is used to retrieve scheduled job details.
Note This API will be implemented in the subsequent releases.
getScheduledJobState This API is used to retrieve the current job state.
getJobEntries This API is used to retrieve the jobs that were received by the Xora server during the specified time range.
getJobFlexFieldEntries This API is used to retrieve all the Job Flex Fields that were created in the Xora server during the specified date range.
changeJobAssignment This API is used to reassign the jobs. When the jobs are reassigned, this Xora API returns the job assignment status.
getJobDetails This API is used to retrieve Job details.
Note This API will be implemented in the subsequent releases.
getJobsCustomStatusEntries This API is used to retrieve all the statuses history for the
jobs during the specified date range.
Utility Services
isCredentialValid This API is used to validate customer login credentials such as Account Id, User Name, and Password.
getMediaDetails This API is used to retrieve Media details using the media IDs.
Confidential Xora API V 4.0 - Application Integration Guide Page 10
Time Services
6 Time Services
Time Services consists of the following APIs:
♦ getTimeEntries
♦ getShiftFlexFieldEntries
6.1 getTimeEntries
6.1.1 Overview
This API is used to retrieve all the shift data and their location that were received by the Xora server during the specified time range. In addition, this API also retrieves the address information for each of these time entries.
A TimeEntry would denote either a “Shift Start” event or a “Shift End” event that was recorded on the phone. “Lunch Start”, “Lunch End” and “Travel Start” events recorded on the phone would also classify as Time Entries.
Scenario
Assume that there are five phone users on the shift today. You can retrieve the time entries made by them with respect to when they started the shift (Shift Start), started the lunch (Lunch Start), finished the lunch (Lunch End), and so on in terms of events.
When you provide the time range information for which these information is needed, this Xora API retrieves the time entries for each of the phone user on shift.
That is, the retrieved data basically provides you the list of clocked timings from Shift Start to Shift End for each individual user for the specified time range.
6.1.2 Request Parameters
Parameter Name Data Type Mandatory Description
credential Complex Yes Credential object.
A data structure used to submit the customer’s login information. The customer must submit this information for every API call.
dateTimeRange Complex Yes The date and time range for which the data is requested.
The DateTimeRange parameter is a data structure used to submit the date range for all the get calls. The fromDate value must be before the toDate value.
pageRequest Complex No PageRequest object.
Confidential Xora API V 4.0 - Application Integration Guide Page 11
Time Services
6.1.3 Response Parameters
Parameter Name Data Type Description
getTimeEntriesReturn Complex TimeEntry40 object.
6.1.4 Example
Let’s retrieve the shift data and their location using the getTimeEntries API. For illustration, let’s use the following sample data to retrieve.
fromDate toDate
01-10-2007 00:00:00
01-11-2007 00:00:00
When this API is executed with the above-mentioned data, the time entry details created within the specified date range is retrieved.
6.1.5 Error Codes
Error Codes 3500, 3501, 3502, 3505
6.1.6 Status Codes and Messages
None
6.1.7 Throttling Rules
♦ Frequency rule (15 minutes)
♦ Date Range Sum Rule (48 hrs)
♦ Date Range Superset Rule (3 calls)
♦ Date Range Limit Rule (24 hrs)
For more information on throttling rules, please refer Throttling Requirements in Appendix.
6.1.8 Sample Java Code
Credential credential = new Credential();
credential.setAccountId(98575);
credential.setUsername("admin"); credential.setPassword("password");
DateTimeRange dateTimeRange = new DateTimeRange();
dateTimeRange.setFromDate(fromDate);
dateTimeRange.setToDate(toDate);
PageRequest pageRequest = new PageRequest();
pageRequest.setPageNumber("2");
Confidential Xora API V 4.0 - Application Integration Guide Page 12
Time Services
//set only if you have a new token
pageRequest.setToken("2l/rNf+D2+rR6qFvFgeR5spfslnqDA4Q");
XoraClient30 xoraClient30 = new XoraClient30 ();
xoraClient30.setTimeServiceURL("http://apps.xora.com/xoraapps/services/XoraTimeTrackTimeServices40?wsdl");
TimeEntry40 timeEntry = xoraClient30.getTimeEntries(credential, dateTimeRange, pageRequest);
6.2 getShiftFlexFieldEntries
6.2.1 Overview
This API is used to retrieve all the Shift Flex Fields that were created in the Xora server during the specified time range.
Scenario
Assume that there are 10 Shift Flex Fields available in the Xora server created over a time period.
To retrieve Shift Flex Fields, you can use this API and provide the From date and To date during which Shift Flex Fields were created. (For ex: 01-01-2007 09:00:00 to 01-31-2007 18:00:00).
Thus this API retrieves all the Shift Flex Fields that were created during this specified time period.
6.2.2 Request Parameters
Parameter Name Data Type Mandatory Description
credential Complex Yes Credential object.
A data structure used to submit the customer’s login information. The customer must submit this information for every API call.
dateTimeRange Complex Yes The date and time range for which the data is requested.
The DateTimeRange parameter is a data structure used to submit the date range for all the get calls. The fromDate value must be before the toDate value.
pageRequest Complex No PageRequest object.
6.2.3 Response Parameters
Parameter Name Data Type Description
getShiftFlexFieldEntriesReturn Complex ShiftFlexField40 object.
Confidential Xora API V 4.0 - Application Integration Guide Page 13
Time Services
6.2.4 Example
Let’s retrieve the shift FlexField details using the getShiftFlexFieldEntries API. For illustration, let’s use the following sample data to retrieve.
fromDate toDate
01-10-2007 00:00:00
01-11-2007 00:00:00
When this API is executed with the above-mentioned data, the details of Flex Fields defined for shift within the specific date range is retrieved.
6.2.5 Error Codes
Error Codes 3500, 3501, 3502, 3503, 3505
6.2.6 Status Codes and Messages
None
6.2.7 Throttling Rules
♦ Frequency rule (15 minutes)
♦ Date Range sum rule (48 hrs)
♦ Date range Superset rule (3 calls)
♦ Date Range Limit Rule (24 hrs)
For more information on throttling rules, please refer Throttling Requirements in Appendix.
6.2.8 Sample Java Code
Credential credential = new Credential();
credential.setAccountId(98575);
credential.setUsername("admin");
credential.setPassword("password");
DateTimeRange dateTimeRange = new DateTimeRange();
dateTimeRange.setFromDate(fromDate);
dateTimeRange.setToDate(toDate);
PageRequest pageRequest = new PageRequest();
pageRequest.setPageNumber("2");
//set only if you have a new token
pageRequest.setToken("2l/rNf+D2+rR6qFvFgeR5spfslnqDA4Q");
XoraClient30 xoraClient30 = new XoraClient30 ();
xoraClient30.setTimeServiceURL("http://apps.xora.com/xoraapps/services/XoraTimeTrackTimeServices40?wsdl");
Confidential Xora API V 4.0 - Application Integration Guide Page 14
Time Services
ShiftFlexField40 shiftFfEntry = xoraClient30.getShiftFlexFieldEntries(credential, dateTimeRange, pageRequest);
Confidential Xora API V 4.0 - Application Integration Guide Page 15
User Management Services
7 User Management Services
User Management Services consists of the following APIs:
♦ createUsers
♦ updateUserInfo
♦ getUserInfo
♦ updateUsersPassword
♦ createTeams
♦ updateTeams
♦ deleteTeams
♦ addUsersToTeam
♦ removeUsersFromTeam
♦ getTeams
♦ highlightUser
7.1 createUsers
7.1.1 Overview
This API is used to create new users.
In return, this API retrieves the status confirming the success or failure of the created user.
You can also provide Team ID to which the user must be associated.
7.1.2 Request Parameters
Parameters that are highlighted in yellow color in this table will be implemented in the subsequent releases.
Parameter Name Data Type Mandatory Description
credential Complex Yes Credential object.
A data structure used to submit the customer’s login information. The customer must submit this information for every API call.
usersArray Array No Array of UserInfo.
insertOptions Complex No InsertOptions object.
Confidential Xora API V 4.0 - Application Integration Guide Page 16
User Management Services
7.1.3 Response Parameters
Parameter Name Data Type Description
createUsersReturn Array Array of UserStatus.
7.1.4 Example
Let’s create a user using the createUsers API. For illustration, let’s use the following sample data to create.
userId Not Required
phoneNumber 6503175470
employeeNumber EN-456
firstName John
lastName Mathews
timeZone CST
shiftType Straight Time
userType Report Admin
isActive True
gmtOffsetMinutes Not Required
teamId 6789
loginUserId 178367
When this API is executed with the above-mentioned data, the user is created along with the user information. In return, the user status (externalUserId, statusCode, statusMessage, and the userId) is shown.
7.1.5 Error Codes
Error Codes 3502, 4002
7.1.6 Status Codes and Messages
Status Code Status Message
3000 ♦ LoginUserId should be unique.
♦ Invalid teamId.
♦ Invalid user type. Only 'Report Admin - Team Leader', 'Customer' and
Confidential Xora API V 4.0 - Application Integration Guide Page 17
User Management Services
Status Code Status Message
'Crew Member' user types are allowed.
♦ Invalid shift type name.
♦ Invalid time zone name.
♦ Invalid phone number.
♦ Invalid employee number. Employee number should be unique and should not contain more than 30 characters.
♦ Unable to create user.
♦ Cannot create the user of given 'user type'.
♦ First Name cannot be null.
♦ Last Name cannot be null.
3001 ♦ Created the user succesfully.
7.1.7 Throttling Rules
♦ Frequency rule (1 day)
For more information on throttling rules, please refer Throttling Requirements in Appendix.
7.1.8 Sample Java Code
Credential credential = new Credential();
credential.setAccountId(98575);
credential.setUsername("admin");
credential.setPassword("password");
UserInfo[] usersArray = new UserInfo[1];
UserInfo userInfo = new UserInfo();
userInfo.setPhoneNumber("6503175470");
userInfo.setEmployeeNumber("EN-456");
userInfo.setFirstName("John");
userInfo.setLastName("Mathews");
userInfo.setTimeZone("Arizona (Phoenix)");
userInfo.setShiftType("Straight Time");
userInfo.setUserType("Report Admin - Team Leader");
userInfo.setLoginUserId("178367");
usersArray[0] = userInfo;
XoraClient30 xoraClient30 = new XoraClient30 ();
xoraClient30.setUserManagementServiceURL("http://apps.xora.com/xoraapps/services/XoraTimeTrackUserManagementServices40?wsdl");
Confidential Xora API V 4.0 - Application Integration Guide Page 18
User Management Services
UserStatus[] userStatusArr = xoraClient30.createUser(credential, usersArray, null);
7.2 updateUserInfo
7.2.1 Overview
This API is used to update the existing user information such as Employee Number, First Name, Last Name, Time Zone, Shift Type, and so on.
In addition, this API retrieves the status confirming the success or failure of the updated information.
Scenario
If there is any mistake or change in the existing user information, you can use this API to modify or update the same. This information includes Employee Number, First Name, Last Name, Time Zone, Shift Type, and so on.
Details in the UserInfo object such as userId, userType, isActive, gmtOffsetMinutes, teamId, cannot be updated.
Note
If there are errors in the UserInfo object, they will be ignored. However the rest of the user details (which were valid in the same request) would get updated. Because of the higher frequency rule in force, there is no need to check for continuous data errors in the request.
7.2.2 Request Parameters
Parameter Name Data Type Mandatory Description
credential Complex Yes Credential object.
A data structure used to submit the customer’s login information. The customer must submit this information for every API call.
UserInfo Array Yes Array of UserInfo.
7.2.3 Response Parameters
Parameter Name Data Type Description
UserStatus Array Array of UserStatus.
7.2.4 Example
Let’s update some of the user information using the updateUserInfo API. For illustration, let’s use the following sample data to update.
userId 178367
Confidential Xora API V 4.0 - Application Integration Guide Page 19
User Management Services
phoneNumber 6503175470
employeeNumber EN-456
firstName John
lastName Mathews
timeZone Arizona (Phoenix)
shiftType Straight Time
userType Not Required
isActive True
gmtOffsetMinutes Not Required
teamId 8298
loginUserId 178367
When this API is executed with the above-mentioned data, the user information is updated accordingly and the user status (statusCode, statusMessage, and the userId) is shown.
7.2.5 Error Codes
Error Codes 3502
7.2.6 Status Codes and Messages
Status Code Status Message
3000 ♦ Invalid input. There is no user information in request.
♦ UserId cannot be null.
♦ Login user Id cannot be null.
♦ First Name cannot be null.
♦ Last Name cannot be null.
♦ Employee number should not contain more than 50 characters.
♦ Invalid user id. User Id should contain only numbers without any space/special characters.
♦ Cannot update. Invalid user id.
♦ Cannot update. Login User Id already exists for the account.
♦ Time zone name cannot be null.
♦ Shift type name cannot be null.
♦ Invalid time zone name.
Confidential Xora API V 4.0 - Application Integration Guide Page 20
User Management Services
Status Code Status Message
♦ Invalid shift type name.
3001 n successfully. ♦ Updated user informatio
3510 ♦ There is no user information in the request.
7.2.7 Throttling Rules
throttling rules, please refer Throttling Requirements
♦ Frequency rule (1 day)
For more information on in
7.2.8 ava Code
ew Credential();
Appendix.
Sample J
Credential credential = n
credential.setAccountId(98575);
credential.setUsername("admin");
credential.setPassword("password");
UserInfo[] usersArray = new UserInfo[1];
UserInfo userInfo = new UserInfo();
userInfo.setPhoneNumber("6503175470");
userInfo.setEmployeeNumber("EN-456");
userInfo.setFirstName("John");
userInfo.setLastName("Mathews");
userInfo.setTimeZone("Arizona (Phoenix)");
userInfo.setShiftType("Straight Time");
userInfo.setUserType("Report Admin - Team Leader");
userInfo.setLoginUserId("178367");
usersArray[0] = userInfo;
XoraClient30 xoraClient30 = new XoraClient30 ();
xoraClient30.setUserManagementServiceURL("http://apps.xora.com/xoraapps/services/XoraTimeTrackUserManagementServices40?wsdl");
UserStatus[] userStatusArr = xoraClient30.updateUserInfo(credential, usersArray, null);
7.3 getUserInfo
7.3.1 Overview
This API is used to retrieve the user information such as User ID, Employee Number, Team Name, Team ID, and so on. You must have Business Plus module to retrieve the user information.
Confidential Xora API V 4.0 - Application Integration Guide Page 21
User Management Services
Following are some of the scescenarios, the respective infor
narios in terms of getting user information. Based on these mation is retrieved:
e is passed, information of those respective team members will be
ged in user is "Report Admin" or "Supervisor" and if they are team leads of one or more team, then information of their team members will be returned.
s
7.3.2
Parameters that are highlighted in yellow color rele s
♦ If the team namreturned. If not, and if the logged in user is "Admin" then all users information except 'Admin' user will be returned.
♦ If log
♦ If logged in user is "Report Admin" or "Supervisor" and not team lead, then all userinformation except 'Admin' user will be returned.
Request Parameters
in this table will be implemented in the subsequent ase .
Parameter Name Data Type Mandatory Description
credential Complex Yes Credential object.
A data structure used to submit the
call.
customer’s login information. The customer must submit this information for every API
userCriteria Complex No UserCriteria object.
selectOptions Complex No SelectOptions object to specify search options.
pageRequest Complex No PageRequest object.
7.3.3 Response Parameters
Parameter Name Data Type Description
getUserInfoReturn Complex UserInfo40 object.
7.3.4 Example
getUserInfo API. For illustration, let’s retrieve user information belonging to the below-mentioned Team Name (sample data). Let’s retrieve user information using the
userId 178367
externalUserId 786
phoneNumber 6503175470
employeeNumber EN-456
firstName John
Confidential Xora API V 4.0 - Application Integration Guide Page 22
User Management Services
lastName Mathews
timeZone Arizona (Phoenix)
shiftType Straight Time
userType Not Required
isActive True
When this API is executed with the above-mentioned sample data, the user information such as userId, phoneNumber, employeeNumber, firstName, lastName, timeZone, shiftType, userType, isActiv tMinute UserId are shown.
7.3.5 des
Erro 350
e, gmtOffse s, teamId, login
Error Co
r Codes 0, 3501, 3502, 3511, 3502
7.3.6 Status Codes and Messages
None
y ru
For more information on throttling rules, please refer Throttling Requirements
7.3.7 Throttling Rules
♦ Frequenc le (1 day)
in
Sample Java Code
new Credential();
Appendix.
7.3.8
Credential credential =
credential.setAccountId(98575);
credential.setUsername("admin");
credential.setPassword("password");
PageRequest pageRequest = new PageRequest();
pageRequest.setPageNumber("2");
//set only if you have a new token
pageRequest.setToken("2l/rNf+D2+rR6qFvFgeR5spfslnqDA4Q");
// enter user ctiteria
UserCriteria userCriteria = new UserCriteria()
userCriteria.setUserId("78450");
userCriteria.setExternalUserId("324980");
userCriteria.setEmployeeNumber("EN-456");
userCriteria.setPhoneNumber("6503175470");
userCriteria.setFirstName("John");
Confidential Xora API V 4.0 - Application Integration Guide Page 23
User Management Services
userCriteria.setLastName("Mathews");
userCriteria.setTimeZone("Arizona (Phoenix)");
userCriteria.setShiftType("Straight Time");
userCriteria.setUserType("Report Admin - Team Leader");
userCriteria.setActive(true);
XoraClient30 xoraClient30 = new XoraClient30 ();
xoraClient30.setUserManagementServiceURL("http://apps.xora.com/xoraapps/services/XoraTimeTrackUserManagementServices40?wsdl");
UserInfo40 users = xoraClient30.getUserInfo(credential, userCriteria, null, pageRequest);
7.4 updateUsersPassword
7.4.1 Overview
This API is used to update the user password associated to the respective user IDs.
In return, this API retrieves the status confirming the success or failure of the updated password.
es, if your user’s password needs to be changed, you can use this API. ssword associated to the userId.
in this table will be implemented in the subsequent
Scenario
For any security purposYou can update the pa
7.4.2 Request Parameters
Parameters that are highlighted in yellow color releases.
Parameter Name Data Type Mandatory Description
credential Complex Yes Credential object.
A data structure used to submit the
must submit this information for every API call.
customer’s login information. The customer
userPasswords Array No Array of UserPassword.
updateOptions Complex No UpdateOptions object.
7.4.3 Response Parameters
Parameter Name Data e Typ Description
updateUsersPasswor ArdReturn ray Array of UserStatus.
Confidential Xora API V 4.0 - Application Integration Guide Page 24
User Management Services
7.4.4 Example
Let’s update the user’s password using the updateUsersPassword API. For illustration, let’s use the foll to updatowing sample data e.
userId 178367
loginPassword 17pass
When this API is executed with the above-mentioned data, the user’s password is updated accordingly and the user status (externalId, statusCode, statusMessage, and userId) is shown.
7.4.5 Error odes
350
C
Error Codes 2, 4003
7.4.6 Status Codes and Messages
Status Code Status Message
3000 ♦ nnot be null.
♦ Password cannot be null.
ntain more than 30 characters.
♦ Invalid user id. User ID sh umbers without any space/special characters.
to this account.
User ID ca
♦ Password should not co
ould contain only n
♦ User ID does not belong
♦ Password cannot be null.
♦ User password is not updated.
3001 ♦ Updated user password successfully.
7.4.7 Throttling
♦ Frequency rule (1 day)
For more information on throttling rules, please refer Throttling Requirements
Rules
in ndix.
7.4.8 Sample Java Code
Credential credential = new Credential();
Appe
credential.setAccountId(98575);
credential.setUsername("admin");
credential.setPassword("password");
PageRequest pageRequest = new PageRequest();
UserPassword[] userPasswords = new UserPassword[2];
UserPassword userPassword = new UserPassword();
Confidential Xora API V 4.0 - Application Integration Guide Page 25
User Management Services
userPassword.setUserId(435344);
userPassword.setLoginPassword("loginpassword");
UserPassword userPassword_1 = new UserPassword();
userPassword_1.setUserId(435345);
userPassword_1.setLoginPassword("loginpassword11");
userPasswords[0] = userPassword;
userPasswords[1] = userPassword_1;
XoraClient30 xoraClient30 = new XoraClient30 ();
xoraClient30.setUserManagementServiceURL("http://apps.xora.com/xoraapps/services/XoraTimeTrackUserManagementServices40?wsdl");
UserStatus[] userStatus = xoraClient30.updateUsersPassword(credential, userPasswords, null);
7.5 createTeams
7.5.1 Overview
This API is used to create teams in Xora TimeTrack web application.
You can also provide UserIds, GeofenceIds, LandmarkIds, ProfileId, SmartJobZones, and must be associated.
tatus confirming the success or failure of the created team.
rameters
emented in the subsequent
TeamLeadId to which the team
In return, this API retrieves the s
7.5.2 Request Pa
Parameters that are highlighted in yellow color in this table will be implreleases.
Parameter Name Data Type Mandatory Description
credential Complex Yes Credential object.
A data structure used to submit the
must submit this information for every API call.
customer’s login information. The customer
teams Array No Array of Team.
insertOptions Complex No InsertOptions object.
7.5.3 Response Parameters
Parameter Name Data T ype Description
updateUsersPasswor Arr AdReturn ay rray of TeamStatus.
Confidential Xora API V 4.0 - Application Integration Guide Page 26
User Management Services
7.5.4 Example
Let’s create a new team using the createTeams API. For illustration, let’s use the following sample data to create.
geofenceIds 487
landmarkIds 398
profileId 23
smartJobZones 35
status Not Required
teamId 987
teamLeadId 89
teamName MyTeam
userId 178367
When this API is executed with the above-mentioned data, the team is created and the team status
7.5.5 des
Error Codes 350
is shown.
Error Co
2, 4004
7.5.6 Status Codes and Messages
Status Code Status Message
3000 ♦ Team name cannot be null.
♦ TeamLeadId cannot be null.
♦ Team Name already exists.
♦ Unable to create team.
Admin.
♦ Invalid profileId.
♦ TeamLeadId is not a Report
3001 ♦ Created the team succesfully.
Created the team. The following userId(s) are not valid and hence are not ♦ added in the team.
7.5.7 Throttli
♦ quenc
ng Rules
Fre y rule (1 day)
Confidential Xora API V 4.0 - Application Integration Guide Page 27
User Management Services
For more information on throttling rules, please refer Throttling Requirements in Appendix.
7.5.8 Sample Ja
new Credential();
va Code
Credential credential =
credential.setAccountId(98575);
credential.setUsername("admin");
credential.setPassword("password");
Team[] teams = new Team[1];
Team team = new Team();
team.setTeamLeadId(7389);
team.setTeamName("MyTeam");
String[] userIds = {"23435", "43589", "45890"};
team.setUserId(userIds);
String[] landmarkIds = {"234", "435", "458"};
team.setLandmarkIds(landmarkIds);
String[] geofenceIds = {"2341", "4352"};
team.setGeofenceIds(geofenceIds);
String [] smartJobZones = {"SmartJob 1","SmartJob 2"};
team.setSmartJobZones(smartJobZones);
team.setProfileId(43234);
XoraClient30 xoraClient30 = new XoraClient30 ();
xoraClient30.setUserManagementServiceURL("http://apps.xora.com/xoraapps/services/XoraTimeTrackUserManagementServices40?wsdl");
TeamStatus[] teamStatus = xoraClient30.createTeams(credential, teams, null);
7.6 updateTeams
7.6.1 Overview
This API is used to update the existing team information such as Status, TeamID, TeamLeadID, TeamName, associated UserIDs, GeofenceIDs, LandmarkIDs, ProfileID, and SmartJobZones.
In return, this API retrieves the status confirming the success or failure of the updated team.
or change in the existing team information, you can use this API to modify
Scenario
If there is any mistake or update the same.
Confidential Xora API V 4.0 - Application Integration Guide Page 28
User Management Services
7.6.2 Request Parameters
Parameters that are highlighted in yellow color in this table will be implemented in the subsequentreleases.
Parameter Name Data Type Mandatory Description
credential Complex Yes Credential object.
A data structure used to submit the customer’s login information. The customer must submit this information for every API call.
teams Array No Array of Team.
updateOptions Complex No UpdateOptions object.
7.6.3 Response Parameters
Parameter Name Data Type Description
updateTeamsReturn Array Array of TeamStatus.
7.6.4 Example
Let’s update team information using the updateTeams API. For illustration, let’s use the following sample data to update.
geofenceIds 487
landmarkIds 398
profileId 23
smartJobZones 35
status Not Required
teamId 987
teamLeadId 91
teamName MyTeam
userId 178367
When this API is executed with the above-mentioned data, the team information is updated accordingly and the team status is shown.
Confidential Xora API V 4.0 - Application Integration Guide Page 29
User Management Services
7.6.5 Error Codes
Error Codes 3502, 4005
7 d e.6.6 Status Co es and M ssages
Status Code Status Message
3000 ♦ Team name cannot be null.
♦ Invalid TeamLeadId.
♦ Invalid profileId.
♦ Invalid team name.
♦ Te not a ortAd
♦ Unable to update team.
amLead is Rep min.
3001 ♦ Updated the team succesfully.
7.6.7 Throttling Rules
mation on throttling rules, please refer Throttling Requirements
♦ Frequency rule (1 day)
For more infor in
Code
Credential credential = new Credential();
Appendix.
7.6.8 Sample Java
credential.setAccountId(98575);
credential.setUsername("admin");
credential.setPassword("password");
Team[] teams = new Team[1];
Team team = new Team();
team.se eadId(tTeamL 7389);
team.setTeamName("MyTeam");
String[] userIds = {"23435", "43589", "45890"};
team.setUserId(userIds);
String[] landmarkIds = {"234", "435", "458"};
team.setLandmarkIds(landmarkIds);
String[] geofenceIds = {"2341", "4352"};
team.setGeofenceIds(geofenceIds);
String [] smartJobZones = {"SmartJob 1","SmartJob 2"};
team.setSmartJobZones(smartJobZones);
team.setProfileId(43234);
Confidential Xora API V 4.0 - Application Integration Guide Page 30
User Management Services
XoraClient30 xoraClient30 = new XoraClient30 ();
xoraClient30.setUserManagementServiceURL("http://apps.xora.com/xoraapps/services/XoraTimeTrackUserManagementServices40?wsdl");
TeamStatus[] teamStatus = xoraClient30.updateTeams(credential, teams, null);
7.7 deleteTeams
7.7.1 ervie
This API is used
In return, this AP onfirming the success or failure of the deleted team.
7.7.2 Request
Parameters that are highlighted in yellow color in this table will be implemented in the subsequent releases.
Ov w
to delete teams.
I retrieves the status c
Parameters
Par Namameter e Data Type Mandatory Description
credential Complex Yes Credential object.
A data structure used to submit the customer’s login information. The customer
PI call. must submit this information for every A
teamsId String Array
No Array of team id.
deleteOptions Complex No DeleteOptions object.
7.7.3 Response Parameters
Parameter Name Data Type Description
deleteTeamsReturn Array Array of TeamStatus.
7.7.4 Example
Let’s delete a team using the deleteTeams API. For illustration, let’s use the following sample data to delete.
teamId 987
When this API is executed with the teamID 987, this team is deleted from the system and the team status is shown.
Confidential Xora API V 4.0 - Application Integration Guide Page 31
User Management Services
7.7.5 Error Codes
Error Codes 3502, 4006
7.7.6 Status Codes and Messages
Status Code Status Message
3000 ♦ Invalid teamId.
nnot delete default team. ♦ Ca
3001 ♦ Successfully deleted the Team.
7.7.7 Throttling Rules
♦
For more information on throttling rules, please refer Throttling Requirements
Frequency rule (1 day)
in Appendix.
7.7.8
Credential credential = new Credential();
Sample Java Code
credential.setAccountId(98575);
credential.setUsername("admin");
credential.setPassword("password");
S teamsId = 35", " 89",tring[] {"234 435 "45890"};
XoraClient30 xoraClient30 = new XoraClient30 ();
xoraClient30.setUserManagementServiceURL("http://apps.xora.com/xoraapps/services/XoraTimeTrackUserManagementServices40?wsdl");
TeamStatus[] teamStatus = xoraClient30.deleteTeams(credential, teamsId, null);
7.8 addUsersToTeam
7.8.1 Overview
d users to teams in Xora TimeTrack web application.
7.8.2 Request Parameters
Parameters that are highlighted in yellow color in this table will be implemented in the subsequent
This API is used to ad
In return, this API retrieves the status confirming the success or failure of the addition.
releases.
Parameter Name Data Type Mandatory Description
credential Complex Yes Credential object.
Confidential Xora API V 4.0 - Application Integration Guide Page 32
User Management Services
Parameter Name Data Type Mandatory Description
A data structure used to submit the customer’s login information. The customer must submit this information for every API call.
userIds String Array
No ded / associated to the User IDs to be adteam.
team No Team ID to which the user IDs must be associated.
Id Integer
insertOptions Complex No InsertOptions object.
7.8.3 Response Parameters
Parameter Name Data Type Description
addUs Return Array Array of UserStatusersToTeam .
7.8.4 Example
Let’s add the following user IDs to a team using the addUsersToTeam API. For illustration, let’s use the following sample data to add.
userIds [8238,2988]
teamId 398
When this API is executed with the above-mentioned data, these user IDs are added / associated
Codes 3502
to the given team ID and the array of user status is shown.
7.8.5 Error Codes
Error , 4007
7.8.6 Status Codes and Messages
Status Code Status Message
3000 ♦ Invalid teamId.
♦ UserId cannot be null.
♦ Invalid user id. User Id should contain only numbers without any
♦ Cannot update. Invalid user id.
space/special characters.
3001 ♦ Added the user successfully.
Confidential Xora API V 4.0 - Application Integration Guide Page 33
User Management Services
7.8.7 Throttling
For more information on throttling rules, please refer
Rules
♦ Frequency rule (1 day)
Throttling Requirements in Appendix.
7.8.8 Sample Java Code
C al credent new Cr ntiaredenti ial = ede l();
credential.setAccountId(98575);
credential.setUsername("admin");
credential.setPassword("password");
int teamId = 5648;
String[] userIds = {"23435", "43589", "45890"};
XoraClient30 xoraClient30 = new XoraClient30 ();
xoraClient30.setUserManagementServiceURL("http://apps.xora.com/xoraapps/se Tra agementServices4rvices/XoraTime ckUserMan 0?wsdl");
UserStatus[] userStatus = xoraClient30.addUsersToTeam(credential, u );serIds, teamId, null
7.9 removeUsersFromTeam
This API is used to remove users from teams in Xora TimeTrack web application.
In return retrieve onfirming the success or failure of the removal.
7.9.2 Request Parameters
7.9.1 Overview
, this API s the status c
Parameter Name Data Type Mandatory Description
credential Complex Yes Credential object.
A data structure used to submit the customer’s login information. The customer must submit this information for every API call.
userIds String Array
No User IDs to be added / associated to the team.
team No Team ID to which the user IDs must be associated.
Id Integer
Confidential Xora API V 4.0 - Application Integration Guide Page 34
User Management Services
7.9.3 Response Parameters
Parameter Name Data Type Description
removeUsersFromTeamReturn Array Array of UserStatus.
7.9
Let’s remove the following user IDs from a illustration, let’s use the following sample data to remove.
.4 Example
team using the removeUsersFromTeam API. For
userIds [8238,2988]
teamId 398
When this API is executed with the above-megiven team ID and the array of user status is
ntioned data, these user IDs are removed from the n. show
7.9.5 Error Codes
3502, 4008Error Codes
7.9.6 Status Codes and Messages
Status Code Status Message
3000 ♦ UserId cannot be null.
♦ Invalid user id. User Id should contain only numbers without any ace/special characters. sp
♦ User id does not belong to this account.
♦ Unable to delete. UserId is of supervisor userType.
♦ Unable to delete. UserId doesnot belongs to the given teamId.
3001 ♦ Deleted Successfully.
7.9.7 Throttling Rules
uency rule
For more information on throttling rules, p
♦ Freq (1 day)
lease refer Throttling Requirements in Appendix.
Confidential Xora API V 4.0 - Application Integration Guide Page 35
User Management Services
7.9.8 Sample Java Code
Credential credential = new Credential();
credential.setAccountId(98575);
c dmiredential.setUsername("a n");
credential.setPassword("password");
int teamId = 5648;
String[] userIds = {"23435", "43589", "45890"};
XoraClient30 xoraClient30 = new XoraClient30 ();
xoraClient30.setUserManagementServiceURL("http://apps.xora.com/xoraapps/services/XoraTimeTrackUserManagementServices40?wsdl");
UserStatus[] userStatus = xoraClient30.removeUsersFromTeam(credential, userIds, teamId);
7.10 getTeams
7.10.1 Overview
Thi re IDs from the Xora TimeTrack web application.
g the success or failure of the retrieved team IDs.
7.10.2 Request Parameters
Parameters that are highlighted in yellow color in this table will be implemented in the subsequent relea
s API is used to trieve team
In return, this API retrieves the status confirmin
ses.
Parameter Name Data Type Mandatory Description
credential Complex Yes Credential object.
o submit the
ery API call.
A data structure used tcustomer’s login information. The customer must submit this information for ev
teamSelectionCrit Complex No TeamSelectionCriteriaeria
object.
selectOptions Complex No SelectOptions object.
7.10.3 Response Parameters
Parameter Name Data Type Description
getTeamsReturn Array Array of Team.
Confidential Xora API V 4.0 - Application Integration Guide Page 36
User Management Services
7.10.4 Example
Let’s retrieve team information using the getTeams API. Fsample data to create.
or illustration, let’s use the following
profileId 6577
teamId 765
teamLeadId 540
teamName MyTeam
userId 3988
When this API is executed with the above-mentioned data, the team information is retrieved.
7.10.5 Error Codes
Error Codes 3502, 4001
7.10.6 Status Codes and Messages
None
7.10.7 Throttling Rules
♦ Frequency rule (1 day)
For more information on throttling rules, please refer Throttling Requirements in
7 ple Jav
Credential credential = new Credentia
Appendix.
.10.8 Sam a Code
l();
credential.setAccountId(98575);
credential.setUsername("admin");
credential.setPassword("password");
TeamSelectionCriteria teamSelectionCriteria = new TeamSelectionCriteria();
teamSelectionCriteria.setProfileId(34578);
teamSelectionCriteria.setTeamId(43567);
teamSelectionCriteria.setTeamLeadId(45678);
t i eamName("MyTeam");eamSelectionCr teria.setT
teamSelectionCriteria.setUserId(46456);
XoraClient30 xoraClient30 = new XoraClient30 ();
xoraClient30.setUserManagementServiceURL("http://apps.xora.com/xoraapps/services/XoraTimeTrackUserManagementServices40?wsdl");
Confidential Xora API V 4.0 - Application Integration Guide Page 37
User Management Services
Team[] team = xoraClient30.getTeams(credential, teamSelectionCriteria, null);
7.11 highlightUser
7.11.1 Overview
This API is used to append a text to a given user when the user is viewed on the map. It is basically used to highlight users on the map.
This will allow external applications to display certain users in specific colors allowing them to depict tues p
Scenario
If an external application like a Towing company needs to display a business status like “Free” or
to the name as displayed in the All User
For example:
In the , the user, would appear as King D On Duty, if append text is “<one space>On Duty”. Note that there is no formatting that is done, but only the text will be added.
business sta ictorially.
“on my way” to pick” or “back from delivery”.
Append Text will be the text that needs to be appended report.
All User Map King D
Note This API is available only to select customersneed access to this API.
. Please contact Xora Support if you
Confidential Xora API V 4.0 - Application Integration Guide Page 38
User Management Services
7.11.2 Request Parameters
Parameter Name Data Type Mandatory Description
credential Complex Yes Credential object.
A data structure used to submit the mer customer’s login information. The custo
must submit this information for every API call.
userMapInfo Array Yes Array of UserMapInfo bean.
A data structure used to submit user information for highlighting user on map.
7.11.3 Response Parameters
Parameter Name Data Type Description
HighlightUserStatus Array Array of HighlightUserStatus.
7.11.4 Example
Let’s append a text to a given user when the user is viewed on the map using the highlightUser API. For illustration, let’s use the following sample data to append.
Property Name Sample Data
appliesTo Single User
textColor FF0037
background FFFFFF
appendText On Duty
userId 63788
When this API is executed with the above-mentioned data, the status of the highlighted user is
7.11.5 Error Codes
shown.
r eEr or Cod s 3500, 3501, 3502, 3509, 3000, 3001
7.11.6 Status Codes and Messages
Status Code Status Message
3000 ♦ Invalid input. No user information in request.
Confidential Xora API V 4.0 - Application Integration Guide Page 39
User Management Services
Status Code Status Message
♦ User Id is required
♦ Invalid user id. Cannot update user information.
♦ Ca e user i ation data shuttle module.
♦ Invalid user id. User Id should cspace/special characters
nnot updat nform . User doesn't have
ontain only numbers without any
3001 ♦ Updated the Highlight User Information successfully
7.11.7 Throttling Rules
♦ Frequency rule (1 day)
Throttling RequirementsFor more information on throttling rules, please refer in
7. va Co
C ntial = Creden
Appendix.
11.8 Sample Ja de
redential crede new tial();
credential.setAccountId(98575);
credential.setUsername("admin");
credential.setPassword("password");
UserMapInfo[] userMapInfoArr = new UserMapInfo[1];
UserMapInfo userMapInfo = new UserMapInfo();
userMapInfo.setUserId("85661");
userMapInfo.setAppliesTo("breadcrumb");
userMapInfo.setTextColor("#001155");
userMapInfo.setBackground("#001355");
userMapInfo.setAppendText("test");
userMapInfoArr[0] = userMapInfo;
XoraClient30 xoraClient30 = new XoraClient30 ();
xoraClient30.setUserManagementServiceURL("http://apps.xora.com/xoraapps/services/XoraTimeTrackUserManagementServices40?wsdl");
HighlightUserStatus[] userStatusArr = xoraClient30.highlightUser(credential, userMapInfoArr);
Confidential Xora API V 4.0 - Application Integration Guide Page 40
Location Services
8 Loca s tion Service
Location Service
♦ createLa
♦ deleteLandmarks
♦ eofe
getLocationEntries
8.1
8.1.1 Overview
rks.
a map.
warehouse, customer locations, job locations, and
ted for an individual team
s consists of the following APIs:
ndmarks
getG nceActivity
♦
♦ getLatestLocation
createLandmarks
This API is used to create landma
Landmarks are special locations that can be displayed on
Scenario
The locations for creating landmarks can be aso on.
This API helps you to create these landmarks. Landmarks can be creaor for all teams at once.
need access to this API. Note This API is available only to select customers. Please contact Xora Support if you
8.1.2 Request Parameters
Parameter Name Data Type Mandatory Description
credential Complex Yes Credential object.
A data structure used to submit the customer’s login information. The customer must submit this information for every API
ll. ca
scope Complex Yes Scope object.
Specifies the scope of the landmark. Whether the landmark must be created for all users or team specific.
A data structure used to specify the scope of a landmark.
landmarks Array Yes Array of Landmark.
A data structure used to define the properties
Confidential Xora API V 4.0 - Application Integration Guide Page 41
Location Services
Parameter Name Data Type Mandatory Description
of a landmark.
8.1.3 Response Parameters
Parameter Name Data Type Description
LandmarkStatus Array Array of LandmarkStatus.
8.1
Let’s create landmark using the createLandmarks API. For illustration, let’s use the following
.4 Example
sample data to create.
Property Name Sample Data
global Yes
teamName MyTeam
landmarkName TeamLandmark
address1 12, 5th Avenue
address2 Boulevard Street
city Santa Cruz
state CA
postalCode 95064-1011
latitude 34.209
longitude -118.3254
zoomLevel 5
distance 50
iconIdentifier Star
showNameOnMap Yes
When this API is executed with the above-mentioned data, the landmarkName, code, message is shown identifying the status of the creation.
8.1.5 Error Codes
des 35Error Co 00, 3501, 3502, 3507, 3511, 3513, 3514, 3515, 3000, 3001
Confidential Xora API V 4.0 - Application Integration Guide Page 42
Location Services
8.1.6 Status Codes and Messages
Status Code Status Message
3000 ♦ Invalid input. Scope is not defined.
name is not specified.
Landmark Name already exists.
♦ Invalid input. There is no landmark information in request.
Invalid z vel. Zoo positive number (1 to 10).
ouldn't create Landmark. Invalid Icon Identifier.
alid Longitude.
Address or Lat / Lon should be present.
♦ Unable to geo-code the address given.
♦ Invalid Lat / Lon and Address.
♦ Invalid Lat / Lon.
Cannot create Landmark. Invalid distance.
♦ Invalid input. There is no data in the request.
♦ Invalid input. Team
♦
♦ oom le mLevel should contain only
♦ C
♦ Invalid Latitude.
♦ Inv
♦
♦
3001 ♦ Landmark created Successfully
8.1.7 Throttling R
Frequency rule (15 minutes)
For more information on throttling rules, please refer Throttling Requirements
ules
♦
in dix.
8 ample Jav
Credential credential = new Credential();
Appen
.1.8 S a Code
credential.setAccountId(98575);
credential.setUsername("admin");
credential.setPassword("password");
Scope scope = new Scope();
scope.setGlobal(false);
scope.setTeamName("MyTeam");
Landmark[] landmarks = new Landmark[1];
Landmark landmark = new Landmark();
landmark.setLandmarkName("TeamLandmark");
landmark.setAddress1("12, 5th Avenue");
Confidential Xora API V 4.0 - Application Integration Guide Page 43
Location Services
landmark.setAddress2("");
landmark.setCity("Santa Cruz");
landmark.setState("CA");
landmark.setPostalCode("95064-1011");
landmark.setLatitude("34.209");
landmark.setLongitude("-118.3254");
land setDmark. istance(20);
landmark.setZoomLevel("5");
landmark.setIconIdentifier("Small Star");
landmark.setShowNameOnMap(true);
landmarks[0] = landmark;
XoraClient30 xoraClient30 = new XoraClient30 ();
xoraClient30.setLocationServiceURL("http://apps.xora.com/xoraapps/services/XoraTimeTrackLocationServices40?wsdl");
LandmarkStatus[] landmarkStatus = xoraClient30.createLandmarks(credential, scope, landmarks);
8.2 deleteLandmarks
8.2.1 Overvie
This API is used to delete a landmark. The landmarks are identified by name. It is possible to delete multiple la
Scenario
If landmarks are no more required for your busilandm
w
ndmarks using the same Xora API call.
ness, you can use this Xora API to delete arks.
Note This API is avail
able only to select customers. Please contact Xora Support if you need access to this API.
8.2.2 Request Parameters
Parameter Name Data Type Mandatory Description
credential Complex Yes Credential object.
A data structure used to submit the customer’s login information. The customer must submit this information for every API call.
landmarks Array of String
Yes Array of landmark names.
Confidential Xora API V 4.0 - Application Integration Guide Page 44
Location Services
8.2.3 Response Parameters
Parameter Name Data Type Description
LandmarkStatus Array Array of LandmarkStatus.
8.2.4 Example
Let’s delete the landmark using the deleteLandmarks API. For illustration, let’s use the following sample data to delete.
landmarks
TeamLandmark
When this API is executed with the above-mentioned data, the landmarkName, code, message is shown identifying the status of the deletion.
8.2.5 Error Codes
Error Codes 3500, 3501, 3502, 3507, 3512 , 3000, 3001
8.2.6 Status Codes and Messages
Status Code Status Message
3000 ♦ Invalid input. Land
♦ User is not author
mark name is null.
ized to delete landmark.
e given Landmark doesn't exists for the customer ♦ Th
3001 ♦ Deleted Landmark Successfully
8.2.7 Throttling Rules
Throttling Requirements
♦ Frequency rule (15 minutes)
For more information on throttling rules, please refer in Appendix.
Samp
Credential();
8.2.8 le Java Code
Credential credential = new
credential.setAccountId(98575);
c s mredential.setU ername("ad in");
credential.setPassword("password");
String[] landMarkNames = {"Landmark1", "Landmark2"};
XoraClient30 xoraClient30 = new XoraClient30 ();
Confidential Xora API V 4.0 - Application Integration Guide Page 45
Location Services
xoraClient30.setLocationServiceURL("http://apps.xora.com/xoraapps/services/XoraTimeTrackLocationServices40?wsdl");
LandmarkStatus[] landmarkStatus = xoraClient30.deleteLandmarks(credential, landMarkNames);
8.3 getGeofenceActivity
T etriev ce activity information tha in the Xora server during the specified time range.
T rieves the ctivities ven time range. For each of the geofence activities, this Xora API retrieves thee time of activity and the address when the
, time, geofence violation information, and so on.
The user activities retrieved with respect to time are:
♦ Leaving Geofence
The API also retrieves the distance of the user from Geofence boundary for an activity that is performed outside a Geofence. The time for which the users were inside or outside the fence is a
t least some geofence alerts have been defined for
If a d a and for some reason, the user had to move out of that geofence, it is understood that the user has violated the geofence rules.
formation and the distance of the user from Geofence boundary for an activity that is performed outside a Geofence. Thus helping you to track your users with respect to the jobs that is supposed to be performed within the specified geofence.
8.3.2 Request
8.3.1 Overview
his API is used to r e the Geofen t were created
hat is, this API ret user a for a Geofence within the gi
activity was performed
♦ Entering Geofence
lso retrieved.
However, these Geofence activities are available only if the users are assigned the “Geofence” module from the Xora Web application and athose users.
Scenario
user has starte n event (ex: Shift Start) within one geofence
This API retrieves the violation time duration in
Parameters
Parameter Name Data Type Mandatory Description
cred dentialential Complex Yes Cre object.
A data structure used to submit the customer’s login information. The customer must submit this information for every API call.
dateTi data is requested.
The DateTimeRange
meRange Complex Yes The date and time range for which the
parameter is a data structure used to submit the date range for all the get calls. The fromDate value must be
Confidential Xora API V 4.0 - Application Integration Guide Page 46
Location Services
Parameter Name Data Type Mandatory Description
before the toDate value.
pageRequest Complex No PageRequest object.
8.3.3 Response Parameters
Parameter Name Data Type Description
getGeofenceActivityReturn Complex GeofenceActivity40 object.
8.3.4 Example
Let’s retrieve geofence activity information using the getGeofenceActivity API. For illustration, let’s use the following sample data to retrieve.
fromDate toDate
01-10-2007 00:00:00
01-11-2007 00:00:00
When this API is executed with the above-mentioned data, the geofence activity details created within the specified date range is retrieved.
8.3.5 Error Codes
Error Codes 3500, 3501, 3502, 3505
8.3.6 Status Codes and Messages
None
8.3.7 Throttling Rules
Credential credential = new Credential();
♦ Frequency rule (15 minutes)
♦ Date Range Sum Rule (48 hrs)
♦ Date Range Superset Rule (3 calls)
♦ Date Range Limit Rule (24 hrs)
8.3.8 Sample Java Code
c c 5redential.setA countId(98 75);
c l.setUse dminredentia rname("a ");
credential.setPassword("password");
DateTimeRange dateTimeRange = new DateTimeRange();
dateTimeRange.setFromDate(fromDate);
Confidential Xora API V 4.0 - Application Integration Guide Page 47
Location Services
dateTimeRange.setToDate(toDate);
PageRequest pageRequest = new PageRequest();
pageRequest.setPageNumber("2");
//set only if you have a new token
pageRequest.setToken("2l/rNf+D2+rR6qFvFgeR5spfslnqDA4Q");
XoraClient30 xoraClient30 = new XoraClient30 ();
xoraClient30.setLocationServiceURL("http://apps.xora.com/xoraapps/services/XoraTimeTrackLocationServices40?wsdl");
G vity4 ceAct ty =eofenceActi 0 geofen ivi xoraClient30.getGeofenceActivity(credential, dateTimeRange, pageRequest);
8.4 getLocationEntries
8.4.1 Overview
This API is used to retrieve the location data that were created in the Xora server during the long with the addresses.
users having the data shuttle module.
serId ecified, then the location entries returned is meant for all the users the d tle module.
use d, then the location entries returned is for the specified user.
e spe rId is not valid, then no records will be returned.
location entries returned is for all the events.
a-separated string. For example, JS, JE, SS.
Lat ud
Latitude and longitude fields sometimes contain values given below to indicate unavailability of d’ settings for GPS.
E-ND or E-PE (No location data available)
♦ RT (Restricted)
on stamp was sent immediately to the Xora .
tion' is used.
specified time range a
The following points list out conditions on the input parameters
♦ Returns the location entries only for the
♦ If the Uhaving
is not spata shut
♦ If the
♦ If th
rId is specifie
cified use
♦ EventFilter helps in fetching only those location entries of user for a given set of events.
♦ If no event filter is specified, then the
♦ EventFilter is comm
itude-Longit e Exceptions
position information or phone having ‘Restricte
♦
Event Details
♦ AR - Auto Real, which means that the locatiServer without store and forward
♦ M - Manual, when option 'Send Loca
♦ SS - Shift Start
♦ LS - Lunch Start
♦ LE - Lunch End
Confidential Xora API V 4.0 - Application Integration Guide Page 48
Location Services
♦ TS - Travel Start
♦ JS - Job Start
♦ JE - Job End
♦ SE - Shift End
♦ EA - End application, occurs when application on phone is exited.
pplication on phone is started.
Server
job events and message from phone.
.
Parameters
♦ SA - Start Application, occurs when a
♦ IE - Internally used to send info on phone to the Xora
♦ PM - Phone message.
Event details are currently sent only for the three
♦ TS - Job Number - correct
♦ JS - Job Number - correct
♦ JE - Job Number - correct
♦ PM - Actual message sent
Events with X_ and GX_ prefixes are used internally and should not be interpreted
8.4.2 Request
Parameter Name
Data Type Mandatory Description
credential Complex Yes Credential object.
A data structure used to submit the customer’s login tomer must submit this API call.
information. The cusinformation for every
dateTimeRange
The DateTimeRange
Complex Yes The date and time range for which the data is requested.
parameter is a data structure .
fore the toDate used to submit the date range for all the get callsThe fromDate value must be bevalue.
userId String No A unique number to identify a user on xora server.
ev F Possible values are JS (Job Start), JE (Job End), CS (Custom Status), SS (Shift Start), and so on.
ent ilter String No Specifies an event mnemonic.
It s a Comma separated event list used as filter.
pageReque Complex No st
PageRequest object.
Confidential Xora API V 4.0 - Application Integration Guide Page 49
Location Services
8.4.3 Response Parameters
Parameter Name Data Type Description
ge c Entry40tLo ationEntriesReturn Complex Location object.
A data structure used to return the location entry details.
8.4.4 Example
Let’s retrieve location data using the getLocationEntries API. For illustration, let’s use the follo n retrieve. wi g sample data to
fromDate toDate userId eventFilter
01 -00 :
-10 2007 01-11-2007 6544 JS :00 00 00:00:00
Wh h details created within the specified date range is retrieved.
Error Codes
en t is API is executed with the above-mentioned data, the location
8.4.5 Error Codes
3500, 3501, 3502, 3505, 3516
8.4.6 sages
None
♦ Frequency rule (15 minutes)
l
e Range Superset Rule (3 calls)
Ra ule (2 )
For more information on throttling ru
Status Codes and Mes
8.4.7 Throttling Rules
♦ Date R
♦ Dat
ange Sum Ru e (48 hrs)
♦ Date nge Limit R 4 hrs
les, please refer Throttling Requirements in Appendix.
8.4.8
Credential credential = new Credential();
Sample Java Code
credential.setAccountId(98575);
credential.setUsername("admin");
credential.setPassword("password");
D eRange imeRan neateTim dateT ge = w DateTimeRange();
dateTimeRange.setFromDate(fromDate);
d nge. Date(t e);ateTimeRa setTo oDat
Confidential Xora API V 4.0 - Application Integration Guide Page 50
Location Services
PageRequest pageRequest = new PageRequest();
pageRequest.setPageNumber("2");
//set only if you have a new token
pageRequest.setToken("2l/rNf+D2+rR6qFvFgeR5spfslnqDA4Q");
//passing userId is optional.
String userId = "45669";
//passinf eventFilter is optional. AR-Auto Real, SS-Shift Start, SE-Shift End
String eventFilter = "AR,SS,SE,JS,JE";
XoraClient30 xoraClient30 = new XoraClient30 ();
xoraClient30.setLocationServiceURL("http://apps.xora.com/xoraapps/services/XoraTimeTrackLocationServices40?wsdl");
LocationEntry40 locationEntry = xoraClient30.getLocationEntries(credential, dateTimeRange, userId, eventFilter, pageRequest);
8.5 getLatestLocation
8.5.1 Overview
This API is used to retrieve the last / latest location of a user. It is based on the event time (time on the phone) and hence there may be different results for the exact same call at different times.
To use this API, you must first validate your login credentials. That means the Xora server must validate your Account Id, User Name, and Password for you to retrieve media details.
8.5.2 Request Parameters
Parameters that are highlighted in yellow color in this table will be implemented in the subsequent releases.
Name Data type Mandatory Description
credential Complex Yes Credential object.
A data structure used to submit the customer’s login information. The customer must submit this information for every API call.
locationDetailCriteria Complex No LatestLocationDetailCriteria object.
selectOptions Complex No SelectOptions object to specify search options.
Confidential Xora API V 4.0 - Application Integration Guide Page 51
Location Services
8.5.3 Response Parameters
Parameter Name Data Type Description
getLatestLocationReturn Array Arra sy of LatestLocationDetail object.
8.5.4 Example
t location using the getLatestLocation API. For illustration, let’s use the to retrieve.
Let’s retrieve the latesfollowing sample data
Property Name Sample Data
a e -2007 sOfEventTim 01-10 00:00:00
fieldList [EventEvent,
Ci ed (mph) Ev ]
ty, Speent Zip
,
numberOfLocations 10
userId 2878
When this API is executed with the above-mentioned data, the details of the latest location are retrieved.
8.5.5 Error Codes
Error Codes 3501, 3502
8.5.6 Throttling Rules
♦ Frequency Rule
8.5.7
Credential credential = new Credential();
Sample Java Code
credential.setAccountId(98575);
credential.setUsername("admin");
credential.setPassword("password");
LatestLocationDetailCriteria latestLocationDetailCriteria = new LatestLocationDetailCriteria();
latestLocationDetailCriteria.setAsOfEventTime(asOfEventTime);
// mention the required column names. if set to null all the columns are returned.
latestLocationDetailCriteria.setFieldList(null);
latestLocationDetailCriteria.setNumberOfLocations("10");
String[] userIds = {"23435", "43589", "45890"};
Confidential Xora API V 4.0 - Application Integration Guide Page 52
Location Services
latestLocationDetailCriteria.setUserId(userIds);
XoraClient30 xoraClient30 = new XoraClient30 ();
xoraClient30.setLocationServiceURL("http://apps.xora.com/xoraapps/services/XoraTimeTrackLocationServices40?wsdl");
LatestLocationDetails[] latestLocations = xoraClient30.getLatestLocation(credential, latestLocationDetailCriteria, null);
Confidential Xora API V 4.0 - Application Integration Guide Page 53
Job Services
9 iceJob Serv s
Job Services consists of the following APIs:
ledJobs
♦ getScheduledJobState
ries
tJobFlexFiel
♦ changeJobAss
♦ getJobsCustomStatusEntries
erview
scheduled jobs in the Xora application. These jobs can be dispatched to the phone users identified by the userId. This API uses the userId to determine the job ass
However, each job created using this API, must have an external ID assigned to it. This ID is in the Xora server.
♦ createSchedu
♦ updateScheduledJobs
♦ cancelScheduledJobs
♦ getScheduledJobDetails
♦ getJobEnt
♦ ge dEntries
ignment
♦ getJobDetails
9.1 createScheduledJobs
9.1.1 Ov
This API is used to create
ignment.
used to relate the respective job
Note External IDs are unique for each created job.
cord will not be created in the Xora response.
ur system (external system) to the Xora server, you ing their
ted
When an external ID is considered as duplicate, the job reServer and the client will be notified about the error in the
The response of this Xora API is an array of Status objects; one status object for each scheduled job that was sent to the Xora server.
Scenario
If you want to create a list of 10 jobs from yocan use this API. Further, you can also dispatch these jobs to the phone users by usrespective userIds.
Ensure to give unique external IDs for these 10 jobs, which will be used to associate jobs creain the Xora server.
Confidential Xora API V 4.0 - Application Integration Guide Page 54
Job Services
9.1.2 Request Parameters
Parameter Name Data Type Mandatory Description
credential Complex Yes Credential object.
ructure used to submit the r’s login information. The customer
call.
A data stcustomemust submit this information for every API
scheduledJobs Array Yes Array of ScheduledJob. Each entry describes the properties of a job.
allOrNothing Boolean Yes If AllOrNothing value is True, then either all the jobs are created or none of them are created.
That means, if one error is encountered in any of the jobs then all the jobs sent in that particular request will be rejected.
The default value is False. This flag serves to control the transaction nature for this batch of jobs.
9.1.3 Response Parameters
Parameter Name Data Type Description
JobStatus Array Array of JobStatus.
9.1.4 Example
Let’s create scheduled jobs using the createScheduledJobs API. For illustration, let’s use the following sample data to create.
Property Name Sample Data
externalId 83788
jobNumber JN-123
jobDescription Pick-up goods
availableFrom 2007-10-30T23:17:48Z
availableTo 2007-10-31T23:17:48Z
scheduledStartTime
2007-10-30T23:17:48Z
estimatedEndTime 2007-10-31T23:17:48Z
Confidential Xora API V 4.0 - Application Integration Guide Page 55
Job Services
Property Name Sample Data
address1 12, 5th Avenue
address2 Boulevard Street
city Santa ruz C
state CA
postalCode 95064-1011
latitude 34.209
longitude -118.3254
contactName John thews Ma
contactPhone 8314830144
fieldName Goods Picked
fieldValues Yes, No, On the Way
isMandatory No
defaultValue Yes
isMultiSelect No
eventId 765
isAlwaysAvailable Yes
userId 2365
sendSms Yes
When this API is executed with the above-mentioned data, the JobStatus (externalId, statusCode,
9.1.5 Error Codes
statusMessage) is shown.
Error Codes 3500, 3501, 3502, 3504, 3000, 3001
9.1.6 Status Codes and Messages
Status Code Status Message
3000 ♦ AllOrNothing is true and the jobs have one or more errors. The first error occurred for the job n with externalId= xxxxxx . Error Message :
Confidential Xora API V 4.0 - Application Integration Guide Page 56
Job Services
Status Code Status Message
"message". No jobs were created."
♦ Invalid input. There is no job information for job n in the request.
♦ External id cannot be null.
♦ External Id should not contai
♦ Job number cannot be null.
♦ Job number should not contain more than 100 characters.
♦ Job ption ca e nu
♦ Job Description should not contain more than 200 characters.
♦ Av m can nul
♦ AvailableTo cannot be null.
♦ AvailableFrom cannot be in p
♦ AvailableTo should be after a
♦ StartTime cannot be null.
♦ StartTime should be after ava
♦ StartTime should be before availableTo date.
♦ Estimate End Time should be after startTime.
ot contain more than 100 characters.
Address2 should not contain more than 100 characters.
♦ City should not contain more than 50 characters.
♦ State should not contain more than 30 characters.
he User Id is null.
ial characters.
Cannot create job. User doesn't have data shuttle module
♦ The external ID is duplicate
♦ The job number ____ was already assigned to userId ____
n more than 100 characters.
Descri nnot b ll.
ailableFro not be l.
ast.
vailableFrom date.
ilableFrom.
♦ Address1 should n
♦
♦ Postal code should not contain more than 10 characters.
♦ T
♦ Invalid user id. User Id should contain only numbers without any space/spec
♦
3001 ♦ Job is created successfully.
9.1.7 Throttling R
♦ Frequency rule (15 minutes)
rror Coun
rm please refer Throttling Requirements
ules
♦ Job E t Rule (500 jobs)
For more info ation on throttling rules, in Appendix.
Confidential Xora API V 4.0 - Application Integration Guide Page 57
Job Services
9.1.8 Sample Java Code
Credential credential = new Credential();
credential.setAccountId(98575);
credential.setUsername("admin");
credential.setPassword("password");
boolean allOrNothing = false;
ScheduledJob[] sJobArray = new ScheduledJob[1];
ScheduledJob scheduledJob = new ScheduledJob();
scheduledJob.setExternalId("Ext-Id-1245");
scheduledJob.setJobNumber("JN-123");
scheduledJob.setJobDescription("Pick-up goods");
// jobStartDate, jobEndDate, scheduledStartTime are calendar instances
scheduledJob.setAvailableFrom(jobStartDate);
scheduledJob.setAvailableTo(jobEndDate);
scheduledJob.setScheduledStartTime(scheduledStartTime);
scheduledJob.setAddress1("12, 5th Avenue");
scheduledJob.setCity("Santa Cruz");
scheduledJob.setState("CA");
scheduledJob.setPostalCode("95064-1011");
scheduledJob.setContactName("John Mathews");
scheduledJob.setContactPhone("8314830144");
scheduledJob.setIsAlwaysAvailable(false);
scheduledJob.setSendSms(false);
scheduledJob.setUserId("23499");
FlexFieldDefinition[] flexFieldDefinitionsArr = new FlexFieldDefinition[1];
FlexFieldDefinition flexFieldDefinition = new FlexFieldDefinition();
flexFieldDefinition.setEventId("343567");
flexFieldDefinition.setFieldName("Goods Picked");
String[] fieldValues = {"Yes", "No", "On the way"};
flexFieldDefinition.setFieldValues(fieldValues);
// set true to make the field mandatory
flexFieldDefinition.setIsMandatory(false);
// set true to enable multiselct ooption
f inition.setIsMultiSelectlexFieldDef (false);
flex DefiField nitionsArr[0] = flexFieldDefinition;
scheduledJob.setFlexFieldDefinition(flexFieldDefinitionsArr);
Confidential Xora API V 4.0 - Application Integration Guide Page 58
Job Services
//set the scheduled job
sJobArray[0] = scheduledJob;
XoraClient30 xoraClient30 = new XoraClient30 ();
xoraClient30.setJobServiceURL("http://apps.xora.com/xoraapps/services/XoraTimeTrackJobServices40?wsdl");
JobStatus[] jobStatus = xoraClient30.createScheduledJobs(credential, sJobArray, allOrNothing);
9.2 updat
9.2.1 Overvie
This API is used anage reassignment of jobs.
This API allows y t are already created by CreateScheduledJobs call. You can now an update in Xora server by the external ID already associated while creating the scheduled job.
After you have identified the external ID, us
If the phone user has already performed that particustatus. If not, you
In addition, an SM bout the job assignment similar to the new Get Jobs in the phone and perform this job a
eScheduledJobs
w
to update scheduled jobs and to m
ou to update scheduled jobs tha identify the scheduled job that needs
e this API to update that particular job.
lar job, an error is raised in the returned can update the job accordingly.
S is sent to the new phone user (new assignee) a job assignments. This phone user can then do theccordingly.
Note JoY
9.2.2 Request
bs can be updated till the job end. ou cannot update externalId and userId.
Parameters
Parameter Name Data Type Mandatory Description
credential Complex Yes Credential object.
A data structure used to subcustomer’s login information. The customer
mit the
must submit this information for every API call.
Sch Job Array of ScheduledJobeduled Array Yes . Each entry describes the properties of a job.
9.2.3 Response Parameters
Parameter Name Data Type Description
JobStatus Array Array of JobStatus.
Confidential Xora API V 4.0 - Application Integration Guide Page 59
Job Services
9.2.4 Example
Let’s update scheduled jobs using the updateScheduledJobs API. For illustration, let’s use the following sample data to update.
Property Name Sample Data
externalId 83788
jobNumber JN-123
jobDescription Pick-up goods
availableFrom 2007-10-30T23:17:48Z
availableTo 2007-10-31T23:17:48Z
scheduledStartTim 2007-10-30T23:17:48Z e
estimatedEndTime 2007-10-31T23:17:48Z
address1 12, 7th Avenue
address2 Boulevard Street
city Santa Cruz
state CA
postalCode 95064-1011
latitude 34.209
longitude -118.3254
contactName John Mathews
contactPhone 8314830144
fieldName Goods Picked
fieldValues Yes, No
isMandatory No
defaultValue Yes
isMultiSelect No
eventId 765
isAlwaysAvailable Yes
Confidential Xora API V 4.0 - Application Integration Guide Page 60
Job Services
Property Name Sample Data
userId 2365
sendSms Yes
When this API is executed with the above-mentioned data, the JobStatus (externalId, statusCostatusMessage) is shown.
de,
500
9.2.5 Error Codes
Error Codes 3 , 3501, 3502, 3504
9.2.6 Throttling Rules
♦ Frequency rule (15 minutes)
♦ Job Error Count Rule(500 jobs)
For more information on throttling rules, please refer Throttling Requirements in Appendix.
9.2.7 Status Codes and Messages
Status Code Status Message
3000 ♦ AllOrNothing is true and the jobs have one or more errors. The first error nalId= xxxxxx . Error Message :
♦ Invalid input. There is no job information for job n in the request
ot be null
♦ External Id should not contain more than 100 characters.
♦ Job Description should not contain more than 200 characters.
♦ AvailableFrom cannot be null
♦ AvailableTo cannot be null
♦ AvailableFrom cannot be in pa
♦ AvailableTo should be after availableFrom date
♦ StartTime cannot be null
♦ StartTime should be after availableFrom
e before availableTo date
♦ Estimate End Time should be after startTime
Address1 should not contain more than 100 characters.
♦ Address2 should not contain more than 100 characters.
♦ City should not contain more than 50 characters.
occurred for the job n with exter"message". No jobs were created."
♦ External id cann
♦ Job Description cannot be null.
st
♦ StartTime should b
♦
Confidential Xora API V 4.0 - Application Integration Guide Page 61
Job Services
Status Code Status Message
♦ State should not contain more than 30 characters.
♦ Postal code should not contain more than 10 characters.
♦ Job for the given ExternalId does not exist
♦ Cannot update the job, the job is already completed.
♦ Cannot find the job
3001 ♦ Scheduled Job updated Successfully
9 Jav
Credential credential = new Credential();
.2.8 Sample a Code
credential.setAccountId(98575);
c eredential.setUs rname("admin");
credential.setPassword("password");
b hoolean allOrNot ing = false;
ScheduledJob[] sJobArray = new ScheduledJob[1];
ScheduledJob scheduledJob = new ScheduledJob();
scheduledJob.setExternalId("Ext-Id-1245");
scheduledJob.setJobNumber("JN-123");
scheduledJob.setJobDescription("Pick-up goods");
// jobStartDate, jobEndDate, scheduledStartTime are calendar instances
scheduledJob.setAvailableFrom(jobStartDate);
scheduledJob.setAvailableTo(jobEndDate);
scheduledJob.setScheduledStartTime(scheduledStartTime);
scheduledJob.setAddress1("12, 5th Avenue");
scheduledJob.setCity("Santa Cruz");
scheduledJob.setState("CA");
scheduledJob.setPostalCode("95064-1011");
scheduledJob.setContactName("John Mathews");
scheduledJob.setContactPhone("8314830144");
scheduledJob.setIsAlwaysAvailable(false);
scheduledJob.setSendSms(false);
scheduledJob.setUserId("23499");
FlexFieldDefinition[] flexFieldDefinitionsArr = new FlexFieldDefinition[1];
FlexFieldDefinition flexFieldDefinition = new FlexFieldDefinition();
flexFieldDefinition.setEventId("343567");
flexFieldDefinition.setFieldName("Goods Picked");
Confidential Xora API V 4.0 - Application Integration Guide Page 62
Job Services
String[] fieldValues = {"Yes", "No", "On the way"};
flexFieldDefinition.setFieldValues(fieldValues);
// set true to make the field mandatory
flexFieldDefinition.setIsMandatory(false);
// set true to enable multiselct ooption
flexFieldDefinition.setIsMultiSelect(false);
flexFieldDefinitionsArr[0] = flexFieldDefinition;
scheduledJob.setFlexFieldDefinition(flexFieldDefinitionsArr);
//s duet the sche led job
sJobArray[0] = scheduledJob;
XoraClient30 xoraClient30 = new XoraClient30 ();
xoraClient30.setJobServiceURL("http://apps.xora.com/xoraapps/services/XoraTimeTrackJobServices40?wsdl");
JobStatus[] jobStatus = xoraClient30.updateScheduledJobs(credential, sJobArray);
9.3 cancelScheduledJobs
9.3.1 Overview
This API is used to cancel a scheduled job created by the CreateScheduledJobs call. This API ident job
On cancellation, an S ned. This SMS is sent in the format ‘Job # <Job_NUM
Once the user do from the phone.
Scenario
After scheduling at this job need not be done or was not necessary, then use this API to cancel the job.
Using the respective external ID assigned
9.3.2 Request
ifies the to be cancelled using the external ID.
MS is sent to notify the user to whom the cancelled job was assigBER> is cancelled. Please do GetJobs’.
es the GetJobs function on the phone, the cancelled job is removed
and assigning a job, if you realize th
to this job, you can cancel the job.
Parameters
Parameter Name Data Type Mandatory Description
credential CredentialComplex Yes object.
ture used to submit the ogin information. The customer
information for every API
A data struccustomer’s lmust submit thiscall.
externalId nal Ids.
sed to identify a
Array of Yes List of Scheduled Job exterString External Id is a unique key u
job on Xora server. This key is unique per
Confidential Xora API V 4.0 - Application Integration Guide Page 63
Job Services
Parameter Name Data Type Mandatory Description
customer.
9.3.3 Response Parameters
Parameter Name Data Type Description
JobStatus Array of JobStatus Array .
9.3.4 mp
Let’s cancel some scheduled Jobs using the cancelScheduledJobs API. For illustration, let’s use el.
Exa le
the following sample data to canc
externalId
EXT-47678
EXT-47694
When this API is executed with the above-mentioned data, the JobStatus (externalId, statusCode, ion. statusMessage) is shown that indicates the status of the cancellat
9.3.5 Error Codes
Error Codes 3500, 3501, 3502, 3506
9.3.6 Status Codes and Messages
Status Code Status Message
3000 ♦ External Id cannot be null
♦ Job for the given ExternalId does not exist.
s already Cancelled
file for the user.
cellation.
♦ Job for the given ExternalId i
♦ Cannot find the pro
♦ Cannot find the Event Id for Job Can
♦ Unable to cancel the scheduled Job.
3001 ♦ Scheduled Job is cancelled Successfully
9.3.7 Throttling Rules
♦ Frequency rule (5 minutes – smaller frequency to enable for more canceling)
RequirementsFor more information on throttling rules, please refer Throttling in Appendix.
Confidential Xora API V 4.0 - Application Integration Guide Page 64
Job Services
9.3.8 Sample Java Code
Credential credential = new Credential();
credential.setAccountId(98575);
credential.setUsername("admin");
credential.setPassword("password");
String[] externalIDArray = {"Ext-345", "Ext-456","dt-446"};
XoraClient30 xoraClient30 = new XoraClient30 ();
xoraClient30.setJobServiceURL("http://apps.xora.com/xoraapps/services/XoraTimeTrackJobServices40?wsdl");
JobStatus[] jobStatus = xoraClient30.cancelScheduledJobs(credential, externalIDArray);
9.4 getScheduledJobDetails
ils.
t ount Id, User Name, and Password for you to create the list Projects.
hlighted in yellow color in this table will be implemented in the subsequent
9.4.1 Overview
This API is used to retrieve scheduled job deta
To use this API, you must first validate your login credentials. That means the Xora server musvalidate your Acc
9.4.2 Request Parameters
Parameters that are higreleases.
Parameter Name Data Type Mandatory Description
credential Complex Yes Credential object.
A data structure used to submit the customer’s login information. The customer must submit this information for every API call.
scheduledJobCriteria
Complex No ScheduledJobCriteria object with criteria to find scheduled jobs.
selectOptions Complex No SelectOptions object to specify search options.
9 rs.4.3 Response Paramete
Parameter Name Data Type Description
getScheduledJobDetailsReturn Array Array of ScheduledJobDetailsResponse object.
Confidential Xora API V 4.0 - Application Integration Guide Page 65
Job Services
9.4.4 Example
Let’s retrieve external job IDs using the getf
ScheduledJobIds API. For illustration, let’s use the ollowing sample data to retrieve.
Property Name Sample Data
teamIds 9848
userIds 675
jobIds 90
createdTimeRange 0-2001-1 07 00:00:00
modifiedTimeRange
01-10-2007 00:22:00
availableFromTimeRange
01-10-2007 00:00:00
availableToTimeRa 01-11-2007 00:00:00 nge
scheduledStaRange
rtTime 01-10-2007 00:00:00
estimatedEndTimeRange
01-11-2007 00:00:00
downloadTimeRange
01-10-2007 00:00:00
scheduledJobStatu Unassigned sCode
scheduledJobDescr Pick up iption
sche obCoctName
duledJ nta Maria Jones
scheduledJobCoctPhone
nta 8316654322
scheduledJobSmMessage
s Yes
scheduledJobAddress1
12, 5th Avenue
scheduledJobAddre Boss2
ulevard Street
Confidential Xora API V 4.0 - Application Integration Guide Page 66
Job Services
Property Name Sample Data
scheduledJobCity Santa Cruz
scheduledJobState CA
scheduledJobPosta 950641011 lCode
When this API is executed with the above-mentioned data, the respective scheduled job details are retrieved.
9.4.5 Error Codes
Error Codes 3502
9.4.6 Status Codes and Messages
ules
None
9.4.7 Throttling R
♦ Frequency Rule
9.4.8 Sample Java Code
Credential credential = new Credential();
credential.setAccountId(98575);
credential.setUsername("admin");
credential.setPassword("password");
XoraClient30 xoraClient30 = new XoraClient30 ();
ScheduledJobCriteria scheduledJobCriteria = new ScheduledJobCriteria();
// set the parameters
xoraClient30.setJobServiceURL("http://apps.xora.com/xoraapps/services/XoraTimeTrackJobServices40?wsdl");
ScheduledJobDetailsResponse[] scheduledJobDetailsResponse = xoraClient30.getScheduledJobDetails(credential, scheduledJobCriteria, null);
9.5 getScheduledJobState
9.5.1 Overview
ed jobs. That is, this API will query the status of a given job usage using the External ID.
Status of a scheduled job can be one of the following:
ssign ny u
This API retrieves the status of schedul
♦ Unassigned - Job is not a ed to a ser
Confidential Xora API V 4.0 - Application Integration Guide Page 67
Job Services
♦ b is assig but has not downlo hone
♦ Job Cancelled - Job is Cancelled
♦ Reassigned - Job is reassigned to some other user
ed - Job push failed
ownloaded by the user / job has been pushed to the phone
b Rejected - User rejecte job
ravel Start - Travel is start hown only for 3 event jobs
♦ Job Start - Job is started
Job End - Job is ended.
ernal
Job Assigned - Jo ned to User aded it to the p
♦ Job Push Fail
♦ Job Push Retry - Retrying to push the job
♦ Job Delivered - User has d
♦ Job Acknowledged - User has downloaded and accepted the job
♦ Job Auto Acknowledged - User has downloaded and accepted the job
♦ Jo d the
♦ T ed. S
♦
♦ Invalid - If ext Id is not found
Note jobs w2. “Jo
The locatio le only for Job Start and Job End states.
1. “Job Push Failed” indicates that the scheduled start time is already over. These ill ne t.
b Pus sh is failed but will be tried again after receiving the next AR record.
art fro d above “Custom job states” (defined by the will b ers.
S
Assume that you have scheduled a job and assigned it to a particular user. After some time, you realize that this job has not been done as your customer calls up to inform that the job is not d
Using the respective external ID assigned to this job, you can now use this Xora API to find out the job status. For example, if the Job Assigned”, then it is u hon ded this job for some reasons.
In such cases, you can prioritize this job and instruct your user offline to download this job i he necess
9.5.2 Request Parameters
n details will be availab
ver get pushed to clienh Retry” means job pu
3. Apuser)
m the states mentionee shown for the gold us
cenario
one.
status retrieved for this job is “e user has not downloanderstood that your p
mmediately and do t ary actions.
Parameter Name Data Type Mandatory Description
credential Comple Credentialx Yes object.
A data structure used to submit the customer’s login information. The customer must submit this information for every API call.
externalId Array of String
es List of Scheduled Job external Ids.
External Id is a unique key used to identify a
Y
job on Xora server. This key is unique per
Confidential Xora API V 4.0 - Application Integration Guide Page 68
Job Services
Parameter Name Data Type Mandatory Description
customer.
9.5.3 Response Parameters
Parameter Name Data Type Description
ScheduledJobState Array Array of scheduledJobState.
9.5.4 Example
Let’s retrieve the status of the scheduled jobs using the getScheduledJobState API. For illustration, let’s use the following sample data to retrieve.
externalID
EXT-47678
When this API is executed with the above-mentioned data, the status of the scheduled job changeTime, latitude, longitude, address1,
Codes
(jobState) along with other details (externalId, address2, city, state, postalCode) is retrieved.
9.5.5 Error
Error Codes 3500, 3501, 3502, 3506
9.5.6 Throttling Rules
♦ Frequency rule (15 minutes)
les, please refer Throttling Requirements in For more information on throttling ruAppendix.
Tip
Return status shows as invalid whentable.
the job does not have a state in the Xora Job
The status and the time should be returned to the client. (Note this time comes now from the ASSIGNMENT table- Xora API 2.0 needs to change as well)
9.5.7 Sample Java Code
Credential credential = new Credential();
credential.setAccountId(98575);
credential.setUsername("admin");
credential.setPassword("password");
DateTimeRange dateTimeRange = new DateTimeRange();
// fromDate, toDate are calendar instances
dateTimeRange.setFromDate(fromDate);
Confidential Xora API V 4.0 - Application Integration Guide Page 69
Job Services
dateTimeRange.setToDate(toDate);
String[] externalIDArray = {"Ext-345", "Ext-456","dt-446"};
XoraClient30 xoraClient30 = new XoraClient30 ();
xoraClient30.setJobServiceURL("http://apps.xora.com/xoraapps/services/XoraTimeTrackJobServices40?wsdl");
ScheduledJobState[] scheduledJobState = xoraClient30.getScheduledJobState(credential, externalIDArray);
9.6
9.6.1 Overview
This API is used to retrieve the jobs that were received by the Xora server during the specified time n
Sce r
Assume that there are 50 jobs available in the Xoare
To ie date and specific time information (For ex: 04-20-2007 09:00:00 to 04-20-2007 18:00:00). Thus the jobs created today for the specified time period
getJobEntries
ra ge.
na io
ra server created over a time period. But you interested only in jobs that were created today.
retr ve jobs that were created today, use this Xora API and provide today’s
will be retrieved to your system.
Note Jobs retrieved incl
ude scheduled jobs and client initiated jobs.
9.6.2 Request Parameters
Parameter Name Data Type Mandatory Description
credential Complex Yes Credential object.
A data structure used to submit the customer’s login information. The customer must submit this information for every API call.
dateTimeRange Complex Yes The date and time range for which the data is requested.
The DateTimeRange parameter is a data structure used to submit the date range for all the get calls. The fromDate value must be before the toDate value.
pageRequest Complex No PageRequest object.
9.6.3 Response Parameters
Parameter Name Data Type Description
Confidential Xora API V 4.0 - Application Integration Guide Page 70
Job Services
Parameter Name Data Type Description
getJobEntriesReturn plex EntrCom Job y40 object.
9.6.4 Example
Let’s retrieve job details using the getJobEntries API. For illustration, let’s use the following sample data to retrieve.
fromDate toDate
01-10-2007 00:00:00
01-11-2007 00:00:00
When this API is executed with the above-mentioned data, the details of the Jobs entered by the user using the phone application within the specified date range are retrieved.
9.6.5 Error
Error Codes 3500
Codes
, 3501, 3502, 3505
9.6.6 Throttling Rules
♦ Frequency rule (15 minutes)
♦ ge Sum Rule (48 hrs)
♦ Date Range Superset Rule (3 calls)
♦ ge Limit Rule (24 hrs)
Date Ran
Date Ran
For more information on throttling rules, please refer Throttling Requirements in Appendix.
9.6.7 Sample Java Code
Credential credential = new Credential();
cre Acdential.set countId(98575);
credential.setUsername("admin");
credential.setPassword("password");
DateTimeRange dateTimeRange = new DateTimeRange();
//fromDate, toDate are calendar instances
dateTimeRange.setFromDate(fromDate);
dateTimeRange.setToDate(toDate);
PageRequest pageRequest = new PageRequest();
pageRe stque .setPageNumber("2");
//set only if you have a new token
pageRequest.setToken("2l/rNf+D2+rR6qFvFgeR5spfslnqDA4Q");
XoraClient30 xoraClient30 = new XoraClient30 ();
Confidential Xora API V 4.0 - Application Integration Guide Page 71
Job Services
xoraClient30.setJobServiceURL("http://apps.xora.com/xoraapps/services/XoraTimeTrackJobServices40?wsdl");
JobEntry40 jobEntry = xoraClient30.getJobEntries(credential, dateTimeRange, pageRequest);
9.7 getJobFlexFieldEntries
9.7.1 Overview
This API is used to retrieve all the Job Flex Fields that were created in the Xora server during the
r a time period. provide the From date and To
ied time period, they will be retrieved to
specified time range.
Scenario
Assume that there are 10 Job Flex Fields available in the Xora server created oveTo retrieve list of all Job Flex Fields you can use this Xora API and date during which these Job Flex Fields are created. (For ex: 01-01-2007 09:00:00 to 01-31-200718:00:00).
If all 10 Job Flex Fields were created during this specifyour system.
9.7.2 Request Parameters
Parameter Name Data Type Mandatory Description
credential Complex Yes Credential object.
A data structure used to submit the customer’s login information. The customer must submit this information for every API call.
dateTimeRange Complex Yes The date and time range for which the data is requested.
The DateTimeRange parameter is a data structure used to submit the date range for all the get calls. The fromDate value must be before the toDate value.
pageRequest Complex No PageRequest object.
9.7.3 Response Parameters
Parameter Name Data Type Description
getJobFlexFieldEntriesReturn Complex JobFlexField40 object.
Confidential Xora API V 4.0 - Application Integration Guide Page 72
Job Services
9.7.4 Example
Let’s retrieve the details of Job FlexFields using the getJobFlexFieldEntries API. For illustration, let’s use the following sample data to retrieve.
fromDate toDate
01-10-2007 01-11-2007 00:0000:00:00 :00
When this API is executed with the above-mentioned data, the details of the Job FlexFields plication within the specified date range are retrieved.
9.7
00
entered by the user using the phone ap
.5 Error Codes
Error Codes 35 , 3501, 3502, 3505
9.7.6 Throttling Rules
♦ Frequency rule (15 minutes)
♦ Date Range Sum Rule (48 hrs)
♦ Date Range S ule (3 calls)
ang 24 hrs)
more in on throttling rules, please refer Throttling Requirements
uperset R
♦ Date R
For
e Limit Rule (
formation in Appendix.
l = new Credential();
9.7.7 Sample Java Code
Credential credentia
credential.setAccountId(98575);
cre Usdential.set ername("admin");
credential.setPassword("password");
DateTimeRange dateTimeRange = new DateTimeRange();
//fromDate, toDate are calendar instances
dateTimeRange.setFromDate(fromDate);
dat ieT meRange.setToDate(toDate);
PageRequest pageRequest = new PageRequest();
pageRequest.setPageNumber("2");
//set if you have token
pageRequest.setToken("2l/rNf+D2+rR6qFvFgeR5spfslnqDA4Q");
XoraClient30 xoraClient30 = new XoraClient30 ();
xoraClient30.setJobServiceURL("http://apps.xora.com/xoraapps/services/XoraTimeTrackJobServices40?wsdl");
Confidential Xora API V 4.0 - Application Integration Guide Page 73
Job Services
JobFlexField40 jobFlexfield = xoraClient30.getJobFlexFieldEntries(credential, dateTimeRange, pageRequest);
9.8 changeJobAssignment
9.8.1 Overview
Overview
This API is used to reassign the jobs. When the jobs are reassigned, this API returns theassignment status.
job
e same job to
Scenario
This API is only used when you want to reassign the job to any other user. That is, for some reason if a user (Assignee-1) is not able to do the assigned job, you can reassign thanother user (Assignee-2) using this API.
Note You cannot reassign a closed job (when the job status is Job End).
9.8.2 Request Parameters
Parameter Name Data Type Mandatory Description
credential Complex Yes Credential object.
call.
A data structure used to submit the customer’s login information. The customer must submit this information for every API
assignee Complex Yes Assignee object.
A data structure used to submit data for job reassignment.
9 rs.8.3 Response Paramete
Parameter Name Data Type Description
JobStatus Array Array of JobStatus.
9.8.4 Example
Let’s change the job assignment using the changeJobAssignment API.
For illustration, let’s use the following sample data to change the job assignment.
externalId userId
EXT-47678 178367
Confidential Xora API V 4.0 - Application Integration Guide Page 74
Job Services
When this API is executed with the above-mentioned data, the externalId now gets associated to the userId that is given (overriding the old assignee) and retrieves statusCode, statusMessage on the change in assignment.
9.8.5 Error Codes
Error Codes 3500
the externalId,
, 3501, 3502, 3504
9 ess.8.6 Status Codes and M ages
Status Code Status Message
3000 ♦ Cannot assign the job. No assignee information
♦ External Id is null
♦ User id cannot be null
♦ Invalid user id. User Id should contain only numbers without any space/special characters
♦ Cannot assign the job. Invalid user id
♦ Cannot assign the job. User doesn't have data shuttle module.
♦ Cannot reassign. Job is already finished
♦ Job does not exists
♦ Cannot find the event id for reassignment
♦ Job cannot be reassigned. Please try later.
3001 ♦ Job is reassigned successfully
9.8.7 Throttling Rules
♦ Frequency rule (15 minutes)
For more information on throttling rules, please refer Throttling Requirements in Appendix.
9.8.8 Sample Java Code
Credential credential = new Credential();
credential.setAccountId(98575);
credential.setUsername("admin");
credential.setPassword("password");
Assignee[] assigneeArr = new Assignee[1];
Assignee assignee = new Assignee();
assignee.setExternalId("EXT-47678");
assignee.setUserId("34545");
assigneeArr[0] = assignee;
Confidential Xora API V 4.0 - Application Integration Guide Page 75
Job Services
XoraClient30 xoraClient30 = new XoraClient30 ();
xoraClient30.setJobServiceURL("http://apps.xora.com/xoraapps/services/XoraTimeTrackJobServices40?wsdl");
JobStatus[] jobStatus = xoraClient30.changeJobAssignment(credential, assigneeArr);
Confidential Xora API V 4.0 - Application Integration Guide Page 76
Job Services
9.9 getJobDetails
9.9.1 Overview
ust first validate your login credentials. That means the Xora server must Id, User Name, and Password for you to create the list Projects.
highlighted in yellow color in this table will be implemented in the subsequent
This API is used to retrieve Job details.
To use this API, you mvalidate your Account
9.9.2 Request Parameters
Parameters that arereleases.
Parameter Name Data Type Mandatory Description
credential Complex Yes Credential object.
A data structure used to submit the customer
call.
customer’s login information. Themust submit this information for every API
jobCriteria Complex No JobCriteria object with project criteria to find projects.
selectOptions Complex No SelectOptions object to specify search options.
9.9.3 Response Parameters
Parameter Name Data Type Description
getJobDetailsReturn Array of Array JobDetailsResponse.
9.9.4 Example
getJobIds API. For illustration, let’s use the following sample data to retrieve. Let’s retrieve internal Job IDs using the
Property Name Sample Data
jobNumber 8392
teamIds 299
userIds 89
externalJobIds EXT98
jobStatusCodes Assigned
Confidential Xora API V 4.0 - Application Integration Guide Page 77
Job Services
Property Name Sample Data
travelStartTimeRange 01-10-2007 10:00:00
jobStartTimeRange 01-10-2007 20:00:00
jobEndTimeRange 01-10-2007 12:30:00
travelStartDbTimeRange 01-10-2007 10:00:00
jobStartDbTimeRange 01-10-2007 10:00:00
jobEndDbTimeRange 01-10-2007 12:35:00
When this API is executed with the above-mentioned data, the respective internal Job ID is retrieved.
9.9.5 Error C
Error Codes
odes
3502
9.9.6 Status Codes and Messages
None
9.9.7 Throttli
♦ Frequenc
ng Rules
y Rule
9.9.8 ple
new Credential();
Sam Java Code
Credential credential =
credential.setAccountId(98575);
credential.setUsername("admin");
credential.setPassword("password");
XoraClient30 xoraClient30 = new XoraClient30 ();
JobCriteria jobCriteria = new JobCriteria();
// set the parameters
xoraClient30.setJobServiceURL("http://apps.xora.com/xoraapps/services/XoraTimeTrackJobServices40?wsdl");
JobDetailsResponse[] jobDetailsResponse = xoraClient30.getJobDetails(credential, jobCriteria, null);
Confidential Xora API V 4.0 - Application Integration Guide Page 78
Job Services
9.10 getJobsCustomStatusEntries
9.10.1 Overview
This API is used to retrieve all the statuses history for the jobs during the specified date range.
That is, you can view the job history information starting from events Job Start to Job End that also includes the job status change made by the phone user.
This information mainly helps you to track your users on the jobs being performed by them.
For example, if there is a delay in completing the job, you can check the status history to find out the current status of the job. If the Job Flex Fields are assigned to the job status, and the phone user has selected the appropriate field value to indicate reason for the delay, then that information is also retrieved.
Note This API will return all the statuses history for the jobs - similar to the Status History section Job Order Report.
Scenario
If one of your phone users has started the job and has not completed the job, you can use this API to know the full history of events that were performed on this job.
For example, if Job Start event was performed and then the user changes the job status to Suspend, this API retrieves the status information from Job Start till Suspend.
Note Job statuses such as Suspend, Hold, Resume, Reject, and so on are defined in the web interface, where there could be a possibility of jobs not being performed due to some genuine reasons.
You can thus take immediate actions to sort out the issues by either reassigning the job, or canceling the job.
By providing the time range information, this API retrieves the history of events occurred for a particular job. In the above-mentioned scenario, the following job event history will be retrieved:
♦ Job Start
♦ Job Suspend
9.10.2 Request Parameters
Parameter Name Data Type Mandatory Description
credential Complex Yes Credential object.
A data structure used to submit the customer’s login information. The customer must submit this information for every API call.
dateTimeRange Complex Yes The date and time range for which the data is requested.
The DateTimeRange parameter is a data
Confidential Xora API V 4.0 - Application Integration Guide Page 79
Job Services
Parameter Name Data Type Mandatory Description
structure used to submit the date range for all the get calls. The fromDate value must be before the toDate value.
pageRequest Complex No PageRequest object.
9.10.3 Response Parameters
Parameter Name Data Type Description
getJobsCustomStatusEntriesReturn Complex CustomJobStatus40 object.
9.10.4 Example
Let’s retrieve the details of Job Custom Status entries using the getJobsCustomStatusEntries API. For illustration, let’s use the following sample data to retrieve.
fromDate toDate
01-10-2007 00:00:00 007 00 00 01-11-2 :00:
When this API is executed with the above-mentioned data, the event status history within the specified date range is retrieved.
9.10.5 Error Codes
Error Codes 3500, 3501, 3502, 3503, 3505
9.10.6 Status Codes and Messages
None
♦ Date Range Sum Rule (48 hrs)
♦ perset Rule (3 c
Range Limit Rule (24 hrs)
For more information on throttling rules, please refer Throttling Requirements
9.10.7 Throttling Rules
♦ Frequency rule (15 minutes)
Date Range Su alls)
♦ Date
in pendix.
9 ample Java Code
Credential credential = new Credential();
Ap
.10.8 S
c AccountId(98575);redential.set
credential.setUsername("admin");
Confidential Xora API V 4.0 - Application Integration Guide Page 80
Job Services
credential.setPassword("password");
DateTimeRange dateTimeRange = new DateTimeRange();
// fromDate, toDate are calendar instances
d FromDate(fateTimeRange.set romDate);
d tToDate(toDateTimeRange.se ate);
PageRequest pageRequest = new PageRequest();
p mber("ageRequest.setPageNu 2");
/ ave a ne/set only if you h w token
pageRequest.setToken("2l/rNf+D2+rR6qFvFgeR5spfslnqDA4Q");
XoraClient30 xoraClient30 = new XoraClient30 ();
xoraClient30.setJobServiceURL("http://apps.xora.com/xoraapps/services/XoraTimeTrackJobServices40?wsdl");
CustomJobStatus40 customeJobStatus = xoraClient30.getJobsCustomStatusEntries(credential, dateTimeRange, pageRequest);
Confidential Xora API V 4.0 - Application Integration Guide Page 81
Utility Services
10 Utility Services
Utility Services consists of the following APIs:
♦ isCredentialValid
♦ getMediaDetails
10.1 isCredentialValid
10.1.1 Overview
This API is used to validate customer login credentials such as Account Id, User Name, and e ta
from s
u
b entries.
Password. The Xora
login credentials must be validated in order to send or retrieve respective daerver. th
Scenario
If you want to get the list of job entries, you can use the getJobEntries API. To use this API, yomust first validate your login credentials. That means the Xora server must validate your Account Id, User Name, and Password for you to retrieve the list of jo
10.1.2 Request Parameters
Parameter Name Data Type Mandatory Description
credential CredentialComplex Yes object.
r must submit this information for every API
A data structure used to submit the customer’s login information. The custome
call.
10.1.3 Response Parameters
Name Data Type Description
True / False Boolean Returns True if the credential is valid.
Returns False if the credential is invalid.
10.1.4 Error Code
Error Codes 3500
s
, 3501, 3502
10.1.5 Status Codes and Messages
None
Confidential Xora API V 4.0 - Application Integration Guide Page 82
Utility Services
10.1.6 Throttling
None
10.1.7 Sample Java Code
C reden ew Cr ntia
Rules
redential c tial = n ede l();
credential.setAccountId(98575);
credential.setUsername("admin");
credential.setPassword("password");
XoraClient30 xoraClient30 = new XoraClient30 ();
xoraClient30.setUtilityServiceURL("http://apps.xora.com/xoraapps/services/XoraTimeTrackUtilityServices40?wsdl");
boolean validCredential = xoraClient30.isCredentialValid(credential);
Confidential Xora API V 4.0 - Application Integration Guide Page 83
Utility Services
10.2 getMediaDetails
10.2.1 Overview
This API is used to retrieve media URL through which the media object can be retrieved. The media URL can be retrieved using the media IDs.
Data in the Media URLs can be stored upto 90
job picture) in your local system
Note Thus, to avoid data loss, you
days only.
must store the corresponding media object (image / by executing the URL before 90 days.
aking a SOAP
ord for you to retrieve media details.
arameters that are highlighted in yellow color in this table will be implemented in the subsequent leases.
It is recommended to make a regular HTTP call to the MediaURL ra(WS) call.
ther than m
To use this API, you must first validate your login credentials. That means the Xora server must validate your Account Id, User Name, and Passw
10.2.2 Request Parameters
Pre
Name Data type Mandatory Description
credential Complex Yes Credential object.
A data structure used to submit the customer’s login information. The customer must submit this information for every API call.
mediaIds Array of String
Yes Array of Media ID.
selectOptions Complex No SelectOptions object to specify search options.
10.2.3 Response Parameters
Parameter Name Data Type Description
mediaDetailsResponse Array Array of MediaDetailsResponse object.
10.2.4 Example
Let’s retrieve media details using the getMediaDetails API. For illustration, let’s use the following sample data to retrieve.
mediaIds
7400
Confidential Xora API V 4.0 - Application Integration Guide Page 84
Utility Services
When this API is executed with the above-mentioned data, the details of the media identified by the given ID are retrieved.
10.2.5 Error Codes
Error Codes 3500, 3501, 3502, 3504
10.2.6 Status Codes and Messages
Status Code Status Message
3517 ♦ Media ID is NULL
3518 ♦ Invalid Media ID
3519 ♦ Invalid Media ID
10.2.7 Throttling Rules
♦ Frequency Rule
♦ Item Limit Rule (Limited to 15)
10.2.8 Sample Java Code
Credential credential = new Credential();
credential.setAccountId(98575);
credential.setUsername("admin");
credential.setPassword("password");
String[] mediaIds = {"4647","6356","4564"};
XoraClient30 xoraClient30 = new XoraClient30 ();
xoraClient30.setUtilityServiceURL("http://apps.xora.com/xoraapps/services/XoraTimeTrackUtilityServices40?wsdl");
Media sRespons DetailsResponses =Detail e[] media xoraClient30.getMediaDetails(credential, mediaIds, null);
Confidential Xora API V 4.0 - Application Integration Guide Page 85
Project APIs
11 Project APIs
For more information on Project APIs, please refer Xora API V 3.0 - API Guide for Projects.pdf
PIs and their details to execute APIs related to This document lists all the thirteen Project AProjects.
Confidential Xora API V 4.0 - Application Integration Guide Page 86
Appendix
Appendix
Request Parameters
Credential
e l must submit thThe cr dentia is a data structure used to submit the customer’s login information. The customer
is information for every Xora API call.
Property Name
Data Type Mandatory Description
accountId Integer Yes The customer id / account id.
username String Yes Login user name.
password String Yes Login user’s password.
userAgent String No The userAgent property is used to identify the calls ora Data Shutt . made by X le (XDS) client
Notet is not used for any
The userAgenprocessing instead just logged in the log file.
DateTimeRange
T eRange is a d re used
The date time format for fromDate and toDate must be in the following format:
-YYYY HH me in 2 r form
he DateTim ata structu to submit the time range for all the get calls.
MM-DD :MM:SS (ti 4 hou at)
Note The fromDate value must be before the toDate value.
Property Name Data Type Mandatory Description
fromDate Calendar Yes The date from when the data is requested.
toDate Calendar Yes The date till when the data is requested.
Confidential Xora API V 4.0 - Application Integration Guide Page 87
Appendix
ScheduledJob
The ScheduledJob is a data structure to submit information of scheduled jobs.
Property Name Data Type Mandatory Description
externalId String Yes (max of A unique key used to identify a job on Xora server. This key is unique per customer. 100 chars)
jobNumber String Job number is considered only
eduledJob.
this in chedul
edJob call. Max 100 Chars
y a job from users point of n integer or combination of
integer, alphabets, and special characters. for CreateSch
We are not updatingupdateS
A number to identifview. This can be a
job sion
Yes (max 200 )
Description of a job. De cript String chars
availableFrom
Calendar Yes The time from when the job is available for download (Start date).
availableTo Calendar Yes The time till the job is available (Expiry date).
scheduledStartTime
Calendar Yes Start time of the job.
estimatedEndTime
Calendar No An estimatemust be afte
d End time of the job. This time r “scheduledStartTime”.
address1 String No (Max 100 chars)
Location / address information where the job is available.
address2 String No (Max 100 chars)
More address information.
city String No (Max 50 chars)
City Name.
state String No (Max 30 chars)
State Name.
postalCode String No (Max 10 chars)
Postal code.
latitude Double No Latitude value.
Reserved for future use.
Confidential Xora API V 4.0 - Application Integration Guide Page 88
Appendix
Property Name Data Type Mandatory Description
longitude Double No Longitude value.
call. Reserved for future use.
contactName
String No The contact name for further job information.
contactPhone
String No The contact phone number for further job information.
flexFieldDefinition
FlexFieldDefinition
No (only considered for
gold users)
The Flex Fields are considered only while creating the job for a TT Gold user.
Also, Xora API checks whether a valid event is available for the given event id otherwise it ignores those Flex Fields.
For a non-gold user we are not inserting any Flex Fields. Only the Flex Fields defined in the profile are applicable for them.
isAlwaysAvailable
Boolean No To mention whether a job is One time Or always available. If true then the job is considered as Always available otherwise considered as One time job.
userId String Yes A unique number that is used to identify a user on Xora server.
Give the value “-1” for this field to create unassigned jobs.
sendSms Boolean No If set to true, an sms will be sent to the user.
FlexFieldDefinition
A data structure used to submit the Flex Field definitions for scheduled jobs.
Property Name
Data Type
Mandatory (Y/N) Description
fieldName String Yes The name of the Flex Field.
fieldValues String Array
No The possible field values for the Flex Field.
isMandatory Boolean Yes (True/False. Default is false)
Whether this flex field is mandatory or not.
defaultValue String No This value will be selected by default.
Confidential Xora API V 4.0 - Application Integration Guide Page 89
Appendix
Property Name
Data Type
Mandatory (Y/N) Description
isMultiSelect Boolean Yes (True/False)
Whether multiple values can be selected for this Flex Field or not.
eventId String Yes This is a unique number to identify an event on Xora server. Also called Xora API ID.
You can find the Xora API ID on View Profile
ert dynamic Flex Fields.
Refer Event ID / Xora API ID Illustration
page under Job Status section. This ID is used to ins
section in Appendix for illustration.
NoteThis ID is while crea
considered only ting the job for a TT
Gold user.
Assignee
A ure us bmit da r job data struct ed to su ta fo reassignment.
Property Name Data Type Mandatory
(Y/N) Description
externalId String Yes A unique key used to identify a job on Xora server. This key is unique per customer.
userId String Yes A unique number that is used to identify a user on Xora server.
Scope
A data structure used to specify the scope of a landmark.
Property Name Data Type Mandatory Description
global Boolean Yes (If True TeamName
ignored)
If True then global landmark will be created.
Only Admin user can create global landmarks, will be
teamName String Yes (if above is
) This property must be used only “global” property value is False.
false
The name of the team for which the landmark has to be created.
Confidential Xora API V 4.0 - Application Integration Guide Page 90
Appendix
Landmark
A data structure used to define the properties of a landmark.
Property Name Data Type Mandatory Description
landmarkName
The landmark name. This is unique per customer. String Yes
address1 String
Either Error will be flagged if both of them are missing. If both are present Lat/Long takes precedence.
No
address or latitude/
A
longitude is mandatory.
ddress of the landmark.
address2 String address. No More
city String City Name. No
state String SNo tate Name.
postalCode PString No ostal code.
latitude String No
Either address or
latitude/ longitude is mandatory.
La
Error will be flagged if both of them are missing. If both are present Lat/Long takes precedence.
titude value.
longitude String No
latitude/ longitude is
Lo
Error will be flagged if both of them are missing. If bo
Either address or
mandatory.
ngitude value.
th are present Lat/Long takes precedence.
zoomLevel String Default is 10
Zoom level at which landmark should start appearing.
distance Integer Yes Radius around the landmark within which if a user is present, landmark becomes visible.
iconIdentifier String Yes The icon to
String Identifier indicating the icon that needs to be used.
be associated with this landmark.
showNameOnMap
Yes If True then landmark name is shown on map.
If False then landmark name is not shown on map.
Boolean
Confidential Xora API V 4.0 - Application Integration Guide Page 91
Appendix
UserMapInfo
A data structure used to submit user information for highlighting user on map.
Property Name Data Type Mandatory Description
appliesTo String S er of the following maps:
♦
♦ rt
♦
Yes pecifies whether the information applies to eith
Single User
All user repo
Bread crumb map
textColor TString No he color of text on map.
background String No The background color.
appendText String No The text to be appended to map.
userId String Yes Ase
T
unique number used to identify a user on Xora rver.
he appended information is assigned to this user.
ScheduledJobCriteria
Parameters that are highlighted in yellow color in this table will be implemented in the subsequent releases.
Property Name Data Type Mandatory Description
teamIds Array of Integer
Used to search for scheduled jobs for a given team or teams.
No Array of team ids.
groupIds Array of Integer
No Array of group ids.
Used to search for scheduled jobs for a given group or groups.
userIds Array oInteger
f
No
Used to search for scheduled jobs for a given
Array of user ids.
user or users.
recurringJobIds
Array of Integer
No Array of recurring job ids.
Used to search for scheduled jobs belonging to any given set of recurring jobs.
jobIds Array oInteger
f
No
Used to search for scheduled
Array of job ids.
jobs containing
Confidential Xora API V 4.0 - Application Integration Guide Page 92
Appendix
Property Name Data Type Mandatory Description
any given job ids.
createdTime Complex DateTimeRRange
ange
No Creation date/time range to search for.
Used to find scheduled jobs created within a given time range.
modifiedTimeRange
Complex DateTimeR
ange
No
t modified within
Last modified date/time range to search for.
Used to find scheduled jobs lasa given time range.
availableFromTimeRange
Complex DateTimeR
ange
No
Used to find scheduled jobs with an Available From tim a
Available From date/time range to search for.
e with given time range.
availableToTi Complex DateTimeR
ange
No vailable To date/time range to search for.
Used to find scheduled jobs with an Available to time with a given time range.
AmeRange
scheduledStartTimeRange
Complex DateTimeR
ange
No Scheduled Start Time date/time range to search for.
Used to find scheduled jobs with a scheduled start time with a given time range.
estimatedEndnge
Complex DateTimeRTimeRa
ange
No
duled jobs with an estimated end time with a given time range.
Estimated End Time date/time range to search for.
Used to find sche
downloadTim Complex eRange DateTimeR
ange
No Download time date/time range to search for.
d scheduled jobs downloaded within a given time range. Used to fin
scheduledJobStatusCode
Scheduled job status code to search for. String No
Used to find scheduled jobs with any given status.
scheduledJobDescription
String Scheduled job description to search for.
Used to find scheduled jobs with any given
No
description.
scheduledJobContactName
String
heduled jobs with any given contact name.
No Scheduled job contact name to search for.
Used to find sc
scheduledJobContactPhone
String No Scheduled job contact phone to search for.
Used to find scheduled jobs with any given
Confidential Xora API V 4.0 - Application Integration Guide Page 93
Appendix
Property Name Data Type Mandatory Description
e contact phone.
scheduledJobSmsMessage
Scheduled job SMS message to search for. String No
Used to find scheduled jobs with any given SMS message.
scheduledJobAddress1
String No Scheduled job address1 to search for.
Used to find scheduled jobs with any given address1.
scheduledJobAddress2
String Scheduled job address2 to search for.
Used to find scheduled jobs with any given address2.
No
scheduledJob String No Scheduled job city to search for.
d scheduled jobs with any given city. City Used to fin
scheduledJob ob state to search for.
scheduled jobs with any given State String No Scheduled j
Used to findstate.
scheduledJobPostalCode
postal code.
String No Scheduled job postal code to search for.
Used to find scheduled jobs with any given
scheduledJobLandmarkIds
Array of String
No Array of landmark ids to search for.
Used to find scheduled jobs containing any given landmarks.
creationAgents
Array of String
No Array of user agent STRINGS to search for.
Used to find scheduled jobs created by any given user agents. (This comes from the credential)
SelectOptions
P that are ted in y coloreleases.
arameters highligh ellow r in this table will be implemented in the subsequent
Property Name
Data Type Mandatory Description
order String No Sets the order of the returned array.
ASC [default]DESC (keyed on ID)
limit Integer No Limits the number or rows selected.
Confidential Xora API V 4.0 - Application Integration Guide Page 94
Appendix
Property Name
Data Type Mandatory Description
Equivalent to ROWNUM <= limit
searchMode String No Sets how search matches are found.
EXACT [default] Only exact matches are returned (case sensitive).
PARTIAL Partial matches are returned (not case sensitive). This parameter applies to:StringsNumbers (int, double, float, etc)
Does NOT apply (is always exact) to: Booleansarrays (and array values)datesdate ranges.
JobCriteria
P t are hted in y colo in the subsequent releases.
arameters tha highlig ellow r in this table will be implemented
Property Name Data Type Mandatory Description
jobNumber String No Exact job number to search for.
Used to find the job or jobs with a given job number.
teamIds Array of No Array of team ids.
Used to search for jobs for a given team or teams.
Integer
groupIds Array of Integer
No Array of group ids.
Used to search for jobs for a given group or groups.
userIds Array of Integer
No Array of user ids.
Used to search for jobs for a given user or users.
recurringJobIds
Array of Integer
No Array of recurring job ids.
Used to search for jobs belonging to any given set of recurring jobs.
externalJobIds
Array of String
No Array of scheduled job ids.
Used to search for jobs belonging to any given scheduled (assigned/dispatched) job.
jobStatusCodes
Array of String
No Array of job status codes to search for.
Used to find jobs with any given statuses.(e.g. find jobs that are either downloaded or assigned,
Confidential Xora API V 4.0 - Application Integration Guide Page 95
Appendix
Property Name Data Type Mandatory Description
but not started)
travelStartTimeRange
r.
Complex: Date range
No Travel start date/time range to search fo
Used to find jobs whose travel start time is in agiven time range.
jobStartTimeRange
Complex
DateTimeRange
No Job start date/time range to search for.
Used to find jobs whose job start time is in a given time range.
jobEndTimeRange
Complex
DateTimeRange
No Job end date/time range to search for.
Used to find jobs whose job end time is in a given time range.
travelStartDbTimeRange
Complex
DateTimeRange
No DB Travel start date/time range to search for.
Used to find jobs whose travel start DB time is in a given time range.
jobStartDbTimeRange
Complex DateTime
No DB Job start date/time range to search for.
Used to find jobs whose job start DB time is in a given time range. Range
jobEndDbTim Complex eRange DateTime
Range
No DB Job end date/time range to search for.
time range. Used to find jobs whose job end DB time is in a given
LatestLocationDetailCriteria
Property Name Data Type Mandatory Description
asOfEventTime
DateTime N A t record before or equal to this eventTime specified. If no value (null) is specified, then the currentTime is taken as the input.
o s of Event Time. The API fetches the lates
fieldList AString
N An array of the fields that the user wants to be re
rray of o trieved.
numberOfLoc String No The number of locations before the eventTime.
For example: If the number was 5, then the last 5 lo
Maximum of 10 locations can be retrieved.
ations
cations would be fetched. Default is 1.
userId AString
N Array of userIds for which the location records m
rray of o ust be retrieved.
Confidential Xora API V 4.0 - Application Integration Guide Page 96
Appendix
PageRequest
Property Name Data Type Mandatory Description
pageNumber String No Page number.
token String No Token is a unique key that identifies a set of data on the server.
UserCriteria
Property Name Da e ta Typ Mandatory Description
active Boolean No If True, the user is active. If False, the user is inactive.
employeeNumber
String No Employee number of the user.
externalUserId
String N Uo ser ID (external)
firstName String No First name of the user.
lastName String No Last name of the user.
phoneNumber String No Phone number of the user.
shiftType String N T works. o he name of the shift in which the user
timeZone String No Time zone name in which the user works.
userId String N To he userId for which the data is retrieved.
userType String No T ort Admin – Team Lead, Customer, and so on.
he type of the user. For example: Admin, Rep
InsertOptions
Property Name Data Type Mandatory Description
ba SINGLE: [default] ems that throw errors, accepts the rest.BATCH:
em throws an
tchMode String No Only rejects it
The entire batch is rejected if any iterror.
limit Integer No Limits the number of items to be inserted. Throws an error if more items are supplied. Used for error
Confidential Xora API V 4.0 - Application Integration Guide Page 97
Appendix
Property Name Data Type Mandatory Description
control and throttles.
writerMode String No verwrites
nds new values to the end of the ,
the beginning types, of
ded.
OVERWRITE: [default] Clears and oexisting fields with new values.
APPEND: Appeexisting values. Certain incompatible data typessuch as Boolean, will be overwritten instead of appended.
PREPEND: Prepends new values toof existing values. Certain incompatible datasuch as Boolean, will be overwritten insteadprepen
UserPassword
Property Name Data Type Mandatory Description
loginPassword
Any password string, but not null. String No
userID Integer No User ID.
UpdateOptions
Property Name Data Type Mandatory Description
batchMode No S y rejects items that throw e
The entire batch is rejected if any item throws an error.
String INGLE: [default] Onlrrors, accepts the rest.BATCH:
limit No Lac
Integer imits the number of items to be inserted. Throws n error if more items are supplied. Used for error ontrol and throttles.
writerMode No Oexisting fields with new values.
APPEND: Appends new values to the end of the existing values. Certain incompatible data types, sa
PREPEND: Prepends new values to the beginning of existing values. Certain incompatible data types, sp
String VERWRITE: [default] Clears and overwrites
uch as Boolean, will be overwritten instead of ppended.
uch as Boolean, will be overwritten instead of repended.
Confidential Xora API V 4.0 - Application Integration Guide Page 98
Appendix
DeleteOptions
Property Name Data Type Mandatory Description
batchMode String No S w e
The entire batch is rejected if any item throws an error.
INGLE: [default] Only rejects items that throrrors, accepts the rest.BATCH:
limit Integer No L s an error if more items are supplied. Used for error control and throttles.
imits the number of items to be inserted. Throw
writerMode No Oe
APPEND: Appends new values to the end of the existing values. Certain incompatible data types, such as Boolean, will be overwritten instead of a
PREPEND: Prepends new values to the beginning of existing values. Certain incompatible data types, such as Boolean, will be overwritten instead of p
String VERWRITE: [default] Clears and overwrites xisting fields with new values.
ppended.
repended.
Team
Property Name D e ata Typ Mandatory Description
geofenceIds Integer No Geofence IDs to be attached to the Team.
lan Landmark IDs to be attached to the Team. dmarkIds Integer No
profileId Integer No Profile ID to be attached to the Team
smartJobZones
Integer No Smart Job Zones to be attached to the Team
status Complex No Status object.
teamId Integer No Team ID.
teamLeadId Integer No Team Lead ID to be attached to the Team.
teamName String No Team Name.
userId Integer No User ID to be attached to the Team.
Confidential Xora API V 4.0 - Application Integration Guide Page 99
Appendix
TeamSelectionCriteria
Property Name Data Type Mandatory Description
profileId Integer No Profiel ID.
teamId Integer No Team ID.
teamLeadId Integer No Team Lead ID.
teamName String No Team Name.
us User ID. erId Integer No
UserInfo
A data structure used to return the user information.
Property Name Data Type Description
userId String ique tify a user on Xora server. A un number used to iden
phoneNumber String Phone number of the user.
employeeNumber String Employee number of the user.
firstName String First name of the user.
lastName String Last name of the user.
timeZone String Time zone name in which the user works.
shiftType String The name of the shift in which the user works.
userType String The type of the user. For example: Admin, Report Admin – Team Lead, Customer, and so on.
isActive Boolean If True, the user is active. If False, the user is inactive.
gmtOffsetMinutes Integer Difference between the users time zone and the GMT time zone.
tea r r’s team. It is a unique number on Xora sever which identifies a team.
mId Intege Id of use
loginUserId String Login user ID.
Confidential Xora API V 4.0 - Application Integration Guide Page 100
Appendix
Response Parameters
UserStatus
U a data re used turn tserStatus is structu to re he results of updateUser API.
Property Name Data Type Description
externalUserId String External user ID.
statusCode String Response code from server.
statusMessage String Status message from the server.
userId String The userId for which the data is updated.
JobStatus
JobStatus is an acknowledgement sent from the Xora server for create / update job request made by er. the custom
Property Name Data Type Description
externalId String A unique key used to identify a job on Xora server. This key ique er. is un per custom
statusCode String A predefined number to denote the status of a job.
statusMessage String Status message from the server.
Job
A data structure used to return the i ation
Entry
nform of job entries.
Property Name Data Type Description
externalId String A unique key used to identify a job on Xora server. This key is unique per customer.
jobNumber String Job number of the job.
internalJobId String A uniXora
que number, which is used to identify a job on server.
jobStartTime Calendar The time at which the job was started.
jobEndTime Calendar The time at which the job was ended.
travelStartTime Calendar The time at which the travel was started.
travelStartComment String The c art even
omment entered by the user during the travel stt.
Confidential Xora API V 4.0 - Application Integration Guide Page 101
Appendix
Property Name Data Type Description
tra ck tr ique number on Xora sever which identifies the lat / f the place from whe as started.
velStartTra ingId S ing A unlon o re the travel w
jobStartComment String The ceven
omment entered by the user during the job start t.
jobStartTrackingId String A unique number on lon of the place where the job was started.
Xora sever which identifies the lat /
jobEndComment String The ceven
omment entered by the user during the job end t.
jobEndTrackingId String A uni lat / lon of the place where the job was ended.
que number on Xora sever which identifies the
travelStartAddress1 String Address 1 of the place where the travel was started.
travelStartAddress2 String Address 2 of the place where the travel was started.
travelStartCity String The name of the city from where the travel was started.
travelStartState String The n . ame of the State in which the travel was started
travelStartPostalCode String Postal code of the place where the travel was started.
jobStartAddress1 String Address 1 of the place where the job was started.
jo ess tr ress 2 of the place where the job was started. bStartAddr 2 S ing Add
jobStartCity String The name of the city in which the job was started.
jobStartState String The name of the state in which the job was started.
jobStartPostalCode String Postal code of the place where the job was started.
jobEndAddress1 String Address 1 of the place where the job was ended.
jobEndAddress2 String Address 2 of the place where the job was ended.
jobEndCity String The n in which the job was ended. ame of the city
jobEndState String The name of the state in which the job was ended.
jobEndPostalCode String Posta . l code of the place where the job was ended
jobTraveledMiles String The total distance covered during the job.
lunchStartTime ateTim The tD e ime at which lunch was started.
lunchStartTrackingId String A unique number on Xora sever which identifies the lat / lon of the place at which the lunch start event was
Confidential Xora API V 4.0 - Application Integration Guide Page 102
Appendix
Property Name Data Type Description
happened.
lunchStartAddress1 String Address 1 of the place where the lunch was started.
lunchStartAddress2 String Address 2 of the place where the lunch was started.
lunchStartCity String The name of the city in which the lunch was started.
lunchStartState String The name of the city in which the lunch was started.
lunchStartPostalCode String Postal code of the place where the lunch was started.
lunchEndTime DateTime The time at which lunch was ended.
lunchEndTrackingId String A unique number on Xora sever which identifies the lat / lon of the place at which the lunch end event was happened.
lunchEndAddress1 Address 1 of the place where the lunch was ended. String
lunchEndAddress2 ing Str Address 2 of the place where the lunch was ended.
lunchEndCity String which the lunch was ended. The name of the city in
lunchEndState String ich the lunch was ended. The name of the state in wh
lunchEndPostalCode ing lace where the lunch was ended. Str Postal code of the p
teamsId String is a unique number on Xora sever which identifies a team. Id of user’s team. It
teamName String The name of user’s team.
userId String A unique number that is used to identify a user on Xora server.
S edJobSta
A d to e s
chedul te
data structure use return th tates of scheduled jobs.
Property Name Data Type Description
externalId mer.
String A unique key used to identify a job on Xora server. This key is unique per custo
jobState String Specifies the state of a job
changeTime DateTime The time at which the state was changed.
latitude String Latitude of the place at which the event occurred.
Confidential Xora API V 4.0 - Application Integration Guide Page 103
Appendix
Property Name Data Type Description
longitude String Longitude of the place at which the event occurred.
address1 String Address1 of the place at which the event occurred.
a Address2 of the place at which the event occurred. ddress2 String
city String The name of the city in which event has occurred.
state String The name of the state in which event has occurred.
postalCode String Postal code of the place at which the event occurred.
LocationEntry
e used to return the location entry details. A data structur
Property Name Data Type Description
trackingId String A unique number on Xora sever which identifies a tracking record.
latitude String Latitude
longitude String Longitude
speed Float Speed
direction Float Direction
eventType String Event type.
eventDetail String Event details.
ev Dat e time at which the event has occurred. entTime eTime Th
dbTime DateT Theime time at which the event was record on Xora server.
address1 Strin Add hich the event has occurred. g ress1 of the location at w
address2 Strin Add . g ress2 of the location at which the event has occurred
city String The name of the city in which the event has occurred.
state St e s occurred. ring Th name of the state in which the event ha
postalCode St os nt has occurred. ring P tal code of the location at which the eve
isCellSiteLocation Boo tr ions. lean Is ue if the tracking records are cell site locat
altitude Flo Theat height of the place.
Confidential Xora API V 4.0 - Application Integration Guide Page 104
Appendix
Property Name Data Type Description
odometer Flo Theat odometer readings during the event.
accuracy Float Accuracy of the location.
userId String A unique number that is used to identify a user on Xora server.
eventHistoryId String A un t on Xora server.
ique number that is used to identify an even
TimeEntry
A d to retu me data structure use rn the ti entry details.
Property Name Data Type Description
internalTimesId String A unique number that is used to identify a shift evenuniquely on Xora server.
t
userId String A unique number that is used to identify a user on Xora server.
shiftStartTime DateTime The time at which shift was started.
shiftEndTime DateTime The time at which shift was ended.
shiftStartTrackingId he as
String A unique number on Xora sever which identifies tlat / lon of the place at which the shift start event whappened.
shiftEndTrackingId String A unique number on Xora sever which identifies the lat / lon of the place at which the shift end event was happened.
lunchStartTime DateTime The time at which lunch was started.
lunchEndTime DateTime The time at which lunch was ended.
lunchStartTrackingId String A unique number on Xora sever which identifies the lat / lon of the place at which the lunch start event was happened.
lunchEndTrackingId String A unique number on Xora sever which identifies the as
happened. lat / lon of the place at which the lunch end event w
regularTime Float The total regular work hours.
overTime Float The over time hours.
Confidential Xora API V 4.0 - Application Integration Guide Page 105
Appendix
Property Name Data Type Description
doubleTime Float hours after over time. The extra
currentShiftType String Latest shift event.
lunchStartAddress1 String Address 1 of the place where the lunch was started.
lunchStartAddress2 String Address 2 of the place where the lunch was started.
lunchStartCity String The name of the city in which the lunch was started.
lunchStartState String The name of the state in which the lunch was started.
lunchStartPostalCode lunch was ended. String Postal code of the place where the
lunchEndAddress1 String Address 1 of the place where the lunch was ended.
lunchEndAddress2 String of the place where the lunch was ended. Address 2
lunchEndCity String The name of the city in which the lunch was ended.
lunchEndState String The name of the state in which the lunch was ended.
lunchEndPostalCode ed. String Postal code of the place where the lunch was end
shiftStartAddress1 String Address 1 of the place where the shift was started.
shiftStartAddress2 String Address 2 of the place where the shift was started.
shiftStartCity String The name of the city in which the shift was started.
shiftStartState which the shift was started. String The name of the state in
shiftStartPostalCode String Postal code of the place where the shift was started.
shiftEndAddress1 String the place where the shift was ended. Address 1 of
shiftEndAddress2 String Address 2 of the place where the shift was ended.
shiftEndCity String The name of the city in which the shift was ended.
s g The name of the hiftEndState Strin city in which the shift was ended.
shiftEndPostalCode ringSt Postal code of the place where the shift was ended.
totalJobs String Total number of jobs.
totalJobTime String The total work hours.
totalTravelTime String The travel time from travel start till job start.
Confidential Xora API V 4.0 - Application Integration Guide Page 106
Appendix
Property Name Data Type Description
totalJobTraveledMiles ring t till job start.
St It is the actual distance traveled from travel sta
milesTraveled String It is the straight-line distance traveled from travel stat till job start.
teamsId ring ra sever which identifies a team.
St Id of user’s team. It is a unique number on Xo
teamName String The name of user’s team.
GeofenceActivity
d to return the geofence activity details. A data structure use
Property Name Data Type Description
geofenceId String A unique number that is used to identify a geofence activity on Xora server.
geofenceName String The name of the geofence.
activityTime DateTime The time at which the event occurred.
activity String Name of the activity.
address1 String Address1 of the location at which the event has rred. occu
address2 String s2 of the location at which the event has occurred.
Addres
city String The name of the city in which the event has occurred.
state String The name of the state in which the event has occurred.
postalCode tringS Postal code of the location at which the event has occurred.
violationDuration String The total time during which the rules are violated.
activityDescription String The description of the activity.
distanceFromGeofence Double The distance between the geofence and location at which the event occurred.
userId String ra A unique number used to identify a user on Xoserver.
Confidential Xora API V 4.0 - Application Integration Guide Page 107
Appendix
LandmarkStatus
A data structure used to return the results of createLandmarks Xora API.
Property Name Da ta Type Description
landmarkName String The landmark name.
code String se code from server. Respon
message String Response message from the server.
HighlightUserStatus
ser Xora API. A data structure used to return the results of highlightU
Property Name Data Type Description
identifier Strin he ug T serId for which the data is updated.
code String Response code from server.
message Strin espog R nse message from server.
CustomJobState
A used to ret sta data structure urn the job tus history.
Property Name Data Type Description
eventId String This is a unique number to identify an event on Xora server.
his i y ora
You can find the Xora API ID on View Profile page under Job Status section. This ID is also used to insert dynamic
x F
TX
s also called as Xora API ID. This ID is represented bAPI IDs in web interface.
Fle ields.
Refer Event ID / Xora API ID Illustration section in Appendix stration. for illu
Note This ID is considered only while creating the job for a TT Gold user.
eventName Strin he n . g T ame of the event for which the Flex Fields are defined
externalId String A unique key used to identify a job on Xora server. This key is unique per customer.
status String The status of the job.
eventTime DateTime Time at which the status was changed.
Confidential Xora API V 4.0 - Application Integration Guide Page 108
Appendix
Property Name Data Type Description
trackingId String uniq identifies the lat / lon of the place where the event was occurred. Foreign key to he tra
A ue number on Xora sever which
t cking table.
address1 Strin ocatg L ion / address information where the job is available.
address 2 Strin ore g M address information.
city Strin ity dg C etails.
state Strin tate g S details.
postalCode Strin ostag P l code details.
eventHistoryId Strin uniqg A ue key to identify occurrence of an event.
J
A data structure used to return the details
obFlexField
of Flex Fields defined for job.
Property Name Data Type Description
externalId Strin uniqg A ue key used to identify a job on Xora server. This key is unique per customer.
internalJobId String A unique number used to identify a job on Xora server.
eventId String
o c
ou cJob Status section. This ID is also used to insert dynamic
lex F
This is a unique number to identify an event on Xora Server.
Als alled Xora API ID.
Y an find the Xora API ID on View Profile page under
F ields.
Refer Event ID / Xora API ID Illustration section in Appendstration.
ix or illuf
Note This ID is considered only while creatingthe job for a TT Gold user.
eventName Strin he n ed. g T ame of the event for which the Flex Fields are defin
fieldName Strin he Fg T lex Field name
fieldValue String The Flex Field value – Provision for multiple values
eventHistoryId Strin uniq rrence of an event. g A ue key to identify occu
ShiftFlexField
A data structure used to return the details of Flex Fields defined for shift.
Confidential Xora API V 4.0 - Application Integration Guide Page 109
Appendix
Property Name Data Type Description
internalTimesId Strin unique key used to identify a shift event on Xora server. g A
eventId String This is a unique number to identify an event on Xora Server.
Also c
You can find the Xora API ID on View Profile page under ob S
Flex F
tration
alled Xora API ID.
J tatus section. This ID is also used to insert dynamic ields.
Refer Event ID / Xora API ID Illus section in Appendix or illuf stration.
Note This id is considered only while creating the job for a TT Gold user.
eventName String The name of the event for which the Flex Fields are defined.
fieldName String The Flex Field name.
fieldValue String The Flex Field value – Provision for multiple values
eventHistoryId String uniq of an event. A ue key to identify occurrence
UserInfo
A data structure used to return the user information.
Property Name Data Type Description
userId String uniq r. A ue number used to identify a user on Xora serve
phoneNumber String Phone number of the user.
employeeNumber String Employee number of the user.
firstName String First name of the user.
lastName String st n La ame of the user.
timeZone String Time zone name in which the user works.
shiftType String The name of the shift in which the user works.
userType String am
The type of the user. For example: Admin, Report Admin – Te Lead, Customer, and so on.
isActive Boolean If True, the user is active. If False, the user is inactive.
gmtOffsetMinutes Integer Difference ween the users time zone and the GMT time zone.
bet
Confidential Xora API V 4.0 - Application Integration Guide Page 110
Appendix
Property Name Data Type Description
teamId Integer Id of user’s team. It is a unique number on Xora sever which identifies a team.
loginUserId String Login user ID.
S uledJobDeta poched ilsRes nse
Property Name D e ata Typ Description
scheduledJobDetail
Comples ScheduledJobDetail object.
status Comples Status object.
S dJobDeta
P ters that are high in y implemented in the subsequent releases.
chedule il
arame lighted ellow color in this table will be
Property Name Da e ta Typ Description
userId Integer Array of user ids.
scheduled jobs for a given user or users. Used to search for
u Login user name. serName String
recurringJobIds A rray ofInteger
Array of recurring job ids.
Used to search for scheduled jobs belonging to any given set of recurring jobs.
jobIds Array of Integer
Array of job ids.
Used to search for scheduled jobs containing any given job ids.
externalJobId String l job ids. Array of externa
availableFrom Date Availabl tie from me.
availableTo Date vailable To date. A
scheduledStartTi Date Scheduled Start Time date/time range. me
estimatedEndTim Date Estimated End Time date/time. e
downloadTime Date Download time date.
Confidential Xora API V 4.0 - Application Integration Guide Page 111
Appendix
Property Name Data Type Description
scheduledJobStatusCode
Code Scheduled job status.
scheduledJobDe String Scheduled job description. scription
scheduledJobContactName
String Scheduled job contact.
scheduledJobCohone
String Scheduled job contact phone. ntactP
scheduledJobSmsMessage
String Scheduled job SMS.
scheduledJobAd String Scheduled job address1. dress1
scheduledJobAddress2
String Scheduled job.
scheduledJobCity String Scheduled job city.
scheduledJobState
String Scheduled job.
scheduledJobPostalCode
String Scheduled job postal code.
scheduledJobLandmarkIds
Array of String
Array of landmark ids to search for.
Used to find scheduled jobs containing any given landmarks.
creationAgents Array of String
Array of user agent STRINGS to search for.
Used to find scheduled jobs created by any given user agents. (This comes from the credential)
lastModifiedDbTime
Date The at w D e/time hen the project was last modified.
notificationType String Notification type.
teamsId String Team ID.
placeHolder1 String Placeholder
placeHolder2 A rray ofString
Placeholder
Confidential Xora API V 4.0 - Application Integration Guide Page 112
Appendix
J oobDetailsResp nse
Property Name Da e ta Typ Description
jobDetail Complex JobDetail object.
status Complex Status object
JobDetail
Parameters that are highlighted in y t releases.
ellow color in this table will be implemented in the subsequen
Property Name Data Type Description
userId Integer heduled jobs for a given user or users.Used to search for sc
userName String Name of the user.
externalJobId String The scheduled job to which the job is associated.
jobId Integer A unique number, which is used to identify a job on Xora server. (Internal Job ID)
teamName String The name of user’s team.
jobNumber String A number to idencan be an intege
tify a job from users point of view. This r or combination of integer, alphabets, and
special characters.
jobTraveledMiles String The total distance covered during the job.
eventDetails Array of Event Detail
The details of the event entered by the user.
Array of EventDetail object.
duration String Duration of the job
creationDbTime DateTime The creation time of the record.
lastModifiedDbTime
DateTime The last modified time of the record.
placeHolder1 String For future use
placeHolder2 Array of String
For future use
Confidential Xora API V 4.0 - Application Integration Guide Page 113
Appendix
Status
Property Name D ata Type Description
statusCode String Status Code.
statusMessage String Status Message.
EventDetail
Parameters that are highlighted in yellow color in this table will be implemented in the subsequent releases.
Property Name Data Type Description
eventId String A unique number that is used to identify an event on Xora server. Also called Xora API ID.
eventName String Event names such as Job Start, Job End, Parts Hold (Custom Status) etc.. – Report_event_name in the DB.
eventTime String The time at which the event has occurred.
eventType String Event types such as JS, JE, CS, and so on.
eventHistoryId String A unique number that is used to identify an event on Xora server.
eventLocation Complex Location at which the event occurred.
Location object.
eventComment String The comment entered by the user during the event.
eventFlexFields f ld
eldArray oFlexFie
Array of FlexFi object.
creationDbTime DateTime e creation time of the record. Th
lastModifiedDbTim e f the record. e
DateTim The last modified time o
placeHolder1 String For future use
placeHolder2 Array of String
For future use
Confidential Xora API V 4.0 - Application Integration Guide Page 114
Appendix
L
P high in y will be implemented in the subsequent r
ocation
arameters that areeleases.
lighted ellow color in this table
Property Name Da e ta Typ Description
accuracy Float Accuracy of the location.
address1 String Address1 of the location at which the event has occurred.
address2 String Address2 of the location at which the event has occurred.
city String The name of the city in which the event has occurred.
state String The name of the state in which the event has occurred.
postalCode String Postal code of the location at which the event has occurred.
altitude String The height of the place.
latitude String The latitude of the place.
longitude String The longitude of the place.
speed String The speed at which the user is moving.
cellSite Boolean Indicates if the location details are from a cell site or not.
e from a cell site
♦ False – Location details are not from a cell site
♦ True – Location details ar
trackingId String A unique number on Xora sever which identifies a tracking record.
direction String The direction in which the user is traveling.
dbCreationTime DateTime The creation time of the record.
placeholder1 String For future use
placeHolder2 Array of String
For future use
M tailsRespo
P are high in y this table will be implemented in the subsequent releases.
ediaDe nse
arameters that lighted ellow color in
Property Name Da e ta Typ Description
mediaDetails Complex MediaDetails object.
Confidential Xora API V 4.0 - Application Integration Guide Page 115
Appendix
Property Name Data Type Description
status Complex Status object.
MediaDetails
P ers that are hi y his table will be implemented in the subsequent releases.
aramet ghlighted in ellow color in t
Property Name Data Type Description
creationTime DateTime The creation time of the media object.
d The device time at which the media object was created. (Timezone information included)
eviceTime DateTime
latitude String The latitude of the place.
longitude String The longitude of the place.
mediaId String A unique number, which is used to identify the media on Xora server. (Internal ID)
mediaType String The type of the media.
mediaUrl String The URL from where the customer can retrieve the media object.
mimeType String Mime type.
notes String Notes attached to the media object.
objectId String Job ID / Shift ID / message ID / JobEvent ID / ShiftEvent ID.
objectType String Job / Shift / Message / JobEvent / ShiftEvent.
userId String A unique number used to identify a user on Xora server.
LatestLocationDetails
Property Name Data Type Description
accuracy Float The accuracy.
address1 String Address.
address2 String Address.
altitude Float The altitude.
cellSiteLocation Boolean Is Cell Site or not.
Confidential Xora API V 4.0 - Application Integration Guide Page 116
Appendix
Property Name Data Type Description
city String City.
dbTime DateTime he time at which the event was inserted into the DB. The db time. T
direction Float The direction.
eventDetail String The detail of the event.
eventHistoryId String The ID for event history. Available only for Gold users.
e D The time at which the evventTime ateTime ent occurred.
eventType S Ttring he type of event.
latitude String Latitude
longitude S Lotring ngitude
odometer F Tloat he odometer reading.
postalCode S Ptring ostal code.
speed F Sloat peed.
state String State.
status Complex Status object.
trackingId String The internal tracking ID.
userId String A unique number used to identify a user on Xora server. The above information is assigned to this user.
userName String User Name.
UserInfo40
Property Name Data Type Description
page Complex Page object.
userInfo A Array of UserInforray .
Confidential Xora API V 4.0 - Application Integration Guide Page 117
Appendix
Page
Property Name Data Type Description
c Current page number. urrentPage String
recordCount the result. String Number of total records in
token String A unique key that identifies a set of data on the server.
totalNoOfPages String Total number of pages of the result.
JobEntry40
Property Name Da e ta Typ Description
jobEntry Array Array of JobEntry.
page C omplex Page object.
JobFlexField40
Property Name Da e ta Typ Description
jobFlexField Array Array of JobFlexField.
page Complex Page object.
CustomJobStatus40
Property Name Data Type Description
customJobState Array Array of CustomJobState.
page Complex Page object.
LocationEntry40
Property Name Da e ta Typ Description
locationEntry Array Array of LocationEntry.
A data structure used to return the location entry details.
page Complex Page object.
Confidential Xora API V 4.0 - Application Integration Guide Page 118
Appendix
GeofenceActivity40
Property Name Data Type Description
geofenceActivity Array Array of GeofenceActivity.
A data structure used to return the geofence activity details.
page Complex Page object.
TimeEntry40
Property Name Data Type Description
timeEntry Array Array of TimeEntry.
page C omplex Page object.
ShiftFlexField40
Property Name Data Type Description
shiftFlexField Array Array of ShiftFlexField.
page C omplex Page object.
TeamStatus
Property Name Da e ta Typ Description
teamID Integer Team ID.
teamName String Team name.
teamStatus C omplex Status object.
FlexField
Parameters that are highlighted in yellow color in this table will be implemented in the subsequent releases.
Property Name Data Type Description
fieldName String The name of the FlexField.
fieldValue String The possible field values for the FlexField.
flexFieldId Integer FlexField. The ID of the
placeHolder1 String For future use.
Confidential Xora API V 4.0 - Application Integration Guide Page 119
Appendix
Property Name Data Type Description
placeHolder2 A rray ofString
For future use.
Confidential Xora API V 4.0 - Application Integration Guide Page 120
Appendix
Throttling Requirements This section describes the list of throttling requirements that need to be conformed by the Xora customers and Xora API users.
D uperSetsecutive I c ts (or same) of the
previous call, then an error status will be sent to the client.
From Date: 10:00To
Status: OK
00To Date: 12:00
S
From Date: 10:00To Date: 13:00
: NOT OK
From Date: 10:00To 11:0
Status: OK
From Date: 10:00To Date: 11:00
K
Dat: 11:0
NO
From Date: 10:00To
Status: OK
From Date: 11:00To Date: 12:00
Status: O
Date: 12:00To : 13:00
Status: OK
From Date: 10:00To Date: 11:00
Status: OK
From Date: 10:05To Date: 11:05
Status: OK
From Date: 10:10To Date: 11:10
Status: OK
ateRangeS Rule 1. If n con Xora AP alls have date ranges that are superse
Date: 11:00 Date: 0 Date: 11:00
From Date: 10:
Status: O
FromDate
e: 10:00To 0
FromDate
Status: T OK
K tatus: OK
Status
DateRangeSumRule
The sum of date ranges for a given
day should not be more than 48 hours.
o Date) <= 48 hours
DateRangeLimitRule
If the time window is higher than or equal to 24 hours, the calls can be made between certain times on the server.
For example, for a get call with “from date” 00:00 and “to date” as 24:00 then this call is n 8PM PST and 1AM PST.
FrequencyRule
n h a certain specified frequency. Any calls below that frequency
For example, get location entries call can be made every 15 minutes. A call happening more than once within that time would not be serviced.
JobErrorCountRule
jobs having errors should not exceed certain limit.
For example, createScheduledJobs can have maximum of 500 jobs with errors per day, if ha uest will be denied.
I
The number of items allowe
For example: in getJobDetailsByIds API, the number external Job IDs provided as input parameter sho cee
That is ∑ (T Date – From
allowed only betwee
The calls ca be made witwould potentially not be serviced.
The sum of the
it exceeds t t limit the req
temLimitRule
d in the request should not exceed the limit.
uld not ex d 50 IDs.
Confidential Xora API V 4.0 - Application Integration Guide Page 121
Appendix
Error Codes This section describes the list of error codes.
Error Code Error Description
3500 Server is busy. Please try later
3501 Server Error
3502 Invalid credential
3503 To access this service you need to subscribe Gold user license
3504 No job in request
3505 Date range error. Invalid date(s) in request
3506 There are no external ids in request
3507 No landmark in request
3508 No a e request ssignee in th
3509 No use ghligr to hi ht on map
3510 There is no user information in the request
3511 Invalid team name
3512 User not authorized to delete landmark
3513 User is not authorized to create Landmarks
3514 User is not authorized to create Global landmarks
3515 User not authorized to create landmarks for other Teams
3516 Invalid user id. User Id should contain only numbers without any space/special characters
3000 Unsuccessful
3001 Successful
4001 Logged in user is not an Admin or Report Admin.
4002 User is not authorized to create users.
4003 User is not authorized to update password.
4004 User is not authorized to create teams.
Confidential Xora API V 4.0 - Application Integration Guide Page 122
Appendix
Error Code Error Description
4005 User is not authorized to update teams.
4006 User is not authorized to delete teams.
4007 User is not authorized to add users to team.
4008 User is not authorized to remove users from team.
4009 Invalid time zone name.
4010 Invalid Shift type name.
4011 Invalid user type.
Confidential Xora API V 4.0 - Application Integration Guide Page 123
Appendix
Event ID / Xora API ID Illustration . Event ID is a unique number to identify an event on Xora server. It is also called as Xora API ID
This ID is represented by Xora API IDs in web interface.
Y P ag ecu Fl
ou can find the Xora Ased to insert dynamic
I ID on View Profile pex Fields.
e under Job Status s tion. This ID is also
Note This ID is considered only while creating the job for TT Gold users.
Confidential Xora API V 4.0 - Application Integration Guide Page 124