Overview
As part of common maintenance and administration tasks, it is of critical importance to always be able to rely on backups if you need to restore your project to a previous state, should an unexpected event occur.
Restoring your project to a previous state when having a database backup is a simple procedure for a Bizagi System, given that Bizagi is data-driven.
For more information, refer to System administration.
Important notes
Backups in such types of tasks are mainly created as a contingency measure.
|
Restoring a database backup should only be considered as a contingency measure to restore a given environment to a previous state, or to move an environment's database to a new location. This means that a development environment backup should only be restored in the same development environment, and a production environment backup should only be restored in the same production environment. To create environments, Bizagi offers its Deployment options. |
If you are using an Oracle database instance as the database engine for a Bizagi project database, perform the backup-and-restore operations through Oracle's Export and Import utility.
If you are using a Microsoft SQL Server database as Bizagi's database instead, refer to SQL Server Backup and Restore.
|
Keep in mind that case attachments are not stored within the backup itself. |
Prerequisites
To use the export and import utilities in an Oracle database for a Bizagi project, you must:
1. Have the Oracle client installed where the export and import will be carried out
The installed client version will most likely differ according to the bit version (32-bit or 36-bit) supported by the database server system. It is required that the Oracle client's version used in the export match the client's version used in the import.
2. Have either the same or compatible character set configured for your Oracle database instances (at the servers), as well as for the Oracle clients involved in the export and import
Ensuring that these character sets are the same one or a compatible one, is essential for Oracle’s export and import utilities to maintain the integrity of the information (otherwise, information contained in the database can become altered).
3. Have no more than one active Oracle home definition
If you have more than one Oracle client installed where you will use the export and import utilities, make sure that the ORACLE_HOME environment variable is properly set to the Oracle client used by Bizagi.
Additional Considerations
If you are moving a Development project to a new server, and wish to keep your existing cases (Process instances), take into account that file attachments are not stored in the database but on Automation Server server (by default), or a file server or ECM, if configured.
If this is the case and you are using Automation Server server as the path for the cases' uploaded files, moving the attachment files would be necessary.
Also, we highly recommend that an experienced user (such as a DBA with an advanced knowledge in Oracle) carry out the export and import utility commands, for three main reasons:
1. The export and import utilities are run using DOS commands with use of command line parameters (which are known to a DBA).
You may choose to use a parameters file if it is useful.
There is more than one way to use Export or Import capabilities, such as the use of RMAN, however this article illustrates the way recommended by Bizagi. You can use RMAN as long as you are an experienced user and can guarantee that the complete information will be considered for backup and restore purposes.
2. Managing an Oracle database of a Bizagi project will require at some point (for a specific instruction in the import), having at hand the credentials to connect as a user with privileges (for example, using the BizagiAdmon user).
3. After you perform the export or import of an Oracle database, it is imperative to review the execution logs, so that any possible errors and warnings thrown in the export and import are handled and solved, or verified as "OK".
Regarding errors, an issue that can show up and that needs immediate resolution, is when a tablespace in Oracle runs out of space (and cannot be extended) during an import. This type of error will not stop the import, but can leave the information incomplete and without integrity.
For example, warnings which may be ignored are those stating:
ORA-31684: Object type USER:"%USER_NAME%" already exists
On the other hand, some warnings which require resolution are like this:
ORA-39082: Object type ALTER_PROCEDURE:"%PROCEDURE_NAME%" created with compilation warnings
|
The BizagiAdmon user must have already been created in the given Oracle database instance. A Bizagi project creation requires that the BizagiAdmon user is previously created. |
Using DataPump Export (expdp)
The Data Pump utility provides a mechanism for transferring data objects between Oracle databases.
Here is how to use the Datapump export utility to backup all the information in a Bizagi project from into a dmp file.
To use Oracle’s DataPump export utility for a Bizagi project, carry out the following steps:
1. Preparting the backup directory
To make use of the DataPump export, you need to specify as a parameter the directory in which the .dmp backup will be saved.
To do this, connect to your Oracle instance with the BizagiAdmon use using a sqlplus command:
sqlplus BizagiAdmon/%BIZAGIADMON_USER_PASSWORD%@%DATABASE_SERVER%:%SERVICE_PORT%/%SERVICE_NAME%
In this commandt:
•%BIZAGIADMON_USER_PASSWORD% is the password for the BizagiAdmon user.
•%DATABASE_SERVER% is the name of the Oracle database server.
•%SERVICE_PORT% is the port number in which the Oracle database services are listening.
•%SERVICE_NAME% is the alias to your database instance.
Once connected, you can look up the created directories for your database instance in which you will also find Bizagi's backup path:
To manually create a different directory to use another physical path for your backup and log, run the sqlplus command as shown below:
Once you have at hand the name of the directory you will use, log off (disconnect) from your Oracle instance’s BizagiAdmon session.
2. Opening a command prompt
Use a command prompt to execute the export commands.
To do this, launch a DOS command prompt:
Browse to your Oracle client home path, and into its "bin" folder:
3. Using the DataPump export utility
The characteristics of the import operation are determined by the export parameters you specify.
Input the following command line from the bin folder location:
expdp USERID=BizAgiAdmon/%SCHEMA_USER_PASSWORD% SCHEMAS=%SCHEMA_USER_TO_EXPORT% DIRECTORY=%BIZAGI_BACKUP_PATH% DUMPFILE=%EXPORT_FILE% LOGFILE=%EXPORT_LOG%
In this command line:
•%SCHEMA_USER_PASSWORD% is the password for the user with system rights (BizAgiAdmon).
•%SCHEMA_USER_TO_EXPORT% is the name of the Bizagi project.
•%BIZAGI_BACKUP_PATH% should be "BizAgiBackupPath" by default if no customization was done, according to step #1 (this parameter is the name for the directory on which the backup is located).
•%EXPORT_FILE% is the path and filename in which the exported information was saved (the .dmp created when running the export).
•%EXPORT_LOG% is the path and filename in which the import log will be recorded. This file commonly uses the .log file extension.
For more information about Oracle's DataPump import and export utility (available from Oracle 10g version databases), refer to external links from the source: http://www.orafaq.com/wiki/Data_Pump.
4. Reviewing the DataPump export log
After the export execution, check for and resolve any possible errors.
To do this, go through the log recorded in the previous step once the export has finished.
This log will be located at the path and filename specified as "%EXPORT_LOG%".
|
The export utility will use the character set defined for your Oracle client. Therefore, and as mentioned at the prerequisites section, this character set should be the same or a compatible one to that defined for the database server. In addition, the character set must also be the same or a compatible one to that involved when using the import utility. |
Using the DataPump Import (impdp)
The Data Pump utility provides a mechanism for transferring data objects between Oracle databases.
We show how to use the DataPump import utility to restore information in a Bizagi project from a .dmp export file, that meets one of the following conditions:
•This .dmp file was previously created through the DataPump export (manually using the expdp command).
•This .dmp file was created by Bizagi. This is done automatically when launching a project upgrade or a deployment.
Backup files created by Bizagi will be found at the "backup path" specified when configuring an Oracle instance to work with Bizagi (prerequisite of Bizagi project creation with Oracle databases).
|
The DataPump import (impdp command) presented in this section will not restore dmp backup files created through the traditional export utility (exp command). Such dmp backup files not considered by this approach were manually created when using the exp command. To importing a dmp file created with the traditional export utility, needs to be done with the traditional import utility (imp command) described in the section above. |
To use Oracle’s DataPump import utility for a Bizagi project, perform the following steps:
1. Make sure there are no active connections
For the DataPump import operation carried out to restore information, it is necessary that the schema user is not in use (has no active connections).
Take into account, that Bizagi Scheduler's service will certainly have active connections if it is in a started status. If this is so, you need to stop the Scheduler service.
|
Take proper precautions when ensuring that there are no active connections. Check for active connections by using BizagiAdmon, through this command:
SELECT s.sid, s.serial#, s.username FROM gv$session s JOIN gv$process p ON p.addr = s.paddr AND p.inst_id = s.inst_id WHERE s.type != 'BACKGROUND' and s.username = '[your_user_schema]'
You can also force kill active connections (by using the command below), but under your responsibility and controlling which specific sessions you are ending. Additionally, validate and guarantee that there are no users working at that moment in the related Bizagi project (user schema).
ALTER SYSTEM DISCONNECT SESSION '[sid],[serial#]' IMMEDIATE; |
2. Delete the schema user
When you restore an existing Bizagi project, the current schema user representing this project is deleted.
To do this, connect to your Oracle instance with the BizagiAdmon user using a sqlplus command:
sqlplus BizagiAdmon/%BIZAGIADMON_USER_PASSWORD%@%DATABASE_SERVER%:%SERVICE_PORT%/%SERVICE_NAME%
In this sqlplus command:
•%BIZAGIADMON_USER_PASSWORD% is the password for the BizagiAdmon user.
•%DATABASE_SERVER% is the name of the Oracle database server.
•%SERVICE_PORT% is the port number in which the Oracle database services are listening.
•%SERVICE_NAME% is the alias to your database instance.
Then, execute the following drop user command (with cascade):
drop user %SCHEMA_USER_TO_IMPORT% cascade;
Note that %SCHEMA_USER_TO_IMPORT% is the name of the Bizagi project.
3. Create the schema user again
The schema user to restore the Bizagi project is created again (as blank) through a Bizagi stored procedure.
In the same session (and in the already connected sqlplus window), execute Bizagi's "spBA_ORA_CreateAppUser" stored procedure to create the project user:
exec spBA_ORA_CreateAppUser('%SCHEMA_USER_TO_IMPORT%','%SCHEMA_USER_PASSWORD%');
4. Look up the backup directory
To use the DataPump import, you will need to specify as a parameter the directory the .dmp backup is in.
Therefore, you can look up the created directories for your database instance in which you will also find Bizagi's backup path:
You can create a different directory for your backup and log, by running the sqlplus lines shown below:
Once you have the name of the directory you will use, log off (disconnect) from your Oracle instance’s BizagiAdmon session.
5. Open a command prompt
A command prompt to execute the import commands.
To do this, launch a DOS command prompt:
Then, browse to your Oracle client home path, and into its "bin" folder:
6. Use the DataPump import utility
Perform the DataPump import parameter specification. The parameters are completely different for those used by the traditional import utility.
Input the following command line from the bin folder location:
impdp USERID=BizAgiAdmon/%SCHEMA_USER_PASSWORD% SCHEMAS=%SCHEMA_USER_TO_IMPORT% DIRECTORY=%BIZAGI_BACKUP_PATH% DUMPFILE=%EXPORT_FILE% LOGFILE=%IMPORT_LOG%
In this command line:
•%SCHEMA_USER_PASSWORD% is the password for the user with system rights (BizAgiAdmon).
•%SCHEMA_USER_TO_IMPORT% is the name of the Bizagi project.
•%BIZAGI_BACKUP_PATH% should be "BizAgiBackupPath" by default if no customization was done, according to step #4 (this parameter is the name for the directory on which the backup is located).
•%EXPORT_FILE% is the path and file name in which the exported information was saved (the .dmp created when running the export).
•%IMPORT_LOG% is the path and file name in which the import log will be recorded. This file commonly uses the .log file extension.
We recommend to use the BizAgiAdmon as the USERID to run the import, so you have a user with permissions to create the necessary objects in the schema.
For more information about Oracle's DataPump import and export utility (available from Oracle 10g version databases), refer to external links from the source: http://www.orafaq.com/wiki/Data_Pump.
7. Review the DataPump import log
After the DataPump import execution, check for and solve any errors (no errors should be shown when performing an import in Bizagi).
To do this, go through the log recorded for this operation once the import has finished.
This log will be located by the path and file name specified as "%IMPORT_LOG%".
The import should finish correctly without warnings and having successfully enabled Bizagi's constraints.
|
The import utility will use the character set defined for your Oracle client. Therefore, and as mentioned in the prerequisites section, this character set should be the same or a compatible one as the one defined for the database server. In addition, the character set must also be the same or a compatible one as that involved when using the export utility. |
After an import, we recommend that you run the following query (with the BizagiAdmon user) to make sure that there are records returned by it which point to any errors/issues:
SELECT * FROM ALL_OBJECTS WHERE OWNER = '%USER_NAME%' AND STATUS <> 'VALID';
Click for more information about this option in the Management Console.