Important

You are browsing the documentation for version 4.1 of OroCommerce, OroCRM and OroPlatform, which is no longer maintained. Read version 5.1 (the latest LTS version) of the Oro documentation to get up-to-date information.

See our Release Process documentation for more information on the currently supported and upcoming releases.

Extend Entities to Support Bulk Import and Export

Import/export capabilities in Oro applications are available for most critical features where the daily operations generate high data load. Bulk import is recommended when manual one-by-one entry is not efficient.

Out of the box, import and export is enabled for the following types of data:

OroCommerce

OroCRM

OroPlatform

Products

Leads

Emails

Price lists

Opportunities

Integrations

Inventory levels

Accounts

Localizations

Contacts

Languages

Business Customers

Users

Organizations

User Groups

User Roles

Business Units

When your business calls for a non-standard solution, you may customize Oro application and enable import/export for the entity that is not listed above. This works for your custom entities or for the standard one that is heavily used in your business.

Enable Import/Export for a Custom Entity

To make OroPlatform capable to export your custom entities as CSV files and to be able to load data from CSV files for your entities, create the following methods, services and configurations:

Implement Configuration Loading Method

To enable Oro application read configuration settings from the configuration files, add a container extension class in the entity bundle and implement the load method, like in the example below:

 1// src/AppBundle/DependencyInjection/AppExtension.php
 2namespace AppBundle\DependencyInjection;
 3
 4use Symfony\Component\Config\FileLocator;
 5use Symfony\Component\DependencyInjection\ContainerBuilder;
 6use Symfony\Component\DependencyInjection\Extension\Extension;
 7use Symfony\Component\DependencyInjection\Loader\YamlFileLoader;
 8
 9class AppExtension extends Extension
10{
11    public function load(array $configs, ContainerBuilder $container)
12    {
13        $loader = new YamlFileLoader($container, new FileLocator(__DIR__.'/Resources/config'));
14        $loader->load('importexport.yml');
15    }
16}

In this example, the importexport.yml file is located in the Resources/config directory of the bundle.

Note

It is recommended to keep the default location and default filename for the import/export configuration file.

Configure Import and Export Services (Processors)

In OroPlatform, import and export processor are implemented in the Oro\Bundle\ImportExportBundle\Processor\ImportProcessor and Oro\Bundle\ImportExportBundle\Processor\ExportProcessor classes that ship with the OroImportExportBundle.

In the importexport.yml configuration file located in the Resources/config directory, define the secrvices that are based on the on abstract OroImportExportBundle services, like in the following example:

Note

In the tags section, specify the entity to enable import/export for.

src/AppBundle/Resources/config/importexport.yml
 1services:
 2    app.importexport.data_converter:
 3        parent: oro_importexport.data_converter.configurable
 4
 5    app.importexport.processor.export:
 6        parent: oro_importexport.processor.export_abstract
 7        calls:
 8            - [setDataConverter, ['@app.importexport.data_converter']]
 9        tags:
10            - name: oro_importexport.processor
11              type: export
12              entity: AppBundle\Entity\Task
13              alias: app_task
14    app.importexport.processor.import:
15        parent: oro_importexport.processor.import_abstract
16        calls:
17            - [setDataConverter, ['@app.importexport.data_converter']]
18        tags:
19            - name: oro_importexport.processor
20              type: import
21              entity: AppBundle\Entity\Task
22              alias: app_task

Prepare Import Data Template

Import capability in Oro applications is documented with a Data Template - a sample import file that illustrates expected structure of the data, like the headers, data types, and acceptable values that are valid for the entity attributes.

User can download data template in a csv format from the list next to the Import option. Oro application creates a file automatically based on the related template fixtures.

To implement these fixtures for your custom entity, create a class that implements TemplateFixtureInterface and extends AbstractTemplateRepository and implement the following methods:

  • getEntityClass()

  • getData()

  • fillEntityData($key, $entity)

  • createEntity($key)

In the fillEntityData method, populate the values for the attributes that shall be included into the template.

Please refer to the following example:

 1// src/AppBundle/ImportExport/TemplateFixture;
 2namespace AppBundle\ImportExport\TemplateFixture;
 3
 4use AppBundle\Entity\Task;
 5use Oro\Bundle\ImportExportBundle\TemplateFixture\AbstractTemplateRepository;
 6use Oro\Bundle\ImportExportBundle\TemplateFixture\TemplateFixtureInterface;
 7
 8class TaskFixture extends AbstractTemplateRepository implements TemplateFixtureInterface
 9{
10    public function getEntityClass()
11    {
12        return 'AppBundle\Entity\Task';
13    }
14
15    public function getData()
16    {
17        return $this->getEntityData('example-task');
18    }
19
20    public function fillEntityData($key, $entity)
21    {
22        $entity->setId(1);
23        $entity->setSubject('Call customer');
24        $entity->setDescription('Please call the customer to talk about their future plans.');
25        $entity->setDueDate(new \DateTime('+3 days'));
26    }
27
28    protected function createEntity($key)
29    {
30        return new Task();
31    }
32}

Next, in the importexport.yml file located in the src/AppBundle/Resources/config/ folder, register the newly created fixtures class as a service. Please refer to the following example:

src/AppBundle/Resources/config/importexport.yml
1services:
2    # ...
3
4    app.importexport.template_fixture.task:
5        class: AppBundle\ImportExport\TemplateFixture\TaskFixture
6        tags:
7            - { name: oro_importexport.template_fixture }

Enable Import and Export in the UI

To enable export and import for Oro application users, reuse the buttons.html.twig template from the OroImportExportBundle. Include it into the twig template in the navigation block (block navButtons). Provide the valid entity_class, export and import processor aliases from the configuration file that is described in the Configure import and export services (processors) section.

 1{# src/AppBundle/Resources/views/Task/index.html.twig #}
 2{% extends 'OroUIBundle:actions:index.html.twig' %}
 3
 4{% set gridName = 'app-tasks-grid' %}
 5{% set pageTitle = 'Task' %}
 6
 7{% block navButtons %}
 8    {% include 'OroImportExportBundle:ImportExport:buttons.html.twig' with {
 9        entity_class: 'AppBundle\\Entity\\Task',
10        exportProcessor: 'app_task',
11        exportTitle: 'Export',
12        importProcessor: 'app_task',
13        importTitle: 'Import',
14        datagridName: gridName
15    } %}
16
17    {# ... #}
18{% endblock %}