How to Register a New Mass Edit Action on Products¶
The Akeneo PIM comes with a number of mass edit actions. It also comes with a flexible way to define your own mass edit actions on selected products.
Prerequisite¶
The mass edit action uses the BatchBundle in order to run mass edit in the background. Readers and Writers are already created so in this cookbook we will focus on how to create a Mass Edit Action and create a Processor. For more information on how to create Jobs, Readers, Processors, or Writers please see Import and Export data.
Phase 1: Create the Operation¶
Tip
Operations are designed to build and transport the configuration (eventually via a form) that will be sent to the background job. No item is updated from here!
The first step is to create a new class in the Operation folder that extends AbstractMassEditOperation and declare this new class as a service in the mass_actions.yml file.
1// /src/Acme/Bundle/CustomMassActionBundle/MassEditAction/Operation/CapitalizeValues.php
2<?php
3
4namespace Acme\Bundle\CustomMassActionBundle\MassEditAction\Operation;
5
6use Akeneo\Pim\Enrichment\Bundle\MassEditAction\Operation\MassEditOperation;
7
8class CapitalizeValues extends MassEditOperation
9{
10 /**
11 * {@inheritdoc}
12 */
13 public function getOperationAlias()
14 {
15 return 'capitalize-values';
16 }
17
18 /**
19 * {@inheritdoc}
20 */
21 public function getFormType()
22 {
23 return 'acme_custom_mass_action_operation_capitalize_values';
24 }
25
26 /**
27 * {@inheritdoc}
28 */
29 public function getFormOptions()
30 {
31 return [];
32 }
33
34 /**
35 * {@inheritdoc}
36 */
37 public function getActions()
38 {
39 return [
40 'field' => 'name',
41 'options' => ['locale' => null, 'scope' => null]
42 ];
43 }
44}
- 2 things will be sent to the Job:
actions: the raw configuration actions, you define what you want here. It will be available within your Job. That’s whatgetActions()is used for. Here actions are hard-coded, but it could be generated by another method or something else.filters: the selection filter to tell the job which items it will work on. It’s used by the Reader.
Once the Operation is created, you must register it as a service in the DI with the pim_enrich.mass_edit_action tag:
1# /src/Acme/Bundle/CustomMassActionBundle/Resources/config/mass_actions.yml
2services:
3 acme_custom_mass_action.mass_edit_action.capitalize_values:
4 public: false
5 class: Acme\Bundle\CustomMassActionBundle\MassEditAction\Operation\CapitalizeValues
6 arguments:
7 - 'mass_edit_capitalize_values'
8 tags:
9 -
10 name: pim_enrich.mass_edit_action
11 alias: capitalize-values
12 acl: pim_enrich_product_edit_attributes
13 datagrid: product-grid
14 operation_group: mass-edit
15 form_type: acme_custom_mass_action_operation_capitalize_values
As you can see, the tag needs several parameters:
name: Tag name to identify all mass edit operations in the PIMalias: Alias of the operation, should be unique among your operationsacl: The ACL the operation is linked todatagrid: The datagrid name this operation appears onform_type: The FormType name this operation uses to be configuredoperation_group: The group the operation belongs to (to regroup operations, see below screenshot)
Note
The alias will be used in the URL (/enrich/mass-edit-action/capitalize-values/configure)
Phase 2: Create the Form extension¶
For this step, you’ll need to register a new form extension in /src/Acme/Bundle/CustomMassActionBundle/Ressources/config/form_extensions/mass_edit/product.yml:
extensions:
pim-mass-product-edit-product-custom:
module: pim/mass-edit-form/product/custom
parent: pim-mass-product-edit
position: 210
targetZone: custom
config:
title: pim_enrich.mass_edit.product.step.custom.title
label: pim_enrich.mass_edit.product.operation.custom.label
labelCount: pim_enrich.mass_edit.product.custom.label_count
description: pim_enrich.mass_edit.product.operation.custom.description
code: custom
jobInstanceCode: custom
icon: icon-custom
The Mass Edit should be defined with at least code, label, icon and jobInstanceCode in the config array.
The combination of the code, label and icon define the Operation.
The jobInstanceCode is the code of the background job.
Then, you will have to create a requirejs module for this extension (/src/Acme/Bundle/CustomMassActionBundle/Ressources/public/js/mass-edit/form/product/custom.js) :
'use strict';
define(
[
'underscore',
'pim/mass-edit-form/product/operation',
'pim/template/mass-edit/product/change-status'
],
function (
_,
BaseOperation,
template
) {
return BaseOperation.extend({
template: _.template(template),
/**
* {@inheritdoc}
*/
render: function () {
this.$el.html(this.template());
return this;
},
});
}
);
Finally, you will have to require your custom module into the /src/Acme/Bundle/CustomMassActionBundle/Ressources/config/requirejs.yml.
config:
paths:
pim/mass-edit-form/product/custom: pimacme/js/mass-edit/form/product/custom
Phase 3: Create the Processor¶
Well! Now the user can select the Operation to launch it. The Operation will send its config (filters, and actions) to a background job process. Now we have to write the Processor that will handle product modifications.
The Processor receives products one by one, given by the Reader:
1// /src/Acme/Bundle/CustomMassActionBundle/Connector/Processor/MassEdit/Product/CapitalizeValuesProcessor.php
2<?php
3
4namespace Acme\Bundle\CustomMassActionBundle\Connector\Processor\MassEdit\Product;
5
6use Akeneo\Tool\Component\StorageUtils\Updater\PropertySetterInterface;
7use Akeneo\Pim\Enrichment\Component\Product\Connector\Processor\MassEdit\AbstractProcessor;
8use Akeneo\Pim\Enrichment\Component\Product\Exception\InvalidArgumentException;
9use Akeneo\Pim\Enrichment\Component\Product\Model\ProductInterface;
10use Symfony\Component\Validator\Validator\ValidatorInterface;
11
12class CapitalizeValuesProcessor extends AbstractProcessor
13{
14 /** @var PropertySetterInterface */
15 protected $propertySetter;
16
17 /** @var ValidatorInterface */
18 protected $validator;
19
20 /**
21 * @param PropertySetterInterface $propertySetter
22 * @param ValidatorInterface $validator
23 */
24 public function __construct(PropertySetterInterface $propertySetter, ValidatorInterface $validator)
25 {
26 $this->propertySetter = $propertySetter;
27 $this->validator = $validator;
28 }
29
30 /**
31 * {@inheritdoc}
32 */
33 public function process($product)
34 {
35 /** @var ProductInterface $product */
36
37 // This is where you put your custom logic. Here we work on a
38 // $product the Reader gave us.
39
40 // This is the configuration we receive from our Operation
41 $actions = $this->getConfiguredActions();
42
43 // Retrieve custom config from the action
44 $field = $actions['field'];
45 $options = $actions['options'];
46
47 // Capitalize the attribute value of the product
48 $originalValue = $product->getValue($field)->getData();
49 $capitalizedValue = strtoupper($originalValue);
50
51 // Use the property setter to update the product
52 $newData = ['field' => $field, 'value' => $capitalizedValue, 'options' => $options];
53 $this->setData($product, [$newData]);
54
55 // Validate the product
56 if (null === $product || (null !== $product && !$this->isProductValid($product))) {
57 $this->stepExecution->incrementSummaryInfo('skipped_products');
58
59 return null; // By returning null, the product won't be saved by the Writer
60 }
61
62 // Used on the Reporting Screen to have a summary on the Mass Edit execution
63 $this->stepExecution->incrementSummaryInfo('mass_edited');
64
65 return $product; // Send the product to the Writer to be saved
66 }
67
68 /**
69 * Validate the product and raise a warning if not
70 *
71 * @param ProductInterface $product
72 *
73 * @return bool
74 */
75 protected function isProductValid(ProductInterface $product)
76 {
77 $violations = $this->validator->validate($product);
78 $this->addWarningMessage($violations, $product);
79
80 return 0 === $violations->count();
81 }
82
83 /**
84 * Set data from $actions to the given $product
85 *
86 * @param ProductInterface $product
87 * @param array $actions
88 *
89 * @return CapitalizeValuesProcessor
90 */
91 protected function setData(ProductInterface $product, array $actions)
92 {
93 foreach ($actions as $action) {
94 $this->propertySetter->setData($product, $action['field'], $action['value'], $action['options']);
95 }
96
97 return $this;
98 }
99}
Again, register the newly created class:
1# /src/Acme/Bundle/CustomMassActionBundle/Resources/config/processors.yml
2services:
3 acme_custom_mass_action.mass_edit.capitalize_values.processor:
4 class: Acme\Bundle\CustomMassActionBundle\Connector\Processor\MassEdit\Product\CapitalizeValuesProcessor
5 arguments:
6 - '@pim_catalog.updater.product_property_setter'
7 - '@pim_catalog.validator.product'
Phase 4: Create the background Job¶
Tip
The Step will run 3 steps: Read, Process & Write. In this cookbook, we use existing Reader and Writer.
We just wrote the Processor in the previous phase, so let’s tell the Job which services to use!
First of all you need to define a new job as follows:
1# /src/Acme/Bundle/CustomMassActionBundle/Resources/config/jobs.yml
2services:
3 acme_custom_mass_action.job.capitalize_values:
4 class: '%pim_connector.job.simple_job.class%'
5 arguments:
6 - 'mass_edit_capitalize_values'
7 - '@event_dispatcher'
8 - '@akeneo_batch.job_repository'
9 -
10 - '@acme_custom_mass_action.step.capitalize_values.mass_edit'
11 tags:
12 - { name: akeneo_batch.job, connector: '%pim_enrich.connector_name.mass_edit%', type: '%pim_enrich.job.mass_edit_type%' }
Then you need to define your step with the proper Reader, Processor and Writer.
1# /src/Acme/Bundle/CustomMassActionBundle/Resources/config/steps.yml
2services:
3 acme_custom_mass_action.step.capitalize_values.mass_edit:
4 class: '%pim_connector.step.item_step.class%'
5 arguments:
6 - 'mass_edit_capitalize_values'
7 - '@event_dispatcher'
8 - '@akeneo_batch.job_repository'
9 - '@pim_connector.reader.database.product'
10 - '@acme_custom_mass_action.mass_edit.capitalize_values.processor'
11 - '@pim_connector.writer.database.product'
You also need to set job parameters:
1# /src/Acme/Bundle/CustomMassActionBundle/Resources/config/job_parameters.yml
2services:
3 acme_custom_mass_action.connector.job.job_parameters.default_values_provider.product_mass_edit:
4 class: '%pim_enrich.connector.job.job_parameters.default_values_provider.product_mass_edit.class%'
5 arguments:
6 - ['mass_edit_capitalize_values']
7 tags:
8 - { name: akeneo_batch.job.job_parameters.default_values_provider }
9
10 acme_custom_mass_action.connector.job.job_parameters.constraint_collection_provider.product_mass_edit:
11 class: '%pim_enrich.connector.job.job_parameters.constraint_collection_provider.product_mass_edit.class%'
12 arguments:
13 - ['mass_edit_capitalize_values']
14 tags:
15 - { name: akeneo_batch.job.job_parameters.constraint_collection_provider }
The Job has to be in your database, so add it to your fixtures:
1# /src/Acme/Bundle/CustomMassActionBundle/Resources/fixtures/jobs.yml
2jobs:
3 mass_edit_capitalize_values:
4 connector: Akeneo Mass Edit Connector
5 alias: mass_edit_capitalize_values
6 label: Mass capitalize products value
7 type: mass_edit
Note
To better understand how to handle this, you can read this chapter: Add your Own Data
If your installation is already set up, use the akeneo:batch:create-job command:
php bin/console akeneo:batch:create-job "Akeneo Mass Edit Connector" "mass_edit_capitalize_values" "mass_edit" "mass_edit_capitalize_values" '{}' "Mass capitalize product values"
Warning
For Enterprise Edition version, see Phase 6 to add job profile permissions in pimee_security_job_profile_access table.
Phase 5: Translating the Mass Edit Action Choice¶
Once you have realized the previous operations (and eventually cleared your cache), you should see a new option on the /enrich/mass-edit-action/choose page.
Akeneo will generate for you a translation key following this pattern:
pim_enrich.mass_edit_action.%alias%.label.
You may now define some translation keys (label, description, success_flash...) in your translations catalog(s).
1# /src/Acme/Bundle/CustomMassActionBundle/Resources/translations/messages.en.yml
2pim_enrich.mass_edit_action:
3 capitalize-values:
4 label: Capitalize values
5 description: The selected product(s) will have capitalized values
6 launched_flash: The bulk action "capitalize values" has been launched. You will be notified when it is done.
7 success_flash: Product(s) values have been updated
8
9batch_jobs:
10 mass_edit_capitalize_values:
11 capitalize_values:
12 label: Capitalize values
Phase 6: Add user groups permissions to job profiles (ENTERPRISE EDITION)¶
In Enterprise Edition version, job profiles are managed with user groups permissions, so you need to add these permissions. To deal with these permissions, you have 3 tables:
akeneo_batch_job_instance: which stores the job profilesoro_access_group: which stored the user groupspimee_security_job_profile_access: which stores the permissions (this table only exists in Enterprise Edition)
You have to get your job instance (job profile) code from the first table, get the user groups from your second table and then execute an insert SQL query to add these permissions. It will be something like:
INSERT INTO pimee_security_job_profile_access VALUES ('', <job_profile_id>, <user_group_id>, 1, 1);
The two last numbers means you give respectively ‘edit’ and ‘execution’ permissions. Otherwise add ‘0’.
Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!