Documentation

Operations

General


Each update for CRM element of any type is followed with significant number of verifications and concurrent actions.

For the purposes of transparency, a single class was designed to include all these processes.

Because each type of entity can have its own specifics and [link=14006646]additional actions[/link], the object instance is retrieved via [link=13981986]factory[/link].

Retrieved object must be accordingly [link=14006736]configured[/link].

Launch is performed using the launch method, returning the object \Bitrix\Main\Result.

Generally, the process is executed as follows:

  1. Plan restriction check.
  2. Check for [link=13982732]element access permissions[/link].
  3. Check for [link=141582]access permissions[/link].
  4. Check for launched workflows.
  5. Executing [link=141582]field logic before saving[/link].
  6. Check for completed required/mandatory fields.
    • If this element wasn't updated up to this point, no further actions are required.
  7. Executing [link=14006646]additional actions before saving[/link].
  8. Saving the [link=13985532]element[/link].
  9. Executing [link=141582]field logic before saving[/link].
  10. Updating [link=13982732]access permission data[/link].
  11. Updating search index.
  12. Saving [link=13980976]history of actions at the element[/link].
  13. Writing data into [link=13962422]timeline[/link].
  14. Executing [link=14006646]additional action after saving[/link].
  15. Sending [link=11301768]push notifications[/link].
  16. Launching workflows and workflow templates.

Methods for executing checks and updates are public.

When required, you can retrieve an operation object and call an access permission check before launching the operation itself.

Methods


Method Description Available from version
public function __construct
(Item $item, Operation\Settings $settings, 
Collection $fieldsCollection = null)
Constructor.
Pass [link=13985532]element[/link], [link=14006736]settings[/link] and collection of [link=13986312]fields[/link] to the constructor.
When no $fieldsCollection is passed, all field-bound features won't be performed.
public function exportSettings(): Operation\Settings
Returns current [link=14006736]settings object[/link]. Returns the same object, not a copy.
ppublic function importSettings
(Operation\Settings $settings): self
Sets new [link=14006736]settings object[/link] for operation.
public function getContext(): Context
Returns current [link=13977672]context[/link] for executed operation.
public function setContext(Context $context): self
Sets new [link=13977672]context[/link] for executed operation.
public function getItem(): Item
Returns [link=13985532]element[/link], handled by operation.
public function getItemBeforeSave(): Item
Returns copy of element in the status before saving to the database. This copy is available only after calling the launch().
public function addAction
(string $actionPlacement, Action $action): self
Adds [link=14006646]additional action[/link] $action to $actionPlacement.
$actionPlacement can get the value beforeSave(Operation::ACTION_BEFORE_SAVE) oe afterSave(Operation::ACTION_AFTER_SAVE).
public function launch(): Result
Launches the operation. Returns \Bitrix\Main\Result.
public function checkAccess(): Result
Executes the [link=13982732]access permission[/link] check.
public function processFieldsWithPermissions(): Result
Executes access permission check for [link=141582]fields[/link].
public function processFieldsBeforeSave(): Result
Checks [link=141582]fields[/link] before saving.
public function checkFields(): Result
  • Checks, if custom fields are completed correctly according to their type and settings.
  • Checks, if required fields are completed.
    • If the stage is updated, checks that all required fields are completed.
    • In the rest of cases, checks only the fields that were modified.
public function checkRequiredFields
(array $requiredFields, Factory $factory): Result
Method checks that $requtedFields fields are completed. $factory - [link=13981986]factory[/link].
The array $requiredFields contains index array with field codes to be checked.
public function processFieldsAfterSave(): Result
Executes field logic after saving. When a value was updated, element will be saved again.
public function getStageDependantRequiredFields
(Factory $factory): array
Returns codes of stage-dependant required fields that must be checked when executing this operation.
public function isItemChanged(): bool
Returns true, when field values were updated, except for values generated automatically.
public function checkRunningWorkflows(): Result
Checks that element has no launched workflows when changing pipelines. If pipeline is not changed, this is not performed.

Config method


To manage operation settings, you can retrieve [link=14006736]settings object[/link] and handle methods directly.
Or you can call methods of this calls and handle the settings.


Method Description
public function disableAllChecks(): self
Method disables all checks when executing the operation.
This method call is similar to the methods disableCheckWorkflows(), disableCheckAccess(), disableCheckFields(), disableCheckRequiredUserFields().
enableAutomation / disableAutomation / isAutomationEnabled
Manages workflow launch.
enableBizProc / disableBizProc / isBizProcEnabled
Manages workflow template launch.
enableCheckAccess / disableCheckAccess / isCheckAccessEnabled
Manages access permission check.
isCheckFieldsEnabled / enableCheckFields / disableCheckFields
Manages correct custom and required fields data.
enableCheckRequiredUserFields / disableCheckRequiredUserFields / isCheckRequiredUserFields
Manages required field data check.
enableFieldProcession / disableFieldProcession / isFieldProcessionEnabled
Manages checks and updates, associated with [link=141582]field logic[/link].
enableSaveToHistory / disableSaveToHistory / isSaveToHistoryEnabled
Manages enabled history entries.
enableBeforeSaveActions / disableBeforeSaveActions / isBeforeSaveActionsEnabled
Manages additional actions before saving.
enableAfterSaveActions / disableAfterSaveActions / isAfterSaveActionsEnabled
Manages additional actions after saving.
enableCheckWorkflows / disableCheckWorkflows / isCheckWorkflowsEnabled
Manages launched workflows check.

Descendants


Base operation class is an abstract class. This calss has five implementation variants with different operations:

  • Operation\Add - adding.
  • Operation\Update - updating.
  • Operation\Delete - deleting.
  • Operation\Copy - copying.
  • Operation\Conversion - converting.

Each of these classes has redefined methods, responsible for operation specifics. But in generally, the operation process is executed in the same sequence.

The difference: deleting action doesn't trigger workflows and business processes, due to it being not needed.

Example


use Bitrix\Crm\Service;

$entityTypeId = 128;

$factory = Service\Container::getInstance()->getFactory($entityTypeId);

$item = $factory->createItem();
$item->setStageId('D128_3:CLIENT');

$operation = $factory->getAddOperation($item)
    ->disableCheckAccess()
    ->disableCheckFields();

$result = $operation->launch();
if (!$result->isSuccess())
{
    print_r($result->getErrorMessages());
}

$newId = $item->getId();

Updating a Quote with starting of associated actions

\Bitrix\Main\Loader::includeModule('crm');

use Bitrix\Crm\Service;

$factory = Service\Container::getInstance()->getFactory(\CCrmOwnerType::Quote);

$itemId = 3; // entity ID

$item = $factory->getItem($itemId);

if ($item) {
  $item->setStageId('SENT');
}

$operation = $factory->getUpdateOperation($item)
    ->disableCheckAccess()
    ->disableCheckFields();

$result = $operation->launch();
if (!$result->isSuccess())
{
    print_r($result->getErrorMessages());
}

© «Bitrix24», 2001-2022
Up