Glossary Item Box

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

# SUBMISSION_REQUEST

# Message Source/Destination

Portal/Client application to Gateway

#

# Processing

The SUBMISSION_REQUEST message is the initial message sent between the client application and the Gateway.

This message contains the document for the Target Spoke (i.e. Department) back-end system in the GovTalkMessage Body. This payload in the body is opaque to the Gateway and is associated with an appropriate XML namespace. The document contained within the Body element must include a single root XML node which wraps the data.

The Class, in addition to identifying the document type in the GovTalkMessage Body, is used by Gateway to identify the Target Spoke (i.e. Department) and the service the document is to be routed to.

Whether the SenderDetails is required in the message depends on the target service's Authentication Level (configured in the Gateway) which is the minimum authentication credential an entity must have to use the service. This value is used by the Gateway to determine the checking/authentication to be performed:

- Level 0:
  - Type 0: SenderDetails not checked
  - Type 1: SenderDetails checked for either:
    - A User ID registered with the Gateway (password is not checked)
    - A valid certificate (though not necessarily known to Gateway) with a valid message digest
  - Type 2: SenderDetails checked for a valid certificate (though not necessarily known to Gateway) with a valid message digest
- Level 1: SenderDetails (either User ID/password or certificate) authenticated by Gateway. The enrolment (identified by Keys) can be access either by a client enrolled in the service or an agent authorised to use the enrolment.
- Level 2: SenderDetails (must be certificate) authenticated by Gateway. The enrolment (identified by Keys) can be access either by a client enrolled in the service or an agent authorised to use the enrolment.

Note:

Submissions from an organisation/agent can be made by a Delegated Rights Management (DRM) User (as well as by a normal Gateway User or Assistant). A DRM user is setup up for an organisation/agent – through the Gateway UI (www.gateway.gov.uk) by an existing Gateway User within the organisation/agent – to represent the organisation. Through the UI the User specifies:

- DRM user's authentication credential (i.e. username/password or digital signature)
- DRM user's email address
- Subset of direct enrolments (and additionally for agents, a subset of the client allocations) the organisation/agent has for which the DRM User can make submissions

# 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 contained within the Body.
Qualifier | MANDATORY. Set to request.
Function | MANDATORY. Set to submit.
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 SUBMISSION_ERROR or SUBMISSION_RESPONSE message back to the Portal/client application. It is recommended this value maintains uniqueness to assist the client (i.e. Portal or client application) with interpreting a response from Gateway.
AuditID | OPTIONAL. If present must conform to the XSD pattern defined in the GovTalk envelope specification ([0-9A-F]{0,32}). The Gateway forwards this value on to the Target Spoke (i.e Department).
CorrelationID | MANDATORY. Element must be empty.
ResponseEndPoint | OPTIONAL. It is recommended that this element is not present. If present it should 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 | OPTIONAL. Either a username/password or digital signature authentication block (as described below) will be included. This is the credentials of the client initiating the business message. Note: If the SUBMISSION_REQUEST is made for a Level 0 (Type 0) then authentication credentials are not required – see description of Level/Type in Processing section (above). This element will be empty or can be omitted.
EmailAddress | OPTIONAL. This allows a client to specify a SMTP notification address for the current submission. If element is omitted (or included, but left empty) then the user's email address registered with the Gateway will be used. Provided the Send Mail flag (on the Gateway) for this class of transaction is set, then the initiator of this message will be notified when a response has been received from the back-end system.
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. The use of clear is not recommended.
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
Key | OPTIONAL. Must contain the appropriate Key element/attribute entries that identify the enrolment the entity has for the document type being submitted. Note: If the authentication level of the target service is Level 0 (Type 0, 1 or 2) then no Key elements are required.
TargetDetails | OPTIONAL. It is recommended that this should not be present.
Organisation | OPTIONAL. If present must be populated with a string between 1 and 64 characters in length.
GatewayValidation | OPTIONAL. It is recommended that this element is not present. Note: The subordinate fields of this element are not currently used by the submission protocol.
ChannelRouting | OPTIONAL. This element and any valid subordinates may be present. Application vendors may use this element and its subordinates to communicate details of their application name and version together with any specific transaction ID values for this submission. Note: The subordinate fields of this element are not currently used by the submission protocol.
GovTalkErrors | OPTIONAL. It is recommended that this element is not present.
GatewayAdditions | OPTIONAL. Element should be empty.
Body | OPTIONAL. Should contain a valid document for the specified transaction type. The document contained within this element must have a single root node associated with a default namespace other than http://www.govtalk.gov.uk/CM/envelope and must be particular to the submitted document type.

# Samples

The mandatory elements within the following sample submission 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>submit</Function> <TransactionID>20021202ABC</TransactionID> <CorrelationID></CorrelationID> <Transformation>XML</Transformation> <GatewayTest>0</GatewayTest> <GatewayTimestamp></GatewayTimestamp> </MessageDetails> <SenderDetails> <IDAuthentication> <SenderID>Test000001</SenderID> <Authentication> <Method>MD5</Method> <Value>fSgjkCA3I9k/J24Y5M3qhu==</Value> </Authentication> </IDAuthentication> <EmailAddress>someone@somewhere.com</EmailAddress> </SenderDetails> </Header> <GovTalkDetails> <Keys> <Key Type="RefNo">0000442355</Key> <Key Type="DOB">29/07/1955</Key> <Key Type="TCH">24-22</Key> </Keys> </GovTalkDetails> <Body> <!-- A valid Body payload with a namespace declaration on the first element --> </Body> </GovTalkMessage>

© Crown Copyright 2008. All rights reserved