Supplier Web Services (Full)

Transcription

1 Supplier Web Services (Full)

2 All rights reserved. No parts of this work may be reproduced in any form or by any means - graphic, electronic, or mechanical, including photocopying, recording, taping, or information storage and retrieval systems - without the written permission of the publisher. Products that are referred to in this document may be either trademarks and/or registered trademarks of the respective owners. The publisher and the author make no claim to these trademarks. This document has been prepared and remains the copyright of ProcServe. The information contained in this document is proprietary and confidential to ProcServe and should only be made available to the recipients defined in the Distribution List, or employees of the recipients business. The recipient of this document agrees that it will not duplicate any information contained within this document except for internal use. This document is version controlled and any updates or amendments will be detailed in the Change Control section of this document. The information defined in this document is relevant to the date and time of its publication. ProcServe accepts no responsibility for inaccuracy of the information contained within this document after its publication date. Printed: September 2009 Software Version: 1.0.0

3 Contents I Table of Contents Foreword Part 1 Introduction About... ProcServe Message... Types and Standards cxml... 4 What is cxml?... 4 How is cxml... Structured? Basda... Part 2 Understanding the Architecture and Communication 2.1 Document... Encoding (UTF-8) Part 3 Contact Details 10 Part Conditions... of Use and Reference Supplier... Web Services Overview Connection... Details Security... Overview 16 Overview How to obtain... a Certificate 17 Certificate... Installation and Registration 18 Calling the DownloadDocumentList... Function 20 Description Parameters Example... Response 22 Negative... Response DownloadDocumentListByStatus... Function 24 Description Parameters Example... Response 26 Negative... Response DownloadDocument... Function 28 Description Parameters Example... Response 30 Negative... Response SetDocumentStatus... Function 35 Description Parameters Example... Response 37 Negative... Response UploadDocument... Function 39 Description... 39

4 Contents II Parameters Example... Response 41 Negative... Response WSDL... Definition 48 Part 5 Appendices 5.1 Example... Messages cxml Basda

5 1 Introduction

6 2 Introduction 1 Introduction 1.1 About ProcServe What is ProcServe? ProcServe provides a Trading Network linking buyers and suppliers together via a shared ecommerce infrastructure What does ProcServe offer? ProcServe offers packaged Trading Solutions to enable our customers of all sizes and technical capabilities to connect to the Trading Network. What do the solutions consist of? The ProcServe solutions are a blend of world-class application Trading Modules, all hosted and managed by ProcServe, combined with professional service packages that ensure a swift implementation and maximum return on investment Essentially the ProcServe Trading Network consists of a Purchase to Payment (P2P) system; a marketplace where goods and services can be selected from catalogues; and a supplier portal where suppliers can receive orders and invoice the buyer. Who else uses the ProcServe Trading Network? The ProcServe Trading Network is used by buying organisations in the private and public sector as well as suppliers. The Trading Network is flexible in that it can be used for large and small organisations such as central government departments and schools. Benefits for Buyers Buying organisations enjoy efficiency improvements by: Providing users with access to a wide variety of suppliers so that they can make more informed, value for money decisions Having access to comprehensive data about spending patterns and suppliers which will enable contracts to be established which offer increased value for money Reducing costs by eliminating administrative and manual procurement processes, including catalogue management and paper transactions Providing an opportunity to join a ready-made trading network, reducing costs of procuring a marketplace and/or purchase-to-pay environment for the subscribing organisations Extending any existing investment in eprocurement or associated capability Meeting specific government and/or internal eprocurement targets Creating better and more accessible management information about procurement spend Benefits for Suppliers Supplier organisations enjoy the following benefits: A service that is free of supplier transaction charges or subscription fees Access to an electronic marketplace to promote products and services to public sector organisations The ability to trade electronically with buyers, including processing purchase orders and invoices, in a manner that is efficient, reducing process time and cost, and potentially reducing account management resource requirements A level playing field for all suppliers regardless of size and location

7 3 Introduction 1.2 Message Types and Standards Message types The ProcServe Trading Network supports various of types of messages for system communication. These include: PunchOut to Catalogue messages: Request to PunchOut Response Outcome of PunchOut Session Business Documents: Request for Quote Quote Order Order Response Order Fulfillment Notice Invoice Credit Note Message/Document format standards For PunchOut, cxml standard messages are transferred between the P2P system and the ProcServe Trading Network. For Business Documents, cxml standard document formats are preferred. However, for some document types, other document formats are also supported, being transformed to and from cxml by the ProcServe Trading Network for use internally and for communication with supplying organisations.

8 4 Introduction 1.3 cxml What is cxml? cxml is an internationally recognised, standard set of message formats and a basic protocol for the communication of those messages between procurement applications, e-commerce websites and suppliers' sales systems. There are messages defined for all the most common business transactions. Examples of these messages are provided later in this guide. cxml is based on the XML language standard. All cxml messages are "well-formed" XML documents. Web-hosted "Document Type Definition" (DTD) files provide the formal schemas i.e. descriptions of constraints in the structure and data content of the compliant documents. Using cxml as the standard for messages provides a number of benefits: It makes it easy to implement advanced functionality It integrates well with suppliers' systems It supports PunchOut to Catalogue transactions It can be expanded to cater for extra data not envisaged by the standard's authors cxml user guides and DTD files are available for free download from the official cxml website: Any expansions in data sent is limited by the point-to-point configurations needed for communication. If the receiver is unaware that an extra string of information is being delivered it may lead to that data being dropped or the whole communication being rejected.

9 5 Introduction How is cxml Structured? cxml has three main elements an Envelope, Header and Line Item. The detail for the three elements is shown in the next table. TABLE ONE STRUCTURE, EXAMPLE AND DESCRIPTION OF CXML. Please note the example below is for illustration purposes only. ELEMENTS DESCRIPTION cxml EXAMPLE STRUCTURE Envelope The root of cxml documents and contains all other elements <?xml version="1.0"?> Indicates that this is an XML file and gives the version of XML <!DOCTYPE cxml SYSTEM " schemas/cxml/ /cxml.dtd"> The type of cxml document and URL of the document type definition. This is the reference as to where the file content can be found. <cxml xml:lang="en-us" Identifies the local language for all of the text used within the document A unique number random generated and time stamped, used for logging purposes to identify documents that might have been lost or had problems. The recommended format is: datetime.process id.random timestamp=" t08:45:35-07:00"> The date and time that the document was sent using the ISO 8601 standard. The recommended format is: The YYYY-MM-DDThh:mm:ss-hh:mm. Should a document fail this number should not change for the following attempts to pass the message. <Header> Opens the header portion of the communication The Header portion of the document contains addressing and authentication information. This information is contained in the substance of the transmission (From, To and Sender) <From> Opens From The originator of the request Header The Header element contains addressing and authentication information and is the same regardless of the specific Request or Response within the body of the cxml message. <Credential domain="duns"> <Identity>[SBO DUNS Number here]</identity> Defining the identifier Contains the detail of the From field </Credential> Fields work in tandem with the meat of the communication coming in between DESCRIPTION The originators unique DUNS number Contains identification and authentication values of the requestor </From> Closes From - <To> Opens To Destination of the request <Credential domain="duns"> <Identity>ProcServe Catalogue System</Identity> Contains the detail of the To field </Credential> </To> <Sender> Always this Contains identification and authentication values of the receiver Closes To - Opens Sender Allows the receiving party to authenticate the requestor <Credential domain="networkuserid">??? <Identity>[SBO Short Name]</Identity>??? <SharedSecret>[A password you send to us]</ SharedSecret> Contains the detail of the Sender field </Credential> The SharedSecret element is used when the Sender has a password that the requester recognizes Contains identification and authentication values of the sender <UserAgent>[MARKETPLACE NAME]</UserAgent> Line Item The line elements differ dependant on the xml message that is being sent. The DTD </Sender> Closes Sender - </Header> Closes the header portion of the communication <Request deploymentmode="production">??? <PunchOutSetupRequest operation="create"> This indicates the type of request that the message is sending

10 6 Introduction (document type definition) will define what can be sent, what is optional and what is mandatory. If you need to send data that is not part of the DTD then extrinsic elements can be used to customise the message and include this data. <BuyerCookie>[Cookie SessionID]</BuyerCookie> <Extrinsic name="user">[user Name]</Extrinsic> <Extrinsic name=" ">[user Address]</ Extrinsic> <Extrinsic name="jpbcloginname">[unique User Logon]</Extrinsic> <Extrinsic name="jpbclanguage">en</extrinsic> Note: All parties receiving this extrinsic must be aware of it and its purpose This element must be included on all subsequent PunchOut operations and is unique per PunchOut session. It enables the P2P to match the differing PunchOut requests. <Extrinsic name="jpbcterritory">gb</extrinsic> <Extrinsic name="procserve Catalogue System ClassView">[Classification View Name]</ Extrinsic> Optional element the requestor wants to pass to the supplier. The specification of the cxml does not define the content of the Extrinsic elements and it is therefore something that the requestor and receiver must agree on. The receiver must know that the extra information is coming however or they will not receive it and it may lead to the message failing to deliver. <Extrinsic name="classview"> Classification View Name]</Extrinsic> <BrowserFormPost> Opens the BrowserFormPost This is specific to the PunchOutOrderMessage and is the destination for the data within the message <URL>[URL for shopping basket response]</url> BrowserFormPost message The source of reference for the message and is system generated </BrowserFormPost> Closes the BrowserFormPost - </PunchOutSetupRequest> Closes this request - </Request> Closes the PunchOut request </cxml> Closes this message to end the message <SupplierSetup> <URL>[Agreed URL]</URL> </SupplierSetup> Close The communication is finished

11 2 Understanding the Architecture and Communication

12 8 Understanding the Architecture and Communication 2 Understanding the Architecture and Communication 2.1 Document Encoding (UTF-8) Encodings are different ways of representing character data, which humans need, to numbers (and therefore the binary codes) that computers need. ProcServe use UTF-8 to encode their documents. UTF8 uses more than one byte to store a character and is the industry standard as it negates many issues previously found in earlier encoding language. Encoding in XML The first line of an XML document has a statement like the following one: <?xml version="1.0" encoding="utf-8"?> This denotes the remainder of the document as XML and informs the reading program how the characters are encoded. UTF-8 is understood by most modern programs and will not break older programs (although they will not display all the characters correctly) since the null code is never used in a real character (unlike UTF-16). UTF-8 can display all the characters there are by using 1 to 4 bytes. There are some issues to with UTF-8 to be wary of. The UK pound sign is often represented by code 163 (A3 in hex) in Windows (using ISO ) but should be two bytes, 194 then 163 (C2 A3 in hex) for UTF-8. Windows clipboard and some other programs like Word can silently change your encoding when copying from one program to another (like word to a browser). Be more careful with characters like,,, as these are common silent conversion issues. You can just use the Unicode values for and character with &#unicode; as this is just ASCII (and therefore good UTF-8 too) i.e. or &#0169 or &#0174 or &#8364 or &#0163 Try not to use etc. as that is really for HTML not XML, even though it may work in some cases. It is not always enough to just set the first line in your program, as the output encoding will still be whatever is native to your system. You need to write the file out in the correct encoding. In Java it would be something like: File file = new File( filename.xml ); OutputStreamWriter osw = new OutputStreamWriter(new FileOutputStreamWriter(file), UTF-8 )); BufferedWriter out = new BufferedWriter(osw); out.write(myxmlstring); out.close();

13 3 Contact Details

14 10 Contact Details 3 Contact Details If you have any queries in regard to our supplier services, ProcServe Supplier Solutions Ltd can be contacted at the following:- How to reach us Comments suppliersupport@procserve.com For general queries, questions and support issues. Please provide full contact details and a description of the support issue / query. Fax: Please provide full contact details and a description of the support issue / query when submitting faxes. Postal Address: ProcServe, 123 Buckingham Palace Road, London, England, SW1W 9SR Please include full contact details with any written correspondence. Phone: For general queries, questions and support issues. Please be ready to provide full contact details and a description of the support issue / query. If you would like to talk to a member of ProcServe's sales team in regards to the provision of Value Added Services for the deployment of ProcServe's Supplier Services please send an to: info@procserve.com

15 4

16 Conditions of Use and Reference This documentation is intended, primarily, for software or system developers who wish to access methods from other systems. It is assumed that you are familiar with the concept of Web Services and have some knowledge of Certificate technology, the HTTP and SOAP protocols and XML document formats. The use of the is on a self-service basis, however Value Added Services from ProcServe Supplier Solutions Limited or it's approved partners are available upon request to assist with the deployment of. In order to use successfully you must first register with ProcServe Supplier Solutions Limited. However, please note that the consequences of your use of are your responsibility. It is expected and highly recommended that you will perform testing and ensure that the results are satisfactory before going on to use with live documents for your business. The Web Service methods provide helpful error messages which will aid testing.

17 Overview ("SWS") is a set of SOAP Web Services which allow Suppliers to connect to the Supplier Portal to transfer electronic business documents between the Portal and their local network infrastructure to facilitate the integration to existing back-office systems. SOAP is a simple XML-based protocol to let applications exchange data over the internet. For more information on SOAP Web Services see This guide is intended as a developer reference to aid with the construction of a web service client which will consume the SWS services. It assumes some familiarity with Web Services, XML, X509 Client Certificates and other related technologies. If your company does not have access to the relevant technologies and skills to implement a client for SWS, then SWS is probably not the ideal solution for your integration requirements. In this case you should contact your Supplier Portal service provider for information on other integration methods which may be available. Scope "SWS" is a set of web services which are instantiated by the client, not the server "SWS" allows the client to collect Purchase Orders, and upload Invoices and Credit Notes "SWS" allows the consuming application to specify which format the documents should be downloaded in "SWS" services ensure the identity of any consumers using secure client certificates "SWS" is not a "push" technology, it is a passive "self-service" interface "SWS" does not provide direct integration into back-office systems, it is purely a message transport system. Applications which consume the "SWS" services will perform integration with client-side systems. The functions currently available include: 1. DownloadDocumentList returns a summary list of documents found in the Supplier Portal database. 2. DownloadDocumentListByStatus returns a summary list of documents found in the Supplier Portal database by Supplier Status. 3. DownloadDocument returns the full content of a single document. 4. SetDocumentStatus will update a specific document status 5. UploadDocument stores a new document in the Supplier Portal database and, optionally, transmits it to the relevant Buying Organisation. It is anticipated that the first three functions will be used to bring documents (e.g. purchase orders) into your back-office system. The SetDocumentStatus function is used to update downloaded documents so that they are classified with a status indicating that they have already been downloaded. The UploadDocument fucntion is suitable for taking documents that have been created in your backoffice system (e.g. invoices), storing them in the Supplier Portal database and transmitting them to the Buying Organisations. The diagram below provides a graphical representation of how SWS can be deployed.

18 14 NOTE - in addition to, ProcServe Solutions Limited also provide the spconnect application. The spconnect application is a fully packaged software solution that can replicate the functionality of supplier Web Services and has been designed for use by organisations that do not have the internal resources to build customised web service solutions.

19 4.3 Connection Details The URLs are: Live Production: UAT (User Acceptance Testing) / Demo Environment (available upon request for integration testing): 15

20 Security Overview Overview In order to ensure message integrity and security, makes use of HTTP and SOAP protocols and Certificate technology. The following information is for general guidance only.

21 How to obtain a Certificate require the use of trusted client certificates for authenticating the client application. These certificates must be obtained from a trusted certificate authority such as Verisign or Thawte. ProcServe have validated and tested Thawte Personal certificates for use with SWS, although you can use any valid client certificate that is intended for proving your identity to a remote computer, eg: NOTE: Internal or local certificate authorities are not supported. You can acquire a free Personal certificate from Thawte here:

22 Certificate Installation and Registration You will need to install the certificate so that your software uses it when making requests to Supplier Web Services methods. Once the certificate is installed in your Personal certificate store on the computer which will be communicating with SWS, you need to export it in.p7b format and send it to ProcServe via to: Be sure to include all certificates in the certificate chain when exporting the certificate. Do not include the private key. ProcServe will then register your client certificate on the SWS server to ensure that the server will trust you and allow you to use the SWS web services. NOTE: Your request will be rejected with an error message explaining that you are not enabled for Web Services or that the certificate is not recognised until you have sent your certificate in.p7b format to ProcServe. IMPORTANT: Your client certificate should be considered private and is a key to your data within the Supplier Portal. Under no circumstances should you give a copy of the private key to anyone outside your organisation as this could compromise the security of your data. If at any time you feel that the security of your certificate has been compromised, you must contact the ProcServe Helpdesk immediately so that we can disable access to your data using the compromised certificate.

23 Calling the The calling application must pass the client certificate when calling the. The uses the certificate to identify your organisation and will only return documents related to your organisation.

24 DownloadDocumentList Function Description This function returns an XML document string which contains a summary list of transaction documents that are known to the Supplier Portal. The scope of the document list is limited by the parameters you pass to the function and by your credentials (i.e. only documents for your organisation are listed). The XML string has a root element named DownloadDocumentList. Within this root element is one Document element per document. Within each Document element there are other elements that provide the summary details of the document: <DocID> is the unique identity assigned to that document within the Supplier Portal database. <DocTimeStamp> is the date that it was first received into the Supplier Portal database. <DocNo> is the document order number as assigned by the buying organisation. <DocDate> is the document date that as stated by the buying organisation. <Void> is a "Y" or "N" flag indicating whether or not the document has been cancelled/superseded. <PreviousDownloads> is a count of the number of times this document has been downloaded from using the DownloadDocument method. <DocStatus> this is the Supplier's status for the document. <BuyerDUNS> this is the Buyer's DUNS number. <Source> indicates the means by which the document came to be in the database. NOTE - a DUNS number is a nine digit numerical code assigned to an organisation by Dun & Bradstreet. Please see for more information.

25 Parameters Name DocumentType Type String StartDateTime String BuyerDUNS String NewDocumentsOnly Integer Notes A three character string indicating the kind of document you want a list of. Currently, the valid values are: "ORD" (Orders) "INV" (Invoices) "CRN" (Credit Notes) The date and, optionally, time of the earliest document to be included in the list. Note that this is the date that Supplier Portal was first aware of the document i.e. when it was received by Supplier Portal or created within Supplier Portal not necessarily the same as the Transaction Date stated within the document. We recommend that you supply the date in YYYY-MM-DD format e.g. " " The Buyer's DUNS number (can be left blank) A "0" value indicates that you want details of all documents consistent with the other 2 parameters. A "1" value indicates that you want details only of documents that have not yet been downloaded via the DownloadDocument function.

26 Example Response The following example lists 2 documents of type "ORD" i.e. orders. <DownloadDocumentList> <Document type="ord"> <DocID>659</DocID> <DateTimeStamp> T16:41: :00</DateTimeStamp> <DocNo>SG10009</DocNo> <DocDate> T00:00:00+01:00</DocDate> <Void>N</Void> <PreviousDownloads>0</PreviousDownloads> <DocStatus>Imported</DocStatus> <BuyerDUNS> </BuyerDUNS> <Source>Supplier Portal User Input</Source> </Document> <Document type="ord"> <DocID>661</DocID> <DateTimeStamp> T16:45: :00</DateTimeStamp> <DocNo>SG10010</DocNo> <DocDate> T00:00:00+01:00</DocDate> <Void>N</Void> <PreviousDownloads>0</PreviousDownloads> <DocStatus/> <BuyerDUNS> </BuyerDUNS> <Source>Supplier Portal User Input</Source> </Document> </DownloadDocumentList>

27 Negative Response Note that it is not considered to be an error condition if there are no documents within the scope defined by the parameters passed. Your software should cater for the "empty list" scenario. An "empty list" is returned as follows: <DownloadDocumentList></DownloadDocumentList> A SOAP Exception (which includes an error message) is returned when it is not possible to successfully complete the processing that you have requested. So your software may need to trap SOAP Exceptions. The following are typical conditions that would result in a SOAP Exception: Missing or invalid Certificate Invalid parameter value e.g. poorly formatted StartDateTime Supplier not permitted or configured to use Supplier Portal database not available

28 DownloadDocumentListByStatus Function Description Returns an XML document string which contains a summary list of transaction documents that are known to Supplier Portal. The scope of the document list is limited by the parameters you pass to the function and by your credentials (i.e. only documents for your organisation are listed). The XML string has a root element named DownloadDocumentList. Within that, there is one Document element per document. Within each Document element there are other elements that provide the summary details of the document: <DocID> is the unique identity assigned to that document within the Supplier Portal database. <DocTimeStamp> is the date that it was first received into the Supplier Portal database. <DocNo> is the document order number as assigned by the buying organisation. <DocDate> is the document date as stated by the buying organisation. <Void> is a "Y" or "N" flag indicating whether or not the document has been cancelled/superseded. <PreviousDownloads> is a count of the number of times this document has been downloaded from using the DownloadDocument method. <DocStatus> this is the Supplier's status for the document. <BuyerDUNS> this is the Buyer's DUNS number. <Source> indicates the means by which the document came to be in the database. NOTE - a DUNS number is a nine digit numerical code assigned to an organisation by Dun & Bradstreet. Please see for more information.

29 Parameters Name DocumentType Type String StartDateTime String BuyerDUNS DocumentStatus String String Notes A three character string indicating the kind of document you want a list of. Currently, the valid values are: "ORD" (Orders) "INV" (Invoices) "CRN" (Credit Notes) The date and, optionally, time of the earliest document to be included in the list. Note that this is the date that Supplier Portal was first aware of the document i.e. when it was received by Supplier Portal or created within Supplier Portal not necessarily the same as the Transaction Date stated within the document. We recommend that you supply the date in YYYY-MM-DD format e.g. " " The Buyer's DUNS number (can be left blank) The Supplier's status for the document (50 characters)

30 Example Response The following example lists 2 documents of type "ORD" i.e. orders. <DownloadDocumentList> <Document type="ord"> <DocID>659</DocID> <DateTimeStamp> T16:41: :00</DateTimeStamp> <DocNo>SG10009</DocNo> <DocDate> T00:00:00+01:00</DocDate> <Void>N</Void> <PreviousDownloads>0</PreviousDownloads> <DocStatus>Imported</DocStatus> <BuyerDUNS> </BuyerDUNS> <Source>Supplier Portal User Input</Source> </Document> <Document type="ord"> <DocID>661</DocID> <DateTimeStamp> T16:45: :00</DateTimeStamp> <DocNo>SG10010</DocNo> <DocDate> T00:00:00+01:00</DocDate> <Void>N</Void> <PreviousDownloads>0</PreviousDownloads> <DocStatus/> <BuyerDUNS> </BuyerDUNS> <Source>Supplier Portal User Input</Source> </Document> </DownloadDocumentList>

31 Negative Response Note that it is not considered to be an error condition if there are no documents within the scope defined by the parameters passed. Your software should cater for the "empty list" scenario. An "empty list" is returned as follows: <DownloadDocumentList></DownloadDocumentList> A SOAP Exception (which includes an error message) is returned when it is not possible to successfully complete the processing that you have requested. So your software may need to trap SOAP Exceptions. The following are typical conditions that would result in a SOAP Exception: Missing or invalid Certificate Invalid parameter value e.g. poorly formatted StartDateTime Supplier not permitted or configured to use Supplier Portal database not available

32 DownloadDocument Function Description Returns a string which provides the full content of the requested document in an XML format. A parameter passed to the function specifies which standard XML format that you want - please see Parameter section. Currently supported XML formats for download are: Purchase Orders Currently supported XML formats for download are: cxml version 1.2 or greater with ProcServe conventions cxml version 1.2 or greater BASDA ebis 3.07 BASDA ebis 3.09 NOTE: Please contact ProcServe Supplier Solutions Limited to enquire about other business documents or XML formats.

33 Parameters Name DocumentID Type Integer FormatID Integer Notes The unique document id of the document you want. This can be found in the details returned from the DownloadDocumentList function. Indicates the standard format to be used for the string representation of the document that is returned. Currently, valid values are:"1" = cxml version 1.2 or greater with ProcServe conventions "3" = BASDA ebis 3.07 "4" = BASDA ebis 3.09 "5" = cxml version 1.2 or greater

34 Example Response <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE cxml SYSTEM " <cxml timestamp=" t09:54:52-0:00" version=" " xml:lang="en-gb" payloadid="dwpxml "> <Header> <From> <Credential domain="duns"> <Identity> </Identity> </Credential> <Credential domain="gln"> <Identity> </Identity> </Credential> <Credential domain="sellerrefforbuyer"> <Identity>ZDO123</Identity> </Credential> </From> <To> <Credential domain="duns"> <Identity> </Identity> </Credential> <Credential domain="gln"> <Identity> </Identity> </Credential> <Credential domain="buyerrefforseller"> <Identity>OGC123</Identity> </Credential> </To> <Sender> <Credential domain="networkuserid"> <SharedSecret>some.password.here</SharedSecret> </Credential> <UserAgent>pecos.ipm v9.1</useragent> </Sender> </Header> <Request deploymentmode="production"> <OrderRequest> <OrderRequestHeader orderdate=" t00:00:00" orderid="sg10010" agreementid="abc123" type="new"> <Total> <Money currency="gbp">143.50</money> </Total> <ShipTo> <Address addressid="794" isocountrycode="gb"> <Name xml:lang="en">procserve Demonstration Organisation</Name> <PostalAddress name="ogc"> <DeliverTo>Robert Smith</DeliverTo> <DeliverTo>ProcServe Demonstration Organisation Goods-In</ DeliverTo> <Street>Office of Goverment Commerce</Street> <Street>Trevelyan House</Street> <Street>Great Peter Street</Street> <City>LONDON</City> <State>London</State> <PostalCode>SW1P 2BY</PostalCode> <Country isocountrycode="gb">united Kingdom</Country>

35 </PostalAddress> <Phone name="direct"> <TelephoneNumber> <CountryCode isocountrycode="gb">44</countrycode> <AreaOrCityCode>0870</AreaOrCityCode> <Number> </Number> </TelephoneNumber> </Phone> <Phone name="mobile"> <TelephoneNumber> <CountryCode isocountrycode="gb">44</countrycode> <AreaOrCityCode>07984</AreaOrCityCode> <Number>000000</Number> </TelephoneNumber> </Phone> <Fax> <TelephoneNumber> <CountryCode isocountrycode="gb">44</countrycode> <AreaOrCityCode>0870</AreaOrCityCode> <Number> </Number> </TelephoneNumber> </Fax> </Address> </ShipTo> <BillTo> <Address addressid="794" isocountrycode="gb"> <Name xml:lang="en">procserve Demonstration Organisation</Name> <PostalAddress name="ogc"> <Street>Office of Goverment Commerce</Street> <Street>Trevelyan House</Street> <Street>Great Peter Street</Street> <City>LONDON</City> <State>London</State> <PostalCode>SW1P 2BY</PostalCode> <Country isocountrycode="gb">united Kingdom</Country> </PostalAddress> <Phone name="direct"> <TelephoneNumber> <CountryCode isocountrycode="gb">44</countrycode> <AreaOrCityCode>0870</AreaOrCityCode> <Number> </Number> </TelephoneNumber> </Phone> <Fax> <TelephoneNumber> <CountryCode isocountrycode="gb">44</countrycode> <AreaOrCityCode>0870</AreaOrCityCode> <Number> </Number> </TelephoneNumber> </Fax> </Address> </BillTo> <Shipping trackingdomain="supplier Truck"> <Money currency="gbp">0</money> <Description xml:lang="en-gb">next Day</Description> 31

36 32 </Shipping> <Payment> <PCard number=" " expiration=" " name="mr T Lerone"/> </Payment> <Contact role="purchasingagent"> <Name xml:lang="en">toby Lerone</Name> < >demobuyer@ogc.gov.uk</ > <Phone name="direct"> <TelephoneNumber> <CountryCode isocountrycode="gb">44</countrycode> <AreaOrCityCode>0870</AreaOrCityCode> <Number> </Number> </TelephoneNumber> </Phone> <Phone name="mobile"> <TelephoneNumber> <CountryCode isocountrycode="gb">44</countrycode> <AreaOrCityCode>07984</AreaOrCityCode> <Number>000000</Number> </TelephoneNumber> </Phone> <Fax> <TelephoneNumber> <CountryCode isocountrycode="gb">44</countrycode> <AreaOrCityCode>0870</AreaOrCityCode> <Number> </Number> </TelephoneNumber> </Fax> </Contact> <Extrinsic name="cardtype">visa Credit</Extrinsic> <Extrinsic name="cvv">123</extrinsic> <Extrinsic name="projectreference">project 891</Extrinsic> <Comments>Please respond via if this order cannot be delivered by end of the month, thanks <Attachment> <URL Name="FurtherDetails.doc"> Attachments.aspx?ID=12321</URL> </Attachment> </Comments> </OrderRequestHeader> <ItemOut quantity="5" linenumber="1" requesteddeliverydate=" "> <ItemID> <SupplierPartID>WIDGET001</SupplierPartID> </ItemID> <ItemDetail> <UnitPrice> <Money currency="gbp">20.00</money> </UnitPrice> <Description xml:lang="en">widget type 1, white, OEM version</ Description> <UnitOfMeasure>EA</UnitOfMeasure> <Classification domain="unspsc"> </classification> <Classification domain="gtin"> </classification> <ManufacturerName>Sony</ManufacturerName> <ManufacturerPartID>S19243</ManufacturerPartID> <URL> </ItemDetail>

37 <SupplierID domain="duns"> </supplierid> </ItemOut> <ItemOut quantity="3" linenumber="2" requesteddeliverydate=" "> <ItemID> <SupplierPartID>WIDGET002</SupplierPartID> </ItemID> <ItemDetail> <UnitPrice> <Money currency="gbp">14.50</money> </UnitPrice> <Description xml:lang="en">widget type 2, yellow, retail version</ Description> <UnitOfMeasure>EA</UnitOfMeasure> <Classification domain="unspsc"> </classification> <Classification domain="gtin"> </classification> <ManufacturerName>Sony</ManufacturerName> <ManufacturerPartID>S19284</ManufacturerPartID> <URL> </ItemDetail> <SupplierID domain="duns"> </supplierid> </ItemOut> </OrderRequest> </Request> </cxml> 33

38 Negative Response A SOAP Exception (which includes an error message) is returned when it is not possible to successfully complete the processing that you have requested. So your software may need to trap SOAP Exceptions. The following are typical conditions that would result in a SOAP Exception: Missing or invalid Certificate Invalid parameter value e.g. unknown DocumentID Supplier not permitted or configured to use Supplier Portal database not available

39 4.8 SetDocumentStatus Function Description Stores the passed status against the document in the Supplier Portal database. 35

40 Parameters Name DocumentID Type Integer DocumentStatus String Notes The unique document id of the document you want. This can be found in the details returned from the DownloadDocumentList function. The Supplier's status to be assigned to the document.

41 4.8.3 Example Response <Status>OK</Status> 37

42 Negative Response A SOAP Exception (which includes an error message) is returned when it is not possible to successfully complete the processing that you have requested. So your software may need to trap SOAP Exceptions. The following are typical conditions that would result in a SOAP Exception: Missing or invalid Certificate Invalid parameter value e.g. unknown DocumentID Supplier not permitted or configured to use Supplier Portal database not available The document might be in use by another process

43 UploadDocument Function Description Stores the passed document in the Supplier Portal database and, optionally, submits it for transmission to the Buying Organisation. Returns an XML document string which contains the Document ID assigned to the uploaded document in the Supplier Portal database. Currently supported XML formats for upload are: Invoices Credit Notes Currently supported XML formats for invoice and credit note upload are: cxml version 1.2 or greater with ProcServe conventions cxml version 1.2 BASDA ebis 3.09 NOTE: Please contact ProcServe Supplier Solutions Limited to enquire about other business documents or XML formats.

44 Parameters Name DocumentText AutoSend Type String Integer Notes The text of the document you are uploading into Supplier Portal. A "0" value indicates that you want the document to be uploaded into Supplier Portal but not sent immediately to the Buying Organisation. You will use the Supplier Portal website to review and send the document at some future time. A "1" value indicates that the document should be sent to the Buying Organisation immediately.

45 4.9.3 Example Response <DocID>662<DocID> 41

46 Negative Response A SOAP Exception (which includes an error message) is returned when it is not possible to successfully complete the processing that you have requested. So your software may need to trap SOAP Exceptions. The following are typical conditions that would result in a SOAP Exception: Missing or invalid Certificate Invalid parameter value e.g. unknown DocumentID Supplier not permitted or configured to use Supplier Portal database not available

47 WSDL Definition <?xml version="1.0" encoding="utf-8"?> <wsdl:definitions xmlns:soap=" xmlns:tm=" xmlns:soapenc=" org/soap/encoding/" xmlns:mime=" xmlns:tns=" xmlns:s=" xmlns:soap12=" xmlns:http=" targetnamespace=" impaq.co.uk/webservices/supplierportal/listdocuments" xmlns:wsdl=" xmlsoap.org/wsdl/"> <wsdl:types> <s:schema elementformdefault="qualified" targetnamespace=" uk/webservices/supplierportal/listdocuments"> <s:element name="downloaddocumentlist"> <s:complextype> <s:sequence> <s:element minoccurs="0" maxoccurs="1" name="documenttype" type="s: string"/> <s:element minoccurs="0" maxoccurs="1" name="startdatetime" type="s: string"/> <s:element minoccurs="1" maxoccurs="1" name="newdocumentsonly" type=" s:int"/> </s:sequence> </s:complextype> </s:element> <s:element name="downloaddocumentlistresponse"> <s:complextype> <s:sequence> <s:element minoccurs="0" maxoccurs="1" name=" DownloadDocumentListResult" type="s:string"/> </s:sequence> </s:complextype> </s:element> <s:element name="downloaddocument"> <s:complextype> <s:sequence> <s:element minoccurs="1" maxoccurs="1" name="documentid" type="s:int "/> <s:element minoccurs="1" maxoccurs="1" name="formatid" type="s:int"/> </s:sequence> </s:complextype> </s:element> <s:element name="downloaddocumentresponse"> <s:complextype> <s:sequence> <s:element minoccurs="0" maxoccurs="1" name="downloaddocumentresult" type="s:string"/> </s:sequence> </s:complextype> </s:element> <s:element name="uploaddocument"> <s:complextype> <s:sequence> <s:element minoccurs="0" maxoccurs="1" name="documenttext" type="s: string"/> <s:element minoccurs="1" maxoccurs="1" name="autosend" type="s:int"/> </s:sequence> </s:complextype>

48 44 </s:element> <s:element name="uploaddocumentresponse"> <s:complextype> <s:sequence> <s:element minoccurs="0" maxoccurs="1" name="uploaddocumentresult" type="s:string"/> </s:sequence> </s:complextype> </s:element> </s:schema> </wsdl:types> <wsdl:message name="downloaddocumentlistsoapin"> <wsdl:part name="parameters" element="tns:downloaddocumentlist"/> </wsdl:message> <wsdl:message name="downloaddocumentlistsoapout"> <wsdl:part name="parameters" element="tns:downloaddocumentlistresponse"/> </wsdl:message> <wsdl:message name="downloaddocumentsoapin"> <wsdl:part name="parameters" element="tns:downloaddocument"/> </wsdl:message> <wsdl:message name="downloaddocumentsoapout"> <wsdl:part name="parameters" element="tns:downloaddocumentresponse"/> </wsdl:message> <wsdl:message name="uploaddocumentsoapin"> <wsdl:part name="parameters" element="tns:uploaddocument"/> </wsdl:message> <wsdl:message name="uploaddocumentsoapout"> <wsdl:part name="parameters" element="tns:uploaddocumentresponse"/> </wsdl:message> <wsdl:porttype name="documentssoap"> <wsdl:operation name="downloaddocumentlist"> <wsdl:input message="tns:downloaddocumentlistsoapin"/> <wsdl:output message="tns:downloaddocumentlistsoapout"/> </wsdl:operation> <wsdl:operation name="downloaddocument"> <wsdl:input message="tns:downloaddocumentsoapin"/> <wsdl:output message="tns:downloaddocumentsoapout"/> </wsdl:operation> <wsdl:operation name="uploaddocument"> <wsdl:input message="tns:uploaddocumentsoapin"/> <wsdl:output message="tns:uploaddocumentsoapout"/> </wsdl:operation> </wsdl:porttype> <wsdl:binding name="documentssoap" type="tns:documentssoap"> <soap:binding transport=" <wsdl:operation name="downloaddocumentlist"> <soap:operation soapaction=" SupplierPortal/ListDocuments/DownloadDocumentList" style="document"/> <wsdl:input> <soap:body use="literal"/> </wsdl:input> <wsdl:output> <soap:body use="literal"/> </wsdl:output> </wsdl:operation> <wsdl:operation name="downloaddocument"> <soap:operation soapaction="

49 45 SupplierPortal/ListDocuments/DownloadDocument" style="document"/> <wsdl:input> <soap:body use="literal"/> </wsdl:input> <wsdl:output> <soap:body use="literal"/> </wsdl:output> </wsdl:operation> <wsdl:operation name="uploaddocument"> <soap:operation soapaction=" SupplierPortal/ListDocuments/UploadDocument" style="document"/> <wsdl:input> <soap:body use="literal"/> </wsdl:input> <wsdl:output> <soap:body use="literal"/> </wsdl:output> </wsdl:operation> </wsdl:binding> <wsdl:binding name="documentssoap12" type="tns:documentssoap"> <soap12:binding transport=" <wsdl:operation name="downloaddocumentlist"> <soap12:operation soapaction=" SupplierPortal/ListDocuments/DownloadDocumentList" style="document"/> <wsdl:input> <soap12:body use="literal"/> </wsdl:input> <wsdl:output> <soap12:body use="literal"/> </wsdl:output> </wsdl:operation> <wsdl:operation name="downloaddocument"> <soap12:operation soapaction=" SupplierPortal/ListDocuments/DownloadDocument" style="document"/> <wsdl:input> <soap12:body use="literal"/> </wsdl:input> <wsdl:output> <soap12:body use="literal"/> </wsdl:output> </wsdl:operation> <wsdl:operation name="uploaddocument"> <soap12:operation soapaction=" SupplierPortal/ListDocuments/UploadDocument" style="document"/> <wsdl:input> <soap12:body use="literal"/> </wsdl:input> <wsdl:output> <soap12:body use="literal"/> </wsdl:output> </wsdl:operation> </wsdl:binding> <wsdl:service name="documents"> <wsdl:port name="documentssoap" binding="tns:documentssoap"> <soap:address location=" "/> </wsdl:port> <wsdl:port name="documentssoap12" binding="tns:documentssoap12">

50 46 <soap12:address location=" asmx"/> </wsdl:port> </wsdl:service> </wsdl:definitions>

51 5 Appendices

52 48 Appendices 5 Appendices 5.1 Example Messages cxml Please view the ProcServe website to get the most up to date message types.

53 49 Appendices Basda Please refer to the website for a full and detailed overview of the BASDA ebis 3.07 and 3.09 Document Standards. Sample documents are shown on the ProcServe website

54