Please rate how useful you found this document: 
Average: 3.4 (8 votes)

Overview

ProcessMaker holds vital information about your organization's users and their work; therefore, it is very important to setup a backup system to safeguard the data being stored in ProcessMaker. If periodic backups aren't being made, one lightning strike or an accidental deletion of key files on your system could bring your organization to a grinding halt. Backups can also be very useful for returning to a previous state after making experimental changes to your system or backing up ProcessMaker.

It is recommended that your entire system be backed up in case the entire operating system needs to be restored. For the data stored in ProcessMaker, it is recommended to periodically backup your workspaces. Depending on how critical your data is and how often it is being updated, a daily backup or a weekly backup would be appropriate.

In general, it is recommended to backup and restore workspaces in the same version of ProcessMaker, because the database structure and file structure can change from one version of ProcessMaker to the next. Nonetheless, it is possible to backup a workspace from version 2.5.X and restore it in version 2.8 or version 3.0.

Note: It is recommended to have MySQL installed on the server at least as a service. Otherwise, MySQL will be executed externally, which will slow the response time of the backup/restore process.

Tested Systems

Backing up and restoring workspaces has been tested in the following systems. It will probably work in other systems as well, but it hasn't been tested.

Backup From Restore To
CentOS 7: php 5.4 + apache 2.4 + mysql 5.6
CentOS 7CentOS 6.3
CentOS 7CentOS 6.6
Centos 6.3: php 5.3 + apache 2.2.15
CentOS 6.3CentOS 7 (*)
Centos 6.6: php 5.4 + apache 2.2.15
CentOS 6.6CentOS 7 (*)
CentOS 6.6CentOS 6.3

(*) Even though there is a warning with mysql_connect(), the restore procedure finishes successfully.

Backup FromRestore To
Windows server 2012Windows Server 2012
Windows 8.1Windows Server 2012

Note that some issues were found when restoring backups from Windows 8.1 to Windows 8.1 and from Windows Server 2012 to Windows v. 8.1. These issues will be solved in future versions.

Note: The restoration and backup of a workspace can only be made in the same platform (Windows -> Windows, Linux -> Linux), because the names of the MySQL tables in Windows are not case sensitive, which may cause ProcessMaker to have problems.

Before Backing Up and Restoring Workspaces

Before backing or restoring a workspace, follow the next steps:

Step 1: In the server where ProcessMaker is running, open a command line prompt.

To open a command line prompt in Windows go to Start > All Programs > Accessories > Command Prompt. In most Linux/UNIX systems, it can be found under Accessories > Command Prompt.

Step 2: In the server where ProcessMaker is running, login as the root user or administrator. On Windows systems, start the command prompt as the administrator. On Linux/UNIX systems, open a terminal and login as root user or use the sudo command to gain root privileges:

su or sudo -i

Note: To avoid permission problems when running processmaker command in Linux, use the following best practice: Run the processmaker command using the apache user permissions. To do so, ownership of the ProcessMaker directory must belong to the apache user, so that Apache can read and write data. The -R option makes the ownership changes recursive, so it applies to all files and subdirectories within /opt/processmaker.

chown -R apache:apache /opt/processmaker

The Apache user and group is apache:apache in CentOS/Red Hat, www-data:www-data in Debian/Ubuntu and wwwrun:www in SUSE/OpenSUSE.

Step 3: Navigate to the directory where ProcessMaker is installed. For example:

Manual install in Linux/UNIX:

cd /opt/processmaker

Bitnami install in Linux/UNIX:

cd /opt/processmaker-3.X.X.b1-0/apps/processmaker/htdocs

Manual install in Windows:

cd C:\opt\processmaker

Bitnami install in Windows:

cd C:\Bitnami\processmaker-3.X.X-1\apps\processmaker\htdocs

Automatic install of version 3.0.1.7 and earlier in Windows:

cd C:\Users\USERNAME\AppData\Roaming\ProcessMaker-3_0_X_X\processmaker

Note: The AppData directory is a hidden directory, but the File Explorer can be configured to show hidden files.

Backing Up Workspaces

The workspace backup utility creates a tar file that contains a dump of the database for each workspace and its associated files, which are stored in the INSTALL-DIRECTORY/shared/sites/{WORKSPACE}/ directory. Additional workspaces can be created in ProcessMaker, but most installations of ProcessMaker will have the default "workflow" workspace, which uses the wf_workflow database and stores its files in the INSTALL-DIRECTORY/shared/sites/workflow/ directory.

Note for Linux/UNIX: If the shared directory has been set to 770 permissions for security reasons, then log in as "root" or use the sudo command when backing up a workspace. Another option is to add your user to the apache group (which is "apache" for Red Hat/CentOS/Fedora, "www-data" for Debian/Ubuntu, and "www" for SUSE/OpenSUSE), so that the user can do backups:

useradd -G apache-group username

Issue the command to back up a workspace:

LINUX/UNIX:

php processmaker workspace-backup [WORKSPACE-NAME] [BACKUP-FILE]

Windows:

PHP-DIRECTORY\php.exe processmaker workspace-backup [WORKSPACE-NAME] [BACKUP-FILE]

Remember that workspace names are case sensitive.

By default, the backup file will be created at:
    INSTALL-DIRECTORY/shared/backups/workspace.tar

However, the location of the backup file can be specified with the optional [BACKUP-FILE] parameter. This parameter can include forward slashes "/" to specify a path in Linux/UNIX or backward slashes "\" to specify a path in Windows. If the path or filename contains spaces, enclose it in quotation marks. If using a relative path, then it will start from the location of the processmaker script. If no path is specified, then the file will be created in the INSTALL-DIRECTORY/shared/backups directory.

Examples:

Backup the default "workflow" workspace on a Linux/UNIX server to the location /opt/processmaker/shared/backups/workflow.tar:

php processmaker workspace-backup workflow

Backup the "sales" workspace on a Linux/UNIX server to the location /home/fred/store/pm_sales.tar:

php processmaker workspace-backup sales /home/fred/store/pm_sales.tar

Backup the "Finance" workspace to the location /opt/store/Finance/FinanceBackup.tar, using a relative path:

php processmaker workspace-backup Finance ../store/FinanceBackup.tar

Backup the "sales" workspace on a Windows server to the location C:\Documents and Settings\Amos\sales backup.tar. Remember to enclose paths and filenames with spaces in quotation marks:

PHP-DIRECTORY\php.exe processmaker workspace-backup sales "C:\Documents and Settings\Amos\sales backup.tar"

For help using the workspace-backup option, enter the command:

php processmaker help workspace-backup

While executing a workspace backup, the output will indicate which tables are being backed up and print a summary of the backup at the end, similar to the following:

php processmaker workspace-backup workflow
Backing up to /opt/processmaker/shared/backups/workflow.tar
Backing up database...
Saving database wf_workflow30001
LOCK TABLES                                                               [OK]
Dump of table ABE_CONFIGURATION                                  0 Bytes Saved
Dump of table ABE_REQUESTS                                       0 Bytes Saved
Dump of table ABE_RESPONSES                                      0 Bytes Saved
Dump of table ADDITIONAL_TABLES                                  0 Bytes Saved
Dump of table ADDONS_MANAGER                                  2466 Bytes Saved
Dump of table ADDONS_STORE                                       0 Bytes Saved
Dump of table APPLICATION                                     3056 Bytes Saved
Dump of table APP_ASSIGN_SELF_SERVICE_VALUE                      0 Bytes Saved
Dump of table APP_CACHE_VIEW                                  3721 Bytes Saved
Dump of table APP_DELAY                                        303 Bytes Saved
Dump of table APP_DELEGATION                                  2559 Bytes Saved
Dump of table APP_DOCUMENT                                       0 Bytes Saved
Dump of table APP_EVENT                                          0 Bytes Saved
Dump of table APP_FOLDER                                         0 Bytes Saved
Dump of table APP_HISTORY                                        0 Bytes Saved
Dump of table APP_MESSAGE                                        0 Bytes Saved
Dump of table APP_NOTES                                          0 Bytes Saved
Dump of table APP_OWNER                                          0 Bytes Saved
Dump of table APP_SOLR_QUEUE                                     0 Bytes Saved
Dump of table APP_THREAD                                       372 Bytes Saved
Dump of table APP_TIMEOUT_ACTION_EXECUTED                        0 Bytes Saved
Dump of table BPMN_ACTIVITY                                    929 Bytes Saved
Dump of table BPMN_ARTIFACT                                      0 Bytes Saved
Dump of table BPMN_BOUND                                      2762 Bytes Saved
Dump of table BPMN_DATA                                          0 Bytes Saved
Dump of table BPMN_DIAGRAM                                     140 Bytes Saved
Dump of table BPMN_DOCUMENTATION                                 0 Bytes Saved
Dump of table BPMN_EVENT                                       767 Bytes Saved
Dump of table BPMN_EXTENSION                                     0 Bytes Saved
Dump of table BPMN_FLOW                                       2345 Bytes Saved
Dump of table BPMN_GATEWAY                                     217 Bytes Saved
Dump of table BPMN_LANE                                        358 Bytes Saved
Dump of table BPMN_LANESET                                     184 Bytes Saved
Dump of table BPMN_PARTICIPANT                                   0 Bytes Saved
Dump of table BPMN_PROCESS                                     194 Bytes Saved
Dump of table BPMN_PROJECT                                     213 Bytes Saved
Dump of table CALENDAR_ASSIGNMENTS                               0 Bytes Saved
Dump of table CALENDAR_BUSINESS_HOURS                          106 Bytes Saved
Dump of table CALENDAR_DEFINITION                              188 Bytes Saved
Dump of table CALENDAR_HOLIDAYS                                  0 Bytes Saved
Dump of table CASE_CONSOLIDATED                                  0 Bytes Saved
Dump of table CASE_SCHEDULER                                     0 Bytes Saved
Dump of table CASE_TRACKER                                       0 Bytes Saved
Dump of table CASE_TRACKER_OBJECT                                0 Bytes Saved
Dump of table CATALOG                                         1111 Bytes Saved
Dump of table CONFIGURATION                                    261 Bytes Saved
Dump of table CONTENT                                         5477 Bytes Saved
Dump of table DASHBOARD                                          0 Bytes Saved
Dump of table DASHBOARD_DAS_IND                                  0 Bytes Saved
Dump of table DASHBOARD_INDICATOR                                0 Bytes Saved
Dump of table DASHLET                                         1008 Bytes Saved
Dump of table DASHLET_INSTANCE                                1139 Bytes Saved
Dump of table DB_SOURCE                                          0 Bytes Saved
Dump of table DEPARTMENT                                         0 Bytes Saved
Dump of table DIM_TIME_COMPLETE                                  0 Bytes Saved
Dump of table DIM_TIME_DELEGATE                                  0 Bytes Saved
Dump of table DYNAFORM                                           0 Bytes Saved
Dump of table ELEMENT_TASK_RELATION                              0 Bytes Saved
Dump of table EMAIL_SERVER                                      98 Bytes Saved
Dump of table EVENT                                              0 Bytes Saved
Dump of table FIELDS                                             0 Bytes Saved
Dump of table FIELD_CONDITION                                    0 Bytes Saved
Dump of table GATEWAY                                            0 Bytes Saved
Dump of table GROUPWF                                            0 Bytes Saved
Dump of table GROUP_USER                                         0 Bytes Saved
Dump of table HOLIDAY                                            0 Bytes Saved
Dump of table INPUT_DOCUMENT                                     0 Bytes Saved
Dump of table ISO_COUNTRY                                    14834 Bytes Saved
Dump of table ISO_LOCATION                                 3988501 Bytes Saved
Dump of table ISO_SUBDIVISION                                64199 Bytes Saved
Dump of table LANGUAGE                                       11823 Bytes Saved
Dump of table LEXICO                                             0 Bytes Saved
Dump of table LICENSE_MANAGER                                    0 Bytes Saved
Dump of table LIST_CANCELED                                      0 Bytes Saved
Dump of table LIST_COMPLETED                                     0 Bytes Saved
Dump of table LIST_INBOX                                         0 Bytes Saved
Dump of table LIST_MY_INBOX                                      0 Bytes Saved
Dump of table LIST_PARTICIPATED_HISTORY                          0 Bytes Saved
Dump of table LIST_PARTICIPATED_LAST                             0 Bytes Saved
Dump of table LIST_PAUSED                                        0 Bytes Saved
Dump of table LIST_UNASSIGNED                                    0 Bytes Saved
Dump of table LIST_UNASSIGNED_GROUP                              0 Bytes Saved
Dump of table LOGIN_LOG                                        214 Bytes Saved
Dump of table LOG_CASES_SCHEDULER                                0 Bytes Saved
Dump of table MESSAGE_APPLICATION                                0 Bytes Saved
Dump of table MESSAGE_EVENT_DEFINITION                           0 Bytes Saved
Dump of table MESSAGE_EVENT_RELATION                             0 Bytes Saved
Dump of table MESSAGE_TYPE                                       0 Bytes Saved
Dump of table MESSAGE_TYPE_VARIABLE                              0 Bytes Saved
Dump of table OAUTH_ACCESS_TOKENS                              202 Bytes Saved
Dump of table OAUTH_AUTHORIZATION_CODES                          0 Bytes Saved
Dump of table OAUTH_CLIENTS                                    275 Bytes Saved
Dump of table OAUTH_REFRESH_TOKENS                             203 Bytes Saved
Dump of table OAUTH_SCOPES                                       0 Bytes Saved
Dump of table OBJECT_PERMISSION                                  0 Bytes Saved
Dump of table OUTPUT_DOCUMENT                                    0 Bytes Saved
Dump of table PMOAUTH_USER_ACCESS_TOKENS                       217 Bytes Saved
Dump of table PROCESS                                          339 Bytes Saved
Dump of table PROCESS_CATEGORY                                   0 Bytes Saved
Dump of table PROCESS_FILES                                      0 Bytes Saved
Dump of table PROCESS_OWNER                                      0 Bytes Saved
Dump of table PROCESS_USER                                       0 Bytes Saved
Dump of table PROCESS_VARIABLES                                  0 Bytes Saved
Dump of table PRO_REPORTING                                      0 Bytes Saved
Dump of table RBAC_AUTHENTICATION_SOURCE                         0 Bytes Saved
Dump of table RBAC_PERMISSIONS                                3417 Bytes Saved
Dump of table RBAC_ROLES                                       729 Bytes Saved
Dump of table RBAC_ROLES_PERMISSIONS                          4248 Bytes Saved
Dump of table RBAC_SYSTEMS                                     270 Bytes Saved
Dump of table RBAC_USERS                                       534 Bytes Saved
Dump of table RBAC_USERS_ROLES                                 224 Bytes Saved
Dump of table REPORT_TABLE                                       0 Bytes Saved
Dump of table REPORT_VAR                                         0 Bytes Saved
Dump of table ROUTE                                            976 Bytes Saved
Dump of table SEQUENCES                                         52 Bytes Saved
Dump of table SESSION                                            0 Bytes Saved
Dump of table SESSION_STORAGE                                    0 Bytes Saved
Dump of table SHADOW_TABLE                                       0 Bytes Saved
Dump of table STAGE                                              0 Bytes Saved
Dump of table STEP                                               0 Bytes Saved
Dump of table STEP_SUPERVISOR                                    0 Bytes Saved
Dump of table STEP_TRIGGER                                       0 Bytes Saved
Dump of table SUB_APPLICATION                                    0 Bytes Saved
Dump of table SUB_PROCESS                                        0 Bytes Saved
Dump of table SWIMLANES_ELEMENTS                                 0 Bytes Saved
Dump of table TASK                                            1549 Bytes Saved
Dump of table TASK_USER                                        230 Bytes Saved
Dump of table TRANSLATION                                   375013 Bytes Saved
Dump of table TRIGGERS                                           0 Bytes Saved
Dump of table USERS                                            806 Bytes Saved
Dump of table USERS_PROPERTIES                                 320 Bytes Saved
Dump of table USR_REPORTING                                      0 Bytes Saved
Dump of table WEB_ENTRY                                          0 Bytes Saved
Dump of table WEB_ENTRY_EVENT                                    0 Bytes Saved
UNLOCK TABLES                                                             [OK]
Copying database to backup...
 + /opt/processmaker/shared/upgrade/DTgnB7
Copying files to backup...
 + /opt/processmaker/shared/sites/workflow

ProcessMaker Version 3.0-GA-community
              System CentOS release 6.5 (Final) (Linux)
         PHP Version 5.4.37
      Server Address 192.168.1.228
   Client IP Address 192.168.0.124
             Plugins charts
                     openFlash
                     pmosCommunity
                     processTemplate

      Workspace Name workflow
   Workflow Database mysql://wf_workflow30001:r93fh2vx1zb0@localhost/wf_workflow30001
       MySql Version MySql (Version 5.5.41)

Backing Up Bigger Workspaces

Note: This parameter can NOT be used on Windows systems.

If ProcessMaker is installed on a 32 bit Linux/UNIX system that does not have Large File Support enabled, then the .tar backup file can not be larger than 2GB in size.
To back up a workspace that is larger than 2 GB, use the -s:[MAX-SIZE] or --filesize=[MAX-SIZE] option to break the backup file into multiple compressed files:

php processmaker workspace-backup -s[MAX-SIZE] [WORKSPACE-NAME] [BACKUP-FILE]

By default, the maximum size of the backup file is 1000 megabytes. To use a different maximum file size, set the [MAX-SIZE] in megabytes.

For example, if this option is set to 512 when backing up the "dev" workspace on a Linux system:

php processmaker workspace-backup -s512 dev

Then, a 1.5 GB backup will produce 3 backup files named dev.tar.01, dev.tar.02 and dev.tar.03.

Backing Up Multiple Workspaces

Back up multiple workspaces at the same time with the command:

php processmaker workspace-backup [WORKSPACE1] [WORKSPACE2] [WORKSPACE3] [BACKUP-FILE]

Separate each workspace name with a space. The last parameter will be considered the name of the backup file.

For example, to backup the "workflow", "sales" and "Finance" workspaces to the file "pmBackup.tar":

php processmaker workspace-backup workflow sales Finance pmBackup.tar

Automating Backups

Backups should be made periodically, so it is best to automate the backup process.

Linux/UNIX

In Linux/UNIX, the backups can be scheduled as a cron job. For more information on the format of the crontab file, see Configuring crontab in Linux/UNIX.

For example, the following line can be added to the /etc/crontab file to automatically backup the "workflow" workspace every 12 hours and save it to a file at /opt/processmaker/backups/workflow.tar:

* */12 * * *  root  /opt/processmaker/processmaker workspace-backup workflow
Inserting Date/Time in File Names

Since the backup file will be overwritten every 12 hours, it will not be possible to use the processmaker script's workspace-restore command to roll the workspace back to a state older than 12 hours.

For example, if a database was corrupted 3 days ago, the backup file will have already been overwritten, so it isn't possible to recover the old database. Therefore, it is recommended to use a time stamp in the backup file name, so multiple backup files can be maintained. However, old backup files also need to be periodically eliminated so that the backups don't eat up all the hard drive space on the server.

These cron jobs can be used to make a backup file every 12 hours and save it to a file at /root/backups/workflow_YYYY-MM-DD_HH-MM.tar, as well as automatically delete the old backup files more than 30 days old:

* */12 * * *  root  /opt/processmaker/processmaker workspace-backup workflow /root/backups/workflow_`date +%F_%H-%M`.tar
* */23 * * *  root  tmpwatch 720 /root/backups

The current date and time is automatically inserted into the filename with the date command, such as workflow_2011-03-21_12-01.tar. Make sure to use `` (backticks), so Linux/UNIX will execute the date command, rather than treating it like a quoted string.

The second command automatically deletes any files older than 30 days (30days x 24hours = 720hours) in the /root/backups/ directory every night at midnight, so old backup files will not occupy too much space. If on a Debian/Ubuntu/Mint server, use the tmpreaper command instead of tmpwatch.

Storing Backups Remotely

It is recommended to keep backup copies on a different server (in a different location), so that a hard drive failure or lightning strike won't also destroy the backup copies on the ProcessMaker server. The following script located at /usr/local/bin/pmbackup.sh can be used to make a backup of the "workflow" workspace and store it in another location:

#!/bin/bash
CURDATE=$(date +%F_%H-%M)
/opt/processmaker/processmaker workspace-backup workflow /root/backups/workflow_$CURDATE.tar
gzip /root/backups/workflow_$CURDATE.tar
scp /root/backups/workflow_$CURDATE.tar.gz root@backups.example.com:/root/backups/
rm /root/backups/workflow_$CURDATE.tar.gz

Make sure that the script file is executable:

chmod +x /usr/local/bin/pmbackup.sh

To copy the backup files to the remote server at backups.example.com without having to enter a password for the root user, generate a public/private key with the command:

ssh-keygen -t rsa

Add the public key to the /root/.ssh/authorized_keys file in the backups.example.com server. For more information, see this article.

Then, add the pmbackup.sh script as a cron job on the ProcessMaker server by adding the following line to the /etc/crontab file:

* */23 * * *  root  /usr/local/bin/pmbackup.sh

Windows

On Windows systems, workspaces can be periodically backed up as a scheduled task. Use the SCHTASKS command in DOS to create a scheduled task that periodically executes the processmaker workspace-backup command. For more information on using the SCHTASKS command, see Executing cron.php with the SCHTASKS command.

Examples:

1. Backup the default "workflow" workspace every day at midnight on a ProcessMaker server installed at C:\Users\Bob\AppData\Roaming\ProcessMaker-3_0_0\processmaker:

SCHTASKS /Create /U administrator /P p4s5w0rd /SC DAILY /ST 00:00 /TN PMBackup /TR "C:\Users\Bob\AppData\Roaming\ProcessMaker-3_0_0\processmaker\processmaker workflow-backup workflow"

2. Backup the "sales" workspace to the file C:\Documents and Settings\Bob\Backups\sales workspace.tar every Sunday and Wednesday at midnight on a ProcessMaker server installed at C:\Program Files\ProcessMaker-3_0_0\processmaker:

SCHTASKS /Create /U administrator /P p4s5w0rd /SC WEEKLY /D SUN,WED /ST 00:00 /TN PMBackupSunWed /TR "'C:\Program Files\ProcessMaker-3_0_0\processmaker\processmaker' workflow-backup sales 'C:\Documents and Settings\Bob\Backups\sales workspace.tar'"

Notice how paths and file names that contain spaces are enclosed inside single quotation marks.

3. Backup the "sales" workspace to the file SalesBackup.tar on the 15th of every month at 11pm:

SCHTASKS /Create /U administrator /P p4s5w0rd /SC MONTHLY /D 15 /ST 23:00 /TN PMBackup15Month /TR "C:\Users\Bob\AppData\Roaming\ProcessMaker-2_0_30\processmaker\processmaker workflow-backup sales SalesBackup.tar"
Inserting Date/Time in File Names

It is not possible to insert the current date and time into the backup file name using the system %date% and %time% variables, since SCHTASKS treats them as literal strings. Instead, create a .bat file to execute the processmaker workspace-backup command. For example, the file C:\Users\Bob\pmbackup.bat contains:

C:\Users\Bob\AppData\Roaming\ProcessMaker-3_0_0\processmaker\processmaker workflow-backup workflow workflow-%date%-%time%.tar

Then, use the SCHTASKS command to schedule the periodic execution of the C:\Users\Bob\pmbackup.bat file:

SCHTASKS /Create /U administrator /P p4s5w0rd /SC DAILY /ST 13:00 /TN PMBackupBat /TR "C:\Users\Bob\pmbackup.bat"
Storing Backups Remotely

To securely copy files from Windows, install PuTTY's pscp program on the ProcessMaker server. Then, create a .bat file to execute the processmaker workspace-backup command and use pscp to copy the backup file to a remote server.

For example, the file C:\Documents and Settings\Bob\pmbackup.bat contains the following code to copy the backup file to the /root/backups directory on a remote Linux/UNIX server with a domain name of "example.com":

"C:\Program Files\ProcessMaker-3_0_0\processmaker\processmaker" workflow-backup workflow ^
"C:\Program Files\PuTTY\PSCP.EXE" -pw p4s5w0rd "C:\Program Files\ProcessMaker-2_0_30\processmaker\backups\workflow.tar" root@example.com:/root/backups/workflow-%date%-%time%.tar

Then, use the SCHTASKS command to schedule the periodic execution of the C:\Documents and Settings\Bob\pmbackup.bat file:

SCHTASKS /Create /U administrator /P p4s5w0rd /SC DAILY /ST 00:00 /TN UploadPMBackup /TR "Documents and Settings\Bob\pmbackup.bat"

To copy the backup files to a remote Windows server, install an SSH server on the remote Windows server (with programs such as freeSSHd, CygWin or WinSSHD), so it can accept secure file transfers. Another option is using PuTTY's psftp command to transfer the files using the SFTP protocol.

Errors While Backing Up Workspaces

The following section displays possible error while backing up workspaces.

Mysqldump Error

By default, mysqldump locks all the tables it's about to dump. This ensures the data is in a consistent state during the dump.

The following error can occur:

# ./processmaker workspace-backup wsbundletmp Backing up to /opt/processmaker/shared/backups/wsbundletmp.tar Backing up database... Saving database wf_wsbundletmp mysqldump: Got error : 1045: Access denied for user 'wf_wsbundletmp'@'localhost' (using password: YES) when using LOCK TABLES Copying database to backup... + /opt/processmaker/shared/upgrade/hbh9gS Copying files to backup... + /opt/processmaker/shared/sites/wsbundletmp

It shows because the requested database breaks the data consistency while dumping (e.g. invalid tables, columns, functions or definer/invoker). Usually this error occurs when there is mysqldump with big data. Since ProcessMaker uses a motor engine in various workspaces, this error should occur because a new thread starts that locks tables and the next user can see this error.

There are two solutions to this error:

  • Use one of these mysqldump commands: mysqldump --opt --lock-tables=false -u [USER] -p [DBNAME] > dump.sql mysqldump --opt --single-transaction -u [USER] -p [DBNAME] > dump.sql
  • Add the 'LOCK TABLES' permission to the user: GRANT SELECT,LOCK TABLES ON wf_[DBNAME_original].* TO 'wf_[new_DBNAME]'@'[ServerIP]';

Restoring Workspaces

The restoration and backup of a workspace can only be made on the same platform (Windows -> Windows, Linux -> Linux), because the names of the MySQL tables in Windows are not case sensitive, which may cause ProcessMaker to have problems.

Note: Before the restoration takes place, it is necessary to apply the File Permissions as it was a new installation of ProcessMaker in order to work properly.

To restore a workspace from a backup use the command:

LINUX/UNIX

php processmaker workspace-restore [BACKUP-FILE] [WORKSPACE-NAME]

Windows

PHP-DIRECTORY\php.exe -f processmaker workspace-restore [BACKUP-FILE] [WORKSPACE-NAME]

If the backup file has a .tar extension and it is located in the INSTALL-DIRECTORY/shared/backups directory, then it is not necessary to specify the path or the file extension.

If it is not located in the shared/backups directory, or it doesn't have a .tar extension, then specify the path. Remember to enclose it within double quotes if the file name or path contains spaces.

By default, the backup will be restored to the same workspace name and use the same database names as the original. To overwrite an existing workspace, use the -o or --overwrite option. For example, to overwrite the existing "workflow" workspace:

php processmaker workspace-restore -o workflow

To restore to a different workspace name, specify the optional [WORKSPACE-NAME] parameter. The files from the backup workspace will be copied into the INSTALL-DIRECTORY/shared/sites/[WORKSPACE-NAME]/ directory.

Remember that the workspace name should only contain 13 valid characters in MySQL databases or less, so it can not contain hyphens "-", spaces, periods, commas, semicolons or other special characters. To avoid problems, it is recommended to only use ASCII letters, numbers and underscores "_" for workspace names, since the workspace name should be easy to represent in a web address. Remember that workspace names are case sensitive when being entered in a URL in a web browser, but MySQL databases in Windows are not case sensitive, whereas MySQL databases in Linux are case sensitive.

Restoring a workspace takes a large amount of time. If restoring a workspace that users need to access, it is recommended to do the restore operation during a period when users will not need to access the workspace. The execution time of the processmaker workspace-restore command has been improved to some degree, but the restoration of a workspace with a few cases will still take at least 10 minutes, and large workspaces with many cases can take much longer.

Examples:

To restore a workspace from the INSTALL-DIRECTORY/shared/backups/workflow.tar backup file in Linux:

php processmaker workspace-restore workflow

To restore a workspace from the c:\Documents and Settings\Amos\sales backup.tar file in Windows:

processmaker workspace-restore "C:\Documents and Settings\Amos\sales backup.tar"

To copy the contents of the "workflow" workspace stored in the backup file at shared/backups/workflow.tar to a new workspace named "finance":

php processmaker workspace-restore workflow.tar finance

While the processmaker backup-restore command is executing, it will not display any output on the screen for many minutes. When it has terminated, it will display information similar to the following on the screen:

# php processmaker workspace-restore workflow.tar finance Restoring from /opt/processmaker/shared/backups/workflow.tar Found 1 workspaces in backup: -> workflow.meta > Restoring workflow to finance +> Restoring directory 'workflow.files' > Changing file permissions > Connecting to system database in 'localhost' +> Restoring database wf_workflow to wf_finance Creating user wf_finance for localhost Creating user wf_finance for % 3.0.0.4 < 3.0.0.4 > Verify files enterprise old... Without changes... <*> Verify took 0.30658888816833 seconds. > Updating List tables... <*> Updating List Process took 0.019959926605225 seconds. Removing temporary files Done restoring

Warning: A workspace from a newer version of ProcessMaker can NOT be restored in an older version of ProcessMaker. For example, restoring from v.3.0 to v.2.5 will not work. However, it may be possible to restore a workspace from an older version to an newer version of ProcessMaker, although error messages may be displayed during the restore process.

Note: If restoring a workspace from the Enterprise Edition, the output will also contain the lines: > Verify License Enterprise... <*> Verify took 0.24472689628601 seconds.

After logging into the new workspace for the first time, a dialog box will appear, asking that the Enterprise license file be uploaded for the workspace. If the same organization is still using the workspace, then the same license_XXXXXXXXXXXXX.dat file can be used for the new workspace as well. There is no limit on the number of workspaces that can be created with an Enterprise License. If a different organization will be using the workspace, then contact ProcessMaker Sales to obtain a new Enterprise license.

Click on Browse and select the license_XXXXXXXXXXXXX.dat file to upload it. If the license file is valid, then the login screen will appear again with the message "License installed successfully":

To only show information about a backup file, use the -i option. For example, to show information about the workspace(s) in the shared/backups/sales.tar backup file:

# php processmaker workspace-restore -i sales Found 1 workspace(s) in backup Workspace Name workflow Workflow Database mysql://wf_sales:7v9j0dqft6bk@localhost:3306/wf_sales MySql Version MySql (Version 5.5.43-0+deb7u1-log)

To restore a workspace from a backup file that has multiple workspaces, use the -wWORKSPACE or --workspace=WORKSPACE option to specify which workspace should be restored. For example, to restore the "finance" workspace from the file /root/pmBackup.tar and overwrite the existing "accounting" workspace:

php processmaker workspace-restore -o --workspace=finance /root/pmBackup.tar accounting

or:

php processmaker workspace-restore -o -wfinance /root/pmBackup.tar accounting

For help using the processmaker workspace-restore command:

php processmaker help workspace-restore

The -m option can be used to restore workspaces from multiple backup files (created with the -s option). Specify the name of the backup file, but do not include the numbers at the end of the file name. For example, if restoring from three backup files named pmbackup.tar.00, pmbackup.tar.01 and pmbackup.tar.02, then issue the command:

php processmaker workspace-restore -m pmbackup.tar

ProcessMaker will automatically join all the files whose file names start with "pmbackup.tar" when restoring the workspace(s).

BACKUP-FILE1 is the name of the first backup file, which typically has the extension tar.00.

Note: All the workspace files from the backup will be created in the INSTALL-DIRECTORY/shared/sites/WORKSPACE/ directory, with the same file permissions and same file owner as the shared directory. If not, for greater security, change folders and files permissions of the restored workspace to the same permissions as in the shared folder.

After Restoring a Workspace

After using the processmaker workspace-restore command, it is strongly recommended to issue the following command that repairs the cache of cases in the APP_CACHE_VIEW table: php processmaker cacheview-repair [WORKSPACE]

If no workspace is specified, then the cache will be repaired for all workspaces.

If this command is not executed, the number of cases listed under the Home menu will not be correct. To sort the cases with a language other than English (which is the default), use the -lISO-CODE or --lang=ISO-CODE option to specify the ISO 639-1 code for another language, such as es (Spanish), pt-BR (Brazilian Portuguese), or zh-CN (mainland Chinese). For example, to repair the case cache of the "workflow" and "development" workspaces in French in a Linux system:

php processmaker cacheview-repair -lfr workflow development

In addition, if restoring from a different a workspace from a different version of ProcessMaker, the following command must be executed to update the case schema used by the new version of ProcessMaker:

php processmaker migrate-new-cases-lists [WORKSPACE]

For example, to migrate the case schema for the "workflow" and "development workspaces on a Linux server:

php processmaker migrate-new-cases-lists workflow development

Note: Take into account that until ProcessMaker version 3.0.1.5, this command only worked for workspaces that had only one database wf_<WORKSPACE> and not for workspaces that kept on working with the three databases ProcessMaker used to manage.

Cleaning and restoring table PLUGIN_REGISTRY table

After you have restored the workspace, you can follow these steps to clean the cache and force ProcessMaker to read the updated table PLUGIN_REGISTRY:

1. Remove all records from table PLUGINS_REGISTRY.

DELETE FROM wf_workflow.PLUGINS_REGISTRY WHERE PLUGIN_NAMESPACE <> 'enterprise';

Warning: Do not remove the enterprise plugin (ProcessMaker Enterprise Core Edition). If you delete the enterprise plugin, ProcessMaker becomes unstable. Therefore, it is important to not erase that plugin.

2. Apply the following command to clear the application cache.

./processmaker flush-cache

3. Remove the directory cache inside ProcessMaker.

rm -R processmaker/shared/framework/cache

4. Reload ProcessMaker site.