No two businesses are alike. Once a company acquires a new tool, it usually needs to adapt it to the existing use cases, blueprints, and best practices. Luckily, companies may easily adjust Oro application to the existing business process and facilitate data logistics, for example:

Enable control over the custom data flow to and from Oro applicationExample: A product catalog for the B2B storefront is populated with the data from the existing ERP system, and the purchases statistics provided by the Oro application fuels the ERP reporting engine.

Process custom domain-specific data (via the enhanced structure, like custom attributes and relationships, and advanced workflows)Example: A checkout process may involve collaboration with more than one party, e.g. a legal and financial department review, and may require status confirmation from an external system, for example, customer ERP service with any approvals or details on behalf of the customer.

Synchronize data with an external systemExamples:

Orders created via Oro application should be synchronized into an external system for shipping processing, and a shipping tracking number should be reported back to Oro application.

Import and export via CSV files may be adjusted or enabled for the existing Oro features.

Information from external systems may be used for adjusting to the existing pricing policies and strategies.

Substitute features of the Oro application with similar operations that are already fulfilled by the third party systemsExample: A company may replace customer registration in Oro application with the integrated service they already use (using embedded forms or via data synchronization)

Enhance or adjust existing features to support custom processesExamples:

Quotes may be modified to act as temporary orders that sales representatives create on behalf of the customers.

Installing an extension from the Oro marketplace is the least resource-consuming way to expand the existing functionality of the Oro application.

Oro application’s marketplace is a catalog service for sharing packages that extend a particular Oro application. On the marketplace, Oro and third-party vendors may publish free or chargeable custom packages to distribute commonly-used extension solutions to the Oro community.

To install an extension, use the package manager CLI (oro:package:install command) or the composer CLI (composer require <extension-name>:<version> command). For detailed information, please, see the How To Install Extensions from the Marketplace topic.

In addition to existing extensions, you can create your own customization of the Oro application source code and either use it internally or publish it to the Oro marketplace, if necessary.

Warning

Customization may apply to the application only and should be created in a custom bundle in the src folder of your Oro application. Do not customize packages, Oro and Symfony bundles, and components to avoid difficulties when upgrading the customized system.

Before you begin customizing you Oro application, follow the guidance provided in the Custom Application topic to set up your custom application repository for version control, and install Oro application from your custom repository.

Running the application in development mode (via the http://<oro-application-base-url>/app_dev.php/ link) helps you debug and test your customization steps.

Use the src directory in the root of your Oro application as a working directory for your custom project.

Create a new bundle to put all your custom code and updated configuration files. To customize your Oro application source code and adjust your Oro application behavior, use the methods described in the sections below.

Note

Methods originating from the Symfony framework are marked with the [Symfony] prefix, while Oro-specific methods are labeled with the [Oro] prefix. Oro-specific methods significantly speed up the development process, like the dynamic modification of the content created at the vendors level and quick definition of the new workflows, configuration options, navigation sets. Generic PHP enabled methods are marked with [PHP] prefix.

This immediately enforces the customization changes defined in the bundle to apply to your Oro application.
However, next, you may need to implement custom changes in the existing business logics to benefit from the enabled capabilities.

Use Symfony inheritance (e.g. override controllers, templates, routes of this parent bundle) to customize the existing Oro application bundle. For detailed information, please, see the How to extend existing bundle topic in Oro documentation and How to use compiler passes in Symfony documentation.

Note

Inheritance techniques are easier to implement and maintain than the compiler pass approach.

With the dependency injection tags, you can register a service of specific a type (for example data provider for the layout, custom action for the workflow system, etc.) in the dependency injection container.
To do so, tag your service with a specified dependency injection tag to make it a part of Oro application.

For example, to add a new payment method in your OroCommerce application, first create your own implementation of the PaymentMethodProviderInterface and tag it with the existing oro_payment.payment_method_provider tag, like in the following example:

Use event listeners to interfere with the existing data processing flow and customize it. You can also design new business logics for processing the events. For example, to log a number of web-browsers that are connected to the application server through the websockets (WS) protocol, create your own listener of the clank.client.connected event:

Many items in the Oro application features, like workflows, navigation trees, datagrids, dashboard widgets, are defined in the YAML configuration files. You can easily adjust existing and add new items by modifying these files. For example, to add new sections in the System Configuration UI, modify the Resources/config/oro/system_configuration.yml file in your custom bundle to add new configuration option.

Once added, the option may be displayed in the UI or may affect the Oro application behavior. You may need to implement new or customize existing features to use the new configuration option.

In the Oro application, you can use a new Twig template {placeholder} token/tag that triggers an event-like behavior when the template is rendered. For example, you can add a new markup to the existing template that is generated at the vendor level and keep other parts of the template intact. Please, see the Introduction to Placeholders topic for more details.

Use the Oro data migration mechanism to fine-tune the database schema and load initial data to the Oro application. The mechanism that is enabled in the Oro MigrationBundle uses specific PHP files and classes (migrations and fixtures) that help you to fulfill:

Multi-step data schema modification: Add a sequential and incremental changes to database in the predefined order, if they depend on the preceding migration completion. Sequential changes could have happened on the different stages of the development. Sample sequential changes are:

Add a new user table with id and name columns (initial implementation).

Add an email column to the user table (change was implemented on the later stage to cover missing data for the integration).

Rename the email column to user email (the column name was lined up with the integrated system).

Multi-step data modification: Adjust the data in the database via fixtures that may depend on other fixtures and be processed after them.

Deployment: Migration of the database-level changes (database schema and data) from the development and staging environments to the production environment.

For data model and business processes customization, Oro applications provide the entity and workflow management tools in the web UI (e.g. OroCRM and OroCommerce management console). These tools may be used for quick updates of the existing data structure, for example, add a new field to the existing entity data, change the value options, etc.) and enable easy and fast prototyping, for example, for A/B testing of new business processes automation.

Warning

Results of the customization via UI is stored in the database. Porting such customization from staging to the production environment happens on the database level using data migration. Compared to programmatic customization, customization via UI lacks the versioning and portability. Please, consider using the customization on the source code level to keep the upgrade process simple.

In the System > Entity Management, you can create a data model for a new business entity (e.g. add information about the purchase orders and link them to the B2B orders in OroCommerce), and start using it right away after quick field and relationships configuration. See Entities Management for detailed information.

In the System > Workflows, you can automate a workflow to reflect a custom business process in your organization. See Workflows for detailed information.