Glossary Item Box

Government Gateway 2.2.0 (MR-01) ISV Developer Help (Doc Version 06/03/08) | Send comments on this topic.

# DATA_REQUEST

# Message Source/Destination

Portal/Client application to Gateway

#

# Processing

The DATA_REQUEST message enables a client to request the details of the document submissions that the Gateway is currently handling for them. The Class of the document filters the returned list of CorrelationIDs to that type of document. The client can also indicate date/time ranges to further narrow the search.

The client may send a DATA_REQUEST message if it has not received a reply from the Gateway after the PollInterval timeout value supplied on the previous Gateway message (SUBMISSION_ACKNOWLEDGEMENT, SUBMISSION_RESPONSE or ERROR_RESPONSE) has expired.

The DATA_REQUEST message must be authenticated, and therefore requires the same credentials to be presented by the Portal/client application as were used when submitting the original document.

The DATA_RESPONSE message returned from the Gateway will list the documents that matched the criteria in the DATA_REQUEST. The client can therefore determine if the submitted document is being handled by the Gateway by virtue of the fact that the document appears in the DATA_RESPONSE. Documents that have been deleted from the Gateway will not appear in the DATA_RESPONSE. The client should act promptly on documents if concerned about their status - for example Gateway will remove:

- Successful Business responses received from the Department after 60 days
- Business Error responses received from the Department after 30 days

The results set, if any, produced by a DATA_REQUEST will be contained in the body elements of a DATA_RESPONSE message.

# Message Structure

GovTalkMessage | MANDATORY. A default namespace specified as “http://www.govtalk.gov.uk/CM/envelope”.
EnvelopeVersion | MANDATORY. Set to 2.0, or to 1.0 for backward compatibility.
Header | MANDATORY.
MessageDetails | MANDATORY.
Class | MANDATORY. Identifies the class of XML document being queried. This class filters the returned list of CorrelationIDs currently being handled by Gateway.
Qualifier | MANDATORY. Set to request.
Function | MANDATORY. Set to list.
TransactionID | OPTIONAL. If present must conform to the XSD pattern defined in the GovTalk envelope specification ([0-9A-F]{0,32}). This value will be reflected in the DATA_RESPONSE message. It is recommended this value maintains uniqueness to assist the client with interpreting a response from Gateway.
CorrelationID | MANDATORY. Element must be empty.
Transformation | MANDATORY. Set to XML.
GatewayTest | OPTIONAL. For live submissions, where element is present, it must be set to 0. For ISV Test Service, where element is present it must be set to 1.
GatewayTimestamp | OPTIONAL. Element must be empty.
SenderDetails | MANDATORY. If the Portal/client application provided credentials when the original document was submitted (i.e in the SUBMISSION_REQUEST message) then these same credentials must be are provided here. Otherwise it contains no sub-elements.
For username / password authentication the following elements must be set within the SenderDetails/IDAuthentication block:
SenderID | MANDATORY. Set to supplied client account name.
Method | MANDATORY. Set to MD5 or clear.
Value | MANDATORY. If the value of the Method element is clear then Value must contain a clear text password. If the value of the Method element is MD5 then Value is calculated from the clear password by: Converting to lower case and UTF-8 encoding MD5 hashing Base64 encoding
For digital signature authentication the following elements must be set:
Method | MANDATORY. Set to W3Csigned.
Signature | MANDATORY. Must be populated with the XML node structure necessary to provide a valid digital signature block. See the W3C signing documentation on the W3C site (http://www.w3.org/TR/xmldsig-core).
GovTalkDetails | MANDATORY.
Keys | MANDATORY. Any Key elements will be ignored.
GovTalkErrors | OPTIONAL. It is recommended that this element is not present.
Body | OPTIONAL. May be populated with any Date/Time constraints for the query and whether to return identifier information. Note: If Body element is not included all document submissions for the specified class will be returned.
StatusRequest | OPTIONAL. If included, this element can (but does not need to) be scoped by a different namespace; urn:gateway/statusrequest. Note: If this element is not included the subordinate elements below can still be included directly in the Body (see example).
IncludeIdentifiers | OPTIONAL. If included must have a value of 0 or 1. If set to a value of 1 the DATA_RESPONSE message will return identifier information for outstanding submissions. If set to a value of 0 the DATA_RESPONSE message will NOT return identifier information for outstanding submissions. Note: For backward compatibility this element can be omitted and identifier information will NOT be returned.
StartDate | OPTIONAL. Set to a valid date, of the format dd/mm/yyyy.
StartTime | OPTIONAL. Set to a valid time, of the format hh:mm:ss. If this element is used a valid StartDate must also be set.
EndDate | OPTIONAL. Set to a valid date, of the format dd/mm/yyyy. If this element is used a valid StartDate must also be set which must be earlier than or the same as the value in EndDate.
EndTime | OPTIONAL. Set to a valid time of the format hh:mm:ss. If this element is used a valid EndDate must also be set. If the same start and end date are used this time must be later than the start time.

# Samples

The mandatory elements within the following sample data request are shown in bold while optional elements appear in normal type.
<?xml version="1.0"?> <GovTalkMessage xmlns="http://www.govtalk.gov.uk/CM/envelope"> <EnvelopeVersion>2.0</EnvelopeVersion> <Header> <MessageDetails> <Class>MOSWTSC2</Class> <Qualifier>request</Qualifier> <Function>list</Function> <CorrelationID/> <Transformation>XML</Transformation> </MessageDetails> <SenderDetails> <IDAuthentication> <SenderID>VendorID</SenderID> <Authentication> <Method>MD5</Method> <Value>fSgjkCA3I9k/J24Y5M3qhuQs=</Value> </Authentication> </IDAuthentication> </SenderDetails> </Header> <GovTalkDetails> <Keys/> </GovTalkDetails> <Body> <IncludeIdentifiers>1</IncludeIdentifier> <StartDate>13/11/2006</StartDate> <StartTime>16:00:00</StartTime> <EndDate>13/11/2006</StartDate> <EndTime>16:30:00</EndTime> </Body> </GovTalkMessage>

© Crown Copyright 2008. All rights reserved