Royal Mail Confidential Information

Royal Mail Confidential Information

Royal Mail Wholesale

Mixed Weight solution

External Web Services

Version: 4.0

1st August2011

1Document Control

1.1Contact Details

1.2Change Control

1.3Terms & Abbreviations

2Purpose

3Scope

4Introduction toMixed Weight

5Mixed Weight Web Service Interfaces

5.1Security

5.2Docket

5.2.1Docket Flow Description

5.2.2Docket Notes

5.2.3Import Container/Append Container Methods

5.2.4Import Container/Append Container WSDL

5.2.5Import Container/Append Container Request Data Elements

5.2.6Import Container/Append Container Response Data Elements

5.2.7Import Container/Append Container XML Structures

5.2.8Import Container/Append Container Examples

5.2.9Import Container/Append Container Examples SOAP Request

5.2.10Import Container/Append Container Examples SOAP Response

5.2.11Import Container/Append Container Manual File Loading

5.2.12Delete Container Method

5.2.13Delete Container WSDL

5.2.14Delete Container Request Data Elements

5.2.15Delete Container Response Data Elements

5.2.16Delete Container XML Structure

5.2.17Delete Container Example

5.2.18Delete Container Example SOAP Request

5.2.19Delete Container Example SOAP Response

5.2.20Delete Container Manual File Loading

5.2.21Create Container Method

5.2.22Create Container WSDL

5.2.23Create Container Request Data Elements

5.2.24Create Container Response Data Elements

5.2.25Create Container XML Structure

5.2.26Create Container Example

5.2.27Create Container Example SOAP Request

5.2.28Create Container Example SOAP Response

5.2.29Create Container Manual File Loading

5.2.30Exception Container Method

5.2.31Exception Container WSDL

5.2.32Exception Container Request Data Elements

5.2.33Exception Container Response Data Elements

5.2.34Exception Container XML Structures

5.2.35Exception Container Example

5.2.36Exception Container Example SOAP Request

5.2.37Exception Container Example SOAP Response

5.2.38Exception Container/Manual File Loading

5.3Error Messages

5.4Error Messages Example Response

5.5URL’S

1Document Control

1.1Contact Details

Role / Name / Email Address
Onyemaechi Ezugwu / IT Project Manager /
Telephone / Office Address:
020 7650 2136 or 07590 352 727 / Royal Mail Wholesale
148 Old Street, London, EC1V 9HQ

If you require any further assistance or have questions regarding the content of any part of this document, in the first instance all enquiries should be made through the above person.

1.2Change Control

Any changes to this document will be controlled and distributed by the document owner above.

Issue / Author / Date / History
v1.0 / Onyemaechi Ezugwu / 5h Feb 2010 / Initial Document release
V2.0 / Onyemaechi Ezugwu / 15th Mar 2010 / Updated IntAccount field reference to IntermediaryAccount. Additional sectionscovering XML structure/examples and SOAP requests/responses for the container web services. Additional section covering Error IDs/Messages and error response examples. General formatting of document.
V3.0 / Onyemaechi Ezugwu / 18thJun 2010 / Inclusion of additional Error message identifiers 307B905 and 307B906
V4.0 / Onyemaechi Ezugwu / 11th May 2011 / Updated XML examples to include item weights associated with the additional 4th Weight Band. Clarification against the specification table attributes affected by the additional weight band. Inclusion of the method of approach when dealing with Manual file loading incase of webservice error

1.3Terms & Abbreviations

Term or Abbreviation / Description
DocketHUB / A Third Party System currently used by Royal Mail Wholesale
E*Pro / A Royal Mail System currently used by Royal Mail Wholesale
SOAP / Simple Object Access Protocol
WSDL / Web Service Definition Language

2Purpose

This document is designed to provide Royal Mail Wholesale Customers and posters with guidelines and detailed specifications for use with the web service interfaces for the Mixed WeightService.

3Scope

The web service interfaces included in the document are:

Docket upload
Exceptions upload

4Introduction toMixed Weight

The Mixed Weight service option enables Customers handing over Large Letters, A3 Packets or Packets at an Inward Mail Centre to combine, within a single format, Mailing Items of different weight bands within a container. Mailing items must be sorted by the Customer to the Access 120, Access 1400 or Access Walksort selections. As is the case for all other services, Mixed Weight may not be used for handing over mixed formats in any container.

This technical specification has been based on the original Wholesale Management System (WMS) specification. The Mixed Weight solution makes use of the DocketHUB application to accept the Mixed Weight line listing and then push it through into E*pro. This document outlines the nuances between the DocketHUB and WMS versions of Mixed Weight as well as outlining the specific requirements of thesolution through DocketHUB.

5Mixed Weight Web Service Interfaces

5.1Security

Secure Web Service Access and Data Transmission

The Customer system will be required to submit known login security data each time mailing information is exported to the web service. A unique login (user identifier (UserID)/ password and access code) will be provided to each Customer requiring access to the new Mixed Weightweb service.

UserID and Password Validations:

The UserID and Password will follow current Royal Mail Group criteria. UserIDs will be no less than 8 characters in length and alpha numeric / special characters will be allowed.

Password Expiry:

Users will not be able to change the Mixed Weight web service passwords as doing so could affect the transfer of data out of core hours support. If a Customer requires a change to a password they must contact with a formal request.

5.2Docket

5.2.1Docket Flow Description

Carriers system uploads manifest data via published web service interfaces into DocketHUB. The first response from DocketHUB will include a transaction ID which is used to append subsequent batches of manifest data. Any errors will be returned in the response from DocketHUB.
Once all manifest data is successfully transferred to DocketHUB the carriers system calls the confirm web service interface with the transaction ID. This creates a virtual docket number that is returned to the client.
DocketHUB uploads the carriers Mixed Weight manifest to the E*Pro system via published web service interfaces.
DocketHUB calls the published E*Pro web service interface to create the docket.
An Email of the docket details is sent to a contact list provided by the carrier.
Exceptions are uploaded by the carrier via published web service interfaces into DocketHUB.
Exceptions are uploaded to the E*Pro system via the published web service interface.

5.2.2Docket Notes

Docket uploads follow the same restrictions as the current services as specified in the Royal Mail Condition 9 User guide.

The web services will retain the existing E*Pro limitations of batches of up to 2000 containers per transaction. (A container being a bag, tray, etc.)

Regardless of the size of the request, DocketHUB will provide details of the number of successfully uploaded containers or an error message for each container within a request should a container be rejected.

For Mixed Weight containers, up to fouraverage weight values can be passed per container.

For National Postings a single container could contain mail belonging to each applicable Mixed Weight average weight band e.g. 5 Items at 75g (0g -100g), 4 Items at 150g (101g -251g), 5 Items at 300g (251g-2000g), 1 item at 2100g (2001g -5000g). Each combination of Items and average weight at eachweightband would be priced individually and an overall price for the whole bag is then calculated.

For Zonal Postings, a single container could contain mail belonging to each applicable weight band and each zone.
There is a restriction on the specification of average item weight; within any specific weight band, all zones must specify the same average item weight. For example; for items with an average weight in weight band 3 (>251g – 2000g), specifying Zone A, average weight 251 and Zone B, average weight 252 will result in an error when loading the line listing since they are not the same average weight for this one weight band.

5.2.3Import Container/Append Container Methods

DT_RESPONSE = MI_OS_IMPORT(DT_REQUEST)

DT_RESPONSE = MI_OS_APPEND(DT_REQUEST)

5.2.4Import Container/Append Container WSDL

The SOAP Address Location in the WSDLs is specified as the production URL. You may have to change this to the corresponding UAT URL in section 5.5.

5.2.5Import Container/Append Container RequestData Elements

Mandatory = Must always be present otherwise container will be rejected.

Optional = Can be omitted.

Ignored = Used only in the Mixed Weight solution. The data is not used by the DocketHUB system and will not be validated.

Header

Field / Field Length / Mandatory (M)/
Optional (O) /Ignored (I) / Description
UserID / Alpha Num 30 / M / The user identification used for authentication by the web service.
Password / Alpha Num 30 / M / The user name used for authentication by the web service.
Carrier / Num 4 / M / (In WMS this identifies the carrier of the mail.) In the Mixed Weight solution this field identifies the user access code that is currently used in the E*Pro docket import web services for authentication.
(This will change in the new WMS solution.)
(In WMS the length of the field is Alpha Num 10 whereas in the Mixed Weightsolutionit is Num 4 due to a different security model.
Poster / Alpha Num 9 / M / Identifies the account that will be invoiced for the mail. (can be same as carrier details in new WMS solution)
(In WMS the field is 10 characters.)
The length of the field is restricted to 9 in the Mixed Weight solutionto complywith the Royal Mail E*Pro system.
PostingDate / Date 08 / M / Date the mail was posted. (DDMMYYYY)
OrderNumber / Alpha Num 9 / O / Customer reference data.
(In WMS this is specified as 20 characters.)The length of the field is restricted to 9 in the Mixed Weightsolution due to the functionality of this needing to be compliant with Royal Mail E*Pro.
IntermediaryAccount / Alpha Num 10 / O in WMS
I in DHUB / Can be used to capture intermediary (e.g. mailing house) account details.
TransactionID / Char 32 / M / (On append only), the transaction identifierreturned by posting the initial container upload.

Detail

Field / Field Length / Mandatory (M)/
Optional(O) /Ignored (I) / Description
BagID / Alpha Num 12 / M / Minimum 1 Character.
(In WMS this is specified as 14 characters.) The length is restricted to 12 in the Mixed Weightsolution due to the functionality of this needing to be compliant with the Royal Mail E*Pro system.
SSC / Num(5) / M / Identifies the destination of the container.
ProductCode / Char 3 / M / The three character product code that will be billed against.
Format / Char 1 / M in WMS
O/I in DHUB / Associated with product code, the format of the mail being posted (1 = Letter, 2 = Large Letter / Flat, 3 = Packet, 4 = A3)
DiscountSurcharge / Char 1 / O in WMS
I in DHUB / If the product allows a discount or surcharge to be applied, then a valid Identifier needs to be passed. Valid values are :
1 = Damage
2= Delay
3= Loss
4= Service Fail
5= Rework
6= Extraction
7= Collection
8= 1st Class return
9= Second Class Return
A = Resp Mail
B = Resp Mail Entry
MixedWeight / Char 1 / O in WMS
M in DHUB / If ‘Y’ then identifies the bag has Mixed Weight items. See Note on Mixed Weightpostings
ZoneCode / Char 3 / M / For national, value will be “NAT”. For zonal, values will be “ZOA”,” ZOB”, “ZOC”, “ZOD”, or “ZOZ”.
ItemWeight / Int 4 / M / Average Item weight. (Up to 4 separate entries per zone per container, one for each weight band. Ensuring same average weight across each zone per weight band)
NumberItems / Int 4 / M / The number of items as part of the container.
(Up to 4 separate entries per zone per container, one for each weight band).
ItemID / Char 13 / I / Currently not required.
OriginatingCustomerID / Alpha Num 15 / O / Customer reference data (e.g. originating Customer identifier)
(In WMS this is specified as 20 characters.) The length is restricted to 15 in the Mixed Weightsolution due to the functionality of this needing to be compliant with the Royal Mail E*Pro system.
CustomerField1 / Alpha Num 20 / O in WMS
I in DHUB / Customer reference data. (e.g. cost centre)
CustomerField2 / Alpha Num 20 / O in WMS
I in DHUB / Customer reference data. (e.g. purchase order)
CustomerField3 / Alpha Num 20 / O in WMS
I in DHUB / Customer reference data. (e.g. client reference)
CustomerField4 / Alpha Num 20 / O in WMS
I in DHUB / Customer reference data. (e.g. company code)

Trailer

Field / Field Length / Description
Record Count / Int 4 / The number of detail lines in the request.

5.2.6Import Container/Append Container Response Data Elements

Mandatory = Must always be present otherwise container will be rejected.

Optional = Can be omitted.

Ignored = Used only in the Mixed Weight solution. The data is not used by the DocketHUB system and will not be validated.

Header

Field / Field Length / Mandatory (M)/
Optional (O) /Ignored (I) / Description
UserID / Alpha Num 30 / M / The user identification used for authentication by the web service.
Password / Alpha Num 30 / M / The user name used for authentication by the web service.
Carrier / Num 4 / M / (In WMS this identifies the carrier of the mail.)
In the Mixed Weight solution this field identifies the user access code that is currently used in the E*Pro docket import web services for authentication.
The length of the field is Alpha Num 10 in WMS and Num 4 in the Mixed Weight solution due to different security models
Poster / Alpha Num 9 / M / Identifies the account that will be invoiced for the mail. (can be same as carrier details in new WMS solution)
(In WMS the field is 10 characters.)
The length of the field is restricted to 9 in the Mixed Weight solutionto complywith the Royal Mail E*Pro system.
PostingDate / Date 08 / M / Date The Mail was posted.( DDMMYYYY)
OrderNumber / Alpha Num 9 / O / Customer reference data
(In WMS this is specified as 20 characters.)
The length is restricted to 9 in the Mixed Weight solution due to the functionality of this needing to be compliant with theRoyal Mail E*Pro system.
IntermediaryAccount / Alpha Num 10 / O in WMS
I in DHUB / Can be used to capture intermediary (e.g. mailing house) account details.
TransactionID / Char 32 / M / The transaction identifier returned by posting the initial container upload.
MessageID / Alpha Num 10 / M / The message identifier.
MessageType / Alpha 1 / M / The error type. Can be ‘E’rror or ‘S’uccess.
MessageText / Alpha Num 100 / M / The message text identifier

Detail

Field / Field Length / Mandatory (M)/
Optional(O)/
Ignored (I) / Description
BagID / Alpha Num 12 / M / Minimum 1 Character.
(In WMS this is specified as 14 characters.) The length is restricted to 12 in the Mixed Weightsolution due to the functionality of this needing to be compliant with the Royal Mail E*Pro system.
SSC / Num(5) / M / Identifies the destination of the container.
ProductCode / Char 3 / M / The three character product code that will be billed against.
Format / Char 1 / M in WMS
O/I in DHUB / Associated with product code, the format of the mail being posted (1 = Letter, 2 = Large Letter / Flat, 3 = Packet, 4 = A3)
DiscountSurcharge / Char 1 / O in WMS
I in DHUB / If the product allows a discount or surcharge to be applied, then a valid identifier needs to be passed. Valid values are :
1 = Damage
2= Delay
3= Loss
4= Service Fail
5= Rework
6= Extraction
7= Collection
8= 1st Class return
9= Second Class Return
A = Resp Mail
B = Resp Mail Entry
MixedWeight / Char 1 / O in WMS
M in DHUB / If ‘Y’ then Identifies the bag has Mixed Weight items. See Note on Mixed Weight Postings
ZoneCode / Char 3 / M / For national, value will be “NAT”. For zonal, values will be “ZOA”,” ZOB”, “ZOC”, “ZOD”, or “ZOZ”.
ItemWeight / Int 4 / M / Average Item weight. (Up to 4 separate entries per zone per container, one for each weight band, Ensuring same average weight across each zone per weight band)
NumberItems / Int 4 / M / The number of items as part of the container.
(Up to 4 separate entries per zone per container, one for each weight band).
ItemID / Char 13 / I / Currently not required
OriginatingCustomerID / Alpha Num 15 / O / Customer reference data (e.g. originating Customer identifier)
(In WMS this is specified as 20 characters.) The length is restricted to 15 in the Mixed Weight solution due to the functionality of this needing to be compliant with the Royal Mail E*Pro system.
CustomerField1 / Alpha Num 20 / O in WMS
I in DHUB / Customer reference data.(e.g. Cost Centre)
CustomerField2 / Alpha Num 20 / O in WMS
I in DHUB / Customer reference data.(e.g. purchase order)
CustomerField3 / Alpha Num 20 / O in WMS
I in DHUB / Customer reference data (e.g. client reference)
CustomerField4 / Alpha Num 20 / O in WMS
I in DHUB / Customer reference data (e.g. company code)
MessageID / Alpha Num 10 / M / The message identifier.
MessageType / Alpha 1 / M / The error type. Can be ‘E’rror or ‘S’uccess.
MessageText / Alpha Num 100 / M / The message text.

5.2.7Import Container/Append Container XML Structures

5.2.8Import Container/Append Container Examples

Attached are four xml examples for docket upload. One for a national posting , one for a zonal posting , one for a National Mixed Weight posting and one for a zonal Mixed Weight posting :-

5.2.9Import Container/Append Container Examples SOAP Request

5.2.10Import Container/Append Container Examples SOAP Response

5.2.11Import Container/Append Container Manual File Loading

In the event that your system encounters an error transferring the Mixed Weight SOAP request via the DocketHub Mixed Weight Web Service, the following backup actions should be followed:-

Save an exact copy of the Mixed Weight SOAP request that has failed.
Send the data file to
Dockethub support will contact you once the data has been imported or respond with the reason the request failed.

Note on Delete Docket

If a carrier uploads information incorrectly, and they realise the mistake before calling the “MI_OS_CREATE” Web Service, they can call the “MI_OS_DELETE” web service method and this will remove all the data for a given transaction ID.

5.2.12Delete Container Method

DT_DELETE_RES = MI_OS_DELETE(DT_DELETE_REQ)

5.2.13Delete Container WSDL

5.2.14Delete Container Request Data Elements

Note there is no Header element in the MI_OS_DELETE web service. This is by design as the WSDL is taken from the WMS project.

Mandatory = Must always be present otherwise container will be rejected.

Optional = Can be omitted.

Ignored = Used only in the Mixed Weight solution. The data is not used by the DocketHUB system and will not be validated.

Detail

5.2.15Delete Container Response Data Elements