ESS Dequeue
Dequeue
Given a subscriber identifier, retrieves a block of transactions from the ESS queue for that subscriber.
DEPRECATED
This webservice is deprecated in favor of the new High-Volume Dequeue, which boasts higher transaction throughput and efficiency.
Please make plans to adopt the new webservice in your integration code.
This method is used by subscribers to retrieve ESS transactions. Callers may specify the maximum desired number of transactions to be dequeued and returned in the transaction block, although the maximum is internally subject to the Omnitracs-specified maximum transaction block count configured for the given subscriber. The number of transactions returned is also limited by the fixed size of the transaction buffer (64k). The actual number of transactions dequeued and returned in the transaction block is provided as an attribute of the TransactionBlock data type.
ESS supports acknowledged dequeuing, which requires the subscriber to provide positive acknowledgement for a set of successfully received transactions dequeued in a prior call. The acknowledgement is provided by the subscriber in the form of the transactionId input parameter indicating the highest value transaction ID successfully processed in the prior call. Upon receipt of a non-zero acknowledged transaction ID, ESS will permanently delete all of the subscriber's transactions whose transaction IDs are less than or equal to the acknowledged transaction ID. A zero-value acknowledged transaction ID indicates no prior transactions are being acknowledged.
Implementation Recommendations:
- Dequeue Calling Interval - Optimal client-side and server-side efficiency and performance can be acheived by ensuring each dequeue web service call returns the maximum number of allowable transactions possible (i.e. a full return transaction block). This can be accomplished by optimizing the time interval between successive dequeue web service calls. The optimal time interval will differ for each customer and is directly related to the volume of customer transactions. A 15 minute calling interval is considered optimal in most instances.
- Multi-Threaded Clients - Particular care should be taken when implementing multi-threaded clients capable of issuing concurrent calls to the dequeue web service for the same subscriber. If the threads do not synchronize their acknowledgement of the transactions dequeued from their shared subscriber, duplicate transaction data may be subsequently dequeued. While this will not result in any data loss or corruption on the server-side, it does complicate the client-side implementation and negatively impacts the efficiency of the overall process.
TransactionBlock dequeue(int subscriberId, int blockCount, int transactionId) throws WSException
- subscriberId: The identifier of the subscriber from whose queue transactions will be retrieved. The valid range for this field is 0-999999999. ESS subscriber IDs are unique, read-only identifiers (integers) that are automatically assigned by the SP when you create a new subscriber via the user interface. These are referred to as the "reference" in the UI. Each subscriber you create is given its own transaction queue on the system. The system enqueues transactions to each subscriber's queue based upon the set of transaction type subscriptions held by the subscriber at that time. Customers dequeue transactions from a specific subscriber's queue by specifying its subscriber ID value when calling this web service. Typically, customers will create a single subscriber and a corresponding set of transaction type subscriptions. Although, based upon your integration needs, you may opt to create multiple subscribers, each having its own set of subscriptions. Each subscriber may have identical or different subscriptions if desired.
- blockCount: An integer indicating the maximum number of transactions to retrieve in this request. The number of transactions returned will be less than or equal to this value. The valid range for this field is 0-999.
- transactionId: An integer indicating the identifier of the last transaction successfully dequeued and processed by the subscriber. ESS will permanently delete all transactions for this subscriber whose identifiers are less than or equal to this value. ESS will return transactions that follow this transaction identifier in the queue. A zero-value acknowledged transaction ID indicates no prior transactions are being acknowledged. The valid range for this field is 0-999999999. See ESS TransactionBlock.
Sample XML Request
Only the SOAP body is shown. To see a sample SOAP Envelope and Header, click here.
<soap:Body> <dequeue> <subscriberId>54</subscriberId> <blockCount>100</blockCount> <transactionId>87235</transactionId> </dequeue> </soap:Body>
Sample XML Response
<soapenv:Body> <dequeueResponse> <dequeueReturn> <count>6</count> <transactions>PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48dHJjaz4=</transactions> </dequeueReturn> </dequeueResponse> </soapenv:Body>
Exceptions
001 Unknown Error.
002 Required field not specified.
004 User not authorized.
005 Subscriber ID not found.
006 Subscriber ID is out of valid range.
007 Block Count is out of valid range.
008 Transaction ID is out of valid range.