akeneo / pim-docs

[Community Documentation Repository] The open source Product Information Management (PIM)

Akeneo PIM Documentation

The Akeneo PIM documentation

Build the documentation

Install Docker.

Then make build.

The docs will be built into ./pim-docs-build.

Deploy the documentation

With Circle CI (recommended)

Once you merge a PR into the master branch, it is automatically deployed on the staging server. In order to deploy it in production, please follow these steps:

• Check the staging environment if everything is ok to be deployed in production
• Open the list of merged PR in master branch in Circle CI. You have to be connected with your Github account.
• Click on the first row which should be "On hold"

• Click on the box "approve_to_deploy_in_production" and approve. It will launch the deployment in production.

• It's deployed in production in 1 minute!

Local deployment (not recommended)

Your public SSH key should be deployed on the server (see Ansible configuration). It is strongly recommended to release with the CI process though.

To deploy what you have built, use HOSTNAME=foo.com PORT=1985 VERSION=bar make deploy.

HOSTNAME is the server to deploy the documentation on. PORT is the SSH port to connect to the server. VERSION is the subdirectory of /var/www/ where the documentation will be deployed on the the server. It should be something like 3.2, 4.0 or master.

To know the production and staging environments of pim-docs, please read the inventory.

Contribution

Don't hesitate to suggest cookbook ideas via https://github.com/akeneo/pim-docs/issues.

Developer's notes

• The folder /_themes/sphinx_rtd_theme is a clone from https://github.com/snide/sphinx_rtd_theme, and was updated on 2016-07. If you want to customize the Akeneo theme, please only update /_theme/akeneo_rtd theme.

pim-docs's Issues

Cookbook: How to add an action button or meta data to the product edit form

The article https://docs.akeneo.com/latest/cookbook/ui_customization/add_a_custom_button_to_product_edit_form.html doesn't use the new CSS classes from Akeneo 1.7.

I think that the template and maybe className in export-csv.js needs an update; but I'm not sure about the new correct class names.

Update job configuration in "How to create a new connector ?"

OLD :
reader: pim_base_connector.reader.doctrine.bulk_product
processor: pim_base_connector.processor.csv_serializer.product
writer: pim_base_connector.writer.product_file

NEW :
reader: pim_base_connector.reader.doctrine.product
processor: pim_base_connector.processor.product_to_flat_array
writer: pim_base_connector.writer.file.csv_product

Http status code documentation/implementation mismatch

I found a discrepancy in the API documentation over at api.akeneo.com. From what I can gather, this repo contains the source code to the "normal" documentation, so I suspect this isn't the right place to report this. Sorry! Is there a dedicated (public) repo for the API docs?

The endpoint for deleting products is expected to return 200 OK if the operation was successful (according to docs). When I use the endpoint in version 1.7.2, I get a 204 No Content when the operation is successful.

This isn't holding me up, I just thought I'd report this so that the documentation for the new API is spotless ✨

Thanks!

Change app/console to bin/console (PIM 2.x)

Since the use of Symfony 3 in PIM 2.x, Symfony's console is now located in bin/console instead of app/console.

Please change all those references in pim-docs for branches 2.0/2.1/master

[Cookbook] Missing informations in "How to Create a Reference Data"

Hi,

It seems that many informations are missing on this page : https://docs.akeneo.com/master/cookbook/catalog_structure/creating_a_reference_data.html#how-to-create-a-reference-data

After the configuration of the reference data there is one command to check the doctrine schema and one to check the reference data but nothing about update the doctrine schema or update the database : https://docs.akeneo.com/master/cookbook/catalog_structure/creating_a_reference_data.html#configuring-the-reference-data

It looks like these insctructions are missing :
php doctrine:schema:update --dump-sql
php app/console doctrine:schema:update --force

With only the insctructions of the cookbook, you can't make a reference data work.

Regards,

Rename activity manager

Rename the folder and the links

Enhancements for contributors guide

Hello guys! This week i was thinking about more things we may enhance in dev docs and found that there is nothing exact in code contribution section.

My proposition is to add more info about cloning fetching and pulling to dev repo.

May be something like Sylius did it?

As partner, I would have direct access to migration files from the doc (especially EE upgrade.md)

The doc give links to CE upgrade documentation but EE is not directly available https://docs.akeneo.com/latest/developer_guide/migration/index.html

We could improve our build to include these files each time we deploy the doc, or attach pdf or something else.

Raised by @fitn who can give details ❤️

Contribute a New Connector => broken link

http://docs.akeneo.com/1.5/cookbook/import_export/create-connector.html

URL on the 'Begin by checking on the forum...' row should be https://www.akeneo.com/forums/forum/importexport-connectors/

Add information about ImageMagick in our doc

Add info about ImageMagick which is a pre-requisite for the Enterprise Edition since 1.4 version.
Update cookbook for 1.5 and 1.6 versions - for page System Requirements.

Specify that it needs to be installed only for EE.

URLs to archives should be https

Hello team,

Beautifully structured documents 👌 , thanks a lot for making it easy to getting started with Akeneo PIM 🎉 .

I found a really trivial problem in the docs - in fact, I noticed it a few days ago and thought I'd just let it go... but I've been thinking about it every now and then, so here goes!

I'm following the guide for Installing Akeneo PIM CE with the Archive. As I was writing scripts to download and install Akeneo PIM, I noticed that the download URLs for the archives returned 301 Moved Permanently. The reason for this that the download site uses https, but the documents uses http. This halted my script, as I've disabled auto redirects.

The fix for this is just adding two characters, so very trivial!
Thanks and sorry! 🙂

Broken URL and missing documentation

Link is broken https://docs.akeneo.com/latest/import_and_export_data/ui
It's added to the bottom of page
https://docs.akeneo.com/latest/import_and_export_data/guides/create-connector.html#configure-a-job

Reference documentation for grid system

Hello,

we know that the grid system of Akeneo is based on the Oro platform, but it could be fine to have our own documentation with all available options and what they mean.

Mickaël

Master/2.0 documentation mismatches

https://docs.akeneo.com/master/install_pim/installation_ce_archive.html#initializing-akeneo has references to app/console while the new location is bin/console

https://docs.akeneo.com/master/install_pim/system_requirements/system_install_ubuntu_1604.html still references PHP 5 and PHP 7.0 as experimental, while 2.0 will require PHP 7.1.

Documentation (php-api and otherwise) missing Variant information (2.0/Master)

So the current documentation still has references to variant_group, while this is removed for 2.0, and no documentation to be found regarding the new Variant Products and Family Variants, which are crucial for migration between 1.7 and 2.0.

In TreeListener.php line 72: Tree object class: Pim\Bundle\CatalogBundle\Entity\Category must have tree metadata at this point

Hi All,

I have facing this issue when adding a new field in category using 2.1 version of Akeneo i spent lot of time on that but not able to fix please help on that.

Thanks,

"Submit a Feature Request": broken link to the forum URL

in http://docs.akeneo.com/latest/contributing/feature_request.html.
Correct URL is: https://www.akeneo.com/forums/forum/feature-request/

Improve the deployment of technical documentation

What do we need to do:

• Make the copyrights property dynamic (remove a sed instruction) (#567)
• Make the version dynamic (#569)
• Make html_context['versions'] dynamic (#570)
• Add composer.json into styleguide folder to install the right dependencies (#571)
• Remove the complete installation of a PIM from deploy to testing (travis) (#572)
• Add Makefile file with option to deploy one, multiple or all git branches (try parallelism) depends on others pull requests
• Update actual deployment script to use the Makefile

create-connector - The job "dummy_job" is not registered

could someone double-check that the notes at https://docs.akeneo.com/latest/cookbook/import_export/create-connector.html work with latest release (1.6) cause when i'm ready to do the https://docs.akeneo.com/latest/cookbook/import_export/create-connector.html#create-a-job-instance step, i get:

vagrant@akeneo:~/akeneo$ ./app/console akeneo:batch:create-job 'Dummy Connector' dummy_job export my_job_instance



  [Akeneo\Component\Batch\Job\UndefinedJobException]
  The job "dummy_job" is not registered



akeneo:batch:create-job <connector> <job> <type> <code> [<config>] [<label>]


vagrant@akeneo:~/akeneo$

i guess on the symfony side everything is working as expected:

vagrant@akeneo:~/akeneo$ ./app/console config:dump-reference | grep Acme
  AcmeDummyConnectorBundle
vagrant@akeneo:~/akeneo$

• how do we debug why job "dummy_job" is not registered?
• is this a symfony or akeneo feature?
• where are the docs for this feature?

ps. would be nice if this dummy connector was in a git repo, would save a lot of confusion...

Broken link in `Import and export data » Formats » Attribute data structure`

How to reproduce:

1. Go to [Attribute data structure] (https://docs.akeneo.com/master/import_and_export_data/formats/attribute.html) page.
2. Find a table row with text 'Must be a valid reference data code (see Reference data configuration)'.
3. Click on the link 'Reference data configuration'

Expected: Reference data configuration
Actual result: 404 page

Reference Data Documentation is not up to date

When going throught the docs there is references to classes that don't exist anymore...

It would be better to actually delete them then leave them as they are, it's confusing for anyone trying to migrate more then helpful.

Broken link on 'How to create a new Connector' page

The last link on the page 'customize the UI.' here https://docs.akeneo.com/2.0/import_and_export_data/guides/create-connector.html#configure-the-ui-for-our-new-job goes to a 404. It should probably point to https://docs.akeneo.com/2.0/design_pim/overview.html

Attibute types listing

Akeneo PIM has built in attribute data types. But there is no information about it in the docs section.

We may add built in attributes data types list with explanations how to use them in imports and customized installation. Todays newcomers have to browse source code to find right attribute data types and how to use them.

Documentation branch 1.2 has such page but it disappeared in the future versions.

• pim_catalog_identifier
• pim_catalog_text
• pim_catalog_number
• pim_catalog_boolean
• pim_catalog_price_collection
• etc

Each type in list may be linked to dedicated page with further information (like form types listing in symfony book).

Forcing Uppercase H3 Tags is Not Reader Friendly

This line: https://github.com/akeneo/pim-docs/blob/2.0/_themes/akeneo/static/css/variables-43bf553955.css#L7546

Should probably just be removed.

Forcing these headings to all uppercase makes pages like https://docs.akeneo.com/latest/import_and_export_data/product-import.html quite hard to read.

Add note explanation about user group 'All' in customize_installer section

This docs enhancement was born during this discussion.

According to @nidup group 'All':

The group "all" never appears in the user management UI, neither in group list, neither in user edit, it's a system group added for any users created in the PIM. cf http://demo.akeneo.com/#url=/user/group

It's mainly used in Enterprise Edition to grant permissions to any users and appears in "permissions" tabs of "locale", "attribute", "category", etc (in the Enterprise Edition only).

As I think many new comers will have problem during custom installation trying to translate user group 'All' with others groups. And we have to add note about it in the customize_installer section.

[Contributing] Submitting a feature request - broken link bug

I'm submitting a bug

The link on Submitting a feature request page is broken:

http://www.akeneo.com/forum/feature-request/

RegisterJobNameVisibilityCheckerPass class has been removed

In file AcmeNotifyConnectorBundle.php there is a mention of class Pim\Bundle\ImportExportBundle\DependencyInjection\Compiler\RegisterJobNameVisibilityCheckerPass.

This class has been removed since 1.7 (see CHANGELOG-1.7.md).

The doc should be updated.

Thus, there should also be some doc to explain how to build another tab in the job profiles view, I can't find any, or probably I didn't search well.

Create a Custom Step on 1.7 Cookbook is outdated.

I've used this Custom Step Notification cookbook on previews version to upgrade my bundle to 1.6 and now I need to upgrade for 1.7 I've noticed that this documentation Create-Custom-Step is outdated.

Specifically the way it implements the form that still using the FormConfigurationProviderInterface.

Document about akeneo command lines

Hello,

I would like to contribute to the documentation with a list of available commands in akeneo with description, arguments and specific options.

Only akeneo, pim and pimee commands are concerned.

Are you interested about it?

Regards,

Benjamin

Update the cookbook documentation with updater doc

Document missing commands from ProductAsset and RuleEngine bundles [EE]

Hello,

I've been noticed that a lot of commands are not documented right now. I think we can do something with that, maybe with 1 or 2 cookbooks introducing a task to do and how theses commands can help.

We are talking about these commands:

• pim:asset:generate-missing-variation-files
• pim:asset:generate-variation-files-from-reference
• pim:asset:generate-variation-file
• akeneo:rule:run
• others from RuleEngine bundle?

Cannot install documentation on my system

It seems that my system has to much fresh packages: python 3 with sphinx 1.6.2.

This results in errors when trying to deploy the documentation:

• on 1.5 and 1.6:

  Could not import extension sensio.sphinx.configurationblock (exception: cannot import name 'upper')
  

• on 1.7: pim:installer:assets is failing…

TransformBundle URL - Broken link

TransformBundle link – in PIM Bundles list – is broken.
Page: http://docs.akeneo.com/latest/reference/bundles/index.html

Possibly missing PHP extension in System Requirements

Hello,
I run in to some problems when trying to preview an uploaded image (an image attribute in a product). The image previews was not rendered, as the request return a 500 Internal Server Error. Looking through the logs I found this entry

[2017-04-24 11:48:52] request.CRITICAL: Uncaught PHP Exception
Imagine\Exception\NotSupportedException: "PHP exif extension is required to use the 
ExifMetadataReader" at /akeneo/vendor/imagine/imagine/lib/Imagine/Image/Metadata
/ExifMetadataReader.php line 25 {"exception":"[object] (Imagine\\Exception\\NotSupportedException(code:
 0): PHP exif extension is required to use the ExifMetadataReader at /akeneo/vendor/imagine/imagine
/lib/Imagine/Image/Metadata/ExifMetadataReader.php:25)"} []

Based on the following: "PHP exif extension is required to use the ExifMetadataReader" it was pretty clear that I needed to install exif 🙂 . However, that extension is not listed in the PHP required modules and configuration section of the system requirements document.

I'm a bit uncertain if this is the right way to go, as I'm currently seeing a different exception

request.CRITICAL: Uncaught PHP Exception Imagine\Exception\RuntimeException: 
"call_user_func_array() expects parameter 1 to be a valid callback, function 'imagejpeg' not found or 
invalid function name" at /akeneo/vendor/imagine/imagine/lib/Imagine/Gd/Image.php line 697
 {"exception":"[object] (Imagine\\Exception\\RuntimeException(code: 2):call_user_func_array() expects 
parameter 1 to be a valid callback, function 'imagejpeg' not found or invalid function name at /akeneo
/vendor/imagine/imagine/lib/Imagine/Gd/Image.php:697, ErrorException(code: 0): call_user_func_array() 
expects parameter 1 to be a valid callback, function 'imagejpeg' not found or invalid function name at 
/akeneo/vendor/imagine/imagine/lib/Imagine/Gd/Image.php:580)"} []

Which I'm currently trying to solve with the help of @gplanchat (on slack):

on EE you also need imagemagick package, I can’t remember if it is required in CE too

That has not resolved my problems, but it might very well be that I'm missing some other system package that is required.

[cookbook] How to add a new field type seems outdated

Hi,

We're using EE 1.6.5, we try the following cookbook in order to satisfy some needs.

https://docs.akeneo.com/1.5/cookbook/ui_customization/create_a_new_field_type.html

However, following the exact workflow produces nothing on the UI.

You can find the code used from the cookbook here : https://github.com/ikwattro/akeneo-test/tree/master/src/Acme/Bundle/CustomBundle

No mention of database configuration

Expected a mean to provide akeneo with database information in https://github.com/akeneo/pim-docs/blob/1.7/developer_guide/installation/installation_archive.rst.inc but nothing found.

Problem

Command pim:install fails with

Prepare database schema (driver: doctrine/orm)
Database does not exist yet
Could not create database for connection named `akeneo_pim`
SQLSTATE[HY000] [1045] Access denied for user 'akeneo_pim'@'localhost' (using password: YES)
The command terminated with an error code: 1.

                                                 
  [Exception]                                    
  The command terminated with an error code: 1.                                             

Solution

For those running into the same issue, a quick grep reveals

root@ebd12080e6b1:/var/www/pim-community-standard# grep -R "akeneo_pim" app/config/
app/config/pim_parameters.yml:    # mongodb_database: akeneo_pim
app/config/parameters.yml:    database_name: akeneo_pim
app/config/parameters.yml:    database_user: akeneo_pim
app/config/parameters.yml:    database_password: akeneo_pim
app/config/parameters.yml.dist:    database_name:     akeneo_pim
app/config/parameters.yml.dist:    database_user:     akeneo_pim
app/config/parameters.yml.dist:    database_password: akeneo_pim

Modify your parameters.yml as appropriate and make sure you refresh the cache after you do so php5.6 app/console cache:clear --env=prod

We should notify user who visit a deprecated version of documentation

Hello,

at this moment, only versions 1.5+ of Akeneo are actually maintained. We should warn users of old version and advise them to migrate asap.

For instance, this is what is done in Symfony project:

To do it, we need to rely on version value of each documentation version, then we can easily display a block dynamically to inform our users :)

Document Reference Data: the big plan

• How to create a Reference Data (https://docs.akeneo.com/1.6/cookbook/catalog_structure/creating_a_reference_data.html)
• Document the Menu management (needed to create a CRUD)
• Document the CustomEntityBundle: forms, actions, grids (#495)
• How to create a CRUD for a Reference Data (using CustomEntityBundle) (#494) ? (cookbook/crud_reference_data)
• How to link a reference data to a product type ? (need to be updated) (https://docs.akeneo.com/1.2/cookbook/custom_entity/creating_an_attribute_type.html)
• Document the Datagrid management (/reference/datagrid , needed to display a CRUD)
• What is a Reference Data (/reference/reference_data)

Inline code blocks should not have line breaks

This is an issue in all parts of the technical docs, for example -

Incorrect docs for creating a menu item

The page - https://docs.akeneo.com/latest/design_pim/guides/how_to_customize_menu.html is outdated/incorrect.

1. in the sources, the form extensions declarations are under an extensions: element level
2. the files are located in Resources/config/form_extensions/, not Resources/form_extension/ (under a configdirectory, and plural on extension)
3. if the route name doesn’t start with pim_, the HTTP request is not sent (wut?)
4. root menu elements require a iconModifier config item

cc: @gplanchat

Product value validation link

In http://docs.akeneo.com/master/cookbook/catalog/product/validate.html at the last paragraph "Product value validation":

Should ../custom_entity/creating_an_attribute_type be a link to http://docs.akeneo.com/master/cookbook/catalog/product/validate.html ?

[Register a connector] Add a chapter about registering new job using jobs.yml

please update How to Customize Validation

https://docs.akeneo.com/cookbook/validation/customize_validation.html

this classes today in other namespace:
Pim\Bundle\CatalogBundle\Validator\Constraints\SingleIdentifierAttribute
Pim\Bundle\CatalogBundle\Validator\Constraints\Immutable

new namespace is:
Pim\Component\Catalog\Validator\Constraints

Add a warning when the PIM is installed on a subdirectory domain

We need to add on our installation doc that the PIM should not be installed on a subdirectory of a domain.

Link to the EE edition, public readers see a 404

in page http://docs.akeneo.com/latest/cookbook/product_asset/add_new_transformation.html, the link at the end of the sentence "To see how the imagemagick command is launched, you can take a look at the ImageMagickLauncher." leads to the EE source code.
Such URL require access to a private rep, so public doc reader cannot read further, So it may be helpful to precise that this link require granted access to the EE.

Cookbook: product xml import outdated

According to CHANGELOG 1.7 implementations of Pim\Bundle\ImportExportBundle\JobParameters\FormConfigurationProviderInterface; were removed and there is no such interface in code base anymore, means interface itself was removed too. But it is still used in master https://docs.akeneo.com/master/cookbook/import_export/product-import-from-xml-file.html and 1.7 version of same page.

Custom Entity

All documentation about create Custom Entity
https://github.com/akeneo/pim-docs/blob/2.0/technical_architecture/bundles/custom_entity_bundle/index.rst

is not compatible with Akeneo 2.0 version

Add information about the naming of reference data

Reference data must be named in plural, we should add this information in our cookbook.

[Cookbook] CSV formats, attribute data structure

I'm requesting enhancement

Story

Attribute data structure page was introduced and updated recently by @fitn and merged in branches by @juliensnz

As @jmleroux mentioned during commit conversation: it was created for current stable 1.5 branch.

I

After merging PR we got the same page version for master. But as I mentioned during conversation its information must be updated according to pim-community-dev master branch to correspond to the structure we have i.e.:

• type
• allowed_extensions
• available_locales
• code
• date_max
• date_min
• decimals_allowed
• default_metric_unit
• group
• label-locale
• localizable
• max_characters
• max_file_size
• metric_family
• minimum_input_length
• negative_allowed
• number_max
• number_min
• reference_data_name
• scopable
• unique
• useable_as_grid_filter
• validation_regexp
• validation_rule
• wysiwyg_enabled

II

Currently I'm trying to finish Product information page see #295 and issue #267 , that describes how all product related data is kept and organized in PIM. And there is topic about product attribute types and table describing native attribute types, and as i see now this table is pretty close to that on Attribute data structure page. To make documentation clearer we need to avoid duplication and decide where is the place for attributes native types listing table. Anyway I don't think that page describing attribute data structure must contain information about attribute types at least in that part related to next PIM version tech doc, and the reason it is located there is because there was no dedicated page describing attribute types.

Now as i found updated Import/Export documentation in master I will update my PR for Product Information page with note-references to import/export pages apart for each product related entity described.

Task

• Update Attribute data structure page on master to the actual master structure as in issue description above;
• Avoid content duplication: to decide where is the best place for attribute types listing table and remove duplication.

[Cookbook] Customizing and creating attributes

I'm reporting feature request

According to @nidup answer on issue #267: cookbook section about customizing attribute types and creating new attribute types is very expected.

Let's discuss page basic structure 👀