SOAP 3 Documentation

Latest revision as of 21:37, 11 December 2013

[edit] 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 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 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 local sales representative for further information.

[edit] 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, by default 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. Alternatively you may wish to implement and register the Callback API so that you automatically receive updates when data changes.
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 local sales representative for further information.

[edit] The Interface Definition

Below are listed the various functions that make up the 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.

[edit] Job Creation and Management Functions

Method	Summary
createJob	Creates a new job based on the job data passed in.
updateJob	Updates an existing job, based on the data passed in. Does not apply to Verizon Wireless Cellphones.
progressJobStatus	Moves a job forwards through its logical state transitions. Does not apply to Verizon Wireless Cellphones.
onHoldJob	Places a started job on hold.
resumeJob	Resumes a job previously placed on hold.
recallJob	Recalls a job previously dispatched to a field worker. Optionally forces return even after the job has been started.
confirmJobRecall	Forces completion of the recall, even if the field worker has not confirmed job recall.
cancelJob	Cancels an existing job.
dispatchJob	Sends the job to the specified field worker.
getJobSummary	Retrieves a quick summary of the job, its status, and the customer details.
getJobSummaries	Retrieves a series of summaries of requested jobs, their status, and their customer details.
getJobSummariesBetween	Retrieves all job summaries where the job moved from one state to another state (ie. an event occured) within the specified time period. In general, it is a useful method for finding all jobs that were created, dispatched, or completed within a particular time frame.
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.
getJobDetail	Retrieves the full job details for the specified job.
getJobDetails	Retrieves the full job detail for each of the specified jobs.
getJobDetailsBetween	Retrieves the full job details for all jobs whose Event fell between the two specified dates.
getJobDetailsByExternalRef	Retrieves the full job details for the specified job whose external reference matches the passed in value.
getJobAttributeNames	Retrieves the list of all job custom attributes.
getJobTypeNames	Retrieves the list of all job types.
getUnsynchronisedJobs	Retrieves all jobs which have not previously been synchronised and acknowledged, and all jobs that have changed since their last synchronisation
ackJobSynchronisation	Acknowledges that synchronisation has been performed on the selected jobs.
getJobsBySynchronisation	Retrieve the job(s), referenced by the ID of the job(s) in the external application data to which they are synchronised to, from the job synchronisation table. If the afterPK parameter is not null, the job record(s) retrieved must have a PK greater than that value.

[edit] Customer Management Functions

Method	Summary
createCustomer	Creates a new customer based on the customer data passed in.
getCustomerDetail	Gets the full set of details for a customer, specified by the customer's primary key.
getCustomerDetailByExternalRef	Gets the full set of details for a customer, specified by the customer's external ref field.
getCustomerDetailsUpdatedSince	Gets all customer details for all customers who have had details updated since a specified date and time.
updateCustomer	Updates a customer with new detalis.
deleteCustomer	Marks a customer as deleted.
getCustomerAttributeNames	Gets a list of all custom customer attroibute names.
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.
ackCustomerSynchronisation	Acknowledges all specified customers as having been synchronised.
getCustomersBySynchronisation	Retrieve the customer(s), specified by the ID of the customer(s) in the external application data to which they are synchronised to, from the customer synchronisation table. If the last parameter, i.e. afterPK, is not null, the customer record(s) retrieved must have a Primary Key greater than the afterPK.

[edit] EService User Management Functions

Method	Summary
createUser	Creates a new user based on the user data passed in.
getUserDetail	Gets all the details of a specified user.
updateUser	Updates a particular user with new details.
updateUserPassword	Updates a user's password.
deleteUser	Deletes an existing user.
getUnsynchronisedUsers	Retrieves all users who have not previously been synchronised and acknowledged, and all users that have changed since their last synchronisation.
ackUserSynchronisation	Acknowledges that synchronisation has been performed on the selected users.
getUsersBySynchronisation	Retrieve the user(s), specified by the ID of the user(s) in the external application data to which they are synchronised to, from the user synchronisation table. If the last parameter, i.e. afterPK, is not null, the user record(s) retrieved must have a Primary Key greater than the afterPK.

[edit] EService Field Device Management Functions

Method	Summary
createFieldDevice	Creates a new field device based on the field device data passed in.
getFieldDeviceDetail	Gets the full set of details for a specified field device.
getFieldDeviceDetails	Gets the full set of details for all specified field devices.
getFieldDeviceDetailsUpdatedSince	Gets the full set of details for all field devices that have been updated since the specified date and time.
updateFieldDevice	Updates a field device with new details.
deleteFieldDevice	Marks a field device as deleted.
getFieldDevicePKForName	Gets the primary key of a field device, based on the name passed in.
getFieldDevicePKForDeviceID	Gets the primary key of a field device, based on the device id passed in.

[edit] Resource Management Functions

Method	Summary
createResource	Creates a new resource based on the resource data passed in, and attachs it to the specified resource group.
getResourceList	Gets the full list of all resources stored for this organisation.
getResource	Gets the full details of a single resource.
getResourcesUpdatedSince	Gets the full details of all resources updated since the specified date and time.
deleteResource	Marks a specific resource as deleted.
getUnsynchronisedResources	Retrieves all resources which have not previously been synchronised and acknowledged, and all resources that have changed since their last synchronisation.
ackResourceSynchronisation	Acknowledges that synchronisation has been performed on the selected resources.
getResourceGroups	Gets a list of all resource group names.
createResourceGroup	Creates a new resource group.
deleteResourceGroup	Deletes an existing resource group.
getResourcesBySynchronisation	Retrieve the resource(s), referenced by the id of the resource(s) in the external application data to which it is synchronised to, from the resource synchronisation table. If the afterPK parameter is not null, the resource record(s) retrieved must have a PK greater than that value.

[edit] Callback Functions

Method	Summary
registerCallback	Register an external interface as a interested receiver of callback events.
unRegisterCallback	Unregisters an external interface, and deletes all queued up events for that interface.
getCallbackErrors	Gets a list of all call back errors stored on the server.
getVersion	Gets the version of this SOAP Interface.

[edit] Failure Objects

Method	Summary
AccessDeniedFailure	Indicates the method was called within an invalid username or password.
CallbackAlreadyRegisteredFailure	An attempt has been made to register an instance of the callback interface which has already been registered on EService.
CallbackNotRegisteredFailure	An attempt has been made to unregister an instance of the callback interface which is not registered on EService.
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.
CustomerPKMismatchFailure	Indicates the JobCustomerbean contains a CustomerBean whose primary key does not match the Job's customer's primary key.
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.
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.
IllegalEscapeSequenceFailure	Indicates that the escaped "wild card" values passed in were not valid for the method called.
InvalidCallbackVersionFailure	Indicates that the specified version of the callback interface instance, is not a valid CallbackVersion.
JobNotFoundFailure	An attempt was made to progress/update/modify a job, but the primary key or External ID was not found on the server.
ResourceGroupExistsFailure	An attempt was made to create a resource group which already exists on the server.
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.
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.
TooManyFailure	Indicates there are too many records to be returned, and includes the max number of records that can be returned.
UnknownJobStatusProgressionFailure	Indicates a invalid JobStatus field was passed in, please ensure you only use fields from this enumeration.
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.
ValidationFailure	A complex structure of nested arrays of errors, indicating data passed into a method did not match certain criteria for validation.

[edit] Constants and Enumerated Values

Method	Summary
JobStatus	The list of possible states a job may be in, or progressed to.
JobStatusEvent	The list of possible events that may occur, causing a job to change its state.
ConcurrentUpdateSource	The list of possible sources for a concurrency problem.
CancelState	The list of possible cancel states a job can be in.
CallbackVersion	The list of possible versions an external callback interface could implement.
NADSWebserviceVersion	The list of possible interface versions that can be used to comunicate with EService.

[edit] SOAP 3 Example Code

We have prepared a sample application and source code to aid in learning to use the EService SOAP API. Download this now or Contact your local sales representative for assistance.

[edit] 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 :

USA

Phone : 1800 805 6642

Email : Technical Support

New Zealand

Phone : 0800 ECONZ9

Email : Help Desk

Australia