Items

Handling items

• Class for handling items of any entity type - \Bitrix\Crm\Item
• Getting objects using factory methods \Bitrix\Crm\Service\Factory
• Performing actions (Creating / editing / deleting and others) wrapped into operations \Bitrix\Crm\Service\Operation
• Specifics for handling item/element collections are overviewed in a separate article
• Some details on data structure with bindings

Creating an item

$entityTypeId = \CCrmOwnerType::Deal;

$factory = \Bitrix\Crm\Service\Container::getInstance()->getFactory($entityTypeId);
if (!$factory)
{
    echo 'factory not found';
    return;
}

// default empty item with completed field values, including pipeline, stage, creator fields, etc.
$item = $factory->createItem();

// method returns item data as an array, identical to the "legacy" API structure 
// $item->getCompatibleData();

// now you can write new field values
$item
    ->setAssignedById($newAssigned)
    ->setMycompanyId($newMycompanyId)
;

// can write data as an array, similar to the "legacy" API structure

$item->setFromCompatibleData([
    \Bitrix\Crm\Item::FIELD_NAME_ASSIGNED => $newAssigned,
    \Bitrix\Crm\Item::FIELD_NAME_MYCOMPANY_ID => $newMycompanyId,
])

// doesn't saves data, only stores inside $item 
// to save database changes without performing all related actions, its sufficient to call
// $item->save();
// HOWEVER THIS IS NOT RECOMMENDED.
// All related actions, often ensuring the CRM feature operability will be skipped (counter updates,
// access permissions, search indexes, etc.)

// if must redefine execution context, you must do this directly
$context = new \Bitrix\Crm\Service\Context();
$context->setUserId($userId);

// operation is performed by $userId with all checks
$operation = $factory->getAddOperation($item, $context);
$result = $operation->launch();

Item editing

For example, we would like to change details for contacts associated with a specific item, without all checks.

$entityTypeId = \CCrmOwnerType::Deal;
$entityId = 261;

$factory = \Bitrix\Crm\Service\Container::getInstance()->getFactory($entityTypeId);
// no sense to execute the code further for this entity without "Client" field
if (!$factory || !$factory->isClientEnabled())
{
    echo 'factory not found';
    return;
}

$item = $factory->getItem($entityId);
if (!$item)
{
    echo 'item not found';
    return;
}

// $item->getContacts() returns array with ORM objects from the table b_crm_contact, associated with this item
// it can be useful when you need to read data of associated contacts.

// stores a simple array containing contact binding data
//$existingBindings = $item->getContactBindings();

// add binding to contact with ID = 4
$item->bindContacts(\Bitrix\Crm\Binding\EntityBinding::prepareEntityBindings(\CCrmOwnerType::Contact, [4]));
// delete binding from contact with ID = 3
$item->unBindContacts(\Bitrix\Crm\Binding\EntityBinding::prepareEntityBindings(\CCrmOwnerType::Contact, [3]));

// new bindings data is not saved anywhere yet, just stored inside $item 
// to save database changes without performing all associated actions, just call
// $item->save();
// HOWEVER, THIS IS NOT RECOMMENDED.
// All associated actions, frequently enabling CRM operability will be skipped (counter updates,
// access permission updates, search index updates, etc.)

// if must re-define execution context, you must do it directly
// $context = new \Bitrix\Crm\Service\Context();
// $context->setUserId($userId);

$operation = $factory->getUpdateOperation($item);
$operation->disableAllChecks();

$result = $operation->launch();

Item deleting

$entityTypeId = \CCrmOwnerType::Deal;
$entityId = 260;

$factory = \Bitrix\Crm\Service\Container::getInstance()->getFactory($entityTypeId);
if (!$factory)
{
    echo 'factory not found';
    return;
}

$item = $factory->getItem($entityId);
if (!$item)
{
    echo 'item not found';
    return;
}

// you can delete item without performing extra checks and actions as follows
// $item->delete();
// HOWEVER, THIS IS NOT RECOMMENDED!
// Leftover records will remain inside tables (indexes, bindings and etc.)

$result = $factory->getDeleteOperation($item)->launch();