View source for SOAP 3 Documentation

== The EService SOAP 3 API ==
The API has been developed as a SOAP XML Web Service, which means it is based on a widely supported standard, and is supported by many languages and operating systems. Most developer environments, such as Microsoft's Visual Studio, and IBM's Eclipse-based Developer Environments, directly support Web Service integration. Depending on the sophistication of the client's system, a module can be written and linked to the system, allowing it direct communication with EService.  Alternatively, a stand-alone application can be built to act as a go-between, transferring data between EService and the existing client software (job management application, sales program, accounting software, etc).

The [[SOAP|SOAP]] 3 API is an external interface which allows authorized users to directly connect their system to the ECONZ EService Job Management and Wireless Dispatch system.  The interface allows jobs to be created, updated, dispatched, progressed and completed.  In addition, it also allows for the creation and maintenance of customer, resource, and employee data.

ECONZ has also developed the CallBack Interface.  This interface is a WSDL (Web Services Descriptor Language) file, which describes a Web Service interface that clients may implement for themselves on ther own systems.  Once implemented, the interface can be registered on EService SOAP API by calling the [[#Callback Functions|Register method]], and passing in the URL of the CallBack interface.  By registering the interface on EService, EService is then able to send real-time updates of job events to the CallBack interface.  This will give the client system up-to-the-second monitoring of job progression and field worker events.

To find out more about EService please visit http://www.eservice.econz.com

If you have further questions, you could try looking at the [[Frequently Asked Questions]] page which may answer your query.  Otherwise, please contact your [[#Further Help|local sales representative]] for further information.

== Best Practises ==

* The SOAP API is a request and response system, which means that while you can create new jobs, or update the details of an existing job, you will not receive notifications about the change of details to existing data on the service.
* To check for changes of state of a set of jobs, you must poll the server regularly for the summaries of the jobs you are interested in. See [[getJobSummaries]].
* Polling should be performed no more than once per minute, to avoid over loading the server.
* Jobs where the status has changed can also be retrieved by using the [[getUnsynchronisedJobs]] and [[ackJobSynchronisation]] methods.  Simply AckSynch the jobs you are interested in, and then get Unsynched Jobs.  Each time the job is updated, it will also become unsynched, and thus be returned by the get unsynched method, with full details.
* The sync methods can also be used to store additional external data related to jobs, customers and resources.  For example, this can be used to mark a specific job as having been invoiced by the external system.
* If realtime job status monitoring is required, EService does have the capability to call specific EService-defined functions on external web services, passing across job status updates in real time.  This functionality requires the Call Back Interface to be appropriately implemented and then registered with EService.  Please contact your [[#Further Help|local sales representative]] for further information.

== The Interface Definition ==

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

Please select a link to see documentation on each method's function and features.

=== Job Creation and Management Functions ===

{| border=1
!Method
!Summary
|---- bgcolor=#EDEDFF
|[[createJob]]
|Creates a new job based on the job data passed in.
|---- bgcolor=#EDEDFF
|[[updateJob]]
|Updates an existing job, based on the data passed in.  Does not apply to Verizon Wireless Cellphones.
|---- bgcolor=#EDEDFF
|[[progressJobStatus]]
|Moves a job forwards through its logical state transitions.  Does not apply to Verizon Wireless Cellphones.
|---- bgcolor=#EDEDFF
|[[onHoldJob]]
|Places a started job on hold.
|---- bgcolor=#EDEDFF
|[[resumeJob]]
|Resumes a job previously placed on hold.
|---- bgcolor=#EDEDFF
|[[recallJob]]
|Recalls a job previously dispatched to a field worker.  Optionally forces return even after the job has been started.
|---- bgcolor=#EDEDFF
|[[confirmJobRecall]]
|Forces completion of the recall, even if the field worker has not confirmed job recall.
|---- bgcolor=#EDEDFF
|[[cancelJob]]
|Cancels an existing job.
|---- bgcolor=#EDEDFF
|[[dispatchJob]]
|Sends the job to the specified field worker.
|---- bgcolor=#EDEDFF
|[[getJobSummary]]
|Retrieves a quick summary of the job, its status, and the customer details.
|---- bgcolor=#EDEDFF
|[[getJobSummaries]]
|Retrieves a series of summaries of requested jobs, their status, and their customer details.
|---- bgcolor=#EDEDFF
|[[getJobSummariesBetween]]
|Retrieves a series of summaries of requested jobs between two selected dates.
|---- bgcolor=#EDEDFF
|[[getJobSummariesBetweenStatusAfterPK]]
|Retrieves a summary of every job who's status lies between status A and status B, inclusive and who's primary key lies after the passed key.
|---- bgcolor=#EDEDFF
|[[getJobDetail]]
|Retrieves the full job details for the specified job.
|---- bgcolor=#EDEDFF
|[[getJobDetails]]
|Retrieves the full job detail for each of the specified jobs.
|---- bgcolor=#EDEDFF
|[[getJobDetailsBetween]]
|Retrieves the full job details for all jobs whose Event fell between the two specified dates.
|---- bgcolor=#EDEDFF
|[[getJobDetailsByExternalRef]]
|Retrieves the full job details for the specified job whose external reference matches the passed in value.
|---- bgcolor=#EDEDFF
|[[getJobAttributeNames]]
|Retrieves the list of all job custom attributes.
|---- bgcolor=#EDEDFF
|[[getJobTypeNames]]
|Retrieves the list of all job types.
|---- bgcolor=#EDEDFF
|[[getUnsynchronisedJobs]]
|Retrieves all jobs which have not previously been synchronised and acknowledged, and all jobs that have changed since their last synchronisation
|---- bgcolor=#EDEDFF
|[[ackJobSynchronisation]]
|Acknowledges that synchronisation has been performed on the selected jobs.
|}

=== Customer Management Functions ===

{| border=1
!Method
!Summary
|---- bgcolor=#EDEDFF
|[[createCustomer]]
|Creates a new customer based on the customer data passed in.
|---- bgcolor=#EDEDFF
|[[getCustomerDetail]]
|Gets the full set of details for a customer, specified by the customer's primary key.
|---- bgcolor=#EDEDFF
|[[getCustomerDetailByExternalRef]]
|Gets the full set of details for a customer, specified by the customer's external ref field.
|---- bgcolor=#EDEDFF
|[[getCustomerDetailsUpdatedSince]]
|Gets all customer details for all customers who have had details updated since a specified date and time.
|---- bgcolor=#EDEDFF
|[[updateCustomer]]
|Updates a customer with new detalis.
|---- bgcolor=#EDEDFF
|[[deleteCustomer]]
|Marks a customer as deleted.
|---- bgcolor=#EDEDFF
|[[getCustomerAttributeNames]]
|Gets a list of all custom customer attroibute names.
|---- bgcolor=#EDEDFF
|[[getUnsynchronisedCustomers]]
|Gets the details of all customers who have not been acknowledged as synchronised, and all customers who have been updated since being acknowledged as synchronised.
|---- bgcolor=#EDEDFF
|[[ackCustomerSynchronisation]]
|Acknowledges all specified customers as having been synchronised.
|---- bgcolor=#EDEDFF
|[[getCustomersBySynchronisation]]
|Get a customer, specified by the customer's Account ID, retrieved from the customer synchronisation table. If the last parameter, i.e. afterPK, is not null, the customer retrieved must have a Primary Key greater than the afterPK.

|}

=== EService User Management Functions ===
{| border=1
!Method
!Summary
|---- bgcolor=#EDEDFF
|[[createUser]]
|Creates a new user based on the user data passed in.
|---- bgcolor=#EDEDFF
|[[getUserDetail]]
|Gets all the details of a specified user.
|---- bgcolor=#EDEDFF
|[[updateUser]]
|Updates a particular user with new details.
|---- bgcolor=#EDEDFF
|[[updateUserPassword]]
|Updates a user's password.
|---- bgcolor=#EDEDFF
|[[deleteUser]]
|Deletes an existing user.
|---- bgcolor=#EDEDFF
|[[getUnsynchronisedUsers]]
|Retrieves all users who have not previously been synchronised and acknowledged, and all users that have changed since their last synchronisation.
|---- bgcolor=#EDEDFF
|[[ackUserSynchronisation]]
|Acknowledges that synchronisation has been performed on the selected users.
|}

=== EService Field Device Management Functions ===
{| border=1
!Method
!Summary
|---- bgcolor=#EDEDFF
|[[createFieldDevice]]
|Creates a new field device based on the field device data passed in.
|---- bgcolor=#EDEDFF
|[[getFieldDeviceDetail]]
|Gets the full set of details for a specified field device.
|---- bgcolor=#EDEDFF
|[[getFieldDeviceDetails]]
|Gets the full set of details for all specified field devices.
|---- bgcolor=#EDEDFF
|[[getFieldDeviceDetailsUpdatedSince]]
|Gets the full set of details for all field devices that have been updated since the specified date and time.
|---- bgcolor=#EDEDFF
|[[updateFieldDevice]]
|Updates a field device with new details.
|---- bgcolor=#EDEDFF
|[[deleteFieldDevice]]
|Marks a field device as deleted.
|---- bgcolor=#EDEDFF
|[[getFieldDevicePKForName]]
|Gets the primary key of a field device, based on the name passed in.
|---- bgcolor=#EDEDFF
|[[getFieldDevicePKForDeviceID]]
|Gets the primary key of a field device, based on the device id passed in.
|}
=== Resource Management Functions ===
{| border=1
!Method
!Summary
|---- bgcolor=#EDEDFF
|[[createResource]]
|Creates a new resource based on the resource data passed in, and attachs it to the specified resource group.
|---- bgcolor=#EDEDFF
|[[getResourceList]]
|Gets the full list of all resources stored for this organisation.
|---- bgcolor=#EDEDFF
|[[getResource]]
|Gets the full details of a single resource.
|---- bgcolor=#EDEDFF
|[[getResourcesUpdatedSince]]
|Gets the full details of all resources updated since the specified date and time.
|---- bgcolor=#EDEDFF
|[[deleteResource]]
|Marks a specific resource as deleted.
|---- bgcolor=#EDEDFF
|[[getUnsynchronisedResources]]
|Retrieves all resources which have not previously been synchronised and acknowledged, and all resources that have changed since their last synchronisation.
|---- bgcolor=#EDEDFF
|[[ackResourceSynchronisation]]
|Acknowledges that synchronisation has been performed on the selected resources.
|---- bgcolor=#EDEDFF
|[[getResourceGroups]]
|Gets a list of all resource group names.
|---- bgcolor=#EDEDFF
|[[createResourceGroup]]
|Creates a new resource group.
|---- bgcolor=#EDEDFF
|[[deleteResourceGroup]]
|Deletes an existing resource group.
|}

=== Callback Functions ===
{| border=1
!Method
!Summary
|---- bgcolor=#EDEDFF
|[[registerCallback]]
|Register an external interface as a interested receiver of callback events.
|---- bgcolor=#EDEDFF
|[[unRegisterCallback]]
|Unregisters an external interface, and deletes all queued up events for that interface.
|---- bgcolor=#EDEDFF
|[[getCallbackErrors]]
|Gets a list of all call back errors stored on the server.
|---- bgcolor=#EDEDFF
|[[getVersion]]
|Gets the version of this SOAP Interface.
|}

=== Failure Objects ===

{| border=1
!Method
!Summary
|---- bgcolor=#EDEDFF
|[[AccessDeniedFailure]]
|Indicates the method was called within an invalid username or password.
|---- bgcolor=#EDEDFF
|[[CallbackAlreadyRegisteredFailure]]
|An attempt has been made to register an instance of the callback interface which has already been registered on EService.
|---- bgcolor=#EDEDFF
|[[CallbackNotRegisteredFailure]]
|An attempt has been made to unregister an instance of the callback interface which is not registered on EService.
|---- bgcolor=#EDEDFF
|[[CustomerNotFoundFailure]]
|An attempt was made to update or modify a customer's details, but the primary key of the customer was not found on the server.
|---- bgcolor=#EDEDFF
|[[CustomerPKMismatchFailure]]
|Indicates the JobCustomerbean contains a CustomerBean whose primary key does not match the Job's customer's primary key.
|---- bgcolor=#EDEDFF
|[[ConcurrentUpdateFailure]]
|An attempt was made to update or change something on the server, but the update index passed in does not match the one in the record to be updated.
|---- bgcolor=#EDEDFF
|[[FieldDeviceNotFoundFailure]]
|An attempt was made to reference a particular field device, but the primary key does not match any field devices located on the server.
|---- bgcolor=#EDEDFF
|[[IllegalEscapeSequenceFailure]]
|Indicates that the escaped "wild card" values passed in were not valid for the method called.
|---- bgcolor=#EDEDFF
|[[InvalidCallbackVersionFailure]]
|Indicates that the specified version of the callback interface instance, is not a valid CallbackVersion.
|---- bgcolor=#EDEDFF
|[[JobNotFoundFailure]]
|An attempt was made to progress/update/modify a job, but the primary key or External ID was not found on the server.
|---- bgcolor=#EDEDFF
|[[ResourceGroupExistsFailure]]
|An attempt was made to create a resource group which already exists on the server.
|---- bgcolor=#EDEDFF
|[[ResourceGroupNotFoundFailure]]
|An attempt was made to modify or delete a resource group, but the name of the resource group was not found on the server.
|---- bgcolor=#EDEDFF
|[[ResourceNotFoundFailure]]
|An attempt was made to update or modify a resource's details, but the name of the resource was not found on the server.
|---- bgcolor=#EDEDFF
|[[TooManyFailure]]
|Indicates there are too many records to be returned, and includes the max number of records that can be returned.
|---- bgcolor=#EDEDFF
|[[UnknownJobStatusProgressionFailure]]
|Indicates a invalid [[JobStatus]] field was passed in, please ensure you only use fields from this enumeration.
|---- bgcolor=#EDEDFF
|[[UserNotFoundFailure]]
|An attempt was made to update or modify a user's details, but the primary key of the user was not found on the server.
|---- bgcolor=#EDEDFF
|[[ValidationFailure]]
|A complex structure of nested arrays of errors, indicating data passed into a method did not match certain criteria for validation.
|}

=== Constants and Enumerated Values ===

{| border=1
!Method
!Summary
|---- bgcolor=#EDEDFF
|[[JobStatus]]
|The list of possible states a job may be in, or progressed to.
|---- bgcolor=#EDEDFF
|[[JobStatusEvent]]
|The list of possible events that may occur, causing a job to change its state.
|---- bgcolor=#EDEDFF
|[[ConcurrentUpdateSource]]
|The list of possible sources for a concurrency problem.
|---- bgcolor=#EDEDFF
|[[CancelState]]
|The list of possible cancel states a job can be in.
|---- bgcolor=#EDEDFF
|[[CallbackVersion]]
|The list of possible versions an external callback interface could implement.
|---- bgcolor=#EDEDFF
|[[NADSWebserviceVersion]]
|The list of possible interface versions that can be used to comunicate with EService.
|}

== SOAP 3 Example Code ==

We have prepared a sample application and source code to aid in learning to use the EService SOAP API.  Contact your [[#Further Help|local sales representative]] and enquire about our ECONZ Developer SDK CD.

== Further Help ==
Details about our EService system can be found at http://www.eservice.econz.com

Details about our timecard system can be found at http://www.timecard.econz.com


If you have further questions, you could try looking at the [[Frequently Asked Questions]] page which may answer your query.  


Otherwise, please contact us by :

<u>'''USA'''</u>

Phone : 1800 805 6642

Email : [mailto:technicalsupport@econz.com Technical Support]

<u>'''New Zealand'''</u>

Phone : 0800 ECONZ9

Email : [mailto:helpdesk@econz.com Help Desk]

<u>'''Australia'''</u>

Phone : 1800 006 598

Email : [mailto:helpdesk@econz.com Help Desk]