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:

Plan restriction check.
Check for [link=13982732]element access permissions[/link].
Check for [link=141582]access permissions[/link].
Check for launched workflows.
Executing [link=141582]field logic before saving[/link].
Check for completed required/mandatory fields.

If this element wasn't updated up to this point, no further actions are required.

Executing [link=14006646]additional actions before saving[/link].
Saving the [link=13985532]element[/link].
Executing [link=141582]field logic before saving[/link].
Updating [link=13982732]access permission data[/link].
Updating search index.
Saving [link=13980976]history of actions at the element[/link].
Writing data into [link=13962422]timeline[/link].
Executing [link=14006646]additional action after saving[/link].
Sending [link=11301768]push notifications[/link].
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());
}