Exporting and Importing QuerySurge Projects (Versions: 8.0+)

Versions: 8.0+

Managing QuerySurge Projects: Exporting and Importing QuerySurge Projects

Projects can be exported from a QuerySurge instance and imported into the same or a different instance. This article will outline key information on exporting and importing Projects and walk you through the process of exporting and importing Projects using Global Administration.

Use Cases

Project export and import can be used for several purposes:

• Backup  - for recovery in case of crashes, corruption, or accidental deletion of data
• Archival - to capture Project state periodically over time (for regulatory/compliance auditing purposes), or to move inactive Projects to cold storage with the ability to restore later
• Migration - to move Projects between QuerySurge instances

Considerations

Following are a number of important details on the export and import features. Several items are called to special attention to ensure system stability and usability of exports.

Export File Storage

An exported Project is stored as a single compressed file on disk on the QuerySurge App Server. While compressed, export file sizes vary based on the total amount of data (assets, test results, and staging tables) in the Project at the time of export.

The location of export files for both Windows and Linux installations is on the QuerySurge App Server machine, at <QS Install Dir>/tomcat/webapps/QuerySurge/project_exports.Export file names follow this convention: <sanitized project name>_<YYYYMMDD_HHmmSS>.zip

IMPORTANT! The project_exports directory is considered volatile and may be cleared during QuerySurge upgrades or other events, so export files should be relocated soon after exports are complete.

In Projects with large numbers of historical test results and/or staging tables as well as with large data sets in either form, export files can grow rather large. Regular maintenance of stored exports is recommended to avoid system instability caused by depleted disk space.

To alleviate both of the above considerations, export files may be moved to persistent mass storage areas via any standard file transfer method (local secondary disk partitions/drives, shared network folders, FTP servers, etc.).

Export File Security

To protect confidentiality of exported Project data, several technical measures apply to export files:

• Access restrictions: Only Global Admins logged in to the Global Administration Portal may initiate export of Projects
• Password protection (Optional): In the project export interface, a password may be specified that will later be required to import the exported project file in the future.
  IMPORTANT! Export passwords are not retained in the QuerySurge instance after exporting. When export passwords are applied, Global Admins are responsible for securely storing them outside of QuerySurge for future use. QuerySurge Support does not have any ability to recover lost/forgotten passwords. Loss of export passwords will render export files irrecoverably unusable!
• File encryption: Whether a user-specified password is applied or not, backup files are encrypted using current standards (AES-256). Decryption with external tools is not supported.
  IMPORTANT! Encryption does not prevent loading of non-password protected exports into other QuerySurge instances. 
• Access to export directory: Only individuals with access to the QuerySurge App Server's file system (and other server/network locations where export files are relocated to) may enumerate exported Project files and move them to other locations. System/server administrators are responsible for restricting access to the server file system.

Export Queuing and Project Locking

To prevent overloading of system resources, Project exports are placed on a queue, from which one export is processed at a time. Queue progress can be monitored in Global Administration > Project Export Queue.

Version 12.0+

Version 8.0 - 11.2

In order to avoid conflicts with users editing project assets or user/Agent associations during an export, Projects will be locked before they are queued for export. Projects which are automatically locked by the export process will be unlocked upon completion. If a Project is already locked before export, it will remain so during and after the export.

Import Guidelines

Various guidelines and rules apply when importing projects into a QuerySurge instance:

• When importing a Project export file created with a password, the Project Import Wizard will prompt for the password. 
• All projects in a QuerySurge instance must have unique names. If any existing projects have the same name as the the project to be imported, you must modify the name of the imported project in the Import Project Wizard before the import will be allowed.
• Imported Projects will not maintain associated users and Agents from the originally exported Project. These must be reassigned after import.
• Time required to import depends on the size of the exported Project, QuerySurge server performance, and current load on the QuerySurge instance. Do not close the browser or restart QuerySurge services while importing a project.

Exporting Projects

To export one or more projects, follow these steps:

1. Log into QuerySurge Global Administration Portal as a Global Admin.
2. Navigate to QuerySurge Administration > Manage Projects.
   Note: Entry is named 'Projects' in versions 11.2 and lower 
3. Click Export. The Export Projects window opens. If a project was selected in the prior step, it will automatically added to the export list.
4. To select projects to export, click Add Project in the top right. This will add a new record in the gird and allow selection of the Project to export. Repeat for each applicable projects, or click Add All Projects.
   Note: Projects may not be queued for export multiple times; the Export Projects window only allows selection of each Project once. If a Project is already waiting on the export queue, you will not be able to queue it again.
   
5. Add password to project export. Passwords may be up to 255 characters long. Password protection can be disabled by deselecting this option. 
6. Select the data items to be included in each Project's export file. Note the approximate sizes on disk (before export), and that the totals update as projects are added/removed.
   Note: All desired data must be selected. It is not possible to selectively import data items, or to re-export with different selections at a later time or merge export files.
   • Assets (required) - includes all core assets including folders, QueryPairs, Snippets, Staging Queries, Test Suites, high-level Scenario result details (counts and outcomes), Connections, and Data Retention settings...
   • Test Results (optional) - includes detailed results from test runs such as source/target data and all failures
   • Staging Tables (optional) - includes data from all Staging Tables currently active
   
7. Click Export. If one or more projects are unlocked,  a prompt will appear informing that these projects will be locked for export. If all projects being exported are locked, steps 8 and 10 will be skipped. 
   
8. Click OK. 
9. Since the project will be automatically locked for export, we will want to notify users of this event. This notification is configurable.
   
   Notification Time (minimum 5 seconds): Number of seconds prior to locking a project to notify users. 
   Comment: Notification which will appear for end users informing of the locking of the project. The comment may be up to 1023 characters long.
   
   
10. Click Continue. The Project Export Queue view will open and reflect the Projects that were just queued.

Monitoring Queued Project Exports

Since the process of exporting Projects (as well as the delay for alerting users to pending project locking) can take a significant amount of time, the Project Export Queue view is available to monitor export activity. This view shows the following information:

• Queue Order - order in which Project exports are queued (lower numbers will be processed sooner)
• Project ID
• Project Name
• Status - can be Pending, Alerting Users, and Exporting
• Progress - when the current Status is Exporting, shows approximate percentage of export progress in terms of tables processed (includes all tables for assets, test results, and staging tables). Hovering over the percentage will show a breakdown of the percentage and a count of rows processed.

One or more Pending exports may be cancelled by selecting them (or selecting all) and clicking Cancel Export. Once an export reaches the Alerting Users state, it will no longer be possible to cancel that export. After the Alerting Users state, the Project will be automatically locked and its export will commence.

Importing Projects

To import a previously exported Project, follow these steps:

1. Log into QuerySurge Global Administration Portal as a Global Admin.
2. Navigate to QuerySurge Administration > Projects.
3. Click Import. The Import Project Wizard opens.
4. Click Next to proceed. On the project selection screen, a list will show all project exports in the QuerySurge project export directory located in <QS Install Dir>/tomcat/webapps/ QuerySurge/project_exports
   
5. Select a Project export file to import, and click Next.
   Note: Only one Project export may be imported at a time. To import additional Projects, repeat this process.
6. If a password was applied to the export, you will need to enter the password utilized. Click Next to continue. For an export with no password, this step will be skipped.
   
7. If desired, enter a New Project Name. Click Next to continue.
   Note: If an existing Project in the QuerySurge instance has the same name as the Project being imported, the import will fail due to conflicting Project names. In such a case, modify the New Project Name to make it unique among all existing Projects.
   
8. Review the details of the Project to be imported. If all details appear correct, click Import to start the import process.
   Note: Do not close the browser or restart QuerySurge services while importing a project.
   

After the import is complete, the Project will be shown in the list of projects. User and Agent assignments from the originally exported Project will not be included with the newly imported Project; see the following articles to set up those associations:

Project user assignment
Project Agent assignment