orocrm partner technical training: september 2015

Developer Training 1

Developer Training Program

OroCRM

September 2015

Developer Training

Day 1


Getting Started


Environment- Web Server (Apache or Nginx)- PHP 5.4.9+

- memory_limit = 512M- max_execution_time = 120- extensions:

GD 2.0+, intl, Mcrypt, PCRE 8.0+

- Composer- MySQL 5.1+ or PostgreSQL 9.1+- Node.JS (recommended)


Technology

- Symfony 2 Framework- Doctrine ORM- BackboneJS+Chaplin, RequireJS (AMD) and

JQuery


IDE SettingsPHPStorm

- Symfony 2 plugin- PHP Annotations plugin- XDebug- PHPMD, PHPCS- PHPUnit


Empty Project- Symfony 2 Standard Application

- app: configuration, logs, cache- src: project source bundles- vendor: 3rd party code- web: public resources


Packages

- Package manager: - UI- Command Line:

- oro:package:install- oro:package:update

- Package repositories: - platform: https://github.com/orocrm/platform- crm: https://github.com/orocrm/crm

- Marketplace:- http://marketplace.orocrm.com

https://github.com/orocrm/platform

https://github.com/orocrm/crm


Package Structure

Composer.json

● Name, Description, Homepage● Autoload● Repository● Dependencies


Introduction to OroCRMPartnerBundle

https://github.com/orocrm/training-crm-application


Entities

Developer Training

Overview

Entity types:● Doctrine entities● Configurable entities● Extended entities● Custom entities

Bundles responsibilities:● OroEntityConfigBundle – entity configuration● OroEntityExtendBundle – extended and custom entities● OroEntityBundle – UI for entities management

Entities

Developer Training

What is Doctrine entity?Entities are PHP Objects that can be identified over many requests by a unique identifier or primary key. These classes don’t need to extend any abstract base class or interface. An entity class must not be final or contain final methods. Additionally it must not implement clone nor wakeup or do so safely.An entity contains persistable properties. A persistable property is an instance variable of the entity that is saved into and retrieved from the database by Doctrine’s data mapping capabilities.

Doctrine 2 ORM Documentationhttp://doctrine-orm.readthedocs.org/en/latest/tutorials/getting-started.html

Entities

http://doctrine-orm.readthedocs.org/en/latest/tutorials/getting-started.html

http://doctrine-orm.readthedocs.org/en/latest/tutorials/getting-started.html

Developer Training

Example of Doctrine's entity

● class: OroCRM\Bundle\PartnerBundle\Entity\Partner● DB table: orocrm_partner

Entities

Developer Training

Configurable Entity

• configuration is stored in the database

• two levels of configuration fields: entity and entity field

• different scopes

• configuration file: Resources/config/entity_config.yml

• access configuration fields via services

• change entity configuration in the UI

Entities

Developer Training

Example of using Entity Configuration

OroDataAuditBundle is responsible for audition of entity’s changes. It introduces configuration scope and field with name “auditable”.

When data of entity is modified this bundle checks the value of configuration field and if it's “true”, then it adds respective record to audition log.

Thus any bundle could use Entity Configuration to build it's own business logic.

Configurable Entity

Developer Training

Define configuration schema

• Each bundle can contain file with configuration schema:Resoures/config/entity_config.yml

• contains definitions of config fields on level of entity and field, options used in UI to display these config fields

• Example of configuration schema: Oro/Bundle/DataAuditBundle/Resources/config/entity_config.yml

Configurable Entity

Developer Training

Add entity annotations

• annotation classes: Oro\Bundle\EntityConfigBundle\Metadata\Annotation\ConfigOro\Bundle\EntityConfigBundle\Metadata\Annotation\ConfigField

• example of @Config and @ConfigField annotations in OroCRMPartnerBundle:Partner entity

Configurable Entity

Developer Training

UI management

• System → Entities → Entity Management

• configurable fields are displayed on different pages, depending on configuration schema: grid, view, form

Configurable Entity

Developer Training

Main Commands

• oro:entity-config:cache:clearThis command removes all data related to configurable entities from the application cache.

• oro:entity-config:updateThis command can be used to update configurable entities. Usually you need to execute this command only in “dev” mode when new configuration attribute or whole configuration scope is added.

• oro:entity-config:debugDebugging entity configuration.

Configurable Entity

Developer Training

Extended Entity

• useful for customization of entity if you not own it’s code

• add mapped Doctrine fields to entity without updating code of entity

• add/remove fields dynamically using UI

• show added fields on view, form, grid

• support scalar fields and relations to other entities

Entities

Developer Training

Creating Extended Entity• Extend entity from class with special name• Run command oro:migration:load

This command will do all necessary updates of schema and generate Extend entity caches.

• (Optional) Add new fields using migrations

Important• this class should be empty, it will be replaced dynamically with class

generated in cache: app/cache/%env%/oro_entities/Extend/Entity• don’t forget to call parent::__construct

Extended Entity

Developer Training

Adding Fields to Extended Entity

• using migrationspreferable in case of customization development

• using UIpreferable as a quick way if client code won’t rely on presence of this field

Extended Entity

Developer Training

UI management• System → Entities → Entity Management

• Configurable fields are displayed on different pages, depending on configuration schema: grid, view, form

Important• It's not recommended to build business logic that relies on fields that were

added to entities from the UI, because there are no guarantees that they won't be removed.

Extended Entity

Developer Training

Custom Entity

• create entity using UI or migrations

• manage fields of custom entities

• manage entity configuration

• auto-generated CRUD for custom entity records

Entities

Developer Training

Q & A

Entities

Developer Training

Database Schema Migrations

Migrations and Fixtures

Developer Training

Overview

Database Schema Migrations functionality is intended to help manage changes of database schema.

Goals• control state of application's database schema• allow database schema upgrades via schema

migrations


Developer Training

Migration Class• Each migration represents incremental change of database scheme• Must implement Oro\Bundle\MigrationBundle\Migration\Migration• Must be located in %BundleDirectory%/Migrations/Schema/version_number• Version number must be an PHP-standardized version number string

without "." and "+" characters as a version parts separator• Method up method receives:

• schema – current database structure. With schema parameter, you can create or update database structure without fear of compatibility between database engines.

• queries bag – use it if you want to execute additional SQL queries before or after applying a schema modification. A query can be a string or an instance of a class implements MigrationQuery interface.


Developer Training

Migrations Persistence

• Executed migration saved in database table oro_migrations

• This record is represented by entity Oro\Bundle\MigrationBundle\Entity\DataMigration


Developer Training

Installation Class• Must implement Oro\Bundle\MigrationBundle\Migration\Installation

• getMigrationVersion method must return max migration version number that this installation file replaces

• Replaces running multiple migration files


Developer Training

Load Migrations Commandoro:migration:load

This command collects migration files from bundles, sorts them by version number and applies changes.

Parameters

• force – causes the generated by migrations SQL statements to be physically executed against your database;

• dry-run – outputs list of migrations without apply them;• show-queries – outputs list of database queries for each migration file;• bundles – a list of bundles to load data from. If option is not set, migrations

will be taken from all bundles;• exclude – a list of bundle names which migrations should be skipped.


Developer Training

Dump Migrations Commandoro:migration:dump

• outputs current database structure in format of plain SQL queries• outputs generated PHP class of migration

Generated PHP code could be used to write migration classes during development:1. Create your bundle and all entities with proper Doctrine's mapping2. Run command doctrine:schema:update --force to apply schema changes3. Run command oro:migration:dump > dump.php to generate PHP code of

migrations4. Browse generated file and copy all migrations code related to your entities

into proper migration class.


Developer Training

Extensions for MigrationsExtension encapsulates some part of migration logic that can be reused in migrations of other bundles.

Examples:

Oro\Bundle\MigrationBundle\Migration\Extension\RenameExtensionhelps to rename existing tables without loss of data

Oro\Bundle\EntityExtendBundle\Migration\Extension\ExtendExtensionadds extended relation field, custom entities, enums

Oro\Bundle\ActivityBundle\Migration\Extension\ActivityExtensionadds association of entity with one of activity's entity


Developer Training

Create Migration Extension• Create extension class in YourBundle/Migration/Extension directory

• Create interface %YourExtensionName%ExtensionAwareInterface

• Register an extension in container with tag oro_migration.extension

• Now you can add set%YourExtensionName%Extension method to migration class and instance of extension will be injected


Developer Training

Data Fixtures

Developer Training

OverviewData Fixtures is a way to programmatically create entities and other data during installation and upgrade process. This functionality is based on Doctrine's fixtures and guarantees that each data fixture will be loaded only once.

Data Fixtures

Developer Training

Fixtures TypesMainDelivered with bundle by default. For example, entities of predefined roles of Administrator, Manager and User.

DemoCan be loaded optionally to create bundle's entities intended to demonstrate its features.

Data Fixtures

Developer Training

Fixture Class• Must implement Doctrine\Common\DataFixtures\FixtureInterface• Optionally can implement

Doctrine\Common\DataFixtures\DependentFixtureInterface to load dependent fixtures first

• Main fixtures must be placed in directory Migrations/Data/ORM• Demo fixtures must be placed in directory Migrations/Data/Demo/ORM

Data Fixtures

Developer Training

Load Fixtures Commandoro:migration:data:loadThis command guarantees that each data fixture will be loaded only once.

Parameters

• fixtures-type – select fixtures type to be loaded (main or demo). By default - main

• dry-run – outputs list of fixtures without apply them• bundles – a list of bundle names to load data from (multiple values

allowed) • exclude – a list of bundle names which fixtures should be skipped

(multiple values allowed)

Data Fixtures

Developer Training

Data Fixture State Persistence• Executed migration saved in database record in table oro_migrations_data

• This record is represented by entity Oro\Bundle\MigrationBundle\Entity\DataFixture

Data Fixtures

Developer Training

Fixture With Version• Implement Oro\Bundle\MigrationBundle\Fixture\VersionedFixtureInterface

• getVersion method must returns a version of fixture data

• To load this fixture again, return a greater version

• Optionally implement Oro\Bundle\MigrationBundle\Fixture\LoadedFixtureVersionAwareInterface to know the last loaded version

• Example of fixture with version OroCRM\Bundle\MagentoBundle\Migrations\Data\ORM\LoadShoppingCartStatusData

Data Fixtures

Developer Training

Q & A



Search- MySQL Fulltext as default engine- Mapping configuration: Resources/config/search.yml- Commands

- oro:search:index- oro:search:reindex

- API

http://www.orocrm.com/documentation/index/current/book/searchhttps://github.com/orocrm/platform/tree/master/src/Oro/Bundle/SearchBundle

http://www.orocrm.com/documentation/index/current/book/search

http://www.orocrm.com/documentation/index/current/book/search

https://github.com/orocrm/platform/tree/master/src/Oro/Bundle/SearchBundle

https://github.com/orocrm/platform/tree/master/src/Oro/Bundle/SearchBundle


Data AuditDataAuditBundle- Based on Loggable Doctrine extension- Annotation and Entity Config support

@Config( defaultValues={ "dataaudit"={ "auditable"=true } } )

- Access to data changes log

Developer Training

Datagrids

Developer Training

Overview

Datagrid is table oriented representation of some data from some datasource. It's configuration is declarative YAML based file, that should be placed in Resources/config folder of your bundle and named datagrid.yml.

Datagrids

Developer Training

Datasource

• Type• Query• Parameters binding

http://www.orocrm.com/documentation/index/current/cookbook/how-to-pass-request-parameter-to-grid

Datagrids

Developer Training

• Columns• Sorters• Filters• Properties• Actions• Mass Actions

https://github.com/orocrm/platform/blob/master/src/Oro/Bundle/DataGridBundle/Resources/doc/backend/datagrid.md

ConfigurationDatagrids

Developer Training

Extensions

• Formatter - responsible for backend field formatting (e.g generating url using router, translate using symfony translator, etc..)

• Pager - responsible for pagination• Sorter - responsible for sorting• Action - provides actions configurations for grid• Mass Action - provides mass actions configurations for grid• Toolbar - provides toolbar configuration for view• Grid Views - provides configuration for grid views toolbar• Export - responsible for export grid data

Datagrids

Developer Training

Extending Grids

Grids could be extended in few ways:

• create custom datasource if needed (e.g. already implemented SearchDatasource for working with search engine)

• create custom extension• create some addons to already registered extensions (e.g. some

specific backend formatter)• change base datagrid or base acceptor class (they are passed to

builder as DI parameters)• add listener for datagrid events

Datagrids

Developer Training

Datagrid Events

• oro_datagrid.datagrid.build.pre

• oro_datagrid.datagrid.build.before(.my-grid)

- validage datagrid config and apply necessary config changes

• oro_datagrid.datagrid.build.after(.my-grid)

- add filters or query parameters to the grid datasource

• oro_datagrid.orm_datasource.result.before(.my-grid)- make changes to the data source right before the data is retrieved, e.

g. add ACL restrictions to the query

• oro_datagrid.orm_datasource.result.after(.my-grid)- make changes to already fetched result data

Datagrids

Developer Training

Render Grids

• Import OroUIBundle::macros:html.twig

• Use Twig function renderGrid

Datagrids

Developer Training

Q & A

Datagrids

Developer Training

CRUD

Developer Training

Overview

• Create entity• Update entity• View entity details• Delete entity

CRUD

Developer Training

Controller

• Controller: DemoBundle/Controller/MyNewController.php

• Routing configuration in oro/routing.yml

• Action methods

• @Route and @Template annotations

CRUD

Developer Training

Form and Form Handler

Form- Holds controls for every Entity field- Form Types for complex fields- Sets default values

Form Handler- Validates Form- Submits Form- Saves Form Data

CRUD

Developer Training

Templates

By default templates are looked up in Resources/views/DemoEntity/

Automatically mapped to controller actions:• view.html - View action• update.html - Create and Update actions

You can specify custom templates in Controller @Template annotation

CRUD

Developer Training

References

- http://www.orocrm.com/documentation/index/current/book/entities - http://www.orocrm.com/documentation/index/current/book/crud

CRUD

http://www.orocrm.com/documentation/index/current/book/entities

http://www.orocrm.com/documentation/index/current/book/entities

http://www.orocrm.com/documentation/index/current/book/crud

http://www.orocrm.com/documentation/index/current/book/crud

Developer Training

Q & A

Day 1

Developer Training

Day 2

Developer Training

API


Web API- Integration with application data- Frontend flexibility- Multiple versions support- Security

- API Token- oro:wsse:generate-header

https://github.com/orocrm/platform/tree/master/src/Oro/Bundle/SoapBundle

Web API





REST

- FosRestBundle- Routing- Versioning- Documentation and Sandbox

- NelmioApiDoc Bundle- @ApiDoc annotation

Web API


Sample CRUDController

• @RouteResource annotation• @NamePrefix annotation

Actions:● Get List: cgetAction● Get Entity: getAction● Create: postAction● Update: putAction● Delete: deleteAction

Routes:● oro/routing.yml and oro/routing_api.yml● automatic route generation for entities

Web API


REST: Additional Info

Headers- Request:

X-Include: totalCount, lastModifiedDate

- Response:X-Include-Total-Count: 200X-Include-Unknown: lastModifiedDate

Handler- extend

Oro\Bundle\SoapBundle\Request\Handler\IncludeHandlerInterface- oro_soap.include_handler tag


Web API





SOAP

- BeSimple SoapBundle- WSDL generation- Types- Controllers and Actions

http://besim.pl/SoapBundle

Web API

http://besim.pl/SoapBundle/

http://besim.pl/SoapBundle/

Developer Training

Security & ACL


- ACL stands for Access Control List- responsible bundle is OroSecurityBundle- provides user access only to appropriate levels of

information that is required- categorizes users by their roles and restricts access

based on those roles- prevents user access to records the user does not

allowed to access- based on Symfony standard security model- all benefits of Symfony ACL security are supported

ACL OverviewSecurity & ACL


Example of restricting access to domain objects- consider some domain object, e.g. a comment of blog- user able to edit their own comments- administrators able to edit all comments

Possible Approaches- enforce security in your business methods: keeping a reference inside

each comment to all users who have access, compare these users to provided token

- enforce security with roles: you would add a role for each Comment object, i.e. ROLE_COMMENT_1, ROLE_COMMENT_2, etc.

Problems- couple authorization logic to business code which makes it less

reusable- increase the difficulty of unit testing- performance issue if many users will have access to a single domain

object

Introduction to ACLSecurity & ACL


Solution- enforce security with ACL approach

Example of using Symfony ACL, reference to documentationhttp://symfony.com/doc/current/components/security/introduction.html- http://symfony.com/doc/current/cookbook/security/acl.html- http://symfony.com/doc/current/cookbook/security/acl_advanced.html

Introduction to ACLSecurity & ACL

http://symfony.com/doc/current/cookbook/security/acl.html

http://symfony.com/doc/current/cookbook/security/acl.html


The security bundle comes with the following five access levels:- User

own records- Business Unit

records in records in all business units user is assigned to.- Division

same as the Business Unit level plus subordinate Business Unit - Organization

all records within the organization- System

The user can access all objects within the system

Access LevelsSecurity & ACL


Permissions- VIEW

Controls whether a user is allowed to view a record.- CREATE

Controls whether a user is allowed to create a record.- EDIT

Controls whether a user is allowed to modify a record.- DELETE

Controls whether a user is allowed to delete a record.- ASSIGN

Controls whether a user is allowed to change an owner of a record. For example assign a record to another user.

Security & ACL


Configuring entity ACL- use entity configuration with “security” scope- set the list of supported permissions using

“permissions” parameter: - "All" to consider all available security permissions- “VIEW;EDIT” to consider only specified permissions

Security & ACL


Protecting ResourcesDefining ACL Resources

- Annotations:- @Acl- @AclAncestor

- Configuration file: Resources/config/oro/acl.ymlRestricting Access to Controller Methods

- @Acl annotations with/without parameter converter- bindings

Protecting Custom DQL Queries- oro_security.acl_helper->apply

Manual Access Checks- oro_security.security_facade->isGranted- Twig function resource_granted

Security & ACL


Ownership- Entity configuration: ownership scope

- Types- ORGANIZATION

Oro\Bundle\OrganizationBundle\Entity\Organization- BUSINESS_UNIT

Oro\Bundle\OrganizationBundle\Entity\BusinessUnit- USER

Oro\Bundle\UserBundle\Entity\User

Security & ACL


User Ownership Type ExampleSecurity & ACL


Permissions Management UISystem → User Management → Roles- manage roles- manage entity privileges of role

System → User Management → Users- assign roles to users- assign users to business units and organizations

Security & ACL

Developer Training

References

- http://www.orocrm.com/documentation/index/current/book/security

- https://github.com/orocrm/platform/tree/master/src/Oro/Bundle/SecurityBundle

Security & ACL

http://www.orocrm.com/documentation/index/current/book/security



https://github.com/orocrm/platform/tree/master/src/Oro/Bundle/SecurityBundle




Developer Training

Activities

Developer Training

Overview

• Special entities representing customer-related activities such as phone calls, emails, tasks, etc.)

• Can be associated to other entities from the UI• Associations can be enabled in the Entity Management

section• Add activity button• Activity Lists

Activities

Developer Training

Emails

• Templates• Notification rules• Messages and Threads

Activities

Developer Training

Attachments

• Configuration- System- Storage: Filesystem abstraction layer

• ACL protection• Migration extension• Image Formatters

Activities

Developer Training

Calendars

• Calendar Types:- My Calendar- User Calendars- System Calendars

• Calendar Events

Activities

Developer Training

Notes and Comments

• Enabling Notes for an Entity- From the UI- By Migrations

• Enable Comments for an Activity- From the UI- By Migrations

Activities

Developer Training

New Activity

Create Entity- Extended Entity- Implement Oro\Bundle\ActivityBundle\Model\ActivityInterface

- Activity Group /** * @Config( * defaultValues={ * "grouping"={"groups"={"activity"}} * } * ) */

- Activity Entity Configuration (@Config annotation)

Activities

Developer Training

New Activity

Enable Activity Associations• Migration:

use Oro\Bundle\ActivityBundle\Migration\Extension\ActivityExtension

• Change associations in the UI

Activities

Developer Training

New Activity

Configure UI• Activity List

- Controller action- TWIG Template- Datagrid definition- Entity configuration- Activity List provider

• Activity Button- Button and Link templates- Placeholders- Entity configuration

Activities

Developer Training

References

- https://github.com/orocrm/platform/tree/master/src/Oro/Bundle/ActivityBundle

Activities

https://github.com/orocrm/platform/tree/master/src/Oro/Bundle/ActivityBundle




Developer Training

System Configuration


System Configuration● Multiple Scopes

- Global- User

● Flexible configuration form: Resources/config/system_configuration.yml

Developer Training

Q & A

Day 2

Developer Training

Day 3


User Interface


Contents

• Layout• Widgets• CSS & LESS• Themes• Placeholders• Forms• JavaScript

UI customizations

Developer Training

Introduction• Twig overview• OroUIBundle overview• basic templates• create and use templates• override existing templates

LayoutUI customizations / Layout

Developer Training

Features• available in Symfony 2 out of the box• easy to learn: optimized for web designers• has template oriented syntax: shortcuts for common patterns• fast: compiles templates to plain optimized PHP code• supports: multiple inheritance, blocks, automatic output-escaping, and much

more• extensible: add custom tags, filters, functions, operators, nodes and tags

References• http://twig.sensiolabs.org/documentation• http://symfony.com/doc/current/book/templating.html

Twig Template EngineUI customizations / Layout

http://twig.sensiolabs.org/documentation

http://twig.sensiolabs.org/documentation

http://symfony.com/doc/current/book/templating.html

http://symfony.com/doc/current/book/templating.html

Developer Training

Structure Of Page LayoutUI customizations / Layout

Developer Training

Based on Bootstrap v2.3.0

<div class="responsive-section">

<div class="responsive-cell">

<div class="responsive-block">



</div>




</div>

</div>

<div class="responsive-cell">




</div>




</div>

</div>

</div>

HTML markupUI customizations / Layout


- basic Twig templates- set of reusable macroses- additional Twig functions, filters, nodes- CSS, LESS, JS- external libraries: jQuery plugins, Bootstrap, Font

Awesome, Backbone.js, Underscore.js

https://github.com/orocrm/platform/tree/master/src/Oro/Bundle/UIBundle

UI customizations / Layout

OroUIBundle

Developer Training

Basic TemplatesUI customizations / Layout


Reusable MacrosesOroUIBundle::macros.html.twigViews

- attibuteRow, renderAttribute, renderProperty, renderHtmlProperty, renderSwitchableHtmlProperty, renderColorProperty

Links and buttons- button, addButton, editButton, deleteButton, cancelButton, clientButton, buttonType, buttonSeparator,

saveAndCloseButton- link, clientLink, deleteLink, entityOwnerLink- dropdownClientItem, dropdownButton, dropdownItem, dropdownSaveButton, pinnedDropdownButton

Layout- scrollSubblock, scrollBlock, scrollData, renderPageComponentAttributes, renderWidgetAttributes,

renderWidgetDataAttributes, renderAttributes, attributesOther

- renderPhone, renderList, renderUrl, getApplicableForUnderscore, collectionField, collection_prototype, tooltip

Referenceshttp://twig.sensiolabs.org/doc/tags/macro.html, http://symfony.com/doc/current/cookbook/form/form_customization.html


http://twig.sensiolabs.org/doc/tags/macro.html

http://symfony.com/doc/current/cookbook/form/form_customization.html




Create And Use Templates- create controller and pass data to view- create template with name by pattern

bundle:controller:action- extend one of basic templates of Oro- override content block and/or other blocks- (optional) pass data to parent template- (optional) use widgets to separate content by

different blocks- (optional) support extend fields in view and form

templates



Override Existing TemplateSteps- extend bundle or use app/Resources/views- add template with same name- extend template from parent- override block and add customization- (optional) override controller to pass extra data to

template

Alternative- use placeholders


Developer Training

Q & A



- a reusable UI element that is placed inside the widget container

- widget content may be loaded immediately or via AJAX request

- most of widgets reference to controller actions- content can be refreshed- examples of widgets: contact information, opportunity

information, address book, add address form, import form, etc.

https://github.com/orocrm/platform/blob/master/src/Oro/Bundle/UIBundle/Resources/doc/reference/widgets.md

UI customizations

Widgets






● dialog – show widget content in dialog window● button – show only included content without title and

actions● block – display embedded widget content on page

On frontend Widget containers are Backbone views.

UI customizations / Widgets

Widget Container Types


● widget can be created from backend (in Twig templates) or front-end (JS modules)

● Twig function oro_widget_render

● widgetType – widget type name

● url – URL used to load remote content

● elementFirst – flag to render widget without AJAX request using initial

content

● title – widget title

● alias – widget alias

● wid – unique widget identifier (generated)


Rendering Widget


● extend @Template annotation behavior, try to match Twig templates in next sequence:

- {bundleName}:{controllerName}:{widgetType}/{actionName}.html.twig

- {bundleName}:{controllerName}:widget/{actionName}.html.twig

- {bundleName}:{controllerName}:{actionName}.html.twig

● inside Twig template of widget content should be placed inside element with class “widget-content”, actions could be placed inside “widget-actions” element


Widget Template

Developer Training

• JS modules• oroui/js/widget/abstract• oro/block-widget• oro/buttons-widget• oro/dialog-widget• oroui/js/widget-manager

• widget manager adds ability of widget-to-widget, widget-to-page and page-to-widget interaction based on Backbone events and direct usage of widgets API

• each widget on page has its own unique widget identifier, also a widget can be retrieved by its alias


Widget Client Side

Developer Training

Q & A



● dashboard is an entity with user owner● permissions are managed using ACL● user can have one active dashboard● dashboard view page contains a set of blocks (widgets)● dashboard widgets are also entities● developer can add new widgets and dashboards

UI customizations

Dashboards


Dashboards Configuration

● Resources/config/dashboard.yml

● entities hold states of the specific dashboard and dashboard widgets

● configuration holds static information used to render dashboards and dashboard widgets

UI

Developer Training

Available Dashboard Widgets• quick_launchpad• campaigns_leads• campaigns_opportunity• campaigns_by_close_revenue• my_sales_flow_b2c_chart• my_accounts_activity• my_contacts_activity• my_calendar• recent_calls• recent_emails• opportunities_by_lead_source_chart

UI customizations

Developer Training

Add Dashboard Widget Type

• add controller action• add template extending OroDashboardBundle:Dashboard:

widget.html.twig• update dashboard.yml• optionally write migration and add widget to admin

dashboard• https://github.

com/orocrm/platform/blob/master/src/Oro/Bundle/DashboardBundle/README.md

UI customizations

https://github.com/orocrm/platform/blob/master/src/Oro/Bundle/DashboardBundle/README.md




Developer Training

Dashboard Chart Widgets

• OroChartBundle / flotr2• OroCRMProFusionChartsBundle / fusion• bar, flow, line, pie• chart view builder• data mapping• chart view

UI customizations

Developer Training

Q & A

UI customizations / Dashboards

Developer Training

Asset Management- http://symfony.

com/doc/current/cookbook/assetic/asset_management.html

- collecting CSS & LESS using config- using Resources/config/assets.yml

Commands- assets:install- assetic:dump

DebugMinification

UI customizations

CSS & LESS

http://symfony.com/doc/current/cookbook/assetic/asset_management.html




Developer Training

• change fonts, colors, favicon and application logo• CSS/LESS files that will be included at the end• active theme app/config/config.yml

oro_theme: active_theme: oro

• theme config Resources/public/themes/{theme_name}/settings.yml

• oro:theme:list• debugging theme CSS & LESS

UI customizations

Themes

Developer Training

Q & A

UI customizations / CSS & LESS / Themes

Developer Training

• a point in UI template that can be extended dynamically by any bundle

• a mechanism to customize UI without modifying Twig templates

• comparable with “hooks” or “events” but in context of layout rendering

UI customizations

Placeholders

Developer Training

• configuration in Resources/config/placeholders.yml• items are subscribed to placeholders in configuration• item options:

• template• action• data• applicable• acl• order

• item configuration can contain expressions, they will be resolved in a runtime

UI customizations / Placeholders

Placeholders Configuration

Developer Training

• Twig token or Twig function{% placeholder <placeholder_name> %}

• parameters can be passed{% placeholder <placeholder_name> with {'form' : form} %}

• items will be ordered and rendered and this content will be outputted in place where placeholder that was specified in Twig template

• parameters will be available in items as Twig template variables


Placeholder in Twig Template

Developer Training

Q & A


Developer Training

• Standard Symfony forms- http://symfony.com/doc/current/book/forms.html

• OroFormBundle provides additional form types and templates, e.g.:

- oro_collection- oro_jqueryselect2_hidden, oro_entity_identifier

oro_multiple_entity, oro_entity_create_or_select,- oro_date, oro_datetime, oro_money, oro_percent, oro_timeinterval- oro_encoded_password, oro_icon_select

• Adding form templates in Resources/config/oro/twig.yml

UI customizations

Forms

http://symfony.com/doc/current/book/forms.html

http://symfony.com/doc/current/book/forms.html

Developer Training

• Symfony validation- http://symfony.com/doc/current/book/validation.html

• Constraints• Validators• Validation configuration: validation.yml

UI customizations / Forms

Validation

http://symfony.com/doc/current/book/validation.html

http://symfony.com/doc/current/book/validation.html

Developer Training

• JS validation- https://github.

com/orocrm/platform/blob/master/src/Oro/Bundle/FormBundle/Resources/doc/reference/js_validation.md

• association of server-side validations with client-side validation:

- Count, DateTime, Date, Email, Length, NotBlank, NotNull, Number, Range, RegEx, Repeated, Url

• Loading custom validation rules• Validation for optional group


Client Side Validation

https://github.com/orocrm/platform/blob/master/src/Oro/Bundle/FormBundle/Resources/doc/reference/js_validation.md




Developer Training

Q & A


Developer Training

JavaScript


JavaScript- AMD and RequireJS- MVC and Backbone

UI / Javascript

Developer Training

AMD and RequireJS• Asynchronous module definition (AMD):

• define, require

• RequireJS config generation: • shim, map, paths

• RequireJS build configuration• Customization of RequireJS config in runtime

JavaScript

Developer Training

Client Side Architecture• built over Chaplin (architecture based on the Backbone.

js)• models, views, routes, controllers, modules• application initialization• application config

JavaScript

Developer Training

MVC and Backbonebackbone models, views and controllers

- src\Oro\Bundle\SidebarBundle\Resources\public\js\model.js

- src\Oro\Bundle\SidebarBundle\Resources\public\js\view.js

JavaScript

Developer Training

Navigation


Overview

- OroNavigationBundle- based on KnpMenuBundle- provides navigation menus data- can be configured in navigation.yml

http://www.orocrm.com/documentation/index/current/cookbook/how-to-create-and-customize-application-menu https://github.com/orocrm/platform/blob/master/src/Oro/Bundle/NavigationBundle/README.md

Navigation

http://www.orocrm.com/documentation/index/current/cookbook/how-to-create-and-customize-application-menu




https://github.com/orocrm/platform/blob/master/src/Oro/Bundle/NavigationBundle/README.md





Built-in Menus

- application_menu- usermenu- shortcuts- dots_menu

- pinbar- history- favorite- mostviewed

Navigation


Customizing Menus

● configured in Resources/config/navigation.yml

● configuration will be collected from all bundles

● override menu items

● change menu structure using merge strategy:append (default)

Node will be appended. If same node already present in tree it will be not changed.

replaceAll nodes with same name will be removed and replaced in tree with current node definition

moveAll nodes with same name will be removed and replaced in tree. Node children will be merged with found node children.

Navigation


Navigation Titles

- manage page titles- support of annotations in controller actions- support of configuration files using route names- configuration can be used to override title

annotations- to apply titles changes execute command oro:

navigation:init

Navigation

Developer Training

Localization


Localization- Numbers, dates and time formating (intl and

icu libs)- Name and postal address formating- Dictionaries for currencies, phone prefixes and

default locales- Locale settings: locale, language, location,

timezone, currency- PHP and JS tools

Localization


Localization● System Configuration → Localization● PHP: Oro\Bundle\LocaleBundle\Model\LocaleSettings (oro_locale.settings)

● locale● language● location● calendar● time zone● list of person names formats● list of addresses formats● currency specific data● currency symbols based on currency codes● currency code, phone prefix, default locale based on country

● JS: module orolocale/js/locale-settings

Localization


Person Names● source: Resources/name_format.yml

● %prefix% %first_name% %middle_name% %LAST_NAME% %suffix%

● PHP: Oro\Bundle\LocaleBundle\Formatter\NameFormatter (oro_locale.formatter.name)

● supports interfaces in Oro\Bundle\LocaleBundle\Model: FirstNameInterface, MiddleNameInterface, LastNameInterface, NamePrefixInterface, NameSuffixInterface, FullNameInterface

● Twig filter: oro_format_name

● JS: module orolocale/js/formatter/name

Localization


Addresses● source: Resources/address_format.yml

● %name%\n%organization%\n%street%\n%CITY% %REGION_CODE %COUNTRY_ISO2% %postal_code%

● PHP: Oro\Bundle\LocaleBundle\Formatter\AddressFormatter (oro_locale.formatter.address)

● supports interface Oro\Bundle\LocaleBundle\ModelAddressInterface

● Twig filter: oro_format_address

● JS: module orolocale/js/formatter/address

Localization


Numbers● based on PHP intl extension, uses IntlNumberFormatter

● PHP: Oro\Bundle\LocaleBundle\Formatter\NumberFormatter (oro_locale.formatter.number)

● Twig filter: oro_format_number, oro_format_currency, oro_format_decimal, oro_format_percent, oro_format_spellout, oro_format_duration, oro_format_ordinal

● Twig functions: oro_locale_number_attribute, oro_locale_number_text_attribute, oro_locale_number_symbol

● JS: module orolocale/js/formatter/number, uses numeral.js

● functions in JS module

Localization


Date and DateTime: Formatting● based on PHP intl extension on backend and Moment.js on frontend

● PHP: Oro\Bundle\LocaleBundle\Formatter\DateTimeFormatter (oro_locale.formatter.date_time)

● Uses IntlDateFormatter

● Twig filter: oro_format_date, oro_format_time, oro_format_datetime

● Twig functions: oro_locale_number_attribute, oro_locale_number_text_attribute, oro_locale_number_symbol

● JS: module orolocale/js/formatter/datetime

● functions in JS module

Localization


Dumping Localizationoro:localization:dump

● executed during install/update● localization information from *.yml files dumped to web/js/oro.locale_data.

js (module name oro_locale)● these data can be used in JS to implement localization on frontend

Localization

Developer Training

Translations


Translations

- Symfony Translations as a base- Strings in configuration files- Convention for strings

- <vendor>.<bundle>.[<type>.]<value>- orocrm.contact.form.address_is_required

- Domains: messages, validators, entities, jsmessages, tooltips

Translations


Translation tools

- oro:translation:dump- oro:translation:pack- Crowdin.net

Translations


JavaScript Translations

● jsmessages domain● web/js/translation/[locale].js● orotranslation/js/translator

Translations

Developer Training

Q & A

Day 3

Developer Training

Day 4


Cron JobOroCronBundle- CronCommandInterface

- getDefaultDefinition, “5 * * * *”- oro:cron:* commands for authomatic

execution- add oro:cron to system crontab- Job Queue Daemon

http://www.orocrm.com/documentation/index/current/book/jobs




Batches

- OroBatchBundle based on AkeneoBatchBundle- Processing big sets of data- Flexible architecture

Developer Training

Import & Export

Developer Training

Overview

• Reader• Processor• Writer• Serializer• Strategy• TemplateFixture

http://www.orocrm.com/documentation/index/current/book/importexport https://github.com/orocrm/platform/blob/master/src/Oro/Bundle/ImportExportBundle/Resources/doc/index.md

Import & Export

http://www.orocrm.com/documentation/index/current/book/importexport

http://www.orocrm.com/documentation/index/current/book/importexport

https://github.com/orocrm/platform/blob/master/src/Oro/Bundle/ImportExportBundle/Resources/doc/index.md





Batch Jobs Configuration

Execution of import/export operations is configured in batch_jobs.yml:

- job- type- step

- reader- processor- writer

https://github.com/laboro/platform/blob/master/src/Oro/Bundle/ImportExportBundle/Resources/doc/reference/overview.md

Import & Export





Developer Training

Fields Configuration

@ConfigField annotation• Header• Order• Identity• Excluded• Full

Import & Export

Developer Training

SerializerSerializer is responsible for converting entities to plain/array representation (serialization) and vice-versa (deserialization)

• export Oro\Bundle\ImportExportBundle\Serializer\Normalizer\NormalizerInterface

• import Oro\Bundle\ImportExportBundle\Serializer\Normalizer\DenormalizerInterface

• registered by oro_importexport.normalizer tag

• extends Oro\Bundle\ImportExportBundle\Serializer\Normalizer\ConfigurableEntityNormalizer

Import & Export

Developer Training

Data ConverterData converter is responsible for converting header of import/export file

• basically a map of entity fields: file → entity• extend

Oro\Bundle\ImportExportBundle\Converter\AbstractTableDataConverter

Import & Export

Developer Training

Export ProcessorKnows how to process exported entity using defined data converter and serializer

• extends Oro\Bundle\ImportExportBundle\Processor\ExportProcessor

• should be defined in DI container for every exported entity• data converter and serializer can be injected into processor by

respective setter methods• Controller action OroImportExportBundle:ImportExport:instantExport

(route oro_importexport_export_instant).

Import & Export

Developer Training

Import StrategyStrategy defines the main logic how the entities are being processed. For example import could add new records or it can update only existed ones.

• extends Oro\Bundle\ImportExportBundle\Strategy\Import\AbstractImportStrategy

• for configurable entities: ConfigurableAddOrReplaceStrategy

Import & Export

Developer Training

Fixture ServicesFixtures implementation based on default import/export process

• extends Oro\Bundle\ImportExportBundle\TemplateFixture\TemplateFixtureInterface

• registered by the oro_importexport.template_fixture tag• define data converter• define export processor

Import & Export

Developer Training

Import ProcessorKnows how to process imported entity using defined data converter, serializer and strategy

• extends Oro\Bundle\ImportExportBundle\Processor\ImportProcessor

• should be defined in DI container for every imported entity• strategy, data converter and serializer can be injected into

processor by respective setter methods• import validation processor tag

Import & Export

Developer Training

Adding Import/Export to Grid

• Add buttons to the index.html.twig• Add @ConfigField annotations• importexport.yml• Create a Fixture for import template

Import & Export

Developer Training

Running import

• UI

• oro:import:csv

Import & Export

Developer Training

Import Performance

• disable XDebug• run import in Command Line• run import in Prod Environment• skip import File Validation• disable Optional Listeners• write custom Import Strategy

http://www.orocrm.com/documentation/index/current/cookbook/how-to-accelerate-import

Import & Export




Developer Training

Integrations

Developer Training

Overview

OroIntegrationBundle:- responsible for interaction between third party services and the platform

- provides necessary abstractions for integrations allowing developers to

create integration bundles

- provides basic UI for integration configuration

- extends OroImportExportBundle to process data in the background using

cron and process queue.

Integrations

Developer Training

Integration Foundation

• Integration Channel TypeGrouping of source specific logic that focuses on a specific application or service. For example: Magento channel type, eBay channel type etc.

• Integration ChannelA configured instance of a specific channel type that allows connection to a specific end point, for example specific Magento store or eBay account.

• TransportAn implementation of connection to a third party application that allows work with channel data. For example: SOAP transport, REST transport, direct database connection and much more.

• ConnectorConnector knows how to retrieve data of a specific type from remote instance, using any type of compatible transport for the determined channel. For example: Customer connector, Cart connector.

Integrations


New Integration Channel Type- implement Oro\Bundle\IntegrationBundle\Provider\ChannelInterface

- register in the DI with oro_integration.channel tag using unique type

- optionally implement Oro\Bundle\IntegrationBundle\Provider\IconAwareIntegrationInterface

Channels

Developer Training

Integration Entities

• Use IntegrationEntityTrait

• Configurable entity (@Config annotation)• RemoteId - configurable field (@ConfigField annotation)

Integrations

Developer Training

Transport

Responsibility of transport is communication between connector and channel

• Create entity that will store transport settings- extend Oro\Bundle\IntegrationBundle\Entity\Transport

• Create form to display on channel configuration page• Implement transport type

- implement Oro\Bundle\IntegrationBundle\Provider\TransportInterface

- register in DI container by oro_integration.transport tag:acme.demo_integration.provider.db_transport:

class: %acme.demo_integration.provider.db_transport.class%

tags:

- { name: oro_integration.transport, type: db, channel_type: some_channel}

Integrations

Developer Training

Connectors

Responsibility of connector is retrieving data of specific type from a remote instance

• Create connector class- implement Oro\Bundle\IntegrationBundle\Provider\ConnectorInterface

- register in DI container by oro_integration.connector tag:orocrm_partner.provider.github_issue_connector:

class: %orocrm_partner.provider.issue_connector.class%

tags:

- { name: oro_integration.connector, type: github_issue, channel_type: github }

• Selecting connectors on the UI

Integrations

Developer Training

Utilizing Import/Export FeaturesFor processing imported records the core components of OroImportExportBundle are utilized:

• Data Converter

• Serializer- need to check for the channel type or entity class in

supportsNormalization() and supportsDenormalization() methods

• Strategy- inject logger to show integration process- populate default owner via

Oro\Bundle\IntegrationBundle\ImportExport\Helper\DefaultOwnerHelper

• Import Processor

Integrations

Developer Training

Running integrations

• Cron job*/5 * * * *

• UI- schedule sync- run full re-sync

• oro:cron:integration:sync

Integrations

Developer Training

Reverse SyncFor integration that requires synchronization in both sides there is possibility to declare export process on connector level:

• Converter should implement Oro\Bundle\IntegrationBundle\Provider\TwoWaySyncConnectorInterface

• Export job defined in batch_jobs.yml• Reader: add condition for records required for sync• Writer: push changes to third party system• Run: oro:integration:reverse:sync OR use automated processes

https://github.com/laboro/platform/blob/master/src/Oro/Bundle/IntegrationBundle/Resources/doc/reference/reverse-sync.md

Integrations





Developer Training

Common challenges

• Pass data between jobs/connectors

• Connectors depend on each other

• Performance- increase read batch size- make sure only new records are being pulled- use processes to create related entities

Integrations

Developer Training

Processes

Developer Training

Overview

• provide possibility to automate tasks related to entity management

• use doctrine entity life-cycle events• process can be performed immediately or after some

timeout• use JMS Job bundle to provide possibility of delayed

execution

Processes

Developer Training

How it works

• each of process related to the some entity type • each definition can have several triggers.• user do some action with entity and all appropriate

triggers will run process• if process is delayed a job will be scheduled to run

process• after the specific entity item is deleted all job processes

related to this entity also will be deleted

Processes

Developer Training

Contents

• Definition• Trigger• Job• Commands

Processes

Developer Training

Definition

• persisted via Doctrine OroWorkflowBundle:Process entity in oro_process table

• can be specified in in Resources/config/process.yml• contains:

• related entity type, e.g. user• actions to perform, e.g. change value of some field• execution order, used for immediate (not delayed) processes

subscribed on the same event• enable flag• label• creation date

• updated date

Processes

Developer Training

Trigger

• persisted via Doctrine OroWorkflowBundle:ProcessTrigger entity in oro_process_trigger table

• used to trigger process when specified event is fired• supported events: create, update, delete• entity field name can be specified for update event• execution can be delayed or immediate• if execution is delayed priority can be specified for

process jobs

Processes

Developer Training

Job• persisted via Doctrine OroWorkflowBundle:ProcessJob entity in

oro_process_job table• use for delayed processing• contain data required to run process• according to event job can contain following data:

• create event – entity identity;• update event – entity identity and change set (old and new values);• delete event – entity plain fields (without references).

• contains relation to the trigger used to create this job and entity hash (full class name of the related entity plus identity of the specific entity). This entity hash is required to find all registered jobs

• for the same specific entity (e.g. to remove all related jobs).

Processes

Developer Training

Commands

oro:process:configuration:load• loads processes configuration from *.yml configuration

files to the database• used during application installation and update

oro:process:execute:job• executes process job with specified identifier• used in the JMS jobs to execute delayed processes

Processes

Developer Training

Q & A

Processes

Developer Training

Tracking Websites

• Tracking Website record• Tracking code• Piwik

References:http://www.orocrm.com/documentation/index/current/user-guide/marketing-tracking-website-records https://github.com/orocrm/platform/blob/master/src/Oro/Bundle/TrackingBundle/README.md

http://www.orocrm.com/documentation/index/current/user-guide/marketing-tracking-website-records



https://github.com/orocrm/platform/blob/master/src/Oro/Bundle/TrackingBundle/README.md




Developer Training

Q & A

Day 4


Business Features

Day 5

Developer Training

Workflow

Developer Training

Overview

• solution that allows user to perform set of actions with predefined conditions for specific entity

• a kind of wizard that helps user to implement some business logic • set of ordered actions that can be performed with the specific entity• helps to manage entities, update existing ones and create new• from user POV – set of buttons which may open forms that allow to

manipulate entity data

Workflow

Developer Training

Relation With Entity

• workflow has one related entity class• entity class may have unlimited number of workflows

related to it• entity class may have only one active workflow• entity record at any given moment in time can be

subject to only one workflow. It is possible however to have several workflows for one entity and switch between them

• when a workflow is deleted, all its existing relations to entities and entity records are lost

Workflow

Developer Training

B2B Sales Flow VisualizationWorkflow

Qualify Develop CloseDevelop

Close As Won

Close As Lost

Requalify Lost

Requalify Won

Developer Training

Configuration File

• Resources/config/workflow.yml• configuration file may be split by parts• all included parts must be placed under imports section.• imports may be used in any part of workflow

configuration• configuration cannot be merged

Workflow

Developer Training

Configuration Loading

oro:workflow:definitions:load

• updates workflow definitions• run when you modified configuration

Workflow

Developer Training

Workflow Definition

• can be specified in Resources/config/workflow.yml• persisted via Doctrine’s entity OroWorkflowBundle:

Workflow in table oro_workflow• to push changes of definitions in configuration run

command oro:workflow:load

Workflow

Developer Training

Workflow Item

• it's a record of specific workflow• represented by OroWorkflowBundle:WorkflowItem entity• linked with workflow definition• linked with specific record of related entity• contains reference to current step• contains values of workflow attributes if such exist

Workflow

Developer Training

Attributes

• workflow can manipulate it's own data (Workflow Data) that is mapped by Attributes

• each attribute must have a type and may have options• when Workflow Item is saved its data is serialized

according to configuration of attributes• saving data that is not mapped by any attribute or

mismatched with attribute type is restricted• attribute configuration does not contain any information

about how to render attribute on step forms

Workflow

Developer Training

Attributes Configuration• unique name – Workflow attributes should have unique name in scope of Workflow

that they belong to. Step configuration references attributes by this value.• type – Type of attribute• label – Label can be shown in the UI• entity_acl – Defines an ACL for the specific entity stored in this attribute.

• update – Can entity be updated. Default value is true.• delete – Can entity be deleted. Default value is true.

• property_path – Used to work with attribute value by reference and specifies path to data storage. If property path is specified then all other attribute properties except name are optional - they can be automatically guessed based on last element (field) of property path.

• options – Options of an attribute. Currently next options are supported• class string Fully qualified class name. Allowed only when type either entity or

object.

Workflow

Developer Training

Step

• workflow must contain at least one step• at any given moment in time workflow entity must be in

some step• workflow step can be used as default step• steps are shown in the small widget on the workflow

entity view page• must have at least one transition, either incoming, or

outgoing

Workflow

Developer Training

Step Configuration• name – Step must have unique name in scope of Workflow• label – Label of step, can be shown in UI if Workflow has type wizard• order – This value is used in wizard page to sort steps in UI.• is_final boolean If true than step will be counted as workflow final step.• entity_acl – Defines an ACL for the workflow related entity when workflow

is in this step.• update – Can entity be updated. Default value is true.• delete – Can entity be deleted. Default value is true.

• allowed_transitions – Optional list of allowed transitions. If no transitions are allowed it's same as is_final option set to true

Workflow

Developer Training

Transition

• connects workflow's steps• steps and transitions form a directed graph, where steps

are nodes and transitions are edges• may point to the same step (self-transition)• may have ACL resource• may perform post actions• may have conditions and pre-conditions to restrict or

allow performing transition • transitions appear as buttons on the view of workfow

entity

Workflow

Developer Training

Starting Transition

• special case of transition• don't have starting step• workflow must have either a default step, or a starting

transition

Workflow

Developer Training

Transition Form

• based on registered Symfony's form types• shown to the user after he clicks the transition button• form displays workflow attributes• attributes could be mapped to entity properties or they could be not

mapped• forms are optional, and transition may have no form attached• form appears in the popup windows• form may appear in a separate page

Workflow

Developer Training

Transition ConfigurationWorkflow

• unique name – A transition must have unique name in scope of Workflow• step_to – Next step name• transition_definition – A references to Transition Definition configuration• is_start – If true than this transition can be used to start new workflow• is_hidden – Indicates that this transition must be hidden at frontend• is_unavailable_hidden – transition must be hidden when not allowed• acl_resource – ACL resource to protect transition execution• acl_message – permission error message• message – Notification message will be shown before transition execution.• display_type – Possible options are: dialog, page. "page" require

"form_options"• form_type – (oro_workflow_attributes - default) A form type of transition• frontend_options – Can have such frontend options as class, icon• form_options – options for form types of attributes• transition_definition – Name of associated transition definition

Developer Training

Transition DefinitionWorkflow

• used by Transition to check Conditions and to perform Init Action and Post Actions

• Transition definition configuration:• conditions & pre_conditions – Configuration of Conditions

and Pre Condition that must satisfy to allow transition• post_actions – Configuration of Post Actions that must be

performed after transit to next step will be performed• init_actions – Configuration of Init Actions that may be

performed on workflow item before conditions and post actions

Developer Training

Conditions & Pre Conditions

• Conditions checked when the transition form is committed, if they are not met the transition won’t be conducted

• Pre Conditions are checked first, and affect availability of Transition button UI

• Pre Conditions are required becuase some transtion may use forms, and entered forms data could be used in Conditions

• not yet available on the UI and can be accessed only via configuration files• conditions tree• to add custom condition implement

Oro\Bundle\WorkflowBundle\Model\Condition\ConditionInterface and register service with tag oro_workflow.condition and attribute alias

• conditions configuration

Workflow

Developer Training

Post Actions & Init Actions• executed after the transaction is conducted (i.e. the transition form is

submitted, preconditions and conditions are met, the workflow is moved to the destination step)

• may include creation of another entity, manipulation of the existing entity data and available workflow attributes, email notifications, etc.

• if a post action creates a new record of an entity that has an active workflow with default step, it will be started automatically

• Init Actions performed before transition. Possible use case is to set default values, which will be used by Transition form.

• not yet available on the UI and can be accessed only via configuration files• to add custom post action implement

Oro\Bundle\WorkflowBundle\Model\Action\ActionInterface and register service with tag “oro_workflow.action” and attribute “alias”

• actions configuration

Workflow

Developer Training

Q & A

Workflows


Reports


Reports● Report Wizard

Reports & Segments → Manage Custom Reports

● Configuration files- define in datagrid.yml as usual datagrids- add to Reports & Segments menu in navigation.

yml

http://www.orocrm.com/documentation/index/current/book/reports-configuration

Reports






Analytics

Developer Training

Overview

• RFM metrics• Configurable in UI• oro:cron:analytic:calculate --channel=1

Analytics

Developer Training

Enable RFM for an Entity

Configure entity in the channel:• implement RFMAwareInterface interface• implement RFMAwareTrait trait

Metric providers:• define providers for each metric of the entity to be

collected and implement RFMProviderInterface for each provider

• add the providers to the DI container with orocrm_analytics.builder.rfm tag

Run the calculation command for the channel

Analytics


Delivery


Test Suites- Unit tests- Functional (Integration) tests- Selenium Tests- JavaScript Tests- Code Standards Tests (Sanity Tests)


Unit TestsInstallationTo run unit tests you should have PHPUnit 3.7+ installed.

Running$ phpunit -c app src/Acme/DemoBundle/Tests/Utility/

$ phpunit -c app --testsuite="Unit Tests"

http://phpunit.de/manual/current/en/installation.html



Functional TestsOroCRM takes advantage of Symfony2 functional test framework.

Each test is a PHP class that should be placed in the Tests/Functional subdirectory of your bundle.

Functional tests workflow:• Make a request• Test the response• Click on a link or submit a form• Test the response


Working with Functional Tests

InstallationTo run functional tests you should have PHPUnit 3.7+ installed.

Configuration- app\config\parameters_test.yml- app\config\config_test.yml

Preparingapp/console oro:test:schema:update --env test

app/console doctrine:fixture:load --no-debug --append --no-interaction --env=test --fixtures src/Oro/src/Oro/Bundle/TestFrameworkBundle/Fixtures

Running

$ phpunit -c app --testsuite "Project OroCRM Functional Tests" --verbose --stderr



Selenium TestsInstallationSelenium tests requires:

• PHPUnit 3.7+

• PHPUnit Selenium 1.3.2+

• PhantomJS 1.9+ or Selenium Server 2.37+

ConfigurationMain config options you can find in app\phpunit.xml.dist



http://phpunit.de/manual/3.7/en/selenium.html

http://phpunit.de/manual/3.7/en/selenium.html

http://phantomjs.org/

http://phantomjs.org/


Working with Selenium Tests

Running$ phpunit -c app --testsuite "Project Selenium Tests" --verbose

Writing

- Test example- Page class example- Base page classes:

- AbstractPageGrid- AbstractPageFilteredGrid- AbstractPageEntity


JavaScript TestsInstallationTo run JS tests the following software is required:

• Node.js (JavaScript Engine)

• Karma (Test Runner for JavaScript)

• Jasmine (Behavior-Driven Development Testing Framework)

http://nodejs.org/

http://nodejs.org/

http://karma-runner.github.io/

http://karma-runner.github.io/

http://pivotal.github.io/jasmine/

http://pivotal.github.io/jasmine/


Working with JavaScript Tests

ConfigurationConfiguration for tests-run is placed in app/karma.config.js.dist

Runningkarma start app/karma.conf.js.dist --single-run

Writing- regular test example- karma-requirejs-exposure plugin in action

https://github.com/laboro/karma-requirejs-exposure.git


Code Standards (Sanity) Tests Installation

To check code standards in Oro you’ll need:

• PHP Code Sniffer

• PHP Mess Detector

For ease, we recommend to use xml reports.

http://pear.php.net/package/PHP_CodeSniffer/redirected





Running Sanity Tests

ConfigurationPHP Code Sniffer and PHP Mess Detector configuration can be provided in ruleset.xml files.

Running$ phpcs --encoding=utf-8 --extensions=php --report=checkstyle --standard=rulesetCS.xml --report-file=app/logs/checkstyle.xml ./src

$ phpmd ./src xml rulesetMD.xml --reportfile app/logs/pmd.xml --exclude ../src/Acme


Q&A

[email protected]@orocrm.com

mailto:[email protected]





Marketing

Developer Training

SegmentsRepresentation of some dataset based on entity and set of filters

Types of segments:• Static ("On demand")• Dynamic

Implementation:• Extends Oro\Bundle\QueryDesignerBundle\Model\AbstractQueryDesigner• Segment snapshot• Query builder• Datagrid

https://github.com/laboro/platform/tree/master/src/Oro/Bundle/SegmentBundle

Marketing




Developer Training

Marketing Lists

• Uses wizard similar to Custom Reports• Requires at least on contact information field• Can be used to:

• run Email Campaigns in OroCRM• synchronize with Subscribers Lists in MailChimp• synchronize with Address Books in DotMailer

• Abandoned Cart Campaign• conversion tool

Marketing