Page History

The Maintenance plugin can be used in combination with the solution import hooks to control the workflow when importing solutions into the Servoy Application Server.

The pre-import and post-import hooks i.c.w. the Maintenance plugin allow the automatic execution of administrative tasks on the Servoy Application Server while importing solutions, like:

• Send messages to connected clients, or even kill connected clients.
• Put the server into maintenance mode for the duration of the solution import.
• Perform operations on databases.

Solution Import Hooks
During solution import from the Servoy Admin Page, modules with solution import hook types are handled in a special way.
Their onOpen event handlers are executed before the solution is actually imported. Similarly, modules whose names start with "after_import" are handled as post-import hooks. Their onOpen event handlers are executed after the solution is actually imported.
If multiple import hook modules exists, they will be all handled in this way, but no handling order is guaranteed.

Pre & post import hook modules are to be self contained, meaning that they are not to rely on included modules.

During the execution of the onOpen event handlers from the pre & post import hooks, any output printed with application.output(...) will be redirected to the import log, which you can see in the Servoy Admin page.

Typical usage scenario

• Before importing the solution, connected clients are notified that an import will take place, then they are disconnected and then the server is put into maintenance mode, so that no new clients can connect during the import.
• The import is performed as usual.
• After the import is over, the server is taken out of maintenance mode, so that clients can connect again.

All these steps can be automated by creating a pre-import and a post-import hook module. The pre-import hook module can have the following function set as its onOpen event handler:

function onBeforeImportSolutionOpen()
{
	application.output("Putting server into maintenance mode...");
	plugins.maintenance.setMaintenanceMode(true);
	application.output("Notifying and disconnecting connected clients...");
	plugins.maintenance.sendMessageToAllClients("A solution upgrade will take place on the server. You will be disconnected in 2 minutes.");
	application.sleep(2 * 60 * 1000);
	plugins.maintenance.sendMessageToAllClients("A solution upgrade will take place on the server. You will be disconnected NOW.");
	plugins.maintenance.shutDownAllClients();
	application.output("Proceeding to import...");
}

This function puts the servoy Application Server into maintenance mode and sends a notification to all connected clients, telling them that in two minutes they will be disconnected. The function waits for two minutes, then it sends another message to the clients, telling them that they will be immediately disconnected. Then all connected clients are killed. From this moment on, no new client will be able to connect to the Server.

The post-import hook module can have the following function as its onOpen event handler:

function onAfterImportSolutionOpen()
{
	application.output("Taking server out of maintenance mode.");
	plugins.maintenance.setMaintenanceMode(false);
	application.output("Clients can now connect to the server.");
}

This function takes the Server out of maintenance mode, so that clients can again connect to it.

Modifying Database Structure and Content
Using the Maintenance plugin, it is possible to programmatically modify the database structure. It allows for tables to be created and dropped or modify existing tables by creating and deleting columns.

On solution import, Servoy will automatically create all missing tables and columns, based on the metadata confined in the solution export file. When more control is required on how the columns are created and/or columns need to be removed or altered, the pre import hook i.c.w. the Maintenance plugin allows the developer full control.

For example the following function, set as handler for the onOpen even of a pre-import hook, will delete a no longer needed column from a table.

function onSolutionOpenBeforeImport()
{
	var server = plugins.maintenance.getServer("example_data")
	if (server) {
		var table = server.getTable("todo_list")
		if (table) {
			table.deleteColumn("todo_list_suggested_by")
			var result = server.synchronizeWithDB(table)
			if (result)
				application.output("'Suggested By' column removed.")
			else
				application.output("Something went wrong while deleting column.")
		}
		else {
			application.output("Table 'todo_list' cannot be found.")
		}
	}
	else {
		application.output("Server 'example_data' cannot be found.")
	}
}

The function tries to obtain a reference to the server where the table is stored. If successful, then it tries to obtain a reference to the table which holds the obsolete column. If this step is also successful, then it deletes the column. In order to make the change permanent, the table must be synchronized with the underlying database.

In pre-import and post-import hooks, besides changing the database structure, you can also change the database content. This is done in the classical way, by using the foundset API.

It's also possible to use the rawSQL plugin to modify both data and the datamodel in the database. If changes are made to the datamodel this way, after completing the changes, the function JSServer.reloadDataModel(...) needs to be called, to make the Servoy Application Server aware of the changes made.

Maintenance plugin availablility
The Maintenance plugin is only available to the code being executed inside the pre and post import hooks. The plugin can not be used in normal clients

Debugging
While the maintanance plugins is only available during import on the Servoy Application Server, it works like a normal plugin in Servoy Developer as long the solution type is an import hook. Such an import hook solution can be started and debugged in any client type within Servoy Developer.