GS1Trade Sync Data Pool - Web Services for Data Source

Transcription

1 GS1Trade Sync Data Pool - Web Services for Data Source Connectivity Guide Version 0.9, Draft/Approved,

2 Document Summary Document Item Document Name Current Value (Connectivity Guide) Document Date Document Version 0.9 Document Status Document Description Draft/Approved This document describes the Data Source-specific implementation of web services used for GS1Trade Sync Data Pool system. Contributors Name Tibor Gottdank Zsolt Jacsó Organisation GITM Kft. GITM Kft. Log of Changes Release Date of Change Changed By Summary of Change /02/2016 Tibor Gottdank Skeleton of document /02/2016 Tibor Gottdank First draft /02/2016 Tibor Gottdank Corrected first draft /02/2016 Tibor Gottdank Corrections in Chapter /02/2016 Tibor Gottdank Minor changes /02/2016 Zsolt Jacsó Major changes /03/2016 Zsolt Jacsó New chapter: Expected steps of testing Disclaimer GS1, under its IP Policy, seeks to avoid uncertainty regarding intellectual property claims by requiring the participants in the Work Group that developed this (Connectivity Guide) to agree to grant to GS1 members a royalty-free licence or a RAND licence to Necessary Claims, as that term is defined in the GS1 IP Policy. Furthermore, attention is drawn to the possibility that an implementation of one or more features of this Specification may be the subject of a patent or other intellectual property right that does not involve a Necessary Claim. Any such patent or other intellectual property right is not subject to the licencing obligations of GS1. Moreover, the agreement to grant licences provided under the GS1 IP Policy does not include IP rights and any claims of third parties who were not participants in the Work Group. Accordingly, GS1 recommends that any organization developing an implementation designed to be in conformance with this Specification should determine whether there are any patents that may encompass a specific implementation that the organisation is developing in compliance with the Specification and whether a licence under a patent or other intellectual property right is needed. Such a determination of a need for licencing should be made in view of the details of the specific system designed by the organisation in consultation with their own patent counsel. THIS DOCUMENT IS PROVIDED AS IS WITH NO WARRANTIES WHATSOEVER, INCLUDING ANY WARRANTY OF MERCHANTABILITY, NONINFRINGMENT, FITNESS FOR PARTICULAR PURPOSE, OR ANY WARRANTY OTHER WISE ARISING OUT OF THIS SPECIFICATION. GS1 disclaims all liability for any damages arising from use or misuse of this Standard, whether special, indirect, consequential, or compensatory damages, and including liability for infringement of any intellectual property rights, relating to use of information in or reliance upon this document. Version 0.42, Draft/Approved, 17. februar 2016All rights Page 2 of 16

3 GS1 retains the right to make changes to this document at any time, without notice. GS1 makes no warranty for the use of this document and assumes no responsibility for any errors which may appear in the document, nor does it make a commitment to update the information contained herein. GS1 and the GS1 logo are registered trademarks of GS1 AISBL. Table of Contents 1 Introduction Purpose of Document Document Conventions Target Audience About Web Services Overview Service Characteristics Details of Services Feature Description of Services DataSourceOperations Service The StandardBusinessDocumentHeader parameter Description of DataSourceOperations Service DataSourceOperationsCallback Service Description of DataSourceOperationsCallback Service Return parameter Security DataSourceOperations service Transport over HTTPS Client authentication DataSourceOperationsCallback service Expected transport channel Expected authentication of client calls Connection Parameters Expected steps of testing DS DP DP DS Appendix Attached files Abbreviation Glossary References List of Figures Version 0.42, Draft/Approved, 17. februar 2016All rights Page 3 of 16

4 1 Introduction 1.1 Purpose of Document The GDSN Standard-specific web service is one of the three machine-to-machine interface technology 1 available for communicating with GS1Trade Sync. Therefore, the connectivity documentation of GS1Trade Sync Data Pool contains three main parts. Additionally, the web service-based connectivity documentation divided into two further parts: Connectivity guide for Data Source (DS) Connectivity guide for Data Recipient (DR) The main reason of selection is that it is unnecessary for DS to see DR-specific details and vice versa. This document specifies the implementation details of GDSN DS 2 -specific web services within GS1Trade Sync Data Pool v1.0 system platform. 1.2 Document Conventions This document structure is partially based on the specification standard of Rational Unified Process (RUP) methodology. Within this specification, the terms SHALL, SHALL NOT, SHOULD, SHOULD NOT, MAY, NEED NOT, CAN, and CAN NOT are to be interpreted as specified in [1]. When used in this way, these terms will always be shown in ALL CAPS; when these words appear in ordinary typeface they are intended to have their ordinary English meaning. The following typographical conventions are used throughout the document: ALL CAPS type is used for the special terms from [1] enumerated above. Monospace type is used to denote programming language, UML, and XML identifiers, as well as for the text of XML documents. This document uses several abbreviations which long forms are located in Appendix. 1.3 Target Audience The audience of this specification includes all assigned GS1Trade Sync Data Pool project members from both GS1 Denmark and, and the staff of developer companies assigned to the project on s authority. Additionally, this document is intended for developers and testers who are familiar with the GDSN standard and who has general knowledge of other GS1 standards. 1 There are WS-, AS2-, FTP/FTPS-based interfaces in GS1Trade Sync Data Pool system. 2 DS represents the supply side data in a GDSN process. It can be a company (supplier, manufacturer, distributor etc.) that enters product information into GDSN-based synchronisation systems that are sent to DRs. Version 0.42, Draft/Approved, 17. februar 2016All rights Page 4 of 16

5 2 About Web Services Web services (WSs) are client and server applications that communicate over the web HTTP(s) protocol. Web services provide a standard means of interoperating between software applications running on a variety of platforms and frameworks. WSs are characterized by their great interoperability and extensibility, as well as their machineprocessable descriptions, thanks to the use of XML. Web services can be combined in a loosely coupled way to achieve complex operations. Programs providing simple services can interact with each other to deliver sophisticated added-value services. Rules for communication between different systems need to be defined, such as: How one system can request data from another system. Which specific parameters are needed in the data request What would be the structure of the data (Normally, data is exchanged in XML files, and the structure of the XML file is validated against an XSD file.) What error messages to display when a certain rule for communication is not observed, to make troubleshooting easier Fig. 1 Simple Web Service process Version 0.42, Draft/Approved, 17. februar 2016All rights Page 5 of 16

6 3 Overview In order to communicate properly between DS and DR, WS interfaces are available. The XML-based communication based on GDSN Standard is performed through the GS1Trade Sync Data Pool system (Fig. 2). Fig. 2 Web Service-based communication between Data Source and Data Recipient There are four different WS interfaces in GS1Trade Sync Data Pool environment for appropriate communication: two WS interfaces for DS-based operations in GDSN two WS interfaces for DR-based operations in GDSN Note: This document focuses only the DS-DP, DP-DS relation. Every WS complies with the GS1 standard-specific request/response definition [2]. Note: In the WS-based mechanism each single request receives a response: one method call one transaction one GS1 response [2] 3. The GS1-specific response contains the details about the transaction. 3.1 Service Characteristics For sending product information to DR and getting confirmation (CIC), DS needs to use/implement appropriate WS interfaces. Fig. 3 Web Service-based communication between Data Source and GS1Trade Sync Data Pool 3 It corresponds to the Sect. 5.8 of Catalogue Item Sync [3]. Version 0.42, Draft/Approved, 17. februar 2016All rights Page 6 of 16

7 In order to establish DS-side WS communication, one WS implementation and one WS client implementation is necessary: A WS client implementation is needed to call the WS hosted by DP. It is for sending request from DS to DP. A WS implementation, hosted by DS to receive confirmations from DR through DP Version 0.42, Draft/Approved, 17. februar 2016All rights Page 7 of 16

8 4 Details of Services Next section describes the two WS interfaces related to DS in GS1Trade Sync implementation. Notes: The used WSDL-based service description is technology independent. Every defined operation corresponds to specification of BMS Catalogue Hierarchical Item Sync. [3] Technically, the implementation of DataSourceOperations WS is based on the WCF (Windows Communication Foundation) Service request-response mechanism. 4.1 Feature Description of Services As it mentioned, two WS interface implementation is necessary for the complete communication: a WS interface implemented & hosted by DP (DataSourceOperations service) a WS interface implemented & hosted by DS (DataSourceOperationsCallback service). Note: The two WSDL files are included in Appendix. 4.2 DataSourceOperations Service DataSourceOperations service is hosted by DP and it receives message from DS, validate the message and provides response The StandardBusinessDocumentHeader parameter There is a mandatory parameter of the operations called SBDH (Standard Business Document Header). The object should look like this: <StandardBusinessDocumentHeader xmlns=" <HeaderVersion>1.0</HeaderVersion> //Constant <Sender> <Identifier Authority="GS1"> </Identifier> //Sender GLN </Sender> <Receiver> <Identifier Authority="GS1"> </Identifier> //GS1Trade Sync s GLN </Receiver> <DocumentIdentification> <Standard>GS1</Standard> //Constant <TypeVersion>3.1</TypeVersion> //Constant <InstanceIdentifier>MSG-externalDocumentId</InstanceIdentifier> //Unique instance identifier, possibly guid <Type>catalogueItemNotification</Type> //Type of the message <MultipleType>false</MultipleType>//Constant <CreationDateAndTime> T16:56:47Z</CreationDateAndTime> </DocumentIdentification> </StandardBusinessDocumentHeader> Possible message types within the <Type></Type> node: catalogueitemnotification catalogueitemhierarchicalwithdrawal Version 0.42, Draft/Approved, 17. februar 2016All rights Page 8 of 16

9 4.2.2 Description of DataSourceOperations Service The DataSourceOperations service has the following operations: Operation 1 for receiving Catalogue Item Notification (CIN) 4 from DR. This operation corresponds to Information Model (Sect. 5.4) of Catalogue Item Sync [3]. <wsdl:operation name="receivecatalogueitemnotification"> <wsdl:input wsaw:action=" /ReceiveCatalogueItemNotification" message="tns:datasourceoperationsservice_receivecatalogueitemnotification_inputmessa ge"/> <wsdl:output wsaw:action=" /ReceiveCatalogueItemNotificationResponse" message="tns:datasourceoperationsservice_receivecatalogueitemnotification_outputmess age"/> </wsdl:operation> Operation 2 for Catalogue Item Hierarchical Withdrawal 5. This operation corresponds to Information Model (Sect. 5.3) of Catalogue Item Sync [3]. <wsdl:operation name="receivecatalogueitemhierarchicalwithdrawal"> <wsdl:input wsaw:action=" /ReceiveCatalogueItemHierarchicalWithdrawal" message="tns:datasourceoperationsservice_receivecatalogueitemhierarchicalwithdrawal_ InputMessage"/> <wsdl:output wsaw:action=" /ReceiveCatalogueItemHierarchicalWithdrawalResponse" message="tns:datasourceoperationsservice_receivecatalogueitemhierarchicalwithdrawal_ OutputMessage"/> </wsdl:operation> 4.3 DataSourceOperationsCallback Service DataSourceOperationsCallback Service is hosted by DS and it is for delivering confirmation messages from DR. Note: DS have to host the DataSourceOperationsCallback service on its own machine with the same wsdl can be found in Appendix Description of DataSourceOperationsCallback Service The DataSourceOperationsCallback service as callback service has only one operation: Operation for adding Catalogue Item Confirmation (CIC) 6 to DR. This operation corresponds to Information Model (Sect. 5.2) of Catalogue Item Sync [3]. <wsdl:operation name="receivecatalogueitemconfirmation"> <wsdl:input wsaw:action=" kservice/receivecatalogueitemconfirmation" message="tns:datasourceoperationscallbackservice_receivecatalogueitemconfirmation_in putmessage"/> <wsdl:output wsaw:action=" 4 CIN is a business message used to transmit trade item information from DS or DP to DR with the GDSN. 5 The Catalogue Item Hierarchical Withdrawal is a business message used to transmit trade item information from DS or DP to DR with the GDSN with regards to a correction that is required to an item hierarchy that has already been synchronised. 6 It refers to electronic communication from the DR to the DS indicating what action has been taken on the item. The confirmation process occurs in the recipient s data pool. Version 0.42, Draft/Approved, 17. februar 2016All rights Page 9 of 16

10 kservice/receivecatalogueitemconfirmationresponse" message="tns:datasourceoperationscallbackservice_receivecatalogueitemconfirmation_ou tputmessage"/> </wsdl:operation> Return parameter This chapter describes the expected response in case of service callback. The response can be positive or negative Positive response In case of successful conversation the GS1Response should look like this: <gs1response> <originatingmessageidentifier> <entityidentification>3242c921-3fe4-46d e375f3db5</entityidentification> //Same as the received catalogueitemconfirmation message catalogueitemconfirmationidentification.entityidentification field </originatingmessageidentifier> <receiver> </receiver> // DS own GLN <sender> </sender> // GS1Trade Sync s GLN <transactionresponse> <transactionidentifier> <entityidentification>kato:urn:uuid:86eee ab </entityidentification> //Auto-generated transaction identifier, generated by the sender <contentowner> <gln> </gln> // Sender GLN </contentowner> </transactionidentifier> <responsestatuscode>accepted</responsestatuscode> //Positive status code </transactionresponse> </gs1response> Negative response In case of failed conversation the GS1Response should look like this: <gs1response> <originatingmessageidentifier> <entityidentification>3242c921-3fe4-46d e375f3db5</entityidentification> //Same as the received catalogueitemconfirmation message catalogueitemconfirmationidentification.entityidentification field </originatingmessageidentifier> <receiver> </receiver> // DS own GLN <sender> </sender> // GS1Trade Sync s GLN <gs1exception> Version 0.42, Draft/Approved, 17. februar 2016All rights Page 10 of 16

11 <messageexception> <gs1error> <errorcode>ws100</errorcode> //Constant errorcode allocated to WS communication <errordatetime> t05:45:05+00:00</errordatetime> <errordescription>the same Document Identification InstanceIdentifier may not be repeated on multiple messages</errordescription> //Error description </gs1error> </messageexception> </gs1exception> </gs1response> Version 0.42, Draft/Approved, 17. februar 2016All rights Page 11 of 16

12 5 Security 5.1 DataSourceOperations service Transport over HTTPS DataSourceOpertations WS communicates on a secure transport channel (HTTPS). The main motivation of using the HTTPS protocol, to ensure secure transmission of the exchanged data. For more information about the HTTPS protocol see [4] Client authentication DataSourceOpertations WS performs authentication on every call. Only authenticated users can perform actions. Authentication is based on the client s certificate. Client have to have an X509 valid certificate, which s public key must be shared with GS1Trade Sync s operation staff. We recommended to use the same certificate for client authentication as used for the DataSourceOperationsCallback service s SSL certificate. Every client call must be signed with the certificate, which will be authenticated on the server. For testing purpose self-signed certificates are accepted, but on live environment it is highly recommend to use trusted third-party certificate. 5.2 DataSourceOperationsCallback service Following chapters describes the necessary set-up of the callback service hosted by DS Expected transport channel The expected transport channel is HTTPS. The service must be secured with a trusted SSL certificate Expected authentication of client calls The expected authentication of the client calls is the same as we have on GS1Trade Sync s server side (Chapter 5.1.2). Accordingly we need a service which client authentication scheme is based on certificates. GS1Trade Sync will use the same certificate for signing the client calls, as we use for HTTPS security. This certificate is a trusted third-party certificate on test and live system as well. Version 0.42, Draft/Approved, 17. februar 2016All rights Page 12 of 16

13 6 Connection Parameters DataSourceOperations service: Parameter name Service URL Value Port 5556 WSDL URL singlewsdl URL Note that the client authentication works on domain level, meaning that the wsdls can be downloaded using client certificate. Both service and callback wsdls are available in the Appendix. Version 0.42, Draft/Approved, 17. februar 2016All rights Page 13 of 16

14 7 Expected steps of testing 7.1 DS DP Testing should start with calling the GS1Trade Sync s web service. GS1Trade Sync supplies a certificate can be used temporarily for testing purposes. If a client call with the temporary test certificate succeeds, DS have to change the certificate to their own one. Of course it is necessary to share the new certificate with GS1Trade Sync s operation staff before using it. 7.2 DP DS Once the implementation on Partner side is ready, GS1Trade Sync starts testing. Client calls will be initiated using the Gs1TradeSyncUATClient.cer certificate. Version 0.42, Draft/Approved, 17. februar 2016All rights Page 14 of 16

15 8 Appendix 8.1 Attached files DataSourceOperationsService.Single.wsdl WSDL of the DataSourceOperationsService hosted by GS1Trade Sync DataSourceOperationsCallbackService.Single.wsdl WSDL of the Callback interface hosted by DS TestClientCert.pfx - Client certificate used by the Partner for temporary testing purpose Gs1TradeSyncUATClient.cer Client certificate used by GS1Trade Sync to call Partner s web service 8.2 Abbreviation Abbreviation Term AS2 Applicability Statement 2 CIC CIN DR DS GDSN SBDH XML WCF WS Catalogue Item Confirmation Catalogue Item Notification Data Recipient Data Source Global Data Synchronisation Network Standard Business Document Header extensible Markup Language Windows Communication Foundation Web Service 8.3 Glossary Catalogue Item Confirmation It refers to GDSN-specific electronic communication from the DR to the DS indicating what action has been taken on the item. The confirmation process occurs in the recipient s data pool. Catalogue Item Hierarchical Withdrawal It is a business message used to transmit trade item information from DS or DP to DR with the GDSN with regards to a correction that is required to an item hierarchy that has already been synchronised. Catalogue Item Notification It is a business message used to transmit trade item information from DS or DP to DR with the GDSN. Catalogue Item Publication It is a business message standard used to distribute trade item information within the GDSN. Data Recipient It represents the demand side data. It can be a company that receives product information from a data source. This company could be a retailer, hospital, distributor, wholesaler, foodservice operator, group purchasing organization, government, etc. Data Source It represents the supply side data. It can be a company (supplier, manufacturer, distributor etc.) that enters product information into GDSN-based synchronisation systems that are sent to DRs. Version 0.42, Draft/Approved, 17. februar 2016All rights Page 15 of 16

16 Web Services Client and server applications that communicate over the web HTTP protocol. Web services provide a standard means of interoperating between software applications running on a variety of platforms and frameworks. 8.4 References [1] ISO/IEC, "ISO/IEC Directives Part 2 - Rules for the structure and drafting of International Standards," ISO/IEC, [2] GS1 "XML Transport Instruction and Response", Implementation Guide, GS1 GO, [3] GS1 "Business Message Standard (BMS) Catalogue Item Sync, BMS Release 3.1.0", GS1 Global Office, GS1 AISBL, [4] Https protocol overview List of Figures Fig. 1 Simple Web Service process... 5 Fig. 2 Web Service-based communication between Data Source and Data Recipient... 6 Fig. 3 Web Service-based communication between Data Source and GS1Trade Sync Data Pool... 6 Version 0.42, Draft/Approved, 17. februar 2016All rights Page 16 of 16