Documentation

New invoices

The crm 21.1300.0 update introduces new CRM entity type that replaces legacy invoices.

Work as smart processes

New entity elements/items operate based on the same principle as SPA items. However, new invoices are not SPAs entirely, but a modified Smart process type, with some individual specifics.

You cannot modify settings for these new invoices SPA


Pipelines/categories

Presently, the New invoices do not use pipelines. Pipelines are supported by API due to being based on SPAs.

It means that new invoice elements behave identically to SPA elements, but the pipelines option is disabled in the interface.


Stages

Everything operates in the same manner as for the SPAs, except for identifiers. Additionally, new invoices have different set of stages upon creation (the same as in the legacy invoices).


Elements

Element data is stored in the same manner as in the Smart processes. Descendant class \Bitrix\Main\ORM\Data\DataManager for the DB via ORM compiled in runtime.

In the same runtime, the ORM table have two additional fields, unavailable in SPAs:

  • ACCOUNT_NUMBER - account number. The mechanism is the same as for the field QUOTE_NUMBER for quotes.
  • COMMENTS - html-field with comments.

Custom fields

New invoices data storage is completely identical to SPAs, as mentioned above. Custom fields data is not different from the SPAs.

Custom fields handling is identical to smart processes.

Identifiers

Details

  • Entity type ID - \CCrmOwnerType::SmartInvoice = 31
  • \CCrmOwnerType::isPossibleDynamicTypeId(31) returns false
  • New methods added:
    MethodDescription Available from version
    \CCrmOwnerType::isUseFactoryBasedApproach(
    int $entityTypeId
): bool
    		 Returns true, when new API for entity type is fully implemented and the old one is not required. 
    \CCrmOwnerType::isUseDynamicTypeBasedApproach(
    int $entityTypeId
): bool
    		 Returns true, when API is based on SPAs API. Can be perceived as verification for this type to be operating on the SPAs "engine". 
    \CCrmOwnerType::isDynamicTypeBasedStaticEntity(
    int $entityTypeId
): bool
    		 Returns true, when entity type is based on the SPA API, but is not a smart process itself (Example: new invoices). 
    \CCrmOwnerType::getDynamicTypeBasedStaticEntityTypeIds(): array
    		 Returns array with type IDs, based on SPAs, but are not SPAs themselves (Example: new invoices).

  • The new entity type has its own set of identifiers for almost everything
    • \CCrmOwnerType::SmartInvoice = 31 - entity type ID
    • \CCrmOwnerType::SuspendedSmartInvoice = 32 - entity type ID for recycle bin
    • \CCrmOwnerType::SmartInvoiceName = "SMART_INVOICE" - new entity type string ID
    • \CCrmOwnerType::SuspendedSmartInvoiceName = "SUS_SMART_INVOICE" - new entity type string ID for recycle bin
    • \CCrmOwnerTypeAbbr::SmartInvoice = "SI" - type brief designation.
    • ENTITY_ID for custom fields - \Bitrix\Crm\Service\Factory\SmartInvoice::USER_FIELD_ENTITY_ID = "CRM_SMART_INVOICE"
    • ENTITY_ID for custom fields in recycle bin - \Bitrix\Crm\Service\Factory\SmartInvoice::SUSPENDED_USER_FIELD_ENTITY_ID = "CRM_SMART_INVOICE_SPD"
    • ENTITY_ID for stages is generated as SMART_INVOICE_STAGE_{categoryId}
    • Field prefix STATUS_ID for stages is generated the same as for smart processes - DT31_{categoryId}

General recommendations

In an ideal case, the code shall not clearly distinguish between entity types. Then it will be the most extendable and universal.

When difference must be coded (for example, for a transitory period, when new API is not implemented yet for all entity types), then use the following algorithm:

  • When you need to find out, whether specific type supports new API, use the method \CCrmOwnerType::isUseFactoryBasedApproach(int $entityTypeId): bool
  • When you need to understand, if you are dealing with SPAs, use the method \CCrmOwnerType::isUseDynamicTypeBasedApproach(int $entityTypeId): bool
  • The method \CCrmOwnerType::isPossibleDynamicTypeId(int $entityTypeId): bool is used very rarely, only when you have absolute clear understanding that you need this specific method. Returns true only in case of entityTypeId belonging to a "actual" smart process. Meaning that all static types are excluded, based on smart processes (for example, new invoices). Most frequently, it's not the most advisable approach.

Section display settings

The moment of crm 21.1300.0 release start the ongoing transitory period for switching from legacy to the new invoices. At this moment, interfaces can show only legacy invoices, new invoices or both.

To simplify the work, some new methods were added. Their objective — to give a determine which portion of interface must be displayed, because some specific details will be updated or changed with time.

use Bitrix\Crm\Settings\InvoiceSettings;

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

$isShowOldInvoices = InvoiceSettings::getCurrent()->isOldInvoicesEnabled(); // show legacy invoices or not
$isShowSmartInvoices = InvoiceSettings::getCurrent()->isSmartInvoiceEnabled(); // show new invoices or not

Before showing new invoices in the interface you need to verify the need to show them at all. It's also recommended to hide the old invoices, if InvoiceSettings::isOldInvoicesEnabled returns false.


© «Bitrix24», 2001-2024