Restoring

Now reading version 1.0. For the latest, read: Restoring for version 5.0
Applies to NEXUS Server versions: 1.0 and 1.1

This documentation page references NEXUS Server (part of the deployed NEXUS solution), which has been discontinued. All your PCB design, data management and collaboration needs can now be delivered by Altium Designer and a connected Altium 365 Workspace. Check out the FAQs page for more information.

 

Parent page: Altium NEXUS Server with Oracle Backend

This document is intended for an IT administrator who is restoring their Altium NEXUS Server data when the NEXUS Server is using an Oracle Database Backend. It contains details about the Altium NEXUS Server, it’s 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.

To follow this guide, you should have a general understanding of Oracle database concepts and the windows operating system environment. For more information on how to backup your Altium NEXUS Server and its associated Oracle data, see Altium NEXUS Server with Oracle Backend - Backup.

Restore Process Overview

Restoring the Altium NEXUS 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.

It is important that the steps be followed in the order they are presented.

High level overview of the Altium NEXUS Server and Oracle database restore procedure.High level overview of the Altium NEXUS 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 Altium NEXUS Server data and its associated Oracle data dump has been performed as outlined in the document Altium NEXUS Server with Oracle Backend - Backup.
  2. An IT administrator performs the restoration. At minimum, the user performing NEXUS Server restoration should have administrative rights to the host machine.
  3. A DBA should be present to perform the Oracle data import. At 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 Altium NEXUS Server, configured and working with an Oracle backend. (See the example section for more details on how to handle an environment where a new Altium NEXUS Server is being deployed on a machine and data is imported into that Altium NEXUS Server instance).
  5. The Oracle Schema and Oracle application credentials used on source and destination Oracle servers must be the same.

High-level Overview of the Altium NEXUS Server Architecture

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

High level overview of the Altium NEXUS Server architecture. The Backend Storages of Altium NEXUS Server contains most
of 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 NEXUS Server’s SVN repository. This binary data includes information such as PCB and Schematic Project documents, footprints, symbols, Draftsman and other native or non-native NEXUS 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 Altium NEXUS Server. This is a command line utility that IT administrators can execute to restore their Altium NEXUS Server data. avbackup.exe is the same utility used for restore purposes when the Altium NEXUS Server is configured with a default Firebird database backend, or when using the Oracle database as a backend.

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

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

Example Restoration of NEXUS 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 DBA, but still have the need to restore their NEXUS Server and associated Oracle data on their network. The following steps show how a basic backup of Altium NEXUS Server and Oracle 11G Express can be restored onto a new machine and Oracle database.

When using Altium NEXUS with Oracle as the backend database, the server that is integral to the deployed NEXUS solution supports the following versions of Oracle: 11G Express, 12.1c. Note that versions 18c and 19c are not currently supported.
Alternatively, more advanced IT administrators can write batch files that automatically perform the following procedure.

Required Items

  • Pre-existing working instance of the Altium NEXUS Server with Oracle backend.
  • Pre-existing folders and data sources:
    • Folders where your Altium NEXUS Server and Oracle data will be located need to already exist, and contain a copy of your NEXUS Server backup zip file and Oracle .DMP file.
  • Admin access to the Altium NEXUS Server Host machine. This is required to properly run the Altium NEXUS 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 Altium NEXUS Server with Oracle backend has been setup, please read the document Altium NEXUS Server with Oracle Backend - Installation for an example of how to setup Altium NEXUS Server using Oracle backend on a new machine.
  2. At this point, you should already have an existing instance of the Altium NEXUS Server with Oracle - either because of a new, or previous installation.
  3. On the Altium NEXUS Server Host machine:
    1. Create a restore folder (it helps to have common file paths, for example: C:\Backups). Place the NEXUS Server backup Zip file into this folder.
    2. Restore your Altium NEXUS Server data by running the avbackup.exe tool as Admin. The tool is located in the C:\Program Files (x86)\Altium\Altium NEXUS Server\Tools\BackupTool folder.
    3. Shut down IIS NEXUS Server services, or shutdown the NEXUS Server Host machine. This will prevent any unintended write operations to your Oracle Database by NEXUS Server services.
For more information on how to use the restore tool, see Backing up Your Altium NEXUS Server with an Oracle Backend.

Example restore commands:

  • Command line to navigate to the backup tool directory: cd C:\Program Files (x86)\Altium\Altium NEXUS Server\Tools\BackupTool\.
  • Command line to restore the Altium NEXUS Server data from the file named 2017_Backup.zip, which is stored in the folder C:\Backups: avbackup restore -z "C:\Backups\2017_Backup.zip" -i "C:\Program Files (x86)\Altium\Altium NEXUS Server\LocalVault.ini".
  1. 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.
The Altium NEXUS Server initializes its internal SYSTEM variables and other NEXUS Server parameters during installation, then writes that information to the Oracle database. This only occurs during a brand-new installation of the NEXUS Server, but not during an upgrade. Because the SYSTEM variables and other NEXUS Server parameters may have changed between old and new NEXUS Server installation, it is much simpler to delete/drop the existing user account, schema and its data from the Oracle database, and create a new user account with at least the same name as the account that was assigned to the NEXUS Server in the source Oracle database. When the .dmp file is imported into the Oracle database, the imported SYSTEM variables and NEXUS Server parameters will match those stored inside the Altium NEXUS Server backup Zip file.

Dropping an Oracle user account and its associated schema can be achieved as follows. For this example, we'll drop existing user account ANSUSER313 and its associated Schema from an Oracle 11G 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;

  1. Drop schema associated with NEXUS Server (in this example ANSUSER313 is the name of the schema we want to delete):

drop user ANSUSER313 cascade;

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

shutdown immediate;

startup;

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

sqlplus / as sysdba;

CREATE user ANSUSER313 identified by “Altium”;

GRANT ALL PRIVILEGES TO ANSUSER313;

GRANT IMP_FULL_DATABASE TO ANSUSER313;

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

GRANT DBA TO ANSUSER313;

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

revoke DBA from ANSUSER313;

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

net stop WAS

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

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

where,

ANSUSER313 - user that has full privileges on scheme and rights to access the DB.

Altium -  password for Oracle user account associated to the Altium NEXUS Server.

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

file = c:\Backups\ANSUSER313.dmp - location of backup.

log = c:\Backups\ANSUSER313_import.log - restore log (optional).

fromuser=ANSUSER313 - owner of the backup scheme.

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

  1. 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 current FQDN of your NEXUS Server.
    3. Check values for the following parameters in C:\Program Files (x86)\Altium\Altium NEXUS Server\LocalVault.ini file.
      1. Domain - your name of domain.
      2. WebsiteDomain - FQDN of your NEXUS Server.
      3. DataSourceType=Oracle - if using Oracle DB.
      4. User=ANSUSER313 - 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 Altium NEXUS Server data:

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

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

It might be necessary for the DBA to remap tablespaces of the metadata being imported to the Schema assigned to the Altium NEXUS Server's Oracle DB account, or the Oracle DB import may not work. Especially if the IMPDP/EXPDP commands were used instead of IMP/EXP to generate the Oracle DB backup.

Example:

  1. Create directory reference, note that this does not create a physical folder on the HDD. Simply a pointer in Oracle memory to that folder. You must first create said folder on the HDD manually, then copy its path to the FOLDERPATH placeholder bellow.
    1. CREATE OR REPLACE DIRECTORY MyDirectoryName AS 'FOLDERPATH’;
  2. drop user ALTIUM cascade;
  3. create user ALTIUM identified by PASSWORD;
  4. grant DBA to ALTIUM;
  5. grant connect, resource, create session to ALTIUM;
  6. impdp ALTIUM/PASSWORD@XE full=y directory=MyDirectoryName dumpfile=DMPFILENAME.DMP logfile=LOGFILENAME.log remap_tablespace=ALTIUM:USERS

 

Content