ePriority® and the ePriority logo are registered trademarks of DST Systems, Inc.
Contents
|
Contents |
Appendices |
|---|---|
Introduction
The Batch Status Service is a facility that can be used to obtain information about an existing batch. The batch must already be submitted and detected by our batch processor (detection normally occurs within five minutes of submission). The following information is available for a batch queried using the Batch Status Service:
- Process State
- Delivery State
- Control
- Email Count
- Batch Archive Path
The Batch Status Service can also be used to release pending batches (Control=pending).
Batch Status Service API
Users of the Batch Status Service will query the ePriority web site (www.epriority.com) using http request parameters in the URL. There are two methods of querying the service for a specific batch. The first method requires specifying the batch id. This single piece of information uniquely identifies an ePriority batch. The second method requires a client batch id paired with a client id. Together, these two pieces of information can also identify a specific ePriority batch. Note that failed batches may be resubmitted using the same client batch id, resulting in multiple batches with the same client batch id. In this case, the Service will choose the most recently submitted batch identified by the given client batch id.
The result of a query to the Batch Status Service is an XML file. An XML file will always be returned even when the batch specified is not found or an error occurred. The returned XML file will contain batch status information. If the batch was not found or an error occurred, the process_state element in the XML response will have a value of 'n/a'. Note that when a batch is not found it is not "technically" an error, but the same format is used for non-existent batches as error conditions since there is no batch information to return.
If a query of a pending batch (Control=pending) is accompanied by the action=release parameter, the batch will be released and the new status returned (Control=releasing). Delivery will not begin until the system has processed the new start-delivery and stop-delivery dates for the batch, based on the releasing time. As soon as this processing is complete the Control value will change to 'none' and delivery can begin.
Authentication
The cid (ePriority Client ID), authDate and authHash parameters are required for authentication of all Web API requests. See authentication instructions.
Inputs
You may query the status of a batch using either the ePriority internal Batch ID or the Client Batch ID.
- Query the Batch Status Service using the target batch id.
Syntax:
http://epriority.com/BatchStatus?cid=1234&authDate=1997-07-16T19:20:30& authHash=a19671a63d786d1314b28f2a58e3c4ee&bid=<target_batch_id>
Example:
http://epriority.com/BatchStatus?cid=1234&authDate=1997-07-16T19:20:30& authHash=a19671a63d786d1314b28f2a58e3c4ee&bid=2001042155
- Query the Batch Status Service using the target client batch id.
Syntax:
http://epriority.com/BatchStatus?cid=1234&authDate=1997-07-16T19:20:30& authHash=a19671a63d786d1314b28f2a58e3c4ee&cbid=<target_client_batch_id>
Example:
http://epriority.com/BatchStatus?cid=1234&authDate=1997-07-16T19:20:30& authHash=a19671a63d786d1314b28f2a58e3c4ee&cbid=annual_prospectus_20110930
- Request pending batch release using the target client batch id.
Syntax:
http://epriority.com/BatchStatus?cid=1234&authDate=1997-07-16T19:20:30& authHash=a19671a63d786d1314b28f2a58e3c4ee&cbid=<target_client_batch_id>&action=release
You may release a pending batch using either the ePriority internal Batch ID or the Client Batch ID.
- Release batch using the target batch id.
Syntax:
http://epriority.com/BatchStatus?cid=1234&authDate=1997-07-16T19:20:30& authHash=a19671a63d786d1314b28f2a58e3c4ee&bid=<target_batch_id>&action=release
Example:
http://epriority.com/BatchStatus?cid=1234&authDate=1997-07-16T19:20:30& authHash=a19671a63d786d1314b28f2a58e3c4ee&bid=2001042155&action=release
- Release batch using the target client batch id.
Syntax:
http://epriority.com/BatchStatus?cid=1234&authDate=1997-07-16T19:20:30& authHash=a19671a63d786d1314b28f2a58e3c4ee&cbid=<target_client_batch_id>&action=release
Example:
http://epriority.com/BatchStatus?cid=1234&authDate=1997-07-16T19:20:30& authHash=a19671a63d786d1314b28f2a58e3c4ee&cbid=annual_prospectus_20110930&action=release
Outputs
- Successful Query: A batch was found.
Example:
<?xml version="1.0" encoding="UTF-8"?>
<batch_status xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="www.epriority.com/remote/batchstatus.xsd">
<process_state>succeeded</process_state>
<delivery_state>completed</delivery_state>
<control>none</control>
<email_count>3255</email_count>
<archivePath>/client/1105/archive</archivePath>
</batch_status>
- Unsuccessful Query: The batch was not found or a error occurred.
Example:
<?xml version="1.0" encoding="UTF-8"?>
<batch_status xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="www.epriority.com/remote/batchstatus.xsd">
<process_state>n/a</process_state>
<delivery_state>not started</delivery_state>
<control>none</control>
<email_count>0</email_count>
<archivePath />
</batch_status>
Appendix A: XML Tag Definitions
| Tag | Description | XML Schema Type |
|---|---|---|
| batch_status | The outermost tag for the Batch Status Service defines the namespace and XML schema location. | complexType |
| process_state | Designates the processing state for the batch. | enumeration: n/a || succeeded || failed |
| delivery_state | Designates the delivery state for the batch. This will always be 'not started' unless the process_state is succeeded. | enumeration: not started || delivering || redelivering || completed |
| control | Indicates if batch delivery is pending or batch has been released, halted or aborted. | enumeration: none || halted || aborted || pending || releasing |
| email_count | The number of emails in the batch. This is 0 unless processing has succeeded. | integer |
| archivePath | The ftp path where batch files, archives and logs are stored. This path will only exist when processing has succeeded. If processing has succeeded and delivery is completed, the path will exist until the archive expiration specified in the batch's profile. | string: a directory path without a trailing '/' char. |
Appendix B: XML Schema File
Permanent Location of XML Schema:
www.epriority.com/remote/batchstatus.xsd
<?xml version="1.0"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:annotation>
<xsd:documentation xml:lang="en">
batch query schema for epriority.com.
Copyright 2003 epriority.com. All rights reserved.
</xsd:documentation>
</xsd:annotation>
<xsd:element name="batch_status" type="batchInfoType" />
<xsd:complexType name="batchInfoType">
<xsd:sequence>
<xsd:element name="process_state" type="processType"/>
<xsd:element name="delivery_state" type="deliveryType"/>
<xsd:element name="control" type="controlType"/>
<xsd:element name="email_count" type="xsd:integer"/>
<xsd:element name="archive_path" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
<xsd:simpleType name="processType">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="n/a"/>
<xsd:enumeration value="succeeded"/>
<xsd:enumeration value="failed"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="deliveryType">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="not started"/>
<xsd:enumeration value="delivering"/>
<xsd:enumeration value="redelivering"/>
<xsd:enumeration value="completed"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="controlType">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="none"/>
<xsd:enumeration value="halted"/>
<xsd:enumeration value="aborted"/>
<xsd:enumeration value="pending"/>
<xsd:enumeration value="releasing"/>
</xsd:restriction>
</xsd:simpleType>
</xsd:schema>