Application Updates

This page describes what happens on Bitrix24 when an installed application is updated to a new version: how an update differs from the first installation, which data is retained, and what to consider in the new version's installer. After reading it, you will be able to plan the release of a new mass-market application version so that users' configured scenarios continue working.

This page does not cover the first installation of an application — it is described in Application Installation Options in Bitrix24. What happens during removal is described in the App deletion article.

How a New Version Is ReleasedHow a New Version Is Released

A new version of a mass-market application follows the same path as the first one. The developer adds the version on the Version History tab in the solution card and submits it for moderation. After the first version passes moderation, the solution is published to the catalog automatically; for subsequent versions, the developer controls the Available in the catalog checkbox. For details, see the Procedure for Publishing Solutions in Bitrix24 Market article.

Each Bitrix24 instance updates to the published version separately. The application is not reinstalled: client_id and client_secret remain unchanged, and the installation history is retained.

What Happens During an UpdateWhat Happens During an Update

There is no separate application update procedure: Bitrix24 performs the same installation as the first time, except that it updates the existing application record instead of creating one. Bitrix24 also re-evaluates how the installation is completed, and this determines both the wizard behavior and what happens to the application's service subscriptions.

Application Type	Installation Wizard	Service Subscriptions
Application with an installation wizard — the initial installation path is specified	The installation completion flag is reset. The installation page opens for the user again, and the new version must call installFinish again. Until this call is received, the application is considered unconfigured, and its functionality is blocked	The ONAPPINSTALL subscription is removed and is not created again — even if the application created it itself with event.bind. The ONAPPUSERREADY subscription is recreated for the same installation path
Application without an interface, API-only, or without an initial installation path	Does not open, and the application remains installed	The ONAPPINSTALL and ONAPPUSERREADY subscriptions are recreated for the installation path, and the application receives the ONAPPINSTALL event on every update

This leads to two practical consequences. The installer must work correctly not only on a fresh Bitrix24 instance, but also where the previous version has already configured everything. An application with an installation wizard cannot rely on its own ONAPPINSTALL subscription: the subscription will not exist after an update, so the application will learn about the update only when the user opens the installation page.

What Is Retained During an UpdateWhat Is Retained During an Update

An update does not affect the data the application stores on Bitrix24: CRM records, files, list items. Registrations made through REST are also retained, except for the two service subscriptions listed in the table above.

What	What Happens During an Update
client_id and client_secret	Remain unchanged. The application remains the same, and no repeated OAuth registration is required
Event handlers, except ONAPPINSTALL and ONAPPUSERREADY	Retained. Only removing the application cancels these subscriptions
Widget handlers	Retained under the same condition
Application data stores	Retained. They are cleared only when the application is removed with the Delete application settings and data option enabled
Application settings	Retained under the same condition

New Version Release ChecklistNew Version Release Checklist

1. Make the installer idempotent. The same code runs during both the first installation and an update. Re-registering an existing object must not break the installation.
2. Do not create duplicates when registering again. Most registrations survive an update, so before event.bind, retrieve current subscriptions with event.get; before placement.bind, use placement.get, and register only what is missing. The exceptions are ONAPPINSTALL and ONAPPUSERREADY: Bitrix24 recreates these subscriptions itself.
3. Do not change the codes of automation rules and workflow actions between versions. Automation scenarios and workflows refer to an automation rule by its code. A new version with a different code will leave the configured scenarios broken.
4. Store the version of your data structure separately. Record it in the application data store or on your own side so that the new version's installer knows which migrations to apply.
5. Test the update on a test Bitrix24 instance. Install the previous version, configure scenarios on it — automation rules in pipelines, widgets, event subscriptions — and update to the new version. Make sure the installation wizard runs again and calls installFinish. Testing only a fresh installation is not enough.
6. Ensure backward compatibility of handlers. Users on different Bitrix24 instances do not update simultaneously, and your server will receive requests from both the old and new versions for some time.

Continue LearningContinue Learning

• Application Installation Options in Bitrix24
• App deletion
• Completing Application Installation
• Installation Wizard for Mass-Market Application