Technical upload specification for Royal Mail Mailmark

Transcription

1 Technical upload specification for Royal Mail Mailmark Status: Approved Classification: RESTRICTED

2 Contents 1 INTRODUCTION PURPOSE INTENDED AUDIENCE SCOPE KEY FEATURES SUPPLY CHAIN BATCHES PROCESS OVERVIEW SUBMITTING AN EMANIFEST TO UK MAIL SPOILS TIMINGS IMPLEMENTATION GUIDELINES MAIL PRODUCERS USING INTELLIGENT PRINTERS/ENCLOSERS MAIL PRODUCERS USING A PRODUCTION CONTROL SYSTEM MAIL PRODUCERS USING SORTATION SOFTWARE THAT HAS BEEN MAILMARK BARCODE ENABLED MAIL PRODUCERS USING SORTATION SOFTWARE THAT IS NOT MAILMARK BARCODE ENABLED MAIL PRODUCERS USING EXISTING CONSOLIDATION MACHINES UPLOAD PROCESS DESCRIPTION UPLOAD PROCESS OVERVIEW WEB SERVICE METHOD DETAILS WEB-SERVICE LOGIN ITEM MANIFEST WSDL EXAMPLE XML REQUEST/RESPONSE STRUCTURES WEB SERVICE METHOD DEFINITIONS ITEM_MANIFEST-1 WEB METHOD SPOIL-1 WEB METHOD WEB SERVICE URL & CONNECTION STRATEGIES WEB SERVICE URL COMPRESSION MAILMARK TESTING UPLOAD TESTING OPTIONAL FIELDS IN EMHS FOR MAILMARK REPORTING OPTIONAL FIELDS MAILMARK REPORTING WEB METHOD ERROR CODES AND MESSAGES ERROR HANDLING Status: Approved Classification: RESTRICTED Page 2 of

3 12 APPENDIX A - SCID SETUP APPENDIX B - CONTAINER MANIFESTING & SPOILS FREQUENTLY ASKED QUESTIONS... Change log 1. Added Introduction 2. Added Key Features 3. Modified High-level Requirements to instead contain a full process description a. Addition of spoils process 4. Updated bag-item link section to include additional examples 5. Added web-service method and definition for both standard manifesting and spoils manifesting 6. Provided information on implementation using different site setups 7. Provided information on implementation using compression 8. Added information on becoming accredited with UK Mail 9. Added frequently asked questions 10. Updated information on container level manifesting Status: Approved Classification: RESTRICTED Page 3 of

4 1 Introduction 1.1 Purpose The purpose of this document is to provide implementation guidelines for customers wishing to use UK Mail for the processing of their Mailmark work. It is intended to provide both the business rules and technical information required to process Mailmark in a straightforward manner. It is not intended to provide any rules regarding the physical output of barcodes, any such information should be acquired from the official Royal Mail Mailmark documentation. This can be obtained at Intended audience This document is intended for Mail Producers intending to provide a Mailmark service to their customers, and for third parties wishing to develop a solution to upload item level data into the UK Mail item database. 1.3 Scope This document describes the method of transmitting item level information into the UK Mail item database and additionally sets expectations for the Royal Mail Mailmark reporting. It does not describe the Mailmark barcode format, service requirements or terms and conditions. Status: Approved Classification: RESTRICTED Page 4 of

5 2 Key features 2.1 Supply chain The Mailmark product option introduces a new structure, the Supply Chain. The intention of this Supply Chain is to enable full visibility of those participating in a mailing job, from origin to delivery. This Supply Chain is comprised of the following participants: Mail Originator: from whom the mail originates Mail Producer: responsible for printing and enclosing the mail pieces Mail Carrier: responsible for collecting the mail from the Mail Producer and delivering to Royal Mail. In the case of this document, UK Mail. Bill Payer: account holder responsible for paying Royal Mail Additional to the above, and for the purposes of UK Mail, the following is also acknowledged as a participant, but is not reflected officially within the Royal Mail supply chain: Data Processor: responsible for generating the data used by the Mail Producer for printing and enclosing, and uploading item data to UK Mail. Supply Chains are identified by a unique Supply Chain ID that is provided by Royal Mail. This can be requested by any participant of the Supply Chain, and requires knowledge of the Participant IDs of all members. The UK Mail onboarding team can assist in requesting the creation of Supply Chain IDs via the Client Directors. Supply Chain IDs can be a variety of lengths: 2D barcodes: 7 digits 4-state barcode L: 6 digits Note: This barcode must contain all of the preceding zeroes in both the barcode and the associated item data 4-state barcode C (consolidators): 2 digits A single participant may fulfil multiple roles. The clearest views of this are distinctions between Downstream Access, Agency for Access, (large) Agency for Access and Customer Direct Access whereby: DSA: Bill Payer is UK Mail AFA: Bill Payer is UK Mail CDA/ (large) AFA: Bill Payer is Mail Originator Status: Approved Classification: RESTRICTED Page 5 of

6 A list of expected scenarios, specific to UK Mail, is thus: Scenario Mail Originator Mail Producer Carrier Bill Payer A mailing house (Print & Co), performing a mailing on a client account (Acme Inc.), collected by a DSA carrier (UK Mail) prior to final delivery by Royal Mail A mailing house (Print & Co), performing a mailing on a customers DSA carrier national account (UK Mail), collected by a DSA carrier (UK Mail) prior to final delivery by Royal Mail A mailing house (Print & Co), performing a mailing on a customers DSA carrier zonal account (UK Mail), collected by a DSA carrier (UK Mail) prior to final delivery by Royal Mail A carrier (UK Mail) consolidating and sorting unsorted mail on behalf of a number of clients and mailing houses prior to final delivery by Royal Mail A carrier (UK Mail) consolidating and sorting unsorted mail on behalf of a single CDA client (Acme Inc.) prior to final delivery by Royal Mail Acme Inc. Print & Co UK Mail Acme Inc Acme Inc. Print & Co UK Mail UK Mail National Acme Inc. Print & Co UK Mail UK Mail Zonal UK Mail UK Mail UK Mail UK Mail National Acme Inc. UK Mail UK Mail UK Mail National Supply Chain within UK Mail The procurement of a Supply Chain ID is a requirement in order to use the Mailmark service, and it is additionally linked to a UK Mail Account Number and in turn to a Royal Mail Account Number, when using the Mailmark service within UK Mail. This ensures full traceability through the UK Mail track & trace system. As a result of the above requirement, a set of documentation will need to be completed by the Mail Originator, providing permission for a set of account numbers to be linked to an SCID. A copy of this documentation may be located in Appendix A. In cases where UK Mail operates as the Bill Payer for a Supply Chain, there are two possible distinctions; cases where the mail being provided is national, and cases where the mail is zonal. For each of these distinctions, a different SCID will be required, one where the Bill Payer is National, and one where the Bill Payer is Zonal. As these SCIDs are linked to account number, this therefore means that a single UK Mail account may be used solely for national or zonal, and cannot be used for both. Status: Approved Classification: RESTRICTED Page 6 of

7 2.2 Batches The uploader of Mailmark item data into the UK Mail item database can opt to upload this data under a single or multiple Batch References. This allows for customers to split their uploads into smaller groups that replicate their own internal processes, should they so desire. Batch References have the following restrictions: A unique identity is created each time a Batch Reference, SCID and Input date are combined in the UK Mail database. Subsequent uploads using the same Batch Reference, SCID and Input Date will append data to the existing. Each Batch Reference may only have one single combination of: o o o Class Product Format Batch References will have no impact on processing of mail, but will have an impact on how Royal Mail Mailmark reporting displays their reports. Potential scenarios for how batches may be split: Approach Single mailing per day Multiple jobs per day Multi-cell mailings Separate print jobs Description If the Mail Producer has all of the items for a particular Supply Chain in a single address file, then the Mail Producer may decide to upload the file as a single Batch. If there are multiple jobs being despatched on the same day, then it is possible to upload each job as its own Batch, as each job is produced. If a mailing consists of multiple cells that are being despatched on the same day, then each cell can be uploaded as a separate Batch. If the Mail Producer is using intelligent mail enclosers, or a production control system, then a mailing may be distributed across multiple enclosers as separate print jobs, in which case each individual print job can be loaded as a separate Batch in order to reflect production activity. Status: Approved Classification: RESTRICTED Page 7 of

8 3 Process overview 3.1 Submitting an emanifest to UK Mail Item Raise Spoils Create Create Batch Manifest (if required) Manifest 7 Append To Batch 9 10 Confirm Submit Batch Manifest 3 4 Mail Container Collection Scan 8 End of Day Closure Step Activity Description 1 Item Manifest Submit item level information to UK Mail containing Batch Reference, SCID and individual item level data 2 Raise Spoils (optional) Remove items from a single Batch Reference for an SCID. 3 Mail Collection UK Mail collection from Mail Producer 4 Container (bag/tray) Scan UK Mail initial scan of container label 5 Create Manifest Open a new emanifest with Royal Mail for the Supply Chain associated with the scanned container. The handover date is calculated within the UK Mail system as the next working day. 6 Create Batch Create a new Batch associated with the emanifest for that Supply Chain, using the Batch Reference provided in step 1 7 Append to Batch Upload the individual Mailmark barcode item details for the associated scanned container 8 End of Day closure Scheduled event to close all open manifests based on type of SCID and time of day. Note: 20:50 the day prior to handover for non-consolidated work, 23:50 the day prior to handover for UK Mail consolidated work. 9 Submit Batch Submit the Batch, indicating that no further changes to the Batch are expected. 10 Confirm Manifest This marks the emanifest for a particular Supply Chain as complete. Status: Approved Classification: RESTRICTED Page 8 of

9 If the Mail Producer wishes to split their particular job into multiple Batches, this can be done by specifying a separate Batch Reference at the Item Manifest level. UK Mail will then persist these particular Batch References when creating batches at Royal Mail. Each Batch Reference is unique within an SCID and an Item Manifest date. Supply Chain 1 Batch 1 1 product, 1 format, 1 class Item Manifest Supply Chain 1 Batch 1 1 product, 1 format, 1 class Create Batch Append to Batch Submit Batch Supply Chain 1 Item emanifest Supply Chain 1 Batch 2 1 product, 1 format, 1 class Item Manifest Supply Chain 1 Batch 2 1 product, 1 format, 1 class Create Batch Append to Batch Submit Batch Supply Chain 1 Consignment Supply Chain 1 Sales Order Supply Chain 1 Batch 3 1 product, 1 format, 1 class Supply Chain 1 Batch 3 1 product, 1 format, 1 class Create Batch Append to Batch Submit Batch Supply Chain 2 Batch 1 1 product, 1 format, 1 class Supply Chain 2 Batch 2 1 product, 1 format, 1 class Supply Chain 2 Batch 1 1 product, 1 format, 1 class Supply Chain 2 Batch 2 1 product, 1 format, 1 class Create Batch Append to Batch Submit Batch Create Batch Append to Batch Submit Batch Supply Chain 2 Item emanifest Confirm emanifest Supply Chain 2 Consignment Supply Chain 2 Sales Order Unsorted mail UK Mail offer the ability for mailing houses to provide unsorted in two variations: Pre-barcoded Non-barcoded Should a mailing house opt to send pre-barcoded mail, the process must be the same as with mailsorted mail, whereby the item data is provided, the items are linked to containers, but in particular, the unsorted mail must be declared as Mailmark in both the container level data and the container label. In this case, the Mailmark barcode pre-applied by the Mailing House will not be overwritten, and the original item data will be sent to Royal Mail when the original container is initially scanned. As this does not account for processing within UK Mail, this will result in item data being manifested to Royal Mail with a handover date that differs from the actual. Status: Approved Classification: RESTRICTED Page 9 of

10 In the case of non-barcoded mail, UK Mail will sort the mail to the highest possible standard, as is the current process Linking items to containers As stated in section 3.1, UK Mail performs the upload to Royal Mail once a container has been scanned. This uploading is dependent on the ability to link between the container scanned and the items within the container. In order to achieve this, the requirement is that the Mail Producer sets a link field that can be replicated at a container level and at an item level. This field is split in the following manner: 1. Item level field (Item_Manifest-1): SPARE8 2. Container level field (bag manifest): Alternative Reference The Alternative Reference must be populated for a container whenever a Mailmark service is selected, regardless of the upload method being used (Consignor Live, Web-service Integration or FTP). The reference placed into the Alternative Reference field must then be replicated into the SPARE8 field for all of the items within the container. As with the EIB Item ID, the container-item link must be unique for a 90 day period. In order to achieve uniqueness, it s suggested that this field contain a UK Mail account number and a date field. It is requested that during development of a new system, that the opted format for the container-item link field be discussed with UK Mail to ensure that it does not conflict with any other companies selected format. Scenario Suggested format Comments Direct Mailing A000001_160425_00001 UK Mail account number, creation date and sequentially increasing number Transactional Mailing A000001_160425_00001 UK Mail account number, creation date and sequentially increasing number Consolidation XXX_ Consignment Number, preceded by Mail Producer acronym Container manifesting Alongside the provision of the unique item manifest data for Mailmark jobs, the associated container manifesting into UK Mail must reflect the new services. This is the case for both mailsorted and unsorted mail. These new services are represented by UK Mail Service Codes, regardless of the upload method used for container level information, be it self-labelling or Consignor Live. A full list of the service codes may be found in the Consignor Live Integration Guide located in Appendix B Status: Approved Classification: RESTRICTED Page 10 of

11 3.2 Spoils On occasion, during the printing or enclosing process, items intended for a mailing may be damaged, resulting in them being withdrawn from the intended posting and re-created on a subsequent day. In this case, should the item manifest already have been provided to UK Mail, the Mail Producer may opt to recall the items by calling the spoils service and deducting these items from the manifest. Spoils may be recorded against a batch any time between the item manifest being uploaded to UK Mail, and UK Mail performing the first scan on the container, usually on receipt at the UK Mail collection site. Item level spoils are provided with the intention that user will wish to use this service for the following purposes: Ensuring accurate reporting within the Royal Mail Mailmark reporting suite Removing individual EIB Item IDs from the UK Mail database in order to re-use an item ID within the 90 day period in which an Item ID must remain unique. Please note that this spoils service is referring to the ability to spoil item level information, which impacts the Royal Mail Mailmark reporting. In order to perform container level spoils, which impacts billing, this must be done via the container level manifesting process (commonly Consignor Live), and can be viewed in the UK Mail Consignor Live Integration Extended document in Appendix A. 3.3 Timings Within the Mailmark process, UK Mail will handle the uploading of the emanifest into Royal Mail. This upload is dependent upon receipt of the item manifest from a Mail Producer, as the scanning of a container is the trigger event to send the mail to Royal Mail. Due to the Royal Mail requirement that Item IDs within an SCID be unique for at least 90 days, customers may opt to send their item data into the UK Mail system up to 89 days prior to the mail being physically collected. If the item manifest is not present at the point where the container is scanned, the Mail Producer will be contacted in order to upload the data, and the associated mail will not be moved throughout the UK Mail network. Status: Approved Classification: RESTRICTED Page 11 of

12 4 Implementation guidelines The approach taken to generating emanifests may depend on the nature of the Mail Producer s production process, equipment used and production equipment used. The emanifest upload facilities have been designed to support a variety of upload approaches. 4.1 Mail Producers using intelligent printers/enclosers Where a Mail Producer has invested in intelligent printers/enclosers, then depending on the manufacturer and capabilities of the device, the manufacturer may choose to support direct upload of emanifests directly from the printer/encloser itself. With this approach, the address list will be passed to the intelligent printer/encloser, which will be responsible for applying the Mailmark barcode to the mail piece, and generating the emanifest. In this scenario the intelligent printer/encloser may either generate an output item file, for uploading to UK Mail using a third party upload tool, or the manufacturer may choose to incorporate the upload of the item details directly to UK Mail from the printer/encloser, either as the items are printed, or at the end of the print run. If a Mail Producer has production equipment capable of following this approach, then it is likely that the best implementation approach is to upload item level data to UK Mail in Batches that reflect the print jobs assigned to each printer/encloser. For instance, if a large mailing is split across 4 printer/enclosers then each printer/encloser will generate its own Batch of items for upload to UK Mail. Intelligent enclosers are more likely to have the capabilities to detect spoiled items. Depending on the manufacturer, the registering of those spoils against the Batch may be managed by the printer/encloser, or generated as an output spoils file that will need to be uploaded to UK Mail using a third party upload tool. Status: Approved Classification: RESTRICTED Page 12 of

13 Intelligent Printers/Enclosers Intelligent enclosers upload batch to EIB at the end of each print job. Royal Mail EIB EMHS system UK Mail Item Database Batch 1 Item Manifest Batch 2 Batch 3 Batch 1 Batch 2 Batch 3 Batch 4 Sales Order Batch 4 Batch per print job 4.2 Mail Producers using a production control system Where a Mail Producer has implemented a production control system to manage multiple enclosers, depending on the supplier of the production control system software, job workflow and automated spoils re-queuing may be facilities supported by the production control system. In this instance the creation of Batches of items and identification of any resulting spoils may be facilities that production control system software suppliers incorporate within their production control system Software. Under this approach, the production control system software may generate Batches of items that reflect the allocation of print jobs to printers/enclosers, or it may generate Batches of items based on the mailings being managed by the production control system software, Production control system software may also interrogate the production enclosers, detect spoils and automatically re-queue items for re-print. In this case the production control system software should be able to generate the appropriate spoils information for upload to UK Mail. It is likely that production control system software will be updated to support the automatic uploading of items to UK Mail at the appropriate time, as part of the job workflow management within the production control system. Status: Approved Classification: RESTRICTED Page 13 of

14 Production Control System Customer Production Control System manages mailings, uploads batches to EIB Customer Production Control System Batch 1 Batch 1 Royal Mail UK Mail EIB EMHS systemitem Database Item Manifest Batch 2 Batch 3 Batch 2 Batch 3 Batch 1 Batch 2 Batch 3 Batch 4 Sales Order Batch 4 Batch 4 Batch per mailing 4.3 Mail Producers using sortation software that has been Mailmark barcode enabled Where a Mail Producer has third party sortation software to manage address sortation, it is possible that the sortation software supplier will incorporate the creation of the emanifest as an output of the address sortation process, and embed the required information for the Mailmark barcode item in the sorted address file. This approach lends itself to Mail Producers with traditional enclosers with limited communication capability. In this scenario the Batch is likely to represent the job that has been mail sorted in its entirety. The item manifest may be uploaded to UK Mail as soon as the mailing data sorting process has been complete, despite the fact that this may be several days prior to the mailing being printed and enclosed. This is due to the fact that UK Mail will not upload this data to Royal Mail until the associated container has been received and scanned at a UK Mail depot. Because of the potential delay between data sorting an address file, and enclosing/dispatching of the mailing, it is likely that the upload of the Mailmark Batch will be performed using a separate upload application, which may be provided by the sortation software supplier or be available from third-party software suppliers. Status: Approved Classification: RESTRICTED Page 14 of

15 4.4 Mail Producers using sortation software that is not Mailmark barcode enabled Where a Mail Producer is using existing sortation software that has not been made Mailmark-barcode enabled, then the address list may have been through a traditional sorting process, but it has not been augmented with information to facilitate generation of the Mailmark barcode item, or the generation of an emanifest. In this scenario, which is likely to occur in the early stages of the introduction of Mailmark, then the Mail Producer may need to use a third party application to Mailmark-barcode enable a mail sorted address list and generate the required Mailmark barcode outputs. It is likely that any such third party application will also provide facilities to upload the subsequent Mailmark barcode mailing to UK Mail when the mailing is due to be despatched. Poster manages jobs manually, used third party software to generate EIB compliant manifest and upload to EMHS encloser Royal UK Mail EIB Item EMHS Database system Sorted Address List for printing Item Manifest Batch 1 Address list Mailsort Software EIB item manifest Sales Order EIB Manifest Upload Software Batch 1 Batch per mailing 4.5 Mail producers using existing consolidation machines Where a Mail Producer is utilising mail sortation and consolidation equipment to prepare unsorted mail for handover to UK Mail, then the output of this consolidation machine will need to be Mailmark enabled, and uploaded to UK Mail. As consolidated mail will need to carry a Mailmark to identify it when it is processed through the machine, the mail consolidation manufacturer is likely to have engaged with Royal Mail during the Mailmark Programme to Mailmark barcode enable their equipment. Status: Approved Classification: RESTRICTED Page 15 of

16 It is likely that when using a consolidation machine, emanifests are likely to be generated in Batches that represent each clear down of the machine. Given that the consolidation process is likely to take place close to the time of despatch, it is possible that the consolidator equipment will also provide the facility to automatically upload item level data to the emanifest. If this is not the case, or where consolidation equipment that has not been Mailmark barcode enabled, then provided that the consolidator can provide an item level output file that incorporates the unique item identifier applied to the mail piece. Then a third party tool may be available to take this item level output and generate and upload the item level data to the emanifest. Status: Approved Classification: RESTRICTED Page 16 of

17 Item-Manifest 5 Upload process description 5.1 Upload process overview For each job that a Mail Producer may handle, it can be uploaded to UK Mail as one or more Batches of Mailmark barcode items, where each Batch containing mail for a product, format and container type of mail for a single Supply Chain. Mail Producer / Data Processor Item Manifest submission Mail Producer / Data Processor UK Mail Start 1 Split total batch items into blocks of up to Call item_manifest-1 web-service method with first 1000 items Items validated and Batch Reference entered for SCID and Date 3 Call item_manifest-1 web-service method with subsequent items Items validated and appended to prior entry More items to send? Spoils to raise? 4 Call spoil-1 web-service method Items removed from database More Spoils to raise? End Status: Approved Classification: RESTRICTED Page 17 of

18 Step 1 Batch Splitting The maximum number of items that can be uploaded in a single call into the Item_Manifest-1 webservice is 1,000 items. As a result, either prior to initializing the call, or during the call itself, the total number of items in the batch must be split into manageable amounts of up to 1,000. Steps 2 & 3 Item Manifest uploading The initial call into UK Mail will create an entry in the database with the Batch Reference, Supply Chain ID, Product, Format, Class and Container Type (if supplied). Subsequent calls that have the same combination of Batch Reference, Supply Chain ID and entry date will be validated against the first. Step 4 (optional) Spoils uploads Prior to the containers of mail being scanned at the UK Mail collection depot for the site, a Mail Producer can amend their total item count by sending a spoils call through. This will require specifying the Batch Reference, Supply Chain ID and input date of the original Batch loaded, as well as the individual item IDs requiring deletion. Uploaders may also opt to remove an entire batch should a job not be released at all. Only the uploader whose credentials were used in the original upload may be used to perform spoils against said upload. The Mailmark Spoils process is used solely for modifying the number of items specified in a Batch. This will only have an impact on the Royal Mail emhs reporting, but will not modify the item count against the container, which is used for billing. In order to complete container level spoils, the Consignor Live Integration Guide may be consulted in Appendix B. Note: Removal of an entire batch is up to a maximum of 250,000 items within a Batch. If a larger batch requires deletion, UK Mail IT Service Desk may be contacted via either telephone or to perform the removal. Status: Approved Classification: RESTRICTED Page 18 of

19 6 Web service method details 6.1 Web-service login Access into the UK Mail item-manifest web-service requires the use of a username and password, which will need to be specified in the header of every call into the system. Should a user opt to acquire a third party tool, or create an application internally, said application/tool should have the ability to retain the username and password. In order to acquire this username and password, the Customer General Manager at UK Mail for the Mail Producer should be consulted, and they will then request the setup. These credentials are unique to a single producer and must not be distributed to any other producer/uploader, or any third party. Additionally, certain third party software requires that a Royal Mail username and password be introduced into their software to allow for the Supply Chain IDs to be automatically populated within the software, and as a result credentials for Royal Mail should be acquired. These credentials are provided alongside the emhs login credentials when a user originally registers with Royal Mail. The Participant ID is not required for use uploading into UK Mail. 6.2 Item manifest WSDL The WSDL embedded below describes the latest version of the UK Mail item manifest upload service: Live Test Item_Manifest-1.wsdl Item_Manifest-1_QA.wsdl Spoil-1.wsdl Spoil-1_QA.wsdl 6.3 Example XML request/response structures Web-Service Method Example Request Example Response Item-Manifest-1 Item_Manifest-1Request.xml Item_Manifest-1Response.xml Spoil-1 Spoil-1Request.xml Spoil-1Response.xml Status: Approved Classification: RESTRICTED Page 19 of

20 7 Web service method definitions 7.1 Item_Manifest-1 web method Primary web-service method used to upload item level information into UK Mail Name Optionality Format Description BatchReference Mandatory varchar(50) Batch Reference associated to items. Trimmed to 30 characters when transmitting to Royal Mail SCID Mandatory varchar(7) Royal Mail Supply Chain ID AddressLine1 Optional varchar(60) Mail Item Address Line 1 as printed on the first address line of the mail item (not recipient or business name) AddressLine2 Optional varchar(60) Mail Item Address Line 2 AddressLine3 Optional varchar(60) Mail Item Address Line 3 AddressLine4 Optional varchar(60) Mail Item Address Line 4 AddressLine5 Optional varchar(60) Mail Item Address Line 5 AddressLine6 Optional varchar(60) Mail Item Address Line 6 AddressLine7 Optional varchar(60) Mail Item Address Line 7 AddressLine8 Optional varchar(60) Mail Item Address Line 8 AddressLine9 Optional varchar(60) Mail Item Address Line 9 AdvertisingAttribute1 Optional char(1) To identify any trans-promotional advertising attributes: 0 = Null AdvertisingAttribute2 Optional char(1) To identify any trans-promotional advertising attributes: 0 = Null AdvertisingAttribute3 Optional char(1) To identify any trans-promotional advertising attributes: Status: Approved Classification: RESTRICTED Page 20 of

21 Name Optionality Format Description 0 = Null AdvertisingAttribute4 Optional char(1) To identify any trans-promotional advertising attributes: 0 = Null CampaignName Optional Varchar(30) Optional Customer Specified Campaign Name. Null if not specified by the Mail Producer. Used in Mailmark customer reporting enables 90 days worth of data to be linked together Class Mandatory char(1) The declared class for the mail item. For the purposes of UK Mail: Class = 9 (Standard Network Access) Must match the associated Product and Format. DPS Mandatory varchar(2) The declared Delivery Point Suffix of the PAF address of the Mailmark Item. If the DPS is not available then either the value of 9Z is to be used or the field should be blank. Department Optional varchar(30) Optional Customer Specified Department Name. Null if not specified by the Mail Producer. Used in Mailmark customer reporting EIBItemID Mandatory integer(8) The mail item ID to identify the individual item that has been printed by the bulk mail customer. This is maintained on a per Supply Chain ID and sequentially incremented by the generating system, padded with leading zeroes. The Item ID must remain unique for at least 90 days after the handover date against which it was previously used. For the purposes of UK Mail, this is the handover date to UK Mail and not Status: Approved Classification: RESTRICTED Page 21 of

22 Name Optionality Format Description to Royal Mail. Format Mandatory char(1) The declared format for the mail item: 0 = Null 1 = Letter 2 = Large Letter 3 = Packet (for potential future use) 4 = Parcel (for potential future use) 5 9, A Z Spare (for potential future use) Must match the associated Product and Class Machinable Mandatory char(1) The declared machinability of the mail item: E = Mailmark MailOriginatorSubDivisionName Optional varchar(30) Optional Mail Originator Sub Division Name. Null if not specified by the Mail Producer. Used in Mailmark customer reporting job report. MailSubType1 Optional char(1) The declared sub mail type for the mail item, e.g. bank statement. Null if not specified by the mailing agent. 0 = null MailSubType2 Optional char(1) The declared sub mail type for the mail item, e.g. bank statement. Null if not specified by the mailing agent. 0 = null MailSubType3 Optional char(1) The declared sub mail type for the mail item, e.g. bank statement. Status: Approved Classification: RESTRICTED Page 22 of

23 Name Optionality Format Description Null if not specified by the mailing agent. 0 = null MailSubType4 Optional char(1) The declared sub mail type for the mail item, e.g. bank statement. Null if not specified by the mailing agent. 0 = null MailType Mandatory char(1) The declared mail type for the mail item: 0 = Null/Unknown 1 = Advertising 2 = Business 3 = Fulfilment 4 = Publishing 5 = Business Reply 6 = Freepost 7 = Election Mail 8 = Spare 9 = Consolidated A to Z = Spare MailerID Optional integer(3) Mailing House ID (QMP Number). The Mailer ID is held as an attribute of the Posting Location but is only populated if the Posting Location is a Mailing House. A null value indicates that the customer account is the mailer. Null if not specified by the mailing agent. 0 = Null Status: Approved Classification: RESTRICTED Page 23 of

24 Name Optionality Format Description NumberOfAddressLines Mandatory integer(1) The number of address lines declared by the Mailing Agent which were printed on the Mailmark Item 0-9 lines. (if unknown, use a default value of 4 lines) PAFResellerProduct Optional varchar(10) The resellers product name that was the source of the address file. Null if not specified by the Mail Producer. PAFResellerProductVersion Optional varchar(4) The version of the resellers product that was the source of the address file. Null if not specified by the Mail Producer PAFVersion Optional varchar(4) PAF version if known. Null if not specified by the Mail Producer PostCode Mandatory char(7) The declared Postcode of the PAF address of the item. Inland Postage contains the following characters. Area (1 or 2), District (1 or 2), Sector (1) and Unit (2). If the full postcode is not available, please enter as much of the postcode as possible and pad the remainder of the field with up to 7 zeroes or 7 space characters. Product Mandatory char(3) The declared product for the mail item matching the 3 Character Code within SAP OBA. RTSDPS Conditional char(2) Future use only Must match the associated Format and Class. (Only to be used if a unique response barcode is being used) The declared Return To Sender Delivery Point Suffix of the PAF address of the mail item. Status: Approved Classification: RESTRICTED Page 24 of

25 Name Optionality Format Description RTSPostCode Conditional char(7) Future use only RTSService Conditional char(1) Future use only (Only to be used if a unique response barcode is being used). The declared Return To Sender Postcode of the PAF address of the mail item. Inland postage contains the following characters: Area (1 or 2), District (1 or 2), Sector (1) and Unit (2) (Only to be used if a unique response barcode is being used) Return to Sender service classification: 0 = Null ResellerUsed Optional varchar(10) The name of the reseller that was the source of the address file. Null if not specified by the Mail Producer ResponseClass Optional char(1) Future use only. ResponseDPS Conditional char(2) Future use only ResponseFormat Conditional char(1) Future use only (Only to be used if a unique response barcode is being used) For the purposes of UK Mail, this is: Class = 9 (Standard Network Access) (Only to be used if a unique response barcode is being used) The declared Response Service mail item Delivery Point Suffix of the PAF address of the Response Item (Only to be used if a unique response barcode is being used) The declared format of the Response Item: Status: Approved Classification: RESTRICTED Page 25 of

26 Name Optionality Format Description 0 = Null 1 = Letter 2 = Large Letter 3 = Packet (for potential future use) 4 = Parcel (for potential future use) 5 9, A Z = Spare ResponseItemID Conditional integer(8) Future use only ResponseLicenceNo Conditional char(6) Future use only Respons Type Conditional char(1) Future use only (Only to be used if a unique response barcode is being used) Response Item ID to identify the individual response item that has been printed by the bulk mail customer. This is maintained per Supply Chain ID and sequentially increased by the generating system, padded with leading zeros (Only to be used if a unique response barcode is being used) The Response Service Licence number under which the response item will be billed. The first 6 characters of the full licence is included, i.e. the full licence of AAAA-AABB-BBBB is reduced to AAAAAA. (Only to be used if a unique response barcode is being used) The declared mail type for the Response item: 5 = Business Reply 6 = Freepost Null if not specified by the uploader, 0 Status: Approved Classification: RESTRICTED Page 26 of

27 Name Optionality Format Description = Null ResponsePostCode Conditional char(7) Future use only ResponseSupplyChain Conditional varchar(10) Future use only (Only to be used if a unique response barcode is being used) The declared Response Service mail item Postcode of the PAF address of the Response Item. Inland Postage contains the following characters: Area (1 or 2), District (1 or 2), Sector (1) and Unit (2) (Only to be used if a unique response barcode is being used) Supply Chain ID for the Response element of the mailing. SPARE1 Optional char(1) SPARE field (Royal Mail use only) to support future growth. Null if not specified by the Mail Producer. 0 = Null SPARE2 Optional char(1) SPARE field (Royal Mail use only) to support future growth. Null if not specified by the Mail Producer. 0 = Null SPARE3 Optional char(1) SPARE field (Royal Mail use only) to support future growth. Null if not specified by the Mail Producer. 0 = Null SPARE4 Optional varchar(6) Sector Codes (The Mailmark Insight Advertising sector code) Status: Approved Classification: RESTRICTED Page 27 of

28 Name Optionality Format Description If used these codes must be entered as n.n.n or n.n.nn. Format is validated on submission and batch will be rejected if this formatting rule is not adhered to. 0 is not a valid entry. If a full sector code is not entered the field should be left blank SPARE5 Optional varchar(6) SPARE field (Royal Mail use only) to support future growth. Null if not specified by the Mail Producer. 0 = Null SPARE6 Optional varchar(10) Product Description (The Mailmark Insight Advertising description) Null if not specified by the Mail Producer. 0 = Null SPARE7 Optional varchar(10) SPARE field (Royal Mail use only) to support future growth. Null if not specified by the Mail Producer. 0 = Null SPARE8 Mandatory varchar(20) Container-Item link field Field which links the items in a container to the container which the items are within. Equivalent of container field Alternate Reference. If this field does not match the associated container Alternate Reference field, the container will not be able to be scanned through the UK Mail network SPARE9 Optional varchar(30) Customer Reference Status: Approved Classification: RESTRICTED Page 28 of

29 Name Optionality Format Description Meaningful customer reference which will show in item level reporting. Null if not specified by the Mail Producer. 0 = Null SPARE10 Optional varchar(50) SPARE field (Royal Mail use only) to support future growth. Null if not specified by the Mail Producer. 0 = Null 7.2 Spoil-1 web method Name Optionality Format Description BatchReference Mandatory varchar(50) Batch Reference associated to items. Trimmed to 30 characters when transmitting to Royal Mail SCID Mandatory varchar(7) Royal Mail Supply Chain ID Date Mandatory date The data on which the Batch Reference and SCID requiring spoils was originally submit. Date format YYYY-MM-DD EIBItemID Conditional integer(8) Individual Mailmark Item ID. Must be populated if opting to spoil individual items as opposed to an entire batch. Status: Approved Classification: RESTRICTED Page 29 of

30 8 Web service URL & connection strategies 8.1 Web Service URL Mailing Agents will access to SOAP-based UK Mail web-services using HTTPS over the public internet. In order to begin using Mailmark with UK Mail, testing must first be adhered to. For a standard end-toend go live, this can be completed in the live environment. For developing a new solution and testing the output, this must be completed in the test environment. Developing and testing in live is not acceptable. In order to acquire credentials for performing both testing and live sending, the local UK Mail Customer General Manager for the Mailing House must be consulted, and a request for credentials submitted. When requesting these, it s necessary to specify if the credentials required are for production or test. Web-Service Method Endpoint Type URL Item_Manifest-1 Production Item_Manifest-1 Test 1 Spoil-1 Production Spoil-1 Test Compression Please note that compression in a production environment is subject to a further release of the Mailmark solution within UK Mail. There are additional endpoints defined for the upload services to allow for uncompressed or compressed item-manifest uploads (Gzip or Deflate compression methods are supported). For posters to use compression, the following steps need to be taken: 1. Choose a compression method, GZip or DEFLATE 2. Compress the message envelope with the chosen compression method 3. Add an new HTTP Header named Content-Type with the following values: a. For GZip, use application/x-gzip b. For DEFLATE, use application/x-deflate Status: Approved Classification: RESTRICTED Page 30 of

31 4. Use the appropriate endpoint as defined above. Note that responses from the server will also use the specified compression method, and will have to be decompressed accordingly. These compression methods are available in both test and live environments. Method Environment Endpoint Item_manifest-1 Production TBA Item_manifest-1 Test 1 Spoil-1 Production TBA Spoil-1 Test Status: Approved Classification: RESTRICTED Page 31 of

32 9 Mailmark testing 9.1 Upload Testing For the Mailmark process within UK Mail, UK Mail will be performing the upload into Royal Mail. As a result, there is a set of required testing that each Mail Producer interested in using Mailmark must adhere to the ability to upload item data into UK Mail that links into its associated container manifest. This testing may be split into various situations. Key notes are that Using accredited third party software for item manifest uploading Step Description 1 Register interest in Mailmark with Customer General Manager 2 Acquire web-service credentials for production environment from Customer General Manager as stated in section UK Mail Customer Integrations Analyst to initiate contact with Mail Producer 4 Send item manifest into UK Mail Manifest system 5 Send container level file to Customer Integrations analyst 6 Customer Integrations analyst performs internal testing 7 Customer Integrations analyst provides testing results Using in-house development for item manifest uploading Step Description 1 Register interest in Mailmark with Customer General Manager 2 Acquire web-service credentials for test and production environments from Customer General Manager as stated in section UK Mail Customer Integrations Analyst to initiate contact with Mail Producer 4 UK Mail Customer Integrations Analyst to provide set of scenarios requiring completion to Mail Producer. Scenarios include ability to send data into manifest system, container-item link checks, load testing and error handling. 5 Mail Producer to complete scenarios provided Status: Approved Classification: RESTRICTED Page 32 of

33 6 Customer Integrations Analyst performs internal testing 7 Customer Integrations analyst provides testing results Performing Barcode validation (recommended) Royal Mail can conduct a simple barcode check using a desktop scanner. This will provide detail on the structure and content of the barcode. A live SCID is not required for this check any seven digit numeric string can be used at this point. An electronic copy of the barcode can be ed to mailmarkqa@royalmail.com, or a hard copy can be sent to: Mailmark Quality Assurance Royal Mail Customer Services Drake House Breakwater Road Plymouth PL9 7HW Please ensure that you provide contact details for any feedback to be sent to. A full Quality Assurance test can also be conducted. This involves the production of 200 mail samples carrying live addresses and barcodes containing a live SCID. The samples should be sent to Royal Mail in Plymouth (at the address above) along with a completed copy of the attached form: Mailmark Quality Assurance Form.doc You will need to provide item data to UK Mail in the usual way for UK Mail to upload to Royal Mail please liaise with your UK Mail account manager on this. Once the emanifest has been uploaded to Royal Mail and the samples run through a Royal Mail sorting machine a live Mailmark report will be generated, detailing how many of the samples were read by Royal Mail. Status: Approved Classification: RESTRICTED Page 33 of

34 10 Optional fields in emhs for Mailmark reporting 10.1 Optional Fields Mailmark Reporting Customers who submit emanifest files to UK Mail will have the option to include customer specified date to identify their mailings. This data (if submitted) is then carried through to the Royal Mail emhs and visible in the customer s Mailmark reports 1. These optional fields are: MailOriginatorSubDivisionName CampaignName Department SPARE9 MailOriginatorSubDivisionName Customers who populate the MailOriginatorSubDivisionName field will see that data appear in the Job Report tab in the Mailmark reporting portal. This enables separate emanifests to be linked together in a single report under one job. CampaignName Customers who populate the CampaignName field will see that data appear in the Campaign Report tab in the Mailmark reporting portal. This enables separate emanifests to be linked together in a single report under one campaign. This optional field is particularly recommended by UK Mail, as, under the UK Mail process, emanifest IDs are created by UK Mail, not by the Mail Producer. Populating the Campaign Name enables Mail Producers to link a single job/despatch that may have been handed over to UK Mail over multiple days into one single report. Department Optional field in emhs for customer specified department name, which appears in the Customer s item level Mailmark reports. SPARE9 (Customer Reference) 1 Guidance on the emhs reporting may be found at: Status: Approved Classification: RESTRICTED Page 34 of

35 Optional field in emhs for Customer specified reference. Although the attribute name in the emanifest is called SPARE9, this will appear as Customer Reference in the Mailmark item level report. 11 Web method error codes and messages Error Web Method Response Code Message Description 1 All 0 Success Success No further actions required 2 All 503 Gateway Timeout Proxy/network error preventing connecting between user and webservice. 3 All 504 Service Unavailable 4 All SECU1075 Missing Supporting Tokens 5 All SECU1012 Unable to find the user account for request identities 6 Item_manifest-1 ERR001 The number of items contained in the Item manifest message is greater than Item_manifest-1 ERR002 Cannot have multiple products in a batch 8 Item_manifest-1 ERR003 Cannot have multiple formats in a batch 9 Item_manifest-1 ERR004 Cannot have multiple classes in a batch 10 Item_manifest-1 ERR005 Data Integrity Fault Internal UK Mail error occurred Security header has not been added to web-service call Account has not been added to relevant security groups Maximum number of individual items in a single call cannot exceed 1,000. A single Batch Reference may only have a single Royal Mail OBA code A single Batch Reference may only have a single Royal Mail Format code A single Batch Reference may only have a single Royal Mail Class code Certain fields in the message do not fit to the web-service schema Status: Approved Classification: RESTRICTED Page 35 of

36 Error Web Method Response Code Message Description 11 Item_manifest-1 ERR006 Duplicate Message Item ID already in use 12 Item_manifest-1 ERR007 Item ID has already been used on a previous day 13 Item_manifest-1 ERR008 SPARE8 is already linked to a Batch Reference this is unique 14 Item_manifest-1 ERR020 Cannot have duplicate EIBItemId in a batch 15 Item_manifest-1 ERR037 The Username is not set in the Ukmail headers 16 Item_manifest-1 ERR038 The Username and the SCID are not mapped together Web-service call contains references to the same item ID more than once. Combination of unique item ID and SCID already exists in the UK Mail database. Item-link field has been used in a Batch Reference different from that in the existing message. ItemId already exists in the BatchReference and SCID specified. Security header is present, but no username has been populated. SCID being used is currently in use by a different Mailing House. 17 Item_manifest-1 ERR999 Unhandled Error Internal UK Mail error generated whilst writing to a database. 18 Spoil-1 ERR0026 The message could not be validated against the Schema 19 Spoil-1 ERR0028 At least one item could not be deleted 20 Spoil-1 ERR0029 The Batch status does not allow for this operation 21 Spoil-1 ERR0030 Batch Reference not found Certain fields in the message do not fit to the web-service schema One or more items are either not in a new state, or the item ID specified is not present in the UK Mail database. Some/all of the items associated to the Batch have already been uploaded to Royal Mail. Batch Reference specified in web-service call is not present in UK Mail database Status: Approved Classification: RESTRICTED Page 36 of