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.
   

<soap:Body>
   <dequeue>
      <subscriberId>54</subscriberId>
      <blockCount>100</blockCount>
      <transactionId>87235</transactionId>
   </dequeue>
</soap:Body>

<soapenv:Body>
   <dequeueResponse>
      <dequeueReturn>
         <count>6</count>
         <transactions>PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48dHJjaz4=</transactions>
      </dequeueReturn>
   </dequeueResponse>
</soapenv:Body>
​​​​​