Support Center & Knowledge Base - Easy catalog API connector

Installation

Unzip the zipped bundle into your project src directory.

unzip easycatalog-*.zip to src/*

Enable the bundle in ~/config/bundles.php file.

# ~/config/bundles.php

Induxx\Bundle\EasyCatalogBundle\InduxxEasyCatalogBundle::class => ['all' => true],

Add an Easy Catalog routing file to your project ~/config/routes/easy_catalog.yml

# ~/config/routes/easy_catalog.yml

easy_catalog:

resource: "@InduxxEasyCatalogBundle/Resources/config/routing/easy_catalog_api.yml"

Update the ~/config/packages/security.yml file:

under firewalls above the firewall of api_index:

# ~/config/packages/security.yml

api_induxx:

pattern: ^/api/rest/induxx

security: false

under access_control:

- { path: ^/api/rest/induxx, role: IS_AUTHENTICATED_ANONYMOUSLY }

Download the example bundle below:
Project.zip

Place the example files in your project src file and change filenames and namespace to match your project.

Add the following code to your ~/config/services.yml

# ~/config/services.yml

akeneo_storage_utils:

mapping_overrides:

-

original: Akeneo\Pim\Structure\Component\Model\Family

override: Project\Bundle\ProjectBundle\Entity\Family

Configuration

Setting up the Easy Catalog Xml Export

Create easy catalog export job

Go to the export tab in akeneo and click on the create export profile button.

Choose the Product XML Export under the Easy Catalog Connector and give it a suitable code and label. Click save.

Set the Global Settings

In the global settings you can set your export filename, it is important that you leave the extension .csv. The export creates this file first and later on converts it into an xml. This will happen automaticaly, but if the original extension is not csv the export will fail.

Set content Settings

It is very important to know that the easy catalog export is designed to be used by category. Selecting multiple categories will not break the export but will result in an unusable xml for easy catalog. So make sure you select only 1 catagory in the category field to export all products from this category, if you want to export also the products of children categories select the child categories also as seen in the example.

You can set the other values like any normal product export.

Set Export Entities Settings

The easy catalog export extends on the mapping export, this way mapping can happen to the csv before it is converted to xml.

Make sure that in the export entities product is always selected. Otherwise the export will fail. If you are doing this export without any mapping, only selecting product is enough, the other entites are used only when mapping configuration is given also.

For more information about the mapping bundle: MappingBundle

Triggering the Easy Catalog Export from the UI

The Easy Catalog export can be triggered from inside the UI just like any other export job. Click on the easy catalog export inside the job list.

To start the export just click on the export now button.

Export output

The Easy Catalog will show all the steps being executed, after exporting all the csv it will execute a mapping step, when this is done a last csv to xml conversion step will be executed.

When you click on the download generated files button, you will be prompted to donwload your export xml file.

Get the Easy Catalog Export API Endpoint using the JobInstanceCode

The easy catalog plugin needs an api endpoint that points to the correct xml, we created an endpoint just for that. This api endpoint will return the latest export file created by the given job instance code. If the export given was never triggered before, an error will be returned. The idea is to setup cronjobs to keep these export files up to date.

Setting up a connection

Go to the system tab and sub tab connections. Click on the create new button to create a new connection. The connection we are creating is necessary as we need to use it for the api trigger.

Give your connection a code, label and select Data destination as flow type. Click save. Thats it, all we need now for out API trigger is the code of this connection.

API Endpoint

/api/rest/induxx/EC/v1/products/{connectionCode}/{jobInstanceCode}

Replace connectionCode with the code of your connection we created earlier, replace jobInstanceCode with the code of the product xml export job we created earlier. You can test the url in your browser, if you get an xml as return, your api call was succesfull. If an invalid connectionCode or jobInstanceCode is given, you will get an error.

You can enter this API endpoint int the easy catalog plugin configuration and this way the xml will be loaded into in design.

Here is an example of a basic xml output:

Family Attributes Print Tab - defining model and variant attributes

Under the Settings - Families tab there is now a new tab called print. **

** This tab shows a list of all attributes connected to the selected family, you can change the order and check checkboxes to define them as model attributes or variant attributes. When the easy catalog xml is created every product will have a list with al its attributes, but if models or variants are defined, they will also have seperate lists with only the chosen attributes. This way it easy to create tables inside indesign with main attributes of a global product and seperate tables for the variant attributes which will be different.

Example XML

This is an example XML generated by this bundle.

<?xml version="1.0" encoding="utf-8"?>

<!-- "ecommerce" tag als channel (default Akeneo) wegen standaard maar 1 selecteerbaar in

het jobprofiel -->

<!-- Binnen de rootcategory "master" die voor EasyCatalog gedefinieerd is, enkel de

eerste category element dient gebruikt te worden om deze boom op te bouwen-->

<!-- in dit geval gaat het over de rootcategory "master" die voor EasyCatalog is

gekozen en was de category "master_women_dresses" het eindresultaat -->

<!-- bij tekstuele velden zoals labels en descriptions de CDATA tag gebruiken om

errors te voorkomen -->

<code>master</code>

<label-de_DE><![CDATA[Hauptkatalog]]></label-de_DE>

<label-en_US><![CDATA[Master catalog]]></label-en_US>

<label-fr_FR><![CDATA[Catalogue Principal]]></label-fr_FR>

</level0>

<code>master_women</code>

<label-de_DE><![CDATA[Women]]></label-de_DE>

<label-en_US><![CDATA[Women]]></label-en_US>

<label-fr_FR><![CDATA[Women]]></label-fr_FR>

</level1>

<code>master_women_dresses</code>

<label-de_DE><![CDATA[Dresses]]></label-de_DE>

<label-en_US><![CDATA[Dresses]]></label-en_US>

<label-fr_FR><![CDATA[Dresses]]></label-fr_FR>

</level2>

</categories>

<family>clothing</family>

<parent>athena</parent>

<name>athena</name>

<label-de_DE><![CDATA[Beschreibung]]></label-de_DE>

<label-en_US><![CDATA[Description]]></label-en_US>

<label-fr_FR><![CDATA[Description]]></label-fr_FR>

<value-de_DE><![CDATA[Duitse beschrijving - fictief]]></value-de_DE>

<value-en_US><![CDATA[Length: ShortLining: 100% polyester

Model: Model is 179 cm and wears a size 36

Cervical Shape: Deep V-neck

Total length: 88 cm in size 36

Additional Info: zip, lined

Handle Type: Sleeveless

Composition: 100% nylon

Care instructions: hand wash]]>

</value-en_US>

<value-fr_FR><![CDATA[Franse beschrijving - fictief]]></value-fr_FR>

</description>

<collection>autumn_2016</collection>

</attributes>

<!-- indien gewenst dat er specifieke output nodig is voor productmodels en hun

variantattributen -->

<!-- dit zijn opnieuw alle attributen van een product maar opgesplitst in model -en

variantattributen -->

<model_attributes>

<!-- in dit voorbeeld is "sku" het eerste attribuut gekozen in de

Akeneo>Settings>Family>Print> "model" kolom selectie + sorteervolgorde

configuratie -->

<label-de_DE><![CDATA[SKU]]></label-de_DE>

<label-en_US><![CDATA[SKU]]></label-en_US>

<label-fr_FR><![CDATA[SKU]]></label-fr_FR>

<value-de_DE><![CDATA[1111111152]]></value-de_DE>

<value-en_US><![CDATA[1111111152]]></value-en_US>

<value-fr_FR><![CDATA[1111111152]]></value-fr_FR>

</attribute1>

<!-- in dit voorbeeld is "sku" het TWEEDE attribuut gekozen in de

Akeneo>Settings>Family>Print> "model" kolom selectie + sorteervolgorde

configuratie -->

<label-de_DE><![CDATA[SKU]]></label-de_DE>

<label-en_US><![CDATA[SKU]]></label-en_US>

<label-fr_FR><![CDATA[SKU]]></label-fr_FR>

<value-de_DE><![CDATA[1111111152]]></value-de_DE>

<value-en_US><![CDATA[1111111152]]></value-en_US>

<value-fr_FR><![CDATA[1111111152]]></value-fr_FR>

</attribute2>

</model_attributes>

<variant_attributes>

<!-- in dit voorbeeld is "sku" het eerste attribuut gekozen in de

Akeneo>Settings>Family>Print> "model" kolom selectie + sorteervolgorde

configuratie -->

<label-de_DE><![CDATA[SKU]]></label-de_DE>

<label-en_US><![CDATA[SKU]]></label-en_US>

<label-fr_FR><![CDATA[SKU]]></label-fr_FR>

<value-de_DE><![CDATA[1111111152]]></value-de_DE>

<value-en_US><![CDATA[1111111152]]></value-en_US>

<value-fr_FR><![CDATA[1111111152]]></value-fr_FR>

</attribute1>

<label-de_DE><![CDATA[SKU]]></label-de_DE>

<label-en_US><![CDATA[SKU]]></label-en_US>

<label-fr_FR><![CDATA[SKU]]></label-fr_FR>

<value-de_DE><![CDATA[1111111152]]></value-de_DE>

<value-en_US><![CDATA[1111111152]]></value-en_US>

<value-fr_FR><![CDATA[1111111152]]></value-fr_FR>

</attribute2>

</attribute3>

</attribute4>

</variant_attributes>

</product>

</products>

<!-- lock zetten op de job om te voorkomen dat de file meermaals in een te korte periode

wordt gemaakt -->