Local Bitrix24 modules: boundaries, updates and maintenance

A local module brings related application logic together. But the /local/modules/ path alone does not make a solution independent of platform versions. Define the module's responsibility, dependencies and the scenarios to verify after updates.

This article concerns solution design. It is not a ready-made installer and does not promise compatibility with every edition of Site Management or Bitrix24.

When a module is justified

A module is useful when a feature has its own settings, data, permissions, integration operations or several entry points. For example, the same validation may be needed in the interface, an agent and an administrative operation.

If a small configuration change to a standard tool solves the task, an extra module may be unnecessary. Choose the solution based on the feature's lifecycle, not the size of its first code snippet.

One operation, one application responsibility

Suppose a request must be accepted and sent to an external system. It helps to distinguish three parts:

This separation does not require three large frameworks or a complex hierarchy. It prevents an interface change from forcing an integration rewrite, and an exchange error from disappearing inside an HTML response.

Check permissions on the server. Hiding a button does not prevent direct requests. For a background operation, state who initiated it and on whose behalf it can change data.

Use extension points deliberately

Platform events let custom logic run at a particular stage of an operation. Before registering a handler, verify the event signature, conditions and consequences of failure in the exact module version required.

Evaluate lengthy network operations separately: if they run inside a user request, an unavailable external system can delay the whole scenario. Depending on the task, queued processing may be needed.

The D7 and EventManager documentation helps identify available mechanisms. Internal undocumented methods require closer checking after changes: a method's existence in one version is not a promise of a stable contract.

Data and installation

Installation, upgrade and removal are different operations. An upgrade should not require uninstalling the module and losing accumulated data. The choice to retain data during removal must be clear to the administrator.

Describe data-structure changes as steps that can be repeated. Verify a fresh installation and an upgrade from the previous supported version. Choose the checks based on what changed.

When using an ORM, separately verify the business rules of the entity involved. A generic record-save operation is not always equivalent to the product's standard operation with all its events, permissions and side effects.

What to hand over to the maintaining developer

• The module's purpose and responsibility boundaries.
• Supported environment and significant dependencies.
• Entry points, events, background jobs and settings.
• Installation, upgrade and rollback procedures.
• Public-method examples and expected errors.
• Short verification scenarios after changes or platform updates.

An example of a failed operation is particularly useful: how to identify the problem, where to find diagnostics and under which conditions the action can be retried. This reduces dependence on the author's memory.

Checking readiness

Ask another developer to follow the documentation through one primary scenario and explain what happens on failure. If they must find the author and ask about implicit settings, the handover is incomplete.

• Bitrix24 module development
• Site Management development
• Reliable integrations

Platform documentation

The following platform references are in Russian:

• Example of creating a custom module.
• EventManager in D7.
• Bitrix Framework D7 reference.