xora apis application integration guide

129
Xora APIs Application Integration Guide Xora Inc. 501 Ellis Street Mountain View, CA 94043 www.xora.com [email protected] Version 4.0

Upload: others

Post on 03-Feb-2022

2 views

Category:

Documents


0 download

TRANSCRIPT

Page 1: Xora APIs Application Integration Guide

Xora APIs Application Integration Guide

Xora Inc.

501 Ellis Street

Mountain View, CA 94043

www.xora.com

[email protected]

Version 4.0

Page 2: Xora APIs Application Integration Guide

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

Page 3: Xora APIs 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

Page 4: Xora APIs Application Integration Guide

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

Page 5: Xora APIs Application Integration Guide

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

Page 6: Xora APIs Application Integration Guide

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

Page 7: Xora APIs Application Integration Guide

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

Page 8: Xora APIs Application Integration Guide

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

Page 9: Xora APIs Application Integration Guide

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

Page 10: Xora APIs Application Integration Guide

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

Page 11: Xora APIs Application Integration Guide

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

Page 12: Xora APIs Application Integration Guide

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

Page 13: Xora APIs Application Integration Guide

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

Page 14: Xora APIs Application Integration Guide

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

Page 15: Xora APIs Application Integration Guide

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

Page 16: Xora APIs Application Integration Guide

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

Page 17: Xora APIs Application Integration Guide

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

Page 18: Xora APIs Application Integration Guide

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

Page 19: Xora APIs Application Integration Guide

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

Page 20: Xora APIs Application Integration Guide

Time Services

ShiftFlexField40 shiftFfEntry = xoraClient30.getShiftFlexFieldEntries(credential, dateTimeRange, pageRequest);

Confidential Xora API V 4.0 - Application Integration Guide Page 15

Page 21: Xora APIs Application Integration Guide

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

Page 22: Xora APIs Application Integration Guide

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

Page 23: Xora APIs Application Integration Guide

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

Page 24: Xora APIs Application Integration Guide

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

Page 25: Xora APIs Application Integration Guide

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

Page 26: Xora APIs Application Integration Guide

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

Page 27: Xora APIs Application Integration Guide

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

Page 28: Xora APIs Application Integration Guide

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

Page 29: Xora APIs Application Integration Guide

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

Page 30: Xora APIs Application Integration Guide

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

Page 31: Xora APIs Application Integration Guide

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

Page 32: Xora APIs Application Integration Guide

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

Page 33: Xora APIs Application Integration Guide

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

Page 34: Xora APIs Application Integration Guide

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

Page 35: Xora APIs Application Integration Guide

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

Page 36: Xora APIs Application Integration Guide

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

Page 37: Xora APIs Application Integration Guide

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

Page 38: Xora APIs Application Integration Guide

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

Page 39: Xora APIs Application Integration Guide

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

Page 40: Xora APIs Application Integration Guide

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

Page 41: Xora APIs Application Integration Guide

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

Page 42: Xora APIs Application Integration Guide

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

Page 43: Xora APIs Application Integration Guide

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

Page 44: Xora APIs Application Integration Guide

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

Page 45: Xora APIs Application Integration Guide

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

Page 46: Xora APIs Application Integration Guide

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

Page 47: Xora APIs Application Integration Guide

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

Page 48: Xora APIs Application Integration Guide

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

Page 49: Xora APIs Application Integration Guide

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

Page 50: Xora APIs Application Integration Guide

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

Page 51: Xora APIs Application Integration Guide

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

Page 52: Xora APIs Application Integration Guide

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

Page 53: Xora APIs Application Integration Guide

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

Page 54: Xora APIs Application Integration Guide

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

Page 55: Xora APIs Application Integration Guide

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

Page 56: Xora APIs Application Integration Guide

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

Page 57: Xora APIs Application Integration Guide

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

Page 58: Xora APIs Application Integration Guide

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

Page 59: Xora APIs Application Integration Guide

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

Page 60: Xora APIs Application Integration Guide

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

Page 61: Xora APIs Application Integration Guide

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

Page 62: Xora APIs Application Integration Guide

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

Page 63: Xora APIs Application Integration Guide

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

Page 64: Xora APIs Application Integration Guide

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

Page 65: Xora APIs Application Integration Guide

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

Page 66: Xora APIs Application Integration Guide

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

Page 67: Xora APIs Application Integration Guide

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

Page 68: Xora APIs Application Integration Guide

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

Page 69: Xora APIs Application Integration Guide

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

Page 70: Xora APIs Application Integration Guide

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

Page 71: Xora APIs Application Integration Guide

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

Page 72: Xora APIs Application Integration Guide

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

Page 73: Xora APIs Application Integration Guide

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

Page 74: Xora APIs Application Integration Guide

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

Page 75: Xora APIs Application Integration Guide

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

Page 76: Xora APIs Application Integration Guide

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

Page 77: Xora APIs Application Integration Guide

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

Page 78: Xora APIs Application Integration Guide

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

Page 79: Xora APIs Application Integration Guide

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

Page 80: Xora APIs Application Integration Guide

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

Page 81: Xora APIs Application Integration Guide

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

Page 82: Xora APIs Application Integration Guide

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

Page 83: Xora APIs Application Integration Guide

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

Page 84: Xora APIs Application Integration Guide

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

Page 85: Xora APIs Application Integration Guide

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

Page 86: Xora APIs Application Integration Guide

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

Page 87: Xora APIs Application Integration Guide

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

Page 88: Xora APIs Application Integration Guide

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

Page 89: Xora APIs Application Integration Guide

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

Page 90: Xora APIs Application Integration Guide

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

Page 91: Xora APIs Application Integration Guide

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

Page 92: Xora APIs Application Integration Guide

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

Page 93: Xora APIs Application Integration Guide

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

Page 94: Xora APIs Application Integration Guide

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

Page 95: Xora APIs Application Integration Guide

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

Page 96: Xora APIs Application Integration Guide

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

Page 97: Xora APIs Application Integration Guide

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

Page 98: Xora APIs Application Integration Guide

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

Page 99: Xora APIs Application Integration Guide

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

Page 100: Xora APIs Application Integration Guide

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

Page 101: Xora APIs Application Integration Guide

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

Page 102: Xora APIs Application Integration Guide

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

Page 103: Xora APIs Application Integration Guide

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

Page 104: Xora APIs Application Integration Guide

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

Page 105: Xora APIs Application Integration Guide

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

Page 106: Xora APIs Application Integration Guide

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

Page 107: Xora APIs Application Integration Guide

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

Page 108: Xora APIs Application Integration Guide

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

Page 109: Xora APIs Application Integration Guide

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

Page 110: Xora APIs Application Integration Guide

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

Page 111: Xora APIs Application Integration Guide

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

Page 112: Xora APIs Application Integration Guide

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

Page 113: Xora APIs Application Integration Guide

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

Page 114: Xora APIs Application Integration Guide

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

Page 115: Xora APIs Application Integration Guide

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

Page 116: Xora APIs Application Integration Guide

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

Page 117: Xora APIs Application Integration Guide

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

Page 118: Xora APIs Application Integration Guide

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

Page 119: Xora APIs Application Integration Guide

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

Page 120: Xora APIs Application Integration Guide

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

Page 121: Xora APIs Application Integration Guide

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

Page 122: Xora APIs Application Integration Guide

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

Page 123: Xora APIs Application Integration Guide

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

Page 124: Xora APIs Application Integration Guide

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

Page 125: Xora APIs Application Integration Guide

Appendix

Property Name Data Type Description

placeHolder2 A rray ofString

For future use.

Confidential Xora API V 4.0 - Application Integration Guide Page 120

Page 126: Xora APIs Application Integration Guide

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

Page 127: Xora APIs Application Integration Guide

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

Page 128: Xora APIs Application Integration Guide

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

Page 129: Xora APIs Application Integration Guide

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