Restoring Altium On-Prem Enterprise Server with an Oracle Backend

Parent page: Altium On-Prem Enterprise Server with Oracle Backend

This document is intended for an IT administrator who is restoring their Altium On-Prem Enterprise Server data when the Enterprise Server is using an Oracle Database Backend. It contains details about the Enterprise Server, its restore procedure within the context of using Oracle, important information on system requirements, as well as an example outlining data restoration on the Microsoft Windows platform.

Restore Process Overview

Restoring the Enterprise Server when using an Oracle backend depends on how your company manages its Oracle Databases. Some companies run Oracle Databases on top of Windows Server Operating Systems, while others have entire Oracle datacenters. The restore process typically involves three steps, as illustrated in the following image.

High level overview of the Enterprise Server and Oracle database restore procedure.

Assumptions Made Throughout this Document

While Oracle configurations can vary from site to site, the following assumptions are made throughout this document:

1. A full backup of the Enterprise Server data and its associated Oracle data dump has been performed as outlined in the document Backing up Altium On-Prem Enterprise Server with an Oracle Backend.
2. An IT administrator performs the restoration. At a minimum, the user performing Enterprise Server restoration should have administrative rights to the host machine.
3. A Database Administrator (DBA) should be present to perform the Oracle data import. At a minimum, the user following this guide should have full read/write access to import and modify the company Oracle database.
4. This guide assumes that there is an existing installation of the Enterprise Server, configured and working with an Oracle backend. (See the example section for more details on how to handle an environment where a new Enterprise Server is being deployed on a machine and data is imported into that Enterprise Server instance).
5. The Oracle Schema and Oracle application credentials used on the source and destination Oracle servers must be the same.

High-level Overview of the Enterprise Server Architecture

Similar to other software designed to run on Microsoft Windows, the Enterprise Server is a multi-threaded, multi-service server application. Since this document solely focuses on parts of the Enterprise Server that may interact with an Oracle Database, the following image is simplified to represent the overall Enterprise Server Backend Architecture.

High-level overview of the Enterprise Server architecture. The Backend Storages of Enterprise Server contains most of the customer binary data, while the Windows Services is a collection of supporting services.

This document focuses on the Backend Storages since the data within this block is what gets backed-up, potentially migrated to another machine, then restored either on the same or different machine. Within the Backend Storages, the following items can be found:

• Databases – contains metadata such as component footprint and schematic symbol association, parameters, file paths, links to component supply chain data sources and more. This information could reside inside a Firebird or Oracle database.
• File Storage – this File Storage area holds binary data inside the Enterprise Server’s VCS repository. This binary data includes information such as PCB and Schematic Project documents, footprints, symbols, Draftsman and other native or non-native Enterprise Server documents.

High-level Overview of the Altium Restore Tool

The Altium restore tool is called avbackup.exe. It is the same utility used for backup and restore purposes with the Enterprise Server. This is a command line utility that IT administrators can execute to restore their Enterprise Server data. avbackup.exe is the same utility used for restore purposes when the Enterprise Server is configured with a default Firebird database backend, or when using the Oracle database as a backend.

When using avbackup.exe on an Enterprise Server implementation that uses an Oracle Database, administrators should be mindful of the following:

1. avbackup.exe does NOT support restoring your Enterprise Server metadata to an Oracle Database. This feature only works on Enterprise Server implementations using a Firebird database backend that was originally auto-configured by the Enterprise Server Installer.
2. avbackup.exe accepts the Zip file that it generates when used as a backup tool. This Zip file contains all Enterprise Server binary data.
3. The Enterprise Server must be running. avbackup.exe will automatically shut down all Enterprise Server services (including IIS services) during data restoration, then restart all services it shut down, after a successful restore.

Example Restoration of Enterprise Server Data with Oracle backend on the Windows Platform

In this example, the instructions also cater to smaller businesses who may not have a dedicated Oracle Database Administrator (DBA), but still have the need to restore their Enterprise Server and associated Oracle data on their network. The following steps show how a basic backup of Enterprise Server and its associated Oracle database can be restored onto a new machine and Oracle database.

Required Items

• Pre-existing working instance of the Enterprise Server with Oracle backend.
• Pre-existing folders and data sources:
  • Folders where your Enterprise Server and Oracle data will be located need to already exist, and contain a copy of your Enterprise Server backup zip file and Oracle .DMP file.
• Admin access to the Enterprise Server Host machine. This is required to properly run the Enterprise Server backup Command utility (avbackup.exe).
• Appropriate DBA access to the Oracle server (i.e. Add user’s Windows account to sysDBA role in Windows environment).

Restore Procedure

1. If no pre-existing instance of the Enterprise Server with Oracle backend has been set up, please read the document Installing Altium On-Prem Enterprise Server with an Oracle Backend for an example of how to set up Enterprise Server using Oracle backend on a new machine.
2. At this point, you should already have an existing instance of the Enterprise Server with Oracle – either because of a new, or previous installation.
3. On the Enterprise Server Host machine:
   1. Create a restore folder (it helps to have common file paths, for example: C:\Backups). Place the Enterprise Server backup Zip file into this folder.
   2. Restore your Enterprise Server data by running the avbackup.exe tool as Admin. The tool is located in the C:\Program Files (x86)\Altium\Altium365\Tools\BackupTool folder.
   3. Shut down IIS Enterprise Server services, or shut down the Enterprise Server Host machine. This will prevent any unintended write operations to your Oracle Database by Enterprise Server services.

4. On the Oracle Database Host machine:
   1. Create a restore folder and place the Oracle .dmp file in this folder (it helps to have common file paths, for example: C:\Backups).
   2. Drop/delete existing schema and user account from Oracle database.

Dropping an Oracle user account and its associated schema can be achieved as follows. For this example, we'll drop the existing user account AESUSER313 and its associated Schema from an Oracle Database on Microsoft Windows:

1. Launch a command prompt with Admin privileges.
2. Stop IIS services if they are present on the Oracle machine using command: net stop WAS, then press Y and enter.
3. Connect to Oracle DB by launching an SqlPlus session:

sqlplus / as sysdba

shutdown immediate;

startup restrict;

4. Drop schema associated with Enterprise Server (in this example AESUSER313 is the name of the schema we want to delete):

drop user AESUSER313 cascade;

5. re-activate DB normally either by restarting the machine, or using the following commands:

shutdown immediate;

startup;

3. Create Identical Schema on Oracle Server and assign elevated rights:
   1. Open command line as admin and type:

sqlplus / as sysdba;

CREATE user AESUSER313 identified by “Altium”;

GRANT ALL PRIVILEGES TO AESUSER313;

GRANT IMP_FULL_DATABASE TO AESUSER313;

2. Alternatively, you can temporarily grant DBA role to this user, import files and then revoke this privilege as shown below:

GRANT DBA TO AESUSER313;

3. After successfully importing the DB, revoke the DBA privileges:

revoke DBA from AESUSER313;

4. Restore Oracle data (this section assumes that the user account and schemas are both named AESUSER313 and have password Altium):
   1. Launch command prompt with Admin privileges
   2. Stop IIS Servers using command:

net stop WAS

3. Import the Oracle Data. An example of an import command is:

imp AESUSER313/Altium@xe file=c:\Backups\AESUSER313.dmp log=c:\Backups\AESUSER313_import.log fromuser=AESUSER313 touser=AESUSER313

where,

AESUSER313 – user that has full privileges on scheme and rights to access the DB.

Altium – password for Oracle user account associated with the Enterprise Server.

xe – network service name of target DB contained in tnsnames.ora.

file = c:\Backups\AESUSER313.dmp – location of backup.

log = c:\Backups\AESUSER313_import.log – restore log (optional).

fromuser=AESUSER313 – owner of the backup scheme.

touser=AESUSER313 – the new owner of the scheme (if the owners are different, you must create new user with appropriate privileges and roles).

5. Verify data integrity.
   1. Check tnsname.ora file. You should update the network service name (if you changed DB server).
   2. Validate IIS server settings. Check column “Host name" in bindings in IIS Manager to current. There should be the current Fully Qualified Domain Name (FQDN) of your Enterprise Server.
   3. Check values for the following parameters in C:\Program Files (x86)\Altium\Altium365\LocalVault.ini file.
      1. Domain – the name of your domain.
      2. WebsiteDomain – FQDN of your Enterprise Server.
      3. DataSourceType=Oracle – if using Oracle DB.
      4. User=AESUSER313 – owner of the scheme.
      5. Password=Altium – DBA defined user password.
      6. DBLocation=FQDN or ip_address:1521 – address of your DB server.
      7. DatabaseName=xe – current network service name of DB, contained in tnsnames.ora.

Conclusion

Although the aforementioned example includes additional details pertaining to interfacing and manipulating an Oracle Database, there are only three key steps to restoring your Enterprise Server data:

1. Step 1 is to stop the IIS services and Enterprise Server IIS Application Pools.
2. Step 2 is to restore the Enterprise Server data.
3. Step 3 is to restore the Oracle data associated with the Enterprise Server.

Performing this procedure in the order described greatly reduces the likelihood of data corruption due to Oracle database and Enterprise Server binary data mismatch.