Once a Rocket.Chat app is created and introduced into a workspace, it undergoes a well-defined lifecycle managed by the Rocket.Chat server. This guide outlines the runtime lifecycle phases, their corresponding methods, and how developers can observe and control app behavior throughout each stage.
Overview
The app lifecycle in Rocket.Chat refers to the sequence of runtime phases that a custom or Marketplace app passes through, starting from installation, going through activation and configuration changes, and ending with uninstallation.
Apps can be installed via the Rocket.Chat Marketplace or manually uploaded as private apps. Once introduced, the server triggers a series of lifecycle events, each of which can be handled via corresponding lifecycle methods provided by the Apps-Engine.
In addition to standard software phases like design, QA, and release, Rocket.Chat apps go through these runtime lifecycle phases:
App installation
App deployment
App logging
App testing
Lifecycle activity in the Logs tab
In the Rocket.Chat Admin UI, apps appear with a status of either enabled or disabled.
To better understand how and when different lifecycle events occur, you can inspect the Logs tab on an app’s Info page. This view captures and displays lifecycle-specific log entries such as:
initializeonEnablesetStatusonSettingUpdated
The logs are displayed in a collapsible, paginated list and can be filtered by event type, timestamp, server instance, and severity level. This makes it easier to trace and debug the behavior of an app in production environments.
Controlling lifecycle behavior
Rocket.Chat exposes a series of extensible methods in the App class that let you control how the app behaves during different lifecycle phases.
Constructed: The app has just been created or instantiated. There is little an app can do at this point.
Initialize: The initialize phase is when the app is prepared by the Rocket.Chat server for activation. During this phase, the app can access configuration values from the Apps-Engine, register necessary objects, and set up internal functionality. If the initialize() method is implemented and returns true, the app continues through the activation process. This method allows the app to define its own initialization behavior, offering a way to customize or override the default setup provided by the Apps-Engine.
async initialize(configurationExtend: IConfigurationExtend, environmentRead: IEnvironmentRead): Promise<void>extendConfiguration: This method is executed as part of the app's default initialization procedure. The configuration accessor enables the app to provide robust functionality such as API Endpoints and Slash Commands using the configuration accessor.
async extendConfiguration(configuration: IConfigurationExtend, environment: IEnvironmentRead): Promise<void>Enable: The app will be enabled if the app parameters are configured correctly. This method is executed during the app's activation process. If it returns false, the Apps-Engine stops the enabling process and unloads the app's resources configured during initialization.
Auto_enabled: the app’sonEnable()function is called, returns true, and the app is enabled automatically (at system startup).Manually_enabled: the app’sonEnable()function is called, returns true, and the app is enabled by the user (such as installing a new app).
async onEnable (environment: IEnvironmentRead, configurationModify: IConfigurationModify): Promise<boolean>Disable: The app can be disabled, either automatically in response to a system interaction or manually through the marketplace. For instance - when Community workspaces have limitations, the apps will be disabled automatically depending on the limit on the number of apps that can be installed per workspace. If the app is a subscription app, it will be disabled when the subscription expires.
async onDisable(configurationModify: IConfigurationModify): Promise<void>Several additional app phases associated with disable are as follows:
App Phase | Description |
|---|---|
| An error occurred while attempting to compile the app, which rendered it inoperable. Attempts to re-enable it will fail, as it requires an update. |
| The app was disabled because its license was invalid. |
| The app was disabled due to an invalid installation or signature validation. |
| The app was disabled due to an unrecoverable error. |
| A user manually disabled the application. |
| The app was disabled due to invalid configuration settings. |
Install: This is only when the application is manually uploaded as a private app or installed through the marketplace. It only occurs once during installation. After installation, you can send messages to the admin notifying them about the availability of the app or send configuration steps and instructions on how to get started to the user who is installing the app.
async onInstall(context: IAppInstallationContext, read: IRead, http: IHttp, persistence: IPersistence, modify: IModify): Promise<void>Uninstall: This phase occurs when a user manually uninstalls an app. This is not feasible to occur automatically. Upon uninstallation, you can use this status to perform housekeeping, notify the server or an external service, or send a message to the user.
public async onUninstall(context: IAppUninstallationContext, read: IRead, http: IHttp, persistence: IPersistence, modify: IModify): Promise<void>SettingUpdated: For instance, the settings for an app can include tokens to authenticate with third-party services. When a change is made to such settings, the app can respond accordingly. The onSettingUpdated method is executed when an administrator modifies a setting provided by the app via the app administration page. This occurs following the update of a configuration. You can now retrieve the modified value.
async onSettingUpdated(setting: ISetting, configurationModify: IConfigurationModify, read: IRead, http: IHttp): Promise<void>PreSettingUpdate: This retrieves a modified parameter's before and after values. For example, if the user modifies a server URL, the app can attempt to connect to the new server to perform validations or seamlessly react to the change.
async onPreSettingUpdate(context: ISettingUpdateContext, configurationModify: IConfigurationModify, read: IRead, http: IHttp): Promise<ISetting>We have now taken a look at the various states of an app and the methods that represent them. With these methods, you can perform different actions for the states of the apps.