SOAP 3 Documentation

From
(Difference between revisions)
Jump to: navigation, search
m (Failure Objects)
(Best Practises)
 
(62 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
== The EService SOAP 3 API ==
 
== The EService SOAP 3 API ==
The [[SOAP|SOAP]] 3 api is an external interface which allows authorised users to directly connect their job management 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.
+
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, 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 [[SOAP_3_Callback_Documentation|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 [[#Further Help|local sales representative]] for further information.
  
 
== The Interface Definition ==
 
== 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 authorised users are able to access the interface.
+
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.
 
Please select a link to see documentation on each method's function and features.
Line 18: Line 35:
 
|---- bgcolor=#EDEDFF
 
|---- bgcolor=#EDEDFF
 
|[[updateJob]]
 
|[[updateJob]]
|Updates an existing job, based on the data passed in.
+
|Updates an existing job, based on the data passed in.  Does not apply to Verizon Wireless Cellphones.
 
|---- bgcolor=#EDEDFF
 
|---- bgcolor=#EDEDFF
 
|[[progressJobStatus]]
 
|[[progressJobStatus]]
|Moves a job forwards through its logical state transitions.
+
|Moves a job forwards through its logical state transitions.  Does not apply to Verizon Wireless Cellphones.
 
|---- bgcolor=#EDEDFF
 
|---- bgcolor=#EDEDFF
 
|[[onHoldJob]]
 
|[[onHoldJob]]
Line 48: Line 65:
 
|---- bgcolor=#EDEDFF
 
|---- bgcolor=#EDEDFF
 
|[[getJobSummariesBetween]]
 
|[[getJobSummariesBetween]]
|Retrieves a series of summaries of requested jobs between two selected dates.
+
|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.  
 +
 
 
|---- bgcolor=#EDEDFF
 
|---- bgcolor=#EDEDFF
 
|[[getJobSummariesBetweenStatusAfterPK]]
 
|[[getJobSummariesBetweenStatusAfterPK]]
Line 76: Line 94:
 
|[[ackJobSynchronisation]]
 
|[[ackJobSynchronisation]]
 
|Acknowledges that synchronisation has been performed on the selected jobs.
 
|Acknowledges that synchronisation has been performed on the selected jobs.
 +
|---- bgcolor=#EDEDFF
 +
|[[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.
 
|}
 
|}
  
Line 110: Line 131:
 
|[[ackCustomerSynchronisation]]
 
|[[ackCustomerSynchronisation]]
 
|Acknowledges all specified customers as having been synchronised.
 
|Acknowledges all specified customers as having been synchronised.
 +
|---- bgcolor=#EDEDFF
 +
|[[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.
 +
 
|}
 
|}
  
Line 137: Line 162:
 
|[[ackUserSynchronisation]]
 
|[[ackUserSynchronisation]]
 
|Acknowledges that synchronisation has been performed on the selected users.
 
|Acknowledges that synchronisation has been performed on the selected users.
 +
|---- bgcolor=#EDEDFF
 +
|[[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.
 +
 
|}
 
|}
  
Line 202: Line 231:
 
|[[deleteResourceGroup]]
 
|[[deleteResourceGroup]]
 
|Deletes an existing resource group.
 
|Deletes an existing resource group.
 +
|---- bgcolor=#EDEDFF
 +
|[[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.
 +
 
|}
 
|}
  
Line 233: Line 266:
 
|[[CallbackAlreadyRegisteredFailure]]
 
|[[CallbackAlreadyRegisteredFailure]]
 
|An attempt has been made to register an instance of the callback interface which has already been registered on EService.
 
|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
 
|---- bgcolor=#EDEDFF
 
|[[CustomerNotFoundFailure]]
 
|[[CustomerNotFoundFailure]]
Line 248: Line 284:
 
|[[IllegalEscapeSequenceFailure]]
 
|[[IllegalEscapeSequenceFailure]]
 
|Indicates that the escaped "wild card" values passed in were not valid for the method called.
 
|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
 
|---- bgcolor=#EDEDFF
 
|[[JobNotFoundFailure]]
 
|[[JobNotFoundFailure]]
Line 294: Line 333:
 
|[[CallbackVersion]]
 
|[[CallbackVersion]]
 
|The list of possible versions an external callback interface could implement.
 
|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 ==
 
== SOAP 3 Example Code ==
  
This is series of examples showing the use of the EService [[SOAP|SOAP]] API.
+
We have prepared a sample application and source code to aid in learning to use the EService SOAP API.  [[Downloads|Download]] this now or Contact your [[#Further Help|local sales representative]] for assistance.
  
== Best Practises ==
+
== Further Help ==
 +
Details about our EService system can be found at http://www.eservice.econz.com
  
This contains a series of hints and suggestions for getting the most out of the interface.
+
Details about our timecard system can be found at http://www.timecard.econz.com
  
== Further Help ==
 
  
This contains various contact details for people seeking further assistance in utilizing the [[SOAP|SOAP]] Interface.
+
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>
 +
 
 +
Email : [mailto:helpdesk@econz.com Help Desk]

Latest revision as of 21:37, 11 December 2013

Contents

[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

Email : Help Desk

Personal tools
MediaWiki Appliance - Powered by TurnKey Linux