gs1trade sync data pool - web services for data source · gs1trade sync data pool - web services...

GS1Trade Sync Data Pool -

Web Services for Data Source

Connectivity Guide

Version 1.0, Approved, 2016.12.13.

GS1 Hungary GS1Trade Sync Data Pool - Web Services for Data Source

Version 0.42, Draft/Approved, 17-02-2016 All rights reserved @ GS1 Hungary of 17

Document Summary

Document Item Current Value

Document Name GS1Trade Sync Data Pool - Web Services for Data Source (Connectivity

Guide)

Document Date 2016.12.13.

Document Version 1.0

Document Status Approved

Document Description This document describes the Data Source-specific implementation of web services used for GS1Trade Sync Data Pool system.

Contributors

Name Organisation

Tibor Gottdank GITM Ltd.

Zsolt Jacsó Trade Connectors A/S

Log of Changes

Release Date of Change Changed By Summary of Change

0.1 08/02/2016 Tibor Gottdank Skeleton of document

0.2 11/02/2016 Tibor Gottdank First draft

0.3 15/02/2016 Tibor Gottdank Corrected first draft

0.4 16/02/2016 Tibor Gottdank Corrections in Chapter 4

0.42 17/02/2016 Tibor Gottdank Minor changes

0.8 23/02/2016 Zsolt Jacsó Major changes

0.9 03/03/2016 Zsolt Jacsó New chapter: Expected steps of testing

0.91 20/09/2016 Tibor Gottdank and Zsolt Jacsó

New chapter: Expected steps of testing

0.92 23/09/2016 Tibor Gottdank Minor changes

1.0 13/12/2016 Zsolt Jacsó Live configuration details, certificate usage updates

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 GS1Trade Sync Data Pool - Web Services for Data Source (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.

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 ................................................................................................. 5

1.1 Purpose of Document ...................................................................................................... 5

1.2 Document Conventions .................................................................................................... 5

1.3 Target Audience .............................................................................................................. 5

2 About Web Services ...................................................................................... 6

3 Overview ...................................................................................................... 7

3.1 Service Characteristics ..................................................................................................... 7

4 Details of Services ........................................................................................ 9

4.1 Feature Description of Services ......................................................................................... 9

4.2 DataSourceOperations Service .......................................................................................... 9

4.2.1 The StandardBusinessDocumentHeader parameter ..................................................... 9

4.2.2 Description of DataSourceOperations Service ........................................................... 10

4.3 DataSourceOperationsCallback Service ............................................................................ 10

4.3.1 Description of DataSourceOperationsCallback Service ................................................ 10

4.3.2 Return parameter ................................................................................................. 11

5 Security ...................................................................................................... 13

5.1 DataSourceOperations service ........................................................................................ 13

5.1.1 Transport over HTTPS ........................................................................................... 13

5.1.2 Client authentication ............................................................................................. 13

5.2 DataSourceOperationsCallback service ............................................................................. 13

5.2.1 Expected transport channel .................................................................................... 13

5.2.2 Expected authentication of client calls ..................................................................... 13

6 Connection Parameters ............................................................................... 14

6.1 UAT ............................................................................................................................. 14

6.2 Live ............................................................................................................................. 14

7 Expected steps of testing ............................................................................ 15

7.1 DS – DP ....................................................................................................................... 15

7.2 DP – DS ....................................................................................................................... 15

8 Appendix .................................................................................................... 16

8.1 Attached files................................................................................................................ 16

8.2 Abbreviation ................................................................................................................. 16

8.3 Glossary ...................................................................................................................... 16



8.4 References ................................................................................................................... 17

8.5 List of Figures ............................................................................................................... 17



1 Introduction

1.1 Purpose of Document

The GDSN Standard-specific web service is one of the three machine-to-machine interface technology1 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 DS2-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 GS1 Hungary, and the staff of developer companies assigned to the project on GS1 Hungary’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.



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 machine-processable 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



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].



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



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.

4.2.1 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="http://www.unece.org/cefact/namespaces/StandardBusinessDocumentHeader">

<HeaderVersion>1.0</HeaderVersion> //Constant

<Sender>

<Identifier Authority="GS1">5790001090159</Identifier> //Sender GLN

</Sender>

<Receiver>

<Identifier Authority="GS1">5790000000029</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>2015-12-04T16:56:47Z</CreationDateAndTime>

</DocumentIdentification>

</StandardBusinessDocumentHeader>

Possible message types within the <Type></Type> node:

catalogueItemNotification

catalogueItemHierarchicalWithdrawal



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="http://services.gs1tradesync.com/2016/05/06/DataSourceOperationsService

/ReceiveCatalogueItemNotification"

message="tns:DataSourceOperationsService_ReceiveCatalogueItemNotification_InputMessa

ge"/>

<wsdl:output


/ReceiveCatalogueItemNotificationResponse"

message="tns:DataSourceOperationsService_ReceiveCatalogueItemNotification_OutputMess

age"/>

</wsdl:operation>

Operation 2 for Catalogue Item Hierarchical Withdrawal5. This operation corresponds to Information Model (Sect. 5.3) of Catalogue Item Sync [3].

<wsdl:operation name="ReceiveCatalogueItemHierarchicalWithdrawal">

<wsdl:input


/ReceiveCatalogueItemHierarchicalWithdrawal"

message="tns:DataSourceOperationsService_ReceiveCatalogueItemHierarchicalWithdrawal_

InputMessage"/>

<wsdl:output


/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.

4.3.1 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="http://services.gs1tradesync.com/2016/05/06/DataSourceOperationsCallbac

kService/ReceiveCatalogueItemConfirmation"

message="tns:DataSourceOperationsCallbackService_ReceiveCatalogueItemConfirmation_In

putMessage"/>

<wsdl:output

wsaw:Action="http://services.gs1tradesync.com/2016/05/06/DataSourceOperationsCallbac

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.



kService/ReceiveCatalogueItemConfirmationResponse"

message="tns:DataSourceOperationsCallbackService_ReceiveCatalogueItemConfirmation_Ou

tputMessage"/>

</wsdl:operation>

4.3.2 Return parameter

This chapter describes the expected response in case of service callback. The response can be positive or negative.

4.3.2.1 Positive response

In case of successful conversation the GS1Response should look like this:

<gS1Response>

<originatingMessageIdentifier>

<entityIdentification>3242c921-3fe4-46d8-8626-620e375f3db5</entityIdentification> //Same as the received catalogueItemConfirmation message catalogueItemConfirmationIdentification.entityIdentification field

</originatingMessageIdentifier>

<receiver>5790001090159</receiver> // DS own GLN

<sender>5790000000029</sender> // GS1Trade Sync’s GLN

<transactionResponse>

<transactionIdentifier>

<entityIdentification>kato:urn:uuid:86eee880-6773-4988-9284-

ab7336154461</entityIdentification> //Auto-generated transaction identifier, generated by the sender

<contentOwner>

<gln>5790001090159</gln> // Sender GLN

</contentOwner>

</transactionIdentifier>

<responseStatusCode>ACCEPTED</responseStatusCode> //Positive status code

</transactionResponse>

</gS1Response>

4.3.2.2 Negative response

In case of failed conversation the GS1Response should look like this:

<gS1Response>

<originatingMessageIdentifier>

<entityIdentification>3242c921-3fe4-46d8-8626-620e375f3db5</entityIdentification> //Same as the received catalogueItemConfirmation message

catalogueItemConfirmationIdentification.entityIdentification field

</originatingMessageIdentifier>

<receiver>5790001090159</receiver> // DS own GLN

<sender>5790000000029</sender> // GS1Trade Sync’s GLN

<gS1Exception>



<messageException>

<gS1Error>

<errorCode>WS100</errorCode> //Constant errorCode allocated to WS communication

<errorDateTime>2016-01-19T05: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>



5 Security

5.1 DataSourceOperations service

5.1.1 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]

5.1.2 Client authentication

DataSourceOpertations WS performs authentication on every call.

Only authenticated users can perform actions.

Authentication is based on the client’s certificate.

Every client call must be signed with the certificate, which will be authenticated on the server.

5.1.2.1 UAT certificate

GS1Trade Sync’s team issue a client certificate for the partner.

For downloading the wsdl files the TestClientCert.pfx can be used.

5.1.2.2 Live certificate

Client must have an X509 valid certificate, which’s public key must be shared with GS1Trade Sync’s

operation staff.

We require to use a dedicated client certificate.

For information, how the client / server certificate differs, visit [5].

5.2 DataSourceOperationsCallback service

Following chapters describes the necessary set-up of the callback service hosted by DS.

5.2.1 Expected transport channel

The expected transport channel is HTTPS. The service must be secured with a trusted SSL certificate.

5.2.2 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 Gs1TradeSyncUATClient.cer certificate on UAT environment, and the

Gs1TradeSyncDenmark.cer certificate on live environment.



6 Connection Parameters

6.1 UAT

DataSourceOperations service:

Parameter name Value

Service URL https://gs1tradesync-uat.pro-sharp.hu/DataSourceOperationsService.svc

Port 5556

WSDL URL https://gs1tradesync-uat.pro-sharp.hu:5556/DataSourceOperationsService.svc?wsdl

singleWSDL URL https://gs1tradesync-uat.pro-sharp.hu:5556/DataSourceOperationsService.svc?singleWsdl

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.

6.2 Live

DataSourceOperations service:

Parameter name Value

Service URL https://gdsnoperationservice.gs1tradesync.dk/DatasourceOperationsService.svc

WSDL URL https://gdsnoperationservice.gs1tradesync.dk/DatasourceOperationsService.svc?wsdl

singleWSDL URL https://gdsnoperationservice.gs1tradesync.dk/DatasourceOperationsService.svc?singleWsdl

https://gs1tradesync-uat.pro-sharp.hu/DataSourceOperationsService.svc

https://gs1tradesync-uat.pro-sharp.hu:5556/DataSourceOperationsService.svc?wsdl

https://gs1tradesync-uat.pro-sharp.hu:5556/DataSourceOperationsService.svc?wsdl

https://gs1tradesync-uat.pro-sharp.hu:5556/DataSourceOperationsService.svc?singleWsdl

https://gs1tradesync-uat.pro-sharp.hu:5556/DataSourceOperationsService.svc?singleWsdl

https://gdsnoperationservice.gs1tradesync.dk/DatasourceOperationsService.svc?wsdl

https://gdsnoperationservice.gs1tradesync.dk/DatasourceOperationsService.svc?wsdl

https://gdsnoperationservice.gs1tradesync.dk/DatasourceOperationsService.svc?singleWsdl

https://gdsnoperationservice.gs1tradesync.dk/DatasourceOperationsService.svc?singleWsdl



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 in case of live environment.

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 on UAT environment, and using the Gs1TradeSyncDenmark.cer certificate on live environment.



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 on UAT environment

Gs1TradeSyncDenmark.cer

Client certificate used by GS1Trade Sync to call Partner’s web service on Live environment

8.2 Abbreviation

Abbreviation Term

AS2 Applicability Statement 2

CIC Catalogue Item Confirmation

CIN Catalogue Item Notification

DR Data Recipient

DS Data Source

GDSN Global Data Synchronisation Network

SBDH Standard Business Document Header

XML eXtensible Markup Language

WCF Windows Communication Foundation

WS 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.

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, 2011.

[2] GS1 "XML Transport Instruction and Response", Implementation Guide, GS1 GO, 2012.

[3] GS1 "Business Message Standard (BMS) Catalogue Item Sync, BMS Release 3.1.0", GS1 Global Office, GS1 AISBL, 2015.

[4] Https protocol overview https://en.wikipedia.org/wiki/HTTPS

[5] Client vs server certificate https://blogs.msdn.microsoft.com/kaushal/2012/02/17/client-certificates-vs-server-certificates/

8.5 List of Figures

Fig. 1 Simple Web Service process .......................................................................................... 6 Fig. 2 Web Service-based communication between Data Source and Data Recipient ...................... 7 Fig. 3 Web Service-based communication between Data Source and GS1Trade Sync Data Pool ....... 7

https://en.wikipedia.org/wiki/HTTPS

https://blogs.msdn.microsoft.com/kaushal/2012/02/17/client-certificates-vs-server-certificates/

https://blogs.msdn.microsoft.com/kaushal/2012/02/17/client-certificates-vs-server-certificates/

gs1trade sync data pool - web services for data source · gs1trade sync data pool - web services...

Documents