GS1 connector

Attribute value mapping

We can also target specific values per attribute. The matching value listed will translate into a compatible GS1 value.

Supported attributes

Import / Export

Import and exporting the mapping file can be done from inside akeneo import and export jobs. Simple create a new Import/Export profile with the job called “Attribute values mapping import/export”

Here is an example of how a mapping file could look like.

Validation

Beware all the akeneo attribute codes and GS1 attribute need to exist. Else the validator will provide you with validion feedback inside the step.

GS1 Connector

GS1 Account

Your GS1 account currently is required and hard-linked to your GS1-connector. We only support 1 GS1 account per connector.

That account consists of the following parameters.

You can set or update these parameters on the server of needed.

# app/config/parameters.yml

parameters:

    gsone_sftp_host: ~

    gsone_sftp_port: ~

    gsone_sftp_user: ~

    gsone_sftp_password: ~

    primary_gsone_gln_account: ~

    primary_gsone_gln_datapool: ~

    primary_gsone_account_name: ~

GS1 Specifications

GTIN

The GTIN identifier is the standard GS1 equivalent for EAN but with a leading 0.

Find more information about the GTIN number here… https://www.gs1belu.org/nl/standaarden/gtin

properties that are part of the GTIN:

• GTIN generally similar to the EAN_CODE

• GTIN required 14 digit code in stead of the standard 13 for EAN_CODE.

• GTIN is leading so use the GTIN identifier within the XML scope.

• GTIN’s are used to identity your product across all target market.

Akeneo attributes

GS1 Publication client/target market

This attribute code is required in order to generate a CIN message to the selected target market(s) / country_code.

• attribute_code: gs1_client_publication

• properties: localizable, multi-select

GS1 Message state

This attribute is a global select type attribute with 3 options GS1_APPROVED, GS1_REQUESTED_FOR_APPROVAL and GS1_DECLINED. The connector will interact with the datapool and update the product state reflecting the current status.

Provisional publication code

This attribute code is required and communicates your provisional publication state to GS1. You must set the value “Preliminary” or “Final” in order to allow for export.

GsOneIdentifier

The GsOneIdentifier is a generated identifier that contains origin breadcrumbs.

Here is an example of such an identifier:

CIN|CIP_<gs1_client_publication>_<gln_sender>_<step_id>_<job_id>_<EAN/GTIN>

CIN_8714039900003_056_5413436000004_10_20_08715743012693

CIP_8714039900003_056_5413436000004_10_20_08715743012693

Template

GS1 require the rendering of XML Documents that it can read. In order to facilitate this correctly, we created a GS1 Template manager where you can link a family, upload an Twig document that describes how that XML is build, link your GS1 account.

Link your XML

We use a Symfony Twig engine to generate these kinds of Documents as it provides the most flexibility combined with good performance. You can use provide the template XML in 2 different options.

Option A: By extension

We include a versioned twig document inside the connector containing all the information for building the correct XML document. This document can be extended by another but smaller document that we provide. That document contains all the information or context the versioned twig document needs in order to build the XML correctly.

Notice the include 'cin_message_1_0.xml.twig'

{#

    gdsnTradeItemClassification list defines all Product Data related items

#}

{% set gdsnTradeItemClassification = ['3_009', '3_032', '4_014', '4_015', '4_020', '4_021', '4_027', '4_030', '4_362', '4_364', '4_365', '4_367', '4_371', '4_372', '4_374', '4_384', '4_385', '4_391', '4_421', '4_661', '5_004', '5_006', '5_067', '7_192', '8_247', '8_248', '8_307', '8_319', '8_321', '8_322', '8_323'] %}

{#

    code_to_label_attr list defines all attribute codes that needs the option label 

    not the code value, the label locales are the ones defined in the publish to 

    market attribute

#}

{% set code_to_label_attr = ['3_003','4_014'] %}

{#

    safetyDataSheetModule : list of Safety DataSheet FILE attributes

#}

{% set gsdn_safety_data_sheet_information = [] %}

{#

    referencedFileDetailInformationModule : list of image, packshot, document FILE 

    attributes

#}

{% set gsdn_referenced_file_detail_information = ['packshot_C1C1_S01'] %}

{#

    videoInformationModule : list of all VIDEO attributes

#}

{% set gsdn_video_information = ['video'] %}

{% include 'cin_message_1_0.xml.twig' with {

    'code_to_label_attr': code_to_label_attr,

    'url_mapping': {

        'file_url_datasheet':'file_pdf_datasheet'

    },

    'gdsnTradeItemClassification': gdsnTradeItemClassification,

    'gsdn_referenced_file_detail_information': 

        gsdn_referenced_file_detail_information,

    'gsdn_video_information': gsdn_video_information,

    'gsdn_safety_data_sheet_information': gsdn_safety_data_sheet_information

} %}

Option B: Provide a Master

Another option if extension is not possible is that you provide the complete twig document yourself. You can still use the same twig functions but without a start template.

Global variables

Twig extensions

Normalize with context

You can also provide a specified context for some extra conditions to trigger.

context / Number Format

GS1 requires a precision of 3 digits for floats. When the correct attribute_type is set we can transform this correctly but when we are dealing with text we don’t have that automatic transformation.

In order to counter this issue we provide an option to force number formatting onto a numeric value. Beware if the value is not numeric we skip this format.

{{ normalize('3_014', ['number_format']) }}

Working with assets/files

When working with assets or files GS1 distinguishes then into different formats. Here we will link our media content data from the pim to the Datapool.

The First format is SafetyDataSheet.

getSafetyDataSheetInformation Module

This module expects a list of attribute_code(s) you wish to distribute to the Datapool. The attribute code should be an attribute FILE type and should provide a PDF document. No other documents are accepted. The module is localisable so it you provide localisable attributes it will set the language code together with the node. We also provide a resource URL this is downloadable link that points to the pim as source with a unique hash.

{% set gsdn_safety_data_sheet_information = ['your_safety_attribute_code'] %}

getFileMetaInformation Module

This module expects a list of attribute_code(s) you wish to distribute to the Datapool. The module is localisable so it you provide localisable attributes it will set the language code together with the node. We also provide a resource URL this is downloadable link that points to the pim as source with a unique hash. The attribute code should be an attribute FILE type and should provide a TIFF file. This is the preferred image format.

{% set gsdn_referenced_file_detail_information = ['packshot_C1C1_S01', 'packshot_C1R1_S02'] %}

getVideoInformation Module

This module expects a list of attribute_code(s) you wish to distribute to the Datapool. The module is localisable so it you provide localisable attributes it will set the language code together with the node. The resource URL in Akeneo CE is the product data value formed URL you have provided.

{% set gsdn_video_information = ['video'] %}

Packshot

GS1 allow a variety of packshots to be uploaded, in order to distinguish the correct facade GS1 allow you to incorporate a formatted filename, guidelines defined by GS1 into.

Product_Images_SpecificationsAndUsageRules_EN_v1.8.pdf
EN-product image checklist_FMCG.pdf

In order to abide by these guidelines we introduced an option to set the formatted text inside the attribute code. When processing the file the formatted text will be handled differently.

Here is an example:

This 2 packshots as example

# packshot_C1C1_S01 generates this filename

<fileName>08715743012693_C1C1_S01.tiff</fileName>

# packshot_C1R1_S02 generates this filename

<fileName>08715743012693_C1R1_S02.tiff</fileName>

If not correct format is detected inside the attribute_code we simple reference the original uploaded filename.

URL-attribute

A URL-attribute does not technically exist in Akeneo. We use the text-attribute where one can enter the media URL path of a specific asset. This attribute supports global, localizable and scopable but has no added validation like does the URL exist.

We generally consider an URL-attribute as a text-attribute with the suffix _url inside the attribute code.

Here an example how the XML module referencedFileDetailInformationModule is used for de nl_BE value of https://test.induxx.be/pds_nl.pdf

<referenced_file_detail_information:referencedFileDetailInformationModule

    xmlns:referenced_file_detail_information=

        "urn:gs1:gdsn:referenced_file_detail_information:xsd:3"

    xsi:schemaLocation="urn:gs1:gdsn:referenced_file_detail_information:xsd:3 

        http://www.gs1globalregistry.net/3.1/schemas/gs1/gdsn/

            ReferencedFileDetailInformationModule.xsd">

    <referencedFileHeader>

        <referencedFileTypeCode>DOCUMENT</referencedFileTypeCode>

        <fileFormatName>PDF</fileFormatName>

        <fileName>pds.pdf</fileName>

        <fileLanguageCode>nl</fileLanguageCode>

        <uniformResourceIdentifier>https://test.induxx.be/pds_nl.pdf

        </uniformResourceIdentifier>

    </referencedFileHeader>

</referenced_file_detail_information:referencedFileDetailInformationModule>

URL-attribute overruling

The URL-attribute allows another file-attribute to overruled, this is neccasary when the pim holds the original file-attribute as a secundary option. In order to make this relation between the URL-attribute and a file-attribute work we recommend that the URL attribute uses a suffix _url.

• e.g. : sds_per_locale should have the URL-attribute sds_per_locale_url

When the URL-attribute is filled then relation file-attribute will be excluded.

URL-attribute overruling by mapping

We also support URL-attribute overruling that without the correct suffix _url annotation. In order the set the relation here we introduced a url_mapping to define the correct override attribute.

{% include 'cin_message_1_0.xml.twig' with {

    'code_to_label_attr': code_to_label_attr,

    'url_mapping': {

        'file_url_datasheet':'file_pdf_datasheet'

    },

    ...

} %}

GS1 reading logs

When a message interaction is started with the Datapool it is possible that somewhere in this process the product is not accepted.

The reasons albeit missing or unexpected values will be logged into a txt file that you can download from the server.

Since every interaction form a job inside the pim, we have stored all these logs together with the generated CIP and CIN messages from that export.

Where can I find these logs?

You will find the logs, generated CIN and CIP messages inside the Activity / Process Tracker.

How do I know if my product got declined?

Your product GS1 message state will be set to DECLINED if the process ended with errors.

Delta export example

• If a delta export is setup for nighty GS1 exports.

• That cron task will generate 1 new delta job activity every day inside the “Process tracker” .

• Inside the delta job we will store the generated CIN_messages, CIP_messages and logs if any.
  
  

Product requirements

In this topic we try to explain all the requirements to when a product is considered ready for export.

Did my product export correctly?

If these conditions are not met correctly the product will not export. To be sure see the “GS1 message state” attribute inside your product. If the GS1 message state was not set to REQUEST_FOR_APPROVAL after a daily export it didn’t export.

Filters

In order to exports products to GS1 we use 3 filters. So if you have difficulty exporting products make sure that your products are accepted by these filters.

We have to make to following assumptions in order to export any product to GS1:

attribute 5_131:

• labeled Provisional publication code for GS1 must be created as an single select

• must contain the option values “Preliminary”, “Final” and “Do not publish”

• must be available inside the family / product

attribute gs1_client_publication:

• labeled Publication in GS1 for client/target market must be created as an multi select

• target market options must be available"

• must be available inside the family / product

First Filter (family)

Every template is hard-linked to at least one family. Every Family has linked products. Those family products are considered the first filter. Let’s call these family products a FamilyProductCollection from here on.

Second Filter (Provisional publication code)

We also have a second filter in place, by default only selected products can be exported. We have to set the Provisional publication code for GS1 must contain value “Preliminary” or “Final” in order to mark the product ready for GS1 export.

Third Filter (Publication in GS1 for client/target market)

Lastly we a third filter in place, this filter define what client/target market is linked to what locale. The GS1 connector will generate and XML per target market and it’s selected locales for that market.

For example let’s say we wish to export to the Belgium Intergamma target market. We have to link the locale(s) we wish to export to the correct target market option.

GS1 message state Filter

The GS1 message state is not a real filter, as this attribute is completely controlled by the connector. If the GS1 message state is set to REQUEST_FOR_APPROVAL Request for Approval then that product is currently in process by the Datapool. All other states will not filter out the product.

Delta Export

Not a real filter but we need to note it here. During a delta export we can only export products that are changed that day. During a delta export this filter is the first filter in the stack.

Requirements Summary for export

Requirements on the Akeneo Family:

• the product family should have a linked GS1 template

• attributes 5_131, gs1_client_publication and gs1_message_state shoulb part of the family Requirements on the Akeneo Product:

• attribute 5_131 must be set to “Preliminary” or “Final”

• attribute gs1_client_publication must have at least one target market selected

• attribute gs1_message_state should not have REQUEST_FOR_APPROVAL selected

CIN document archiver

This document describes how to archive your documents locally on the server or onto another server. All you need to do is provide the required correct configuration and credentials if needed in order for the archiver to work. Since credentials and path configuration are considered env (environment) variables the will require a deploy and a setup the configure correctly.

CIN Document

The document filename is based on the target_market + GTIN number + extension. The CIN document is the exact same document we produced for the Datapool.

Defaults

By default the document archiver is not setup so no unwanted bloat would be created. The archiver can store or as local storage or with an external storage.

Setting up the archiver for local storage

# src/Bundle/GsOneConnectorBundle/Resources/config/file_storage.yml

parameters:

  gsone_document_storage_dir: '%kernel.root_dir%/gsone_document_storage'

services:

  Induxx\Component\FileStorage\FileStorageProvider.gsone_document_storage_dir:

    class: Induxx\Component\FileStorage\FileStorageProvider

    arguments:

      - '%gsone_document_storage_dir%'

      - 'gsone_document_storage_dir'

Setting up the archiver for external storage

# config/..

oneup_flysystem:

  adapters:

    your_external_adapter:

      sftp:

        host: "%sftp_host%"

        port: "%sftp_port%"

        username: "%sftp_user%"

        password: "%sftp_password%"

        root: ~

        timeout: ~

        privateKey: ~

        permPrivate: ~

        permPublic: ~

        directoryPerm: ~

  filesystems:

    your_external_filesystem:

      adapter: your_external_adapter

      alias: your_external_filesystem

# src/Bundle/GsOneConnectorBundle/Resources/config/file_storage.yml

services:

  Induxx\Component\FileStorage\FileStorageProvider.gsone_document_storage_dir:

    class: Induxx\Component\FileStorage\FlySystemStorageProvider

    arguments:

      - '@oneup_flysystem.your_external_filesystem'

      - 'incoming_path'

      - 'gsone_document_storage_dir'

GS1 Commands

In summary we use 2 different commands to interact with the Datapool. The first command is the daily delta exporter, this command generated the initials CIN messages. The second command is the Datapool message retriever, this command retrieves and exchanges messages between the pim and the Datapool.

Daily delta export Command

The daily delta export ensures that all changed products with all required conditions met will be generated in XML documents and send to the Datapool, see product requirements for more information regarding the conditions. This delta export is setup by cron.

Retrieve Messages command

This command interacts and handles messages with the Datapool. It also produces a CIP message if the CIP Document got accepted. The command also persists the current state of the product message process between the pim and the Datapool. It also stores and collects the message interactions or generated messages in the process tracker.

GS1 message interactions

The GS1 connector uses the job manager or Process Tracker from the pim to deal with all interactions between the pim and the Datapool. Every job originates from a delta export launched from a cron. We use the GS1 message state attribute to communicate on the product to reflect the process state with the Datapool.

GLN Messages flow

These are the message flow and interaction between the connector and to Datapool. Every message is distinct, we capture the most useful information in these messages but not all. For example we do capture the state of the message, the sender GLN, receiver GLN and the error messages if any.

The state we capture are per target market and are subliminal, only we all states reach an agreement on a product example all accepted (approved), all not accepted (declined) we communicate that as a global state on the product.

This is a table of all messages and there corresponding states, in a processable order.