Validoo Operations Manual

1. Log of changes

Version	Changes made	Date	Responsible
3.1_A1	First version after Validoo platform release.	2019-02	Robin Widberg
3.1_B1	Major updates and additions	2021-09	Robin Widberg and Sylvia Pellegrini

2. Introduction

2.1 Operations Manual

This document describes how to interact with Validoo platform. The document should be read by solution providers and Data Recipients when setting up communication to interact with Validoo platform. The document should be read together with the GDSN Operations Manual. This document describes the Swedish data pool’s additional functionality and the message choreography in Validoo platform.

2.2 GDSN Operations Manual

The GDSN Operations Manual describes how to interact within GDSN. Some of the principles are therefore not applicable when a user interacts with the Validoo platform, because this interaction is by definition outside GDSN.

All solution providers are required to read the GDSN Operations Manual, except for a few sections, that are not applicable. The table below specifies which chapters of the GDSN Operations Manual should be taken into consideration, or are not applicable when setting up direct communication with Validoo.

Chapter	Chapter name	Requirement	Comment
1	Introduction	Take into consideration
2	GDSN Standards	Take into consideration	Mainly 2.1 and 2.2. Manages all communication to and from GDSN for users. For communication with a Data Recipient that is not connected to Validoo, please contact GS1 Sweden for more information.
3	Joining GDSN	Not applicable
4	Use of xml in GS1 and GDSN	Take into consideration
5	Message Transport	Take into consideration	Manages, all communication to and from GDSN.
6	GDSN Specifics	Take into consideration
7	Document retention	Not applicable
8	Disaster recovery	Not applicable
9	GPC implementation and integration in GDSN	Not applicable
10	References	Not applicable

3. Messages and definitions

This section gives a short description of each message sent between the Data Source, Validoo platform (GDSN), and the Data Recipient.

3.1 Standard Business Document Header (SBDH)

SBDH is not a message or message type, but a part included in all message types below. SBDH is used as an enveloping mechanism for all XML-based exchanges. For more information, see the GDSN Operations Manual.

3.2 Catalogue Item Notification (CIN)

A CIN is a carrier message that carries information about one trade item hierarchy.

3.3 GS1 Response

The GS1 Response message informs about a validation and is described in detail in the current Business Document Specification (BDS).

3.4 Catalogue Item Confirmation (CIC)

The CIC message contains feedback from the previously sent CIN message regarding the status according to the local validation rules or retailer specific rules. Fig 1 shows the CIC message structure.

The message can be sent from the Data Recipient back to the Data Source as verification that the Data Recipient has received the CIN message, and as feedback on the content.

The CIC message is not mandatory but is recommended for the Data Recipient to send. It is possible to send multiple CIC messages for one CIN message, even a long time after the CIN message was received.

The feedback (CIC information) can be positive (status “Received” or “Synchronised”) or negative (status “Review” or “Rejected”):

• Received – The CIN message follows the Data Recipient’s specific rules, but no business decision has been made on the data.
• Review – The Data Recipient has opinions on the GTIN and requests that the Information Provider changes or corrects the trade item information.
• Rejected – The Data Recipient is not interested in this GTIN and does not want to receive any more CIN messages for it.
• Synchronised – the GTIN is approved by the Data Recipient and is integrated into the Data Recipient’s internal systems.

3.5 Catalogue Item Subscription (CIS)

A CIS message is sent by the Data Recipient to place a subscription for trade item information.

3.6 Catalogue Item Hierarchical Withdrawal (CIHW)

A CIHW message is sent from a Data Source through a data pool (GDSN) to a Data Recipient to make a withdrawal of an item hierarchy that has already been synchronised.

3.7 Information Provider and Supplier

The Information Providers in the form of Suppliers, register and maintain information of trade items in their Source Data Pool to be shared through GDSN. When sharing to a Data Recipient the Source Data Pool registers the trade items in the Global Registry (GR) and sends the information to the Recipient Data Pool.

3.8 Data Source

Typically a Manufacturer/Distributor. The Data Source maintains trade item information that it wants entered into the GDSN and registers trade item information in a Source Data Pool to be registered with the Global Registry and sent to the Recipient Data Pool

3.9 Data Recipient and Buyer

The Data Recipients in the form of Buyers, subscribe to trade item information to receive new and updated information. Subscriptions can be placed by any of the following combinations of criteria:

• Trade Item (GTIN)
• Information Provider (GLN)
• Target Market
• GPC Brick

The Data Recipient receives the trade item information they are authorized to view, use and download. Authorization is performed by the Information Provider by sharing trade items.

To be a Data Recipient in Validoo platform, the recipient must be a Buyer. The Data Recipient can also belong to another Recipient data pool in which case they will pass the subscriptions to Validoo platform, and the trade item information will be sent through them.

3.10 Solution Provider

A Solution Provider is a service provider with a verified connection to Validoo platform. The Solution Provider can offer a system that is capable of sending trade item information to Data Recipients in GDSN. The solution provider offers a system that meets the criteria for the GDSN choreography and is capable of sending trade item information to data recipients in GDSN.

4. Description of publication and subscription process

The Global Registry, Data Recipient, Validoo platform and the Data Source communicate by sending and receiving messages when publishing and subscribing to trade item information. The process is summarized in Fig. 2 and described in more detail below. The messages and their definitions are described in section 5.

4.1 Process start

The process starts when the Data Source decides to publish trade item information to the Data Recipient(s).

4.2 Process implementation

1. The Data Source creates or corrects the trade item information and chooses Data Recipient(s). The trade item information is transported in GDSN through the CIN message.
2. The Data Source sends the CIN message to Validoo platform.
3. Validoo platform validates the CIN according to the GDSN Validation Rules, local Swedish rules and recipient specific rules. Validoo platform sends a validation report back to the Data Source. The validation report shows if the validation of the CIN according to the GDSN Validation Rules is approved (OK) or not approved (NOK).
   • Validoo platform validates a CIN with a set of three different rules.
     • GDSN rules
       A set of rules that the GDSN network has decided to implement. All data pools run the GDSN rules that apply to their target market and scope.
     • Local Swedish rules
       A set of rules that GS1 Sweden and the local community in Sweden have decided to implement.
     • Recipient specific rules
       Different recipients allow different measurements for a trade item and the rules will prevent a recipient from receiving something too big or too heavy.
   • Validation NOK on GDSN rules.
     Validoo platform sends the validation report GS1 Response message with responseStatusCode value “REJECTED” to the data source. The Data Source then needs to correct the CIN and repeat the process from step 1.
   • Validation NOK on Swedish rules or recipient specific rules.
     Validoo platform specifies the errors in a validation report within a CIC message and sends it with the status “REVIEW” to the Data Source. The Data Source then needs to correct the CIN and repeat the process from step 1. See section 3.4 Catalogue Item Confirmation (CIC) for more information about the message.
   • Validation OK on GDSN rules and Swedish rules.
     Validoo platform sends the validation report GS1 Response with responseStatusCode value “ACCEPTED” to the Data Source. Validoo platform sends an RCI (Registry Catalogue Item) message to the Global Registry. When the RCI message is received by the Global Registry and the containing items are registered they reply with a CIRR (Catalogue Item Registration Response) message.
4. Validoo platform stores the CIN and starts the publication process.
   Validoo platform sends a CIN to each Data Recipient who has a subscription that matches the criteria for the trade item and has access to the trade item (is Data Recipient on the trade item).
5. The Data Recipient reviews the CIN and sends feedback in a CIC message to the Data Source through Validoo platform. The CIC shows if the feedback is negative (status “REVIEW” or “REJECTED”) or positive (status “ACCEPTED” or “SYNCHORNISED”). Note that this CIC is not mandatory and only possible for Data Recipients with AS2 connectivity.
   • Negative confirmation, (CIC)
     The Data Recipient sends a CIC with the status “REVIEW” or “REJECTED” to Validoo platform. Validoo platform validates the format of the CIC message and sends a validation report to the Data Recipient. The validation report shows if the validation of the format of the CIC message is not approved (NOK) or approved (OK).
     • Validation NOK
       Validoo platform sends the validation report GS1 Response with responseStatusCode valure “REJECTED” to the Data Recipient. The Data Recipient needs to correct the CIC message format and repeat the process.
     • Validation OK
       Validoo platform sends the validation report GS1 Response with responseStatusCode value “ACCEPTED” to the Data Recipient. Validoo platform forwards the CIC to the Data Source. The data source might need to correct the CIN and repeat the process from step 1. If the responseStatusCode value was “REJECTED” and the format validation was OK, Validoo platform will block future attempts to send CIN messages from the Data Source for that trade item hierarchy to that Data Recipient. A Data Recipient can release the block by sending a new CIC message with the status “REVIEW”, “ACCEPTED” or “SYNCHRONISED”.
   • Positive confirmation, CIC
     The Data Recipient sends a CIC with the status “ACCEPTED” or “SYNCHRONISED” to Validoo platform. Validoo platform validates the format of the CIC message and sends a validation report to the Data Recipient. The validation report shows if the validation of the format of the CIC message is not approved (NOK) or approved (OK).
     • Validation NOK
       Validoo platform sends the validation report GS1 Response with responseStatusCode value “REJECTED” to the Data Recipient. The Data Recipient needs to correct the CIC message format and repeat the process.
     • Validation OK
       Validoo platform sends the validation report GS1Response with responseStatusCode value “ACCEPTED” to the Data Recipient. Validoo platform forwards the CIC to the Data Source.

5. Specific information for sending and receiving systems

5.1 SBDH

The system used by the Solution Provider must have a GLN as identification and this GLN must be sent in the SBDH for all message types as Sender (XML attribute at SBDH level). Each Information Provider registered in Validoo with a GLN, has a Solution Provider or system selected/registered with another GLN. The combination of these GLNs, the GLN of the Information Provider, and the GLN for the used system for sending trade item information, must be correct to get trade items sent to Data Recipients. See GDSN Operations Manual for more information regarding how. If this combination of GLNs is incorrect Validoo will reject the CIN sent with validation rule 730245.

Each sent message must have a unique instance identifier value. This value is used when response messages are sent back.

If a Solution Provider sends a CIN message with a SBDH to Validoo platform and Validoo platform forwards the information to the Data Recipient then Validoo platform adds its own SBDH in the message with correct information (GLN for Validoo platform as sender and its own instance identifier).

GLN for Validoo platform test (PreProd) environment: 7300020000022

GLN for Validoo platform production (Prod) environment: 7300020000008

5.2 CIN

Validoo platform validates the CIN according to the GDSN Validation rules and the local Swedish validation rules. The rules are specified in documents that can be found on GS1 Swedens website. Validoo also validates the CIN for some recipient specific rules described as Recipient rules. These can also be found in the document with the local Swedish validation rules.

The validation result is sent back by Validoo platform. The validation report also specifies which errors, if any, that have been found in the CIN.

Read the GDSN Operations manual for more information regarding the content needed in the CIN.

5.2.1 Validation of recipient specific rules

Different recipients allow different measurements for a trade item and the rules will prevent a Recipient from receiving something too big or too heavy. The following measurements are validated in the set of recipient specific rules where the limit values can vary between Recipients:

• Pallet height
• Weight on 1/1 pallet
• Weight on 1/2 pallet
• Weight on 1/3 pallet
• Weight on 1 /4 pallet
• Weight on non-consumer units
• Weight on consumer units

All Recipients do not have this functionality added so each supplier needs to talk to their Recipients about what specific measurements they allow. The Data Recipient can manage their limit values and exceptions to the limit values in Validoo Platform.

5.3 GS1 Response

For each correctly addressed message sent to Validoo platform a GS1 Response will be sent back that will contain different information depending on the result of the validations performed on the input message. The instance identifier value in the sent message will be included in the GS1 Response message to connect them. See the GDSN Operations manual for more information.

The status of the message is provided in the field responseStatusCodes with the following code values:

• REJECTED is used to indicate back to the sender of the original (requesting) message, various errors that might occur while processing the message at the recipient side.
• ACCEPTED is used to indicate that the message was accepted by Validoo platform.

5.4 CIC

The GTIN is used in the CIC to connect the message with the CIN sent from the Data Source.

CIC message scenarios:

• For every sent CIN, one Data Recipient can send several CIC messages, each with a different or the same status.
• The CIC can be positive from one Data Recipient but negative from another.
• The Data Recipient can choose to send only positive or only negative CIC messages.
• The Data Recipient can choose to not send CIC messages since this is not mandatory.

• CIC messages can be sent at any time, even a long time after the CIN was sent.
• Auto publishing job that is run daily in Validoo platform to identify changes that have occurred on items that affect all Data Recipients of the trade item information or changes that affect other trade item hierarchies. This results in that CIC messages can be returned for trade item hierarchies and Data Recipients even though a CIN has not been addressed to that specific Data Recipient or trade item hierarchy at that time.

5.5 CIHW

The Catalogue Item Hierarchical Withdrawal (CIHW) message is used to withdraw a published hierarchy to correct an issue with the links between GTINs in a hierarchy. The CIHW message can also be used by the Data Source to inform their respective Data Recipient that a given trade item information is being withdrawn from being shared with them.

1. The only valid document command for the CIHW message is DELETE.
2. The CIHW message can only be sent on the highest level of the published hierarchy, also defined as the top GTIN.
3. To correct a hierarchy for incorrect links, the hierarchy must be deleted using the CIHW message with the reason code value HIERARCHY_LINK_CORRECTION and then resent with the correct links.
4. To stop sharing a hierarchy with a Data Recipient, a CIHW message with the hierarchy deletion reason code value PUBLICATION_ WITHDRAWAL shall be sent to Validoo platform.
   • The Data Recipient GLN is addressed as Data Recipient in the CIHW message.

When the Data Recipient receives a CIHW message with the hierarchy deletion reason code value PUBLICATION_WITHDRAWAL, the hierarchy with its top GTIN is withdrawn for the Data Recipient, resulting in the Data Recipient having no access rights to these GTINs anymore. Without access rights, the Data Recipient is not a Buyer anymore of these GTINs and has no access to them via Validoo platform. Note that access can still be granted through public channels when GTINs are public.

If the top GTIN is withdrawn, the child GTINs, if they are not part of any other published hierarchy, are also withdrawn.

If there is both a current and a future version of the GTIN, the withdrawal of the Data Recipient applies for both the current and the future version. That is if the Data Recipient exists in both versions.

Example 1

The Data Recipient has the following hierarchies, A and D, with a common GTIN C.

A CIHW message with the hierarchy deletion reason code value PUBLICATION_ WITHDRAWAL on top GTIN “A” is received by the Data Recipient. For the Data Recipient, GTIN A and GTIN B are withdrawn. GTIN C is still published because the Data Recipient still receives the hierarchy with top GTIN “D” where GTIN “C” is a child GTIN.

When CIHW message with the hierarchy deletion reason code value PUBLICATION_ WITHDRAWAL is done for all Data Recipients, the GTINs become withdrawn in Validoo platform, if the GTINs are not part of another published hierarchy as in the example above.

If the Data Recipient receives a CIHW message with the hierarchy deletion reason code value HIERARCHY_LINK_CORRECTION, it means that something has been changed in the hierarchy regarding the links between the GTINs. After this message, a CIN message is required containing the correct links between the GTINs.

Example2

A special case that can cause one of the GTINs not to be part of any hierarchy.

The following hierarchy exists with top GTIN A.

A CIHW message with the hierarchy deletion reason code value HIERARCHY_LINK_CORRECTION with top GTIN A.

Then a new CIN message is received with the following structure:

A new GTIN D is added instead of the GTIN C. This means that GTIN C is not published anymore if it is not part of any other published hierarchy.

Example 3

A GTIN belongs to several published hierarchies. GTIN C belongs to hierarchy A and D.

First a CIHW message with the hierarchy deletion reason code value HIERARCHY_LINK_CORRECTION with top GTIN A is received by the Data Recipient.

Then a new CIN message with document command ADD is received with the following structure:

This means that the following hierarchies exist with top GTIN B and top GTIN D.

If there is both a current and a future version of the GTINs, the hierarchal link withdrawal applies for both versions.

5.6 Current and future version

In the GDSN standard, the attribute effectiveDateTime tells from which date the trade item information starts to apply. If the effectiveDateTime is < today date and is the latest effectiveDateTime for the item, it’s the current version of the trade item information. If effectiveDateTime > today date, it’s a future version that will apply when the effectiveDateTime is reached and then becomes the current version. Validoo platform only handles one future version, which means that if the Information Provider creates a future version of the trade item information (effectiveDateTime > today date) and then creates another future version of the trade item information the first future version is replaced by the new future version, no matter what effectiveDateTime the first or second future version has.

5.7 Global, local or trading partner information

GDSN has three levels of information in the CIN, so-called global attributes, local attributes, and trading partner-dependent attributes. When there are changes in any of the global or local attributes, the changes affect all Data Recipients of the item for the specific target market. Trading partner-dependent attributes changes only affect the addressed Data Recipients. For more information about global and local attributes, see the current version of the Trade Item Information Guideline.

5.8 Affected Data Recipients

A CIN is addressed to a Data Recipient (Buyer). The Information Provider sends a CIN for the trade item hierarchy (see definition of trade item hierarchy) for every Data Recipient (Buyer).

Affected Data Recipients are the Data Recipients that have been addressed any time earlier by the Information Provider for a specific trade item hierarchy, but not with the new changes. The Data Recipient has previously received the CIN with the trade item hierarchy. When a global or local attribute changes and the Data Recipient is not addressed with these changes by the Information Provider, Validoo platform considers these Data Recipients as affected Data Recipients.

For example, this trade item hierarchy with items A-B-C and following Data Recipient (DR1, DR2, DR3) has been addressed by the Information Provider.

The Information Provider addresses the CIN A-B-C with global/local attribute changes to Data Recipient 1 and Data Recipient 2. Data Recipient 1 and 2 gets the CIN immediately after validation OK. In the “auto publishing” job the CIN with items A-B-C validates the recipient-specific rules for Data Recipient 3, and if NOK on any of the rules, a CIC Review message, specified with GTIN “A”, is sent back to the Solution Provider containing the errors. If validated OK the CIN is sent to the Data Recipient and a CIC Received message, specified with GTIN “A”, is sent back to the Solution Provider.

5.9 Affected hierarchies

A CIN with its item structure builds a trade item hierarchy, from the top item down to the base item(s). An item can be part of several trade item hierarchies, but each CIN only contains one trade item hierarchy, which means that an attribute change on an item in a CIN that is received by Validoo platform and is part of any other trade item hierarchy, affects that trade item hierarchy. Validoo platform handles these trade item hierarchies as affected trade item hierarchies.

Example

Trade item hierarchy with items A-B-C and following Data Recipients: DR1, DR2, DR3 and trade item hierarchy D-F-C with Data Recipient DR3, DR4, these trade item hierarchies have been addressed by the Information Provider earlier to these Data Recipients.

The Information Provider addresses the CIN A-B-C with global/local attribute changes on item C to Data Recipient 1 and Data Recipient 2. Data Recipient 1 and 2 gets the CIN with the items A-B-C immediately after validation OK.

In the “auto publishing” job, the CIN with items A-B-C validates the recipient specific rules for Data Recipient 3. If NOK on any of the recipient specific rules, a CIC Review message, specified with GTIN “A” as catalogueItemReference, is sent back to the Solution Provider. If validated OK, the CIN is sent to Data Recipient 3 and a CIC Review message specified for GTIN A as catalogueItemReference is sent back to Solution Provider.

Then the job validates the CINs for D-F-C, the GDSN rules, Swedish rules and recipient specific rules for Data Recipient 3 and Data Recipient 4. If NOK on any of the Swedish rules or recipient specific rules, a CIC Review message, specified with GTIN “D” as catalogueItemReference, is sent back to the Solution Provider containing the errors. If validated OK the CIN is sent to the Data Recipient and a CIC Received message, specified with GTIN “D” as catalogueItemReference, is sent back to the Solution Provider.

5. 10 Access list

The Buyers that have access to a trade item, are the Buyers that have been addressed by the Information Provider in the trade item information. These Data Recipients are the

Buyers that are on the item’s access list.

5.11 Lifecycle of trade item

Figure 3 shows the trade item life cycle statuses.

5.11.1 Draft

The draft status is an internal status of Validoo platform and is not applicable to the GDSN flow.

5.11.2 Published

When an Information Provider publishes trade item information. The CIN is sent to Validoo platform and validated OK on GDSN and local rules.

5.11.3 Discontinued

In the trade item information, there is the attribute discontinueDateTime, when this date is reached, the item becomes discontinued in Validoo platform.

5.11.4 Withdrawn

When the Information Provider wants to withdraw a publishing of a trade item hierarchy to one Data Recipient, a CIHW message with the hierarchy deletion reason code value PUBLICATION_ WITHDRAWAL is done for the specific Data Recipient. It is important that the Solution Provider removes the specific data recipient from their access list. If the Information Provider wants to withdraw the item to all Data Recipients, a CIHW message with the hierarchy deletion reason code value PUBLICATION_ WITHDRAWAL is done for all Data Recipients, and the items become withdrawn in Validoo platform, if the items are not part of another published trade item hierarchy.

5.12 Auto publishing job

Validoo platform has an “auto publishing” job that runs daily. This job checks for changes made to items, that affect the Data Recipients and the trade item hierarchies that have not been addressed by the Information Provider, and therefore not been sent out to the Data Recipients, but they are affected by these changes.

In this job, Validoo platform checks all items that have changes that affect other Data Recipients or other trade item hierarchies, but these changes have not been addressed, by the Information Provider. The job validates the CINs for the Data Recipients. If validated NOK on any of the Swedish rules or recipient specific rules, a CIC Review message, specified with top item GTIN as catalogueItemReference, is sent back to the Solution Provider containing the validation errors.

Note, if there is any GDSN rule error, then no GS1 Response message will be sent back. This is because GS1 Response responds with the originatingMessageIdentifier and no CIN has been sent to Validoo platform with actual changes. Therefore, no GS1 Response can be responded back to the Solution Provider.

5.13 Date related processes

In Validoo platform some processes are date related, the following exists:

Items with a reached discontinueDateTime become Discontinued.

Validoo platform has the following logic regarding future versions of trade item information and access lists. When a future version of trade item information becomes a current version, then all Data Recipients that had access to the previous version also get access (the Data Recipient is added to the access list) to the new current version.

This means that if an item has three Data Recipients on the current version of the trade item information, and the Information Provider creates a future version of the trade item information that is only addressed to one of the Data Recipients (DR1), then only DR1 in the example above has access to the future version of the trade item information. When the future version becomes the current version (effectiveDateTime is reached), the Data Recipients of the previous current version of the trade item information will be added to the access lists for the new current version of the trade item information.

6. Further information

More information and documentation, for example, code lists, example files and xml schemas can be found on GS1 Swedens website.

6.1 Code lists

Code lists can be downloaded in an XML structure through the website. It is recommended to automatically download the code lists once a day since this will allow the system to always have updated codes and definitions.