Akeneo 1.6 : Creating an Installation Bundle.
In the cook book of Akeneo we can find a section about how to cutimize the dataset : https://docs.akeneo.com/1.6/cookbook/setup_data/customize_dataset.html
For having done this a few times I can say that the instructions are not very clear if you wish to do slightly more then what the default installer does..
To keep the tutorial short I will consider that you already know symfony, and won't give precissions on how to create a bundle or such details.
First let's create our own dataset then we will see how the akeneo installation of the dataset's work in order to really understand what we did.
Creating a new Dataset.
We will start by creating a new custom bundle. In the Akeneo tutorial they call this the AcmeAppBundle, but in reality this bundle has no other purpose and should have a standard name. We will call it AcmeInstallerBundle in order to reference the PimInstallerBundle.
We will first get the fixtures. Those are called dataset in the Akeneo cookboook. Once again there is a naming issue and this one has probably it's origins from the older versions of Akeneo where doctrine datafixtures were used for the installation.
If you are using Akeneo CE copy the content of fallowing directory into your Resources/fixtures/myDataSet/ :
vendor/akeneo/pim-community-dev/src/Pim/Bundle/InstallerBundle/Resources/fixtures/minimal
If not the content of
vendor/akeneo/pim-enterprise-dev/src/PimEnterprise/Bundle/InstallerBundle/Resources/fixtures/minimal
Basically the entreprise version has more files as it needs to add more data for various functionnalities unavailable in the community version.
You can edit those files to add your own content.
Creating a custom import.
Now creating yout custom dataset wasn't to complicated, but what if you have created your own entities? And you would like to populate a dataset for those. Or your import format has nothing to do with the csv files of Akeneo?
For that we need to regsiter a new "task" that will import your new file. Prior to Akeneo 1.6 this was done throught a mix of Doctrine Fixtures and jobs. Now it has been slightly changed and all imports are throught jobs. I will suppose you have already created a job to make imports possible throught the Akeneo interface.
If you haven't you can find a tutorial about it here : https://docs.akeneo.com/1.6/cookbook/import_export/index.html
Now we need to tell Akeneo that it needs to execute those jobs during the installation. To do that we will change the pim_installer.fixture_loader.job_instances_builder service. Let's create a new fixture_loader.yml file and load it with the dependency injection.
First let's see the service in the original file : vendor/akeneo/pim-community-dev/src/Pim/Bundle/InstallerBundle/Resources/config/fixture_loader.yml
pim_installer.fixture_loader.job_instances_builder:
class: '%pim_installer.fixture_loader.job_instances_builder.class%'
arguments:
- '@file_locator'
- '@pim_connector.reader.file.yaml_job_instance'
- '@pim_installer.processor.denormalization.job_instance'
- [ '%pim_installer.fixture_loader.job_loader.config_file%' ]
We can see that the last parameter is the list of the fixtures_jobs config files to read. If you are using the EE edition you can find a service looking like this :
pim_installer.fixture_loader.job_instances_builder:
class: '%pim_installer.fixture_loader.job_instances_builder.class%'
arguments:
- '@file_locator'
- '@pim_connector.reader.file.yaml_job_instance'
- '@pim_installer.processor.denormalization.job_instance'
- [ '%pim_installer.fixture_loader.job_loader.config_file%', '%pimee_installer.fixture_loader.job_loader.config_file%' ]
So what we need to do is to add our own fixtures_jobs.yml file. We should have something like this :
parameters:
acme_installer.fixture_loader.job_loader.config_file: 'AcmeInstallerBundle/Resources/config/fixture_jobs.yml'
services:
pim_installer.fixture_loader.job_instances_builder:
class: '%pim_installer.fixture_loader.job_instances_builder.class%'
arguments:
- '@file_locator'
- '@pim_connector.reader.file.yaml_job_instance'
- '@pim_installer.processor.denormalization.job_instance'
- [ '%pim_installer.fixture_loader.job_loader.config_file%', '%acme_installer.fixture_loader.job_loader.config_file%' ]
Once this in place we can create our fixtures_jobs.yml file. We don't need to load this file with the DI, as it will be loaded by the pim installer fixture loader service. Let's do that and create our job in it.
jobs:
fixtures_acme_custom_yml:
order: 300
connector: Data fixtures
alias: fixtures_acme_custom_yml:
label: Acme Custom
type: fixtures
configuration:
filePath: acme_custom.yml
fixtures_acme_custom_yml being the name of the job you created the same way you would have created any other import job. The only particularity is that you need to tag the job properly for it to work as a fixture :
tags:
- { name: akeneo_batch.job, connector: '%pim_installer.connector_name.data_fixtures%', type: '%pim_installer.job.fixture_type%' }
The only "magical" thing here is the file path. Akeneo is going to resolve the file paths according to the dataset, nothing very complicated.
Now that everything is in place we can reinstall akeneo using the pim:install command.
How does it works
The pim:install command launches multiple other commands :
- pim:installer:check-requirements : Checks that you have all the necessery system compnontes installes & that permissions are fine. You can use these command even on an installed akeneo to check if you new server is fine or so.
- pim:installer:db This will create all the database structure. This will actually execute the doctrine database creation & schema creation commands.
Once it has done this then it will load all the jobs we have defined using the fixture_jobs.yml
Once again it will do nothing magic, it will simply use the akeneo:batch:job command to execute those jobs as if it was any other job.
Conclusion
Akeneo might seem complicated at first and it might look daunting to create your own datasets. They indeed are much simplier systems to do this in different tools; but once you get the grasp of it you see how powerfull the installer of Akeneo can be.
We indeed wrote a lot of code; but think about it we have created the jobs to import our custom entities as well. And these imports are easily usable from the User interface of Akeneo. There is nealry no code duplication "for the fixture" part.
What this method allows as well which other tools don't usually allow is to actually skip/replace a part of the process. Everything is services, and so compnontes that you can replace.