Crm Call Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require oro/crm-call-bundle
   

   Ensure the bundle is enabled in config/bundles.php:

   Oro\Bundle\CallBundle\OroCallBundle::class => ['all' => true],
   

2. Enable Calls for Entities: Use the oro_activity.entity configuration to enable calls for specific entities (e.g., Customer or Lead):

   # config/packages/oro_activity.yaml
   oro_activity:
       entity:
           Oro\Bundle\CustomerBundle\Entity\Customer:
               activities:
                   - call
   

3. First Use Case:

   • Logging a Call: Access the entity (e.g., Customer) in the UI, navigate to the "Activities" tab, and click "Add Call". Fill in the call details (duration, notes, etc.) and save.
   • Viewing Calls: The "Activities" tab will now show a list of logged calls for the entity.

4. Key Files to Review:

   • Resources/doc/reference/entities.md (Call entity structure).
   • Resources/doc/reference/form_type.md (Form customization).

Implementation Patterns

Common Workflows

1. Integrating with Custom Entities

• Enable Calls: Extend oro_activity.yaml to include your entity:

  oro_activity:
      entity:
          App\Entity\CustomEntity:
              activities:
                  - call
  

• Customize Call Form: Override the call form type in your bundle:

  // src/Form/Type/CallTypeExtension.php
  namespace App\Form\Type;
  
  use Oro\Bundle\CallBundle\Form\Type\CallType;
  use Symfony\Component\Form\AbstractTypeExtension;
  use Symfony\Component\Form\FormBuilderInterface;
  
  class CallTypeExtension extends AbstractTypeExtension
  {
      public function buildForm(FormBuilderInterface $builder, array $options)
      {
          $builder->add('custom_field', TextType::class);
      }
  
      public static function getExtendedType()
      {
          return CallType::class;
      }
  }
  

  Register the extension in services.yaml:

  services:
      App\Form\Type\CallTypeExtension:
          tags:
              - { name: form.type_extension, extended_type: Oro\Bundle\CallBundle\Form\Type\CallType }
  

2. Programmatic Call Creation

Use the CallManager service to create calls programmatically:

use Oro\Bundle\CallBundle\Entity\Call;
use Oro\Bundle\CallBundle\Manager\CallManager;

class MyService
{
    private $callManager;

    public function __construct(CallManager $callManager)
    {
        $this->callManager = $callManager;
    }

    public function logCall($entity, $duration, $notes)
    {
        $call = new Call();
        $call->setDuration($duration);
        $call->setNotes($notes);
        $call->setEntity($entity);

        return $this->callManager->save($call);
    }
}

3. DataGrid Customization

Extend the call datagrid to add custom columns or filters:

# config/packages/oro_call.yaml
oro_datagrid:
    grids:
        oro_call-call:
            columns:
                custom_field:
                    label: Custom Field
                    type: twig
                    template: OroCallBundle:CallGrid:custom_field.html.twig
            filters:
                custom_field:
                    type: string
                    data_name: customField

4. Event Listeners

Trigger actions on call creation/update:

use Oro\Bundle\CallBundle\Entity\Call;
use Oro\Bundle\CallBundle\Event\CallEvents;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class CallSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents()
    {
        return [
            CallEvents::POST_SAVE => 'onCallSave',
        ];
    }

    public function onCallSave(CallEvent $event)
    {
        $call = $event->getCall();
        // Custom logic (e.g., send notification)
    }
}

5. API Integration

Enable the call API endpoint in config/packages/oro_api.yaml:

oro_api:
    rest:
        call:
            enabled: true
            action:
                create: true
                update: true
                get: true

Integration Tips

• Dependency Injection: Use CallManager, CallRepository, or CallQueryBuilder directly in services/controllers. Example:

  public function __construct(
      private CallManager $callManager,
      private CallRepository $callRepository
  ) {}
  

• Twig Extensions: Access call-related data in templates via oro_call.twig.call_extension (if not private in your version). Example:

  {{ oro_call.get_call_duration(call) }} minutes
  

• Validation: Customize call validation by extending the Call entity or using constraints:

  use Symfony\Component\Validator\Constraints as Assert;
  
  class CallExtension
  {
      public function buildForm(FormBuilderInterface $builder, array $options)
      {
          $builder->add('duration', IntegerType::class, [
              'constraints' => [
                  new Assert\GreaterThanOrEqual(1),
              ],
          ]);
      }
  }
  

• Localization: Translate call-related labels/placeholders via translator service:

  $this->translator->trans('oro.call.form.label.duration');
  

Gotchas and Tips

Pitfalls

1. Entity Configuration:

   • Forgetting to enable calls for an entity in oro_activity.yaml will hide the "Add Call" button.
   • Fix: Verify activities: [call] is set for your entity.

2. Service Privacy:

   • In v4.1.0+, oro_call.twig.call_extension is marked as private. Use alternative methods (e.g., custom Twig functions) if needed.
   • Fix: Check your bundle version and update references accordingly.

3. DI Parameter Changes:

   • v4.1.0+ removed *.class parameters (e.g., oro_call.call.entity.class).
   • Fix: Replace with direct class names (e.g., Call::class).

4. Form Overrides:

   • Overriding CallType may break if the parent class changes in minor updates.
   • Fix: Use prepend or append methods instead of full overrides where possible.

5. API Permissions:

   • The API endpoint may not be enabled by default. Ensure oro_api.yaml is configured.
   • Fix: Add oro_call to oro_api.rest as shown in the workflows.

6. Database Migrations:

   • Upgrading major versions (e.g., v5.x → v6.x) may require schema updates.
   • Fix: Run php bin/console doctrine:migrations:diff and doctrine:migrations:migrate.

7. Event Dispatching:

   • Events like CallEvents::POST_SAVE may not fire if the call is not persisted properly.
   • Fix: Use CallManager::save() instead of direct entity persistence.

Debugging Tips

1. Check Entity Activities: Run this SQL to verify enabled activities for an entity:

   SELECT * FROM oro_activity_entity WHERE entity_class = 'App\Entity\Customer';
   

2. Datagrid Issues: Clear cache and check for typos in oro_datagrid configuration:

   php bin/console cache:clear
   

3. Form Validation Errors: Enable debug mode and check the browser console for validation messages. Common issues:

   • Missing required fields (e.g., duration).
   • Incorrect data types (e.g., passing a string to a numeric field).

4. Event Subscriber Not Triggering: Verify the subscriber is registered in services.yaml and the event name matches (e.g., CallEvents::POST_SAVE).

5. API Endpoint Not Found: Ensure the route is enabled in oro_api.yaml and the bundle is compiled:

   php bin/console debug:router | grep call
   

Extension Points

1. Custom Call Fields: Add fields to the Call entity via Doctrine extensions or custom tables:

   // src/Entity/CallExtension.php
   namespace App\Entity;
   
   use Doctrine\ORM\Mapping as ORM;
   
   #[ORM\Entity]
   class CallExtension
   {
       #[ORM\Column(type: 'string', nullable: true)]
       private $customField;
   }
   

   Update the form and datagrid to include the new field.