Field

Общее

Different CRM entity types have fields with various codes, but similar (business) logic.

To avoid duplicating calls of different code portions in operations of various types in the new API it was decided to create an dedcated class hierarchy.

Descendant class name is specified in factory in the method getFieldsSettings().

When descendant is not specified, base class is used anyways.

Checking attributes and executing the logic is performed in corresponding methods for operations.

There is no sense to directly call methods, executing the logic outside the operations. However, some other methods can be useful.

Be advised, that this call is used when handling only the fields that have a "physical" column in the element table.

The element table can have specific fields (for example, "Customer" field), not included into the collection of field types. Handling them is performed only at the level of interface.

Attributes

Each field can have a set of attributes defining basic parameters of field behaviour.

\CCrmFieldInfoAttr::Hidden - Field is unavailable in REST and is ignored when merging duplicates.
\CCrmFieldInfoAttr::NotDisplayed - Field is not displayed in the details interface (but can be available in lists).
\CCrmFieldInfoAttr::ReadOnly - Field value cannot be updated by user.
\CCrmFieldInfoAttr::Immutable - Field value can be completed by user only when creating.
\CCrmFieldInfoAttr::UserPKey - Field is primary key. Rarely used.
\CCrmFieldInfoAttr::Required - Field is required.
\CCrmFieldInfoAttr::Multiple - Field is multiple.
\CCrmFieldInfoAttr::Dynamic - Field is a custom field.
\CCrmFieldInfoAttr::Deprecated - Field marked as deprecated (printed in REST).
\CCrmFieldInfoAttr::Progress - Field contains information about element stage. Rarely used .
\CCrmFieldInfoAttr::HasDefaultValue - Field has default value.
\CCrmFieldInfoAttr::AutoGenerated - Field value is generated automatically when creating an element.
\CCrmFieldInfoAttr::Unique - Field value must be unique within table of elements.
\CCrmFieldInfoAttr::CanNotBeEmptied - When user clears value from this field, this update is not applied and when saved is reset to initial status.

Methods

Method	Description	Available from version
public function __construct (string $name, array $description) $name - field code as named in the element table; $description - array with field description with following structure: TYPE - field type, possible values are listed in the constants of class `TYPE_`; TITLE* - field title; ATTRIBUTES - array with listed field attributes; SETTINGS - array with additional settings for arbitrary structure field; USER_FIELD - array with additional settings for arbitrary structure field; SETTINGS - description of custom field settings, when this field is a custom field.	Constructor. It's not recommended to call it directly, use the factory methods for getting the fields.
public function isValueCanBeChanged(): bool	Returns true, when the field value can be modified by the user (checks for available attributes `\CCrmFieldInfoAttr::ReadOnly` and `\CCrmFieldInfoAttr::Immutable`).
public function processWithPermissions (Item $item, UserPermissions $userPermissions): Result $item - element; $userPermissions - access permissions service.	This method must execute additional access permission and logic checks for this field. For example, it is defined in the class of the "Responsible" field type and "Open for all".
public function process(Item $item, Context $context = null): Result $item - element; $context - execution context.	Main methods, called before saving an element when executing an operation.
public function processAfterSave (Item $itemBeforeSave, Item $item, Context $context = null): FieldAfterSaveResult $itemBeforeSave - element in state before saving; $item - element in current state; $context - execution context.	Method, implementing additional logic to be processed after saving the element. This methods shall not call the saving of element directly, new field values must be placed to `FieldAfterSaveResult`.
public function isItemValueEmpty(Item $item): bool	Returns true, when $item has this field value as empty.
public function isValueEmpty($fieldValue): bool	Returns true, when $fieldValue is deemed as empty.
public function getName(): string	Returns field code.
public function setName(string $name): Field	Writes new code for the field $name.
public function getTitle(): string	Returns field name.
public function setTitle(string $title): self	Writes new code for field $title.
public function getType(): string	Returns field type.
public function setType(string $type): Field	Writes new field $type.
public function getAttributes(): array	Returns set of field attributes.
public function setAttributes(array $attributes): Field	Writes new set of field $attributes (re-writes completely).
public function getSettings(): array	Returns set of field settings.
public function setSettings(array $settings): Field	Writes new set of $settings field.
public function isUserField(): bool	Returns true, when field is a custom.
public function getUserField(): array	Returns description of custom field settings.
public function isAutoGenerated(): bool	Returns true, when field value is generated automatically.
public function isMultiple(): bool	Returns true, when field is multiple.
public function isDisplayed(): bool	Returns true, when field must be displayed in element details.
public function isRequired(): bool	Returns true, when field is required.
public function toArray(): array	Returns array with description of field parameters; structure is similar to the constructor $description argument.
public function isFileUserField(): bool	Returns true, when field is custom with "file" base type.
public function getValueNotValidError(): Error	Returns error on incorrectly completed field.
public static function getRequiredEmptyError (string $fieldName, ?string $title = null): Error $fieldName - код поля; $title - название поля.	Returns error on required field is empty.
public function getValueNotUniqueError(): Error	Returns error that field values is not unique.

Descendants

Presently there are following existing field types:

Field	Description
Field\Assigned	Responsible. If user has permission to create only its "Own" elements, user (sourced from context) who performed updates will be forcefully written into the field. When field is not completed, current user forcibly is written into it (taken from context).
Field\Category	Pipeline. When field is updated, it's checked for correct ID of the corresponding pipeline type. After saving, access permissions attributes are cleared if field is updated.
Field\Closed	Closed. Automatically completed depending on current stage semantics.
Field\CloseDate	Date when closed. Automatically completed with current date, if this field value is not completed and the "Closed" field value is true.
Field\CreatedBy	Created by. Automatically completed by current user (from context) when creating. In the rest of cases, forcefully reset to the original state.
Field\CreatedTime	Time when created. Automatically completed with current time when creating a new element.
Field\MovedBy	Moved by. Automatically completed by current user (sourced from context) when changing stage.
Field\MovedTime	When moved. Automatically completed with current time when changing stage.
Field\Number	Number. If the field was cleared upon update, element ID is forcefully written into it. When created, number is generated automatically according to numerator settings. .
Field\Observers	Observers. Updates contents of associated chat.
Field\Opened	Opened for all. When user has access permission for creating/updating elements open for all, then this field has a forced true.
Field\Opportunity	Total. When automatic total calculation is enabled, the value is calculated based on the product items via calculation service.
Field\OpportunityAccount	Total for reports. The value is completed based in the report currency and "Total" field.
Field\PersonTypeId	Payer type. Completed automatically based on company associated to the element.
Field\PreviousStageId	Previous stage. Completed automatically when changing stage.
Field\Stage	Stage. Completed automatically when changing the stage. Upon changed field value, checks correct status related list of stages for current element pipeline. If "Pipeline" field is updated and the new stage is not specified, the value is completed automatically by the first status of the same new pipeline semantics.
Field\TaxValue	Tax total. Completed automatically based on the product items list via calculation service.
Field\UpdatedBy	Who updated. Automatically completed by the current user from context.
Field\UpdatedTime	When updated. Automatically completed by current time.

Example

use Bitrix\Crm\Service;
use Bitrix\Crm\Item;

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

$opportunityField = $factory->getFieldsCollection()->getField(
    Item::FIELD_NAME_OPPORTUNITY
);
if (
    $opportunityField->isValueEmpty($value)
    && $opportunityField->isRequired()
)
{
    $error = $opportunityField::getRequiredEmptyError(
        $opportunityField->getName(),
        $opportunityField->getTitle()
    );
}