SOAP 3 Documentation

From
(Difference between revisions)
Jump to: navigation, search
Line 133: Line 133:
 
|---- bgcolor=#EDEDFF
 
|---- bgcolor=#EDEDFF
 
|[[getUnsynchronisedUsers]]
 
|[[getUnsynchronisedUsers]]
|Retrieves all users who have not previously been synchronised and acknowledged, and all jobs that have changed since their last synchronisation.
+
|Retrieves all users who have not previously been synchronised and acknowledged, and all users that have changed since their last synchronisation.
 
|---- bgcolor=#EDEDFF
 
|---- bgcolor=#EDEDFF
 
|[[ackUserSynchronisation]]
 
|[[ackUserSynchronisation]]
Line 174: Line 174:
 
|---- bgcolor=#EDEDFF
 
|---- bgcolor=#EDEDFF
 
|[[createResource]]
 
|[[createResource]]
|Creates a new resource based on the resource data passed in.
+
|Creates a new resource based on the resource data passed in, and attachs it to the specified resource group.
 
|---- bgcolor=#EDEDFF
 
|---- bgcolor=#EDEDFF
 
|[[getResourceList]]
 
|[[getResourceList]]
|.
+
|Gets the full list of all resources stored for this organisation.
 
|---- bgcolor=#EDEDFF
 
|---- bgcolor=#EDEDFF
 
|[[getResource]]
 
|[[getResource]]
|.
+
|Gets the full details of a single resource.
 
|---- bgcolor=#EDEDFF
 
|---- bgcolor=#EDEDFF
 
|[[getResourcesUpdatedSince]]
 
|[[getResourcesUpdatedSince]]
|.
+
|Gets the full details of all resources updated since the specified date and time.
 
|---- bgcolor=#EDEDFF
 
|---- bgcolor=#EDEDFF
 
|[[deleteResource]]
 
|[[deleteResource]]
|.
+
|Marks a specific resource as deleted.
 
|---- bgcolor=#EDEDFF
 
|---- bgcolor=#EDEDFF
 
|[[getUnsynchronisedResources]]
 
|[[getUnsynchronisedResources]]
|.
+
|Retrieves all resources which have not previously been synchronised and acknowledged, and all resources that have changed since their last synchronisation.
 
|---- bgcolor=#EDEDFF
 
|---- bgcolor=#EDEDFF
 
|[[ackResourceSynchronisation]]
 
|[[ackResourceSynchronisation]]
|.
+
|Acknowledges that synchronisation has been performed on the selected resources.
 
|---- bgcolor=#EDEDFF
 
|---- bgcolor=#EDEDFF
 
|[[getResourceGroups]]
 
|[[getResourceGroups]]
|.
+
|Gets a list of all resource group names.
 
|---- bgcolor=#EDEDFF
 
|---- bgcolor=#EDEDFF
 
|[[createResourceGroup]]
 
|[[createResourceGroup]]
|.
+
|Creates a new resource group.
 
|---- bgcolor=#EDEDFF
 
|---- bgcolor=#EDEDFF
 
|[[deleteResourceGroup]]
 
|[[deleteResourceGroup]]
|.
+
|Deletes an existing resource group.
 
|}
 
|}
  
Line 213: Line 213:
 
|---- bgcolor=#EDEDFF
 
|---- bgcolor=#EDEDFF
 
|[[unRegisterCallback]]
 
|[[unRegisterCallback]]
|.
+
|Unregisters an external interface, and deletes all queued up events for that interface.
 
|---- bgcolor=#EDEDFF
 
|---- bgcolor=#EDEDFF
 
|[[getCallbackErrors]]
 
|[[getCallbackErrors]]
|.
+
|Gets a list of all call back errors stored on the server.
 
|---- bgcolor=#EDEDFF
 
|---- bgcolor=#EDEDFF
 
|[[getVersion]]
 
|[[getVersion]]
|.
+
|Gets the version of this SOAP Interface.
 
|}
 
|}
  
Line 260: Line 260:
 
|---- bgcolor=#EDEDFF
 
|---- bgcolor=#EDEDFF
 
|[[JobStatusEvent]]
 
|[[JobStatusEvent]]
|.
+
|The list of possible events that may occur, causing a job to change its state.
 
|---- bgcolor=#EDEDFF
 
|---- bgcolor=#EDEDFF
 
|[[ConcurrentUpdateSource]]
 
|[[ConcurrentUpdateSource]]
|.
+
|The list of possible sources for a concurrency problem.
 
|---- bgcolor=#EDEDFF
 
|---- bgcolor=#EDEDFF
 
|[[CancelState]]
 
|[[CancelState]]
|.
+
|The list of possible cancel states a job can be in.
 
|}
 
|}
  

Revision as of 06:18, 11 May 2005

Contents

The EService SOAP 3 API

The 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 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 authorised 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

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.
progressJobStatus Moves a job forwards through its logical state transitions.
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 a series of summaries of requested jobs between two selected dates.
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.

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.

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.

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.

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.

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.

Failure Objects

Method Summary
AccessDeniedFailure Indicates the method was called within an invalid username or password.
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.
JobNotFoundFailure An attempt was made to progress/update/modify a job, but the primary key or External ID was not found on the server.
UnknownJobStatusProgressionFailure Indicates a invalid JobStatus field was passed in, please ensure you only use fields from this enumeration.
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

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.

SOAP 3 Example Code

This is series of examples showing the use of the EService SOAP API.

Best Practises

This contains a series of hints and suggestions for getting the most out of the interface.

Further Help

This contains various contact details for people seeking further assistance in utilizing the SOAP Interface.

Personal tools
MediaWiki Appliance - Powered by TurnKey Linux