Plugin Version: 3.0.0|Release Notes


Overview

The Multitenant Workspace Management plugin allows a super user to manage workspaces directly inside the ProcessMaker interface. After logging into the "multitenant" workspace, the super user will be able to:

  • Create workspaces.
  • Backup workspaces.
  • Restore workspaces based on the generated backups.
  • Clone workspaces.
  • Delete workspaces.
  • Enable/Disable workspaces.

The backup, restore, clone and delete operations aren't executed in real time. Instead, they are executed in the background, when the plugin's mttCron.php file is evaluated.

Therefore, make sure that the server where ProcessMaker is installed is configured to execute this file periodically, either as a cron job in Linux/UNIX servers or as a Scheduled Task in Windows servers. Moreover, the user who configures the backup, restore, clone or delete workspaces operations will receive an email notification indicating that these operations were completed successfully.

Requirements

  • ProcessMaker Enterprise version 2.9 or higher with the corresponding license .

Supported Stacks

  • Check this documentation to view the table of ProcessMaker supported stacks.

Browser Requirements

  • To view the browsers supported check the following documentation.

Installation and Configuration

First of all, the Multitenant Workspace Management plugin needs to be installed and enabled inside ProcessMaker.

Login as a user, such as "admin", who has the PM_SETUP and PM_SETUPADVANCED permissions in his/her role. Then, go to ADMIN > Plugins > Enterprise Manager. Inside the Enterprise Plugins tab, download the "Multitenant Workspace Management" plugin inside the list of available plugins.

Alternatively, the plugin can be manually installed by clicking on the Install From File option.

Click on Browse to select the Multitenant Workspace Management plugin file.

When the plugin file is selected, click the Upload button. As soon as the plugin is uploaded to the ProcessMaker server, the plugin list will be refresehed and the Multitenant Workspace Management plugin will be listed as Disabled:

After that select Multitenant Workspace Management and click on Enable:

Its status should now be listed as Enabled and Installed if it is available to be used.

 

If the plugin has been properly installed, the Multitenant Installation option will appear under the Admin > Plugins sidebar

Click on this option and an installation wizard will appear:

Click on Next to begin configuring the plugin. In the next screen, specify the super user who will manage the workspaces:

These credentials will be used to login to the Multitenant Workspace Management interface.

To see a description of the field, mouse inside any of the fields to see its tooltip message:

If the password does not meet the password policies the Confirm Password field will be blocked:

 

Once the information is filled, click on the Install Multitenant Workspace option. Wait until the plugin has finished installing:

The following message will appear indicating that the workspace has been created:

Once the plugin has been installed, click on Next to finish the installation:

Finally click on Sign Up to be redirected to the Multitenant Manager Plugin. At this point it is necessary to upload the Enterprise license file, even if it has already been uploaded before. Upload the licence and click on Update License:

Once the license has been updated successfully, ProcessMaker will redirect the web browser to the login page:

Login with the super user credentials set during the installation, to enter the Multitenant interface:

Managing Roles and Permissions

The super user who was created during the initial configuration of the "multitenant" workspace has the PROCESSMAKER_ADMIN role, which has the following permissions to access all the functions in the Workspace Management interface:

PermissionsDescription
MTT_MULTITENANTAccess to the Multitenant tab.
MTT_LIST_ALL_WORKSPACESAbility to view the list of available workspaces.
MTT_NEW_WORKSPACE   Ability to create new workspaces.
MTT_BACKUP_WORKSPACEAbility to backup workspaces.
MTT_RESTORE_WORKSPACEAbility to restore workspaces from a backup file.
MTT_CLONE_WORKSPACEAbility to clone workspaces.
MTT_DELETE_WORKSPACEAbility to delete workspaces.
MTT_ENABLE_DISABLE_WORKSPACEAbility to disable or enable a workspace.
MTT_REFRESH_WORKSPACES_INFOAbility to refresh the workspace management interface.
MTT_MULTITENANT_LOGAccess to the Multitenant log

Additional users can be created with these permissions by going to Admin > Users and creating users with the PROCESSMAKER_ADMIN role. If wishing to give users access to some of the above funcions, but not all of them, then create a new role and assign some of the permissions to that role. Make sure to include the PM_LOGIN permission in the new role, so users can login to ProcessMaker. Then, assign users to that new role with limited functions.

Workspace Management Interface

The super user and other users with the above permissions in their role will be able to manage all the workspaces from one interface. To login to the Workspace Management interface, in the login screen of ProcessMaker set the Workspace to "multitenant":

Another way to select the "multitenant" workspace is to edit the URL of the login screen in the web browser so it directs to .../sysmultitenant/... :

After logging in, the following screen will appear:

  1. Main menu. It contains the main actions to manage workspaces using the plugin. Each of these options is explained below.
  2. Search field. Enter the name of the workspace to search for. This field uses autocomplete to offer possible matches while entering the workspace name.
  3. Workspace information. It displays information about the workspace such as its name, cases, disk usage, tables and statistics, which are explained below.

Main Menu

The Multitenant menu buttons are located in the top part of the panel under the “Workspace Management” logo and it contains the following options to manage workspaces:

  • New workspace
  • Backup workspace
  • Restore workspace
  • Clone workspace
  • Delete workspace
  • Disable workspace
  • Refresh information.

Some of these actions will be executed when the user clicks on the option in the Multitenant Management interface, but the options to backup, restore or clone a workspace are not executed in real time. Instead, they are set as pending actions that will be executed when the multitenant cron file which is named mttCron.php is executed.

Note: Only one pending action can be executed at a time on a workspace, so the mttCron.php file needs to be executed before a second pending action can be executed on the same workspace.

New Workspace

Select this option to start the creation of a new workspace. Fill in the following information about the new workspace:

  • Name. Enter a name for the new workspace, which is 13 characters or less. It is recommended to only use ASCII letters, numbers and underscores ("_") to avoid problems.
  • Database options. This section defines the MySQL database that will be created to hold data for the new workspace. Each database name can only have 16 characters or less. By default, prefix "wf_" is added to the workspace name.

o    Workflow database. The name of the database which will hold data about processes, cases, users, report tables, etc.  Note: In version 3.0 and later, only one database is used per workspace, whereas previous versions used 3 databases.
o    Drop database if exists. Check this option to delete any existing databases which have the same name as the ones above. In most cases it is not recommended to check this option in most cases.

  • Workspace administrator. Defines the administrator credentials for the new workspace. This user will have "PROCESSMAKER_ADMIN" role which has permissions for all the ProcessMaker functions.

o    Username. Enter the username of the administrator of the new workspace. By default, the username is "admin".
o    Password. Enter the password of the administrator of the new workspace. By default, the password is "admin".
o    Re-type password. The password must be entered twice to confirm it.

After filling out the form, click on “Test” to check whether the entered values are valid and don't conflict with the names of existing MySQL databases. A new message window will open asking if you want to create the new workspace.

Click “No” to close the window and return to the creation window, or click “Yes” to start the creation of the new workspace. After the workspace has been created, a new message window will appear to confirm that the workspace was created:

The workspace which was created will be added to the list of existing workspaces:

To login with the new workspace, is necessary to upload again the Enterprise licence file. A license file must be uploaded for each new workspace which is created, but the same license file can be used for all the workspaces and there is no limit to the number of workspaces which can be created per license.

Backup Workspace

To make a backup of the workspace, first click on the name of the workspace to select it. It will be highlighted in a light blue color, then go to the main menu and select the option: "Backup Workspace":

A new window will open where a short description must be entered for the workspace backup. It can not be more than 20 characters long.

After entering the description, click on “Ok” to start the backup operation, or click on “Cancel” to close the window and return to the previous list.

A message will appear indicating that the backup operation will run in the background:

And its status will change to Backing Up:

The backup file for the workspace will be created the next time the mttCron.php file is executed.

Note: The workspace backup won't be listed in the workspace management list.

When the backup operation finishes, the following email message will be sent to the super user:

Restore Workspace

To restore a workspace from a previous backup, first select the workspace that will be restored. It will be highlighted in a light blue color and click on the Restore Worksapce option:

The following window will display where the backup wanted to be restored will be listed; besides the name of the backup it will include the ProcessMaker version in which the backup was made.

Of more than one backup was generated, those will be listed in the restore list:

Select the backup and click on Ok, the following message will display indicating the operation will be running in background:

And its status will change to Restoring:

The pending restore operation will be completed the next time the mttCron.php file is executed. When the restore operation finishes the following notification will be sent to the user who executed this operation:

Clone Workspace

This option makes a copy of all existing data of a workspace into an existing or new. To clone a workspace, first, select it in the list and go to the main menu and select the option: “Clone Workspace”.

A new window will open where you must fill the necessary information to clone the workspace.

Where:

  • Source workspace. It shows the name of the selected workspace to be cloned.
  • Create clone from. By default, it is set as “Current Version”; nevertheless, if one or more backups of the workspace exist they will be listed in the drop down list.

  • Target workspace. By default, it shows the “New Workspace” option; nevertheless, it is possible to clone a workspace into another. Select among the drop down list the workspace where the copy will be done, remember that all data of the workspace selected will be lost when the cloning is done.

  • New workspace name. This field is only available if the previous field is set as “New Workspace”; write the name of the new workspace where the cloning will be done.

Click “Cancel” to close the window and cancel the operation or click “Ok” to start the cloning of the workspace, the operation will run in background:


And its status will change to Cloning:

Schedule the cron to be executed depending on the process requirements. If cron is executed manually the following message will display:

 

[root@gendoctesting opt]# php -f /opt/processmaker/workflow/engine/plugins/pmWorkspaceManagement/bin/mttCron.php<br>Processing multitenant cron<br>Operations completed

 

When the clone operation finishes the following notification will be sent to the user who executed this operation:

Delete Workspace

Select this option to completely delete all data of a workspace. Select the workspace you want to delete, then go to the main menu and click on the Delete Workspace option:

A message window will ask if you really want to delete the selected workspace.

Select “Cancel” to close the window, or click “Ok” to delete the workspace. The delete operation will run in background:

As soon as the mttCron.php file is executed and the Refresh Information button is clicked, the workspace will be removed from the list.

Also, when the delete operation finishes the following notification will be sent to the user who executed this operation:

Disable Workspace

This option allows disabling a workspace, so it will not be available if a user wants to access it. Select the workspace you want to disable, then go to the main menu and select the option “Disable Workspace”.

A message window will open asking if you really want to disable the workspace.

Click “Ok” to change the status of the workspace. Another window will open with the success or fail message.

The status of the workspace will be “Disabled” in the configuration column.

To enable the workspace, select it and the option “Enable Workspace” will be available in the main menu.

Once the workspace is enabled the following message will appear:

Refresh Information

Select this option to refresh the information of the workspaces management. A message window will open asking if you really want to refresh the information because it may take a while.

Click “No” to cancel the operation or click “Yes” to refresh the information.

Workspace Information

Each item in the list represents a workspace. And in each workspace the plugin shows detailed information about the data that is included in the workspace classified by columns.

The columns and the information they carry are explained next.

Workspace

This column shows only the name of the workspace.

Cases

This column shows information about all cases held in the workspace.

  • Todo. Shows the number of all cases stored in the inbox from all users.
  • Cancelled. Shows the number of cases that have been ‘cancelled’.
  • Paused. Shows the number of all cases that were paused during their execution.
  • Completed. It shows the number of cases that reached an end event in their execution.
  • Draft. Includes cases that are being edited or advanced by the user but have not yet been submitted to the next task.

Disk Usage

This section shows the disk usage of both the workspace and the database.

Tables

  • InnoDB. Shows the number of tables held by the InnoDB engine.
  • MyISAM. Shows the number of tables held by the MyISAM engine.

Statistics

  • Active Processes. Shows the number of processes being currently executed.
  • Number of users. Shows the number of users in the workspace.

Configuration

Status. Shows the current status of the workspace, it could be “enabled” or “disabled”.

Multitenant Manager Log

Access the multitenant manager log

The multitenant log allows administrator users who have the MTT_MULTITENANT_LOG permissions assigned to his/her role. The records of the log can be used to check what actions users have executed.

Search Panel

This section allows searching information under the following criteria:

  • Date from: Search for operations made from a certain date. Click inside the textarea to enable the date picker:

  • Date to. Search for operations that were last executed. Click inside the textarea to enable the date picker:

  • Operation.  Search for the following operations: Any, backup, restore, clone, delete, disable, enable and create workspaces.

  • Result. Filter information according to two results: Successful and Unsuccessful.
  • IP Address. Search results according to the IP Address form where the operations were executed.
  • Content.  Search the information listed in columns, description and details columns.

Number of workspaces will be listed in the panel. Each item in the list shows the logs generated by the “Workspace Management”. It shows the following details:

  • ID
  • Date & Time
  • IP
  • Action
  • Type
  • Description
  • Details

To view the log entry of any of them, click on the item and a new window will open:

 

For instance, if looking for information about successful backups operations, the results will be:

Executing mttCron.php

In order for pending actions to be executed in the Multitenant Workspace Management plugin, the mttCron.php file must be executed. This file can be manually executed by opening a command-line terminal on the server where ProcessMaker is installed and issuing the following command:

php -f {INSTALL-DIRECTORY}/workflow/engine/plugins/pmWorkspaceManagement/bin/mttCron.php

Example in Linux/UNIX:

php -f /opt/processmaker/workflow/engine/plugins/pmWorkspaceManagement/bin/mttCron.php

Example in Windows Vista or later:

"C:\Users\USERNAME\AppData\Roaming\ProcessMaker-X_X_X\php\php.exe" -f "..\..\processmaker\workflow\engine\plugins\pmWorkspaceManagement\bin\mttCron.php"

Example in Windows XP/2003:

"C:\Program Files\ProcessMaker-X_X_X\php\php.exe" -f "..\..\processmaker\workflow\engine\plugins\pmWorkspaceManagement\bin\mttCron.php"

It can take mttCron.php up to an hour to clone or restore a workspace, so be prepared for a long wait if one of those actions is being executed. When mttCron.php has finished, it will display the words "Operations completed":

# php /opt/processmaker/workflow/engine/plugins/pmWorkspaceManagement/bin/mttCron.php
Processing multitenant cron
Operations completed

Note: If an error occurs while restoring a workspace, then redo the restore operation. If the cloning of a workspace is cut short and does not complete, the following error message will be displayed when the Refresh Information button is clicked:

There is no way to continue when cloning of a workspace has been cut short. The only solution is to delete the files and database which were created by cloning and clone the workspace again. The workspace files to be deleted are located at {INSTALL-DIRECTORY}/shared/sites/{CLONE-NAME}. If using Linux/UNIX, the root user on the ProcessMaker server can delete the cloned workspace files with the following command in a terminal:

rm -rf /opt/processmaker/shared/sites/CLONE-NAME

Then, login to MySQL as the root user and delete the cloned workspace database which is generally 1 database named wf_{CLONE-NAME} in version 2.8 and later or 3 databases (wf_{CLONE-NAME}, rb_{CLONE-NAME} and rp_{CLONE-NAME}) in earlier versions. For example:

mysql -u root -p
mysql> show databases;
mysql> drop database wf_myclone;
mysql> exit;

It is recommended to set the mttCron.php file to periodically execute on the server where ProcessMaker is installed, either as a cron job in Linux/UNIX or a Scheduled Task in Windows.

Example in Linux/UNIX:

To execute the mttCron.php file every 30 minutes on a Linux/UNIX server, add the following line to the /etc/crontab file:

*/30 * * * * root php -f /opt/processmaker/workflow/engine/plugins/pmWorkspaceManagement/bin/mttCron.php

Example in Windows Vista or later:

To execute the mttCron.php file every 30 minutes on a Windows server, open a terminal and issue the following command:

SCHTASKS /Create /U administrator /P p4s5w0rd /SC MINUTE /MO 30 /TR ^
"C:\Users\USERNAME\AppData\Roaming\ProcessMaker-X_X_X\php\php.exe -f ..\..\processmaker\workflow\engine\bin\cron.php"