The Upgrader / Installer Utility Program and Upgrade procedure

If Developers add code to your App, they will rebuild it, and you will need to switch from your current App to the new one. If the database of you App is upgraded or changed (running scripts to change its structure) these changes have to be propagated to all instances of the database.
Many changes can be made to an Orixa App without the need for an Upgrade, as many changes will propage via data-updates, so the need for upgrades should be rare.
When there is a need to UPGRADE the database, use the Upgrader / Installer Utility.

Developers managing Orixa systems with remote users can upgrade their systems using this utility. If the user on the remote machine follows these steps they will be able to upgrade their systems by themselves, provided the developer has set up the correct backup file-stores on the server before they start.

The Orixa Upgrader / Installer Utility

Installer Utility: "OrxUpgrader.exe"

Controls on the Upgrade Page

The "Upgrade" page of the Upgrader / Installer    

1. "App Name" list. This retrieves the name(s) of Orixa Apps stored in the Registry of the current computer. If None are present it will be blank. For an upgrade there should be names present in the list. Pick the one you want to upgrade.
2. Orixa stores the database connection details for your App and a security key in the Registry. If the connection details of your App changes (for example with a new IP Address) you can access and update these details here.
3. Server Downloads store files. Once you have clicked the "Find Files" button, if the Upgrader can find the "ServerDownloads" Store for this computer, any files present there will be shown in this list.
4. Find Files button. Opens the "ServerDownloads" store for this computer. This is the store/folder on the server computer where update and upgrade files are saved.
5. Fields to hold names of files to be used in the Upgrade. Drag files from the Server-Downloads Files List into these fields. Note that an upgrade may involve upgrading just the database, or just replacing the App File, it is not necessary for all the fields to be completed in every case.
6. The App File will be copied into the Folder detailed in the "App Folder" field. This should be automatically set from the Registry settings, however if you want to copy the App File into a different folder, you can click "Pick" to navigate to a suitable folder on your computer.
7. Execute Upgrade button. Once clicked, if there is a valid file name in the "Database Backup", "SystemDB Backup" or "App File-Name" fields the program will copy these files from the ServerDownloads store to the local computer and then (for database files) restore the appropriate database.
8. Exit button, to close the Upgrader / Installer Utility.
9. Help-information panel. As you hover over different areas of the screen this will show explanations of what to do.

Simple Upgrade Process

A new version of your App, and / or database is created. It will be uploaded to a cloud-location. When you run data-updates in your App it checks for a new version, if it finds one it will issue a message "There is a new version of your App Available, please run the Upgrader program to install it."

To Download a new, upgraded App and database, undertake the following steps:

OrxUpgrader	First ensure that you have exited your App. Then run the Upgrader Utility: Find the "OrxUpgrader" Program, it is usually in the folder that holds your Orixa App. Run it, the main screen, shown below should open.
Upgrader: simple upgrade 1	Select the name of your App from the drop-down list. Click "Find Files" to locate files in your Server-Downloads store. Find the new version of your App from the list of files in the "Server-Downloads Store". Note that from time to time your Developer may ask you to download other files using this procedure. In that case your Developer will give you the name of the file to find in the "Server-Downloads Store" list, and you can follow the same steps.
Upgrader: simple upgrade 2	To just install a new App executable: Click on the file you want to use and drag it to the "App File-Name" field. Note that you can also type the name into the field. Check that the "App Folder" field contains the folder-path where your App is stored. If it does not, correct it. Click on the "Copy new files …" button. This will copy the new file into the "App Folder." Depending on your internet connection this process may take some time.
Adding Database Backup to the upgrade	To Upgrade to a new App and replace the database(s): Drag the Backup file for your new database(s) from its location in the Server-Downloads Store Files List to the "Database Backup File" and "SystemDB Backup File" field(s). Depending on the nature of the upgrade you may need to change only one of these databases. If there is also a new version of the App executable, that can be copied as well. Note: If you want to copy more than 1 new file (for example the if other Utility Files are needed) you can drag-and-drop as many files as you like into the "App File Name" field. Be sure to set the folder for the App, you can type it in or pick it using the button. Click "Copy new files" the upgrader will copy the files, and if DB Backup files are included in the upgrade, the new database files will be restored on the system.

Developer Steps for Upgrading / Installing

Prior to the upgrade, all users must ensure that they have "Run Updates" on their machine, to pass all data from their systems to the centre. After this point they can continue to use their Orixa Apps, but any data they add or edit will be lost after the Upgrade.

Once the central database holds all updates, the developer can then run upgrade scripts to transform and extend the system, creating the new version.

These upgrade scripts will have been developed and tested against test versions of the database. Running the upgrades rarely takes more than a few minutes.

After the central database has been upgraded:

1. Make a backup file of the main "Data" database of the finalized new version of your App database.
2. Delete all update-files in all user-download-stores, as these will already be present in the backup file created in step 1., above. Users should stop calling "updates" of data from their App, and ideally they should stop using their App, as new updates may not be compatible with their older version of the database.
3. If the upgrade includes changes to the SystemDB database, make a backup file of this database as well (this step is rarely needed).
4. Find the new Exe file for your App. This is usually provided for you by your Orixa Developer. (This step is only needed occasionally)
5. Copy the "Base System Files" (detailed below) into every downloads-store for all remote-computer users.
6. Request that every tablet-computer undertakes the steps detailed above in "Ugrade Steps on each user machine."

For Upgrade

The Developer creates new App and DB Backup Files. These must be copied into every user's "Server-Downloads" Store (the store which is used to hold all update files that synchronize the user's system with the central database). The user runs the Upgrader, and undertakes the steps detailed above on each users machine.

For New Install

The Developer creates a remote store and copies all the Base System Files, into it. The Developer then runs the Utility on the user's machine, following steps laid out below. The installation is not completely automated, but this allows customization as per a Developer's needs.

What Are the "Base System Files"?

All the files detailed in the table below are needed:

YourAppSys.exe Softwarelogo.jpg	The main Executable file for your App: It will have a name set by you / your developer. The "Softwarelogo.jpg" is just the picture file which will be shown when your App first starts. You can use any image-file you like, provided it is in JPG format, and you rename it.
OrxServer.exe OrxServer.ini OrxDBUtil.exe OrxUpgrader.exe	The Supporting Orixa Executables: OrxServer is the database engine, which runs on each computer and allows the Orixa App to access the databases. The OrxServer.ini is a text file which holds the settings for the Server. The OrxDBUtil.exe is the Orixa Database Utility. This file is optional. Only include it if the user needs its functionality. The OrxUpgrader.exe is the Upgrader Utility. This is useful if you wish to allow Users to undertake their own upgrades in the future.
Data-BU-2021-11-11.EDBBkp Data-BU-2021-11-11-SysDB.EDBBkp	Database Backup Files:  These usually have names similar to the file-names on the left. You will have created these files in the earlier step.
en_GB.aff en_GB.dic en_US.aff en_US.dic	Dictionary / Spelling Correction Files: These 4 files allow Orixa to do live spell-checking of words typed into your App.

If you are Upgrading, make sure you have exited the Orixa App on the machine prior to running the Upgrader. Also, if other programs are accessing the Orixa database (such as Excel or other automation programs) ensure these are also closed.
If any program is accessing the Orixa database during the upgrade, the upgrade process will fail, as a database can only be restored while there is just one user connected, but no damage will be done to any part of the Orixa system.

New Installation

New Install

A Server Store should have been created with all the Base System Files needed for an installation. 

These are:

1. Database and SystemDB backup files with the current version of your database and up-to-date data.
2. Executeable "App" files, and the Dictionary and Software Logo files.
   - YourAppSys.exe (this is the program the user runs)
   - OrxServer.exe (this is the database server program) and OrxServer.ini (the text file containing settings)
   - Dictionary files: en_US.dic, en_GB.dic, en_US.aff, en_GB.aff (these are used by Orixa's built in spell-checkers)
   - Softwarelogo.jpg (this is used to show a company logo at start up. You can use your own image file if you wish to, to customize the App).
3. Optional Utility files: OrxDBUtil.exe and OrxUpgrader.exe.

On the user's Computer

1. Create a new Folder "C:\YourAppSys"
2. Copy the OrxUpgrader.exe into this folder and run it.
3. Click on the "New Installation" page.

"New Installation" Page of the Upgrader / Installer

New Installation Page

1. Fields to hold settings for the App and the Remote Store which will be used during the set-up and for communication with the server once set up is complete. Be sure to enter the correct server password in the "Remote Store DB Password" field.
2. File List (note the example shown is displaying files, so the "Create and Open Remote Store" button has already been clicked)
3. Create Empty database: This button sets up all the files and folders needed for the system. Note that is uses "App Folder" as the base for the installation. The "App Folder" should contain the folder you wish to use for the installation.
4. "Create and open remote store" once remote store details are correctly entered, the Utility will create a "ServerDownloads" store with these details, and then open it, and load the file-list into "2."
5. Installation buttons. "Copy to Local" will copy all needed files into the appropriate locations note that you must select backup files you want to transfer "App" files will be copied automatically using their names, but the remote store may contain several backup files so you have to select the ones you want to use.
   Restore DB and SysDB: This will open a window with a list of the backup-files you have just copied with "Copy to Local", you can then select which one to use to restore the "Data" database and the "SystemDB" database.

Restore DB and SysDB

Orixa Server Database Restoration Form

After you click the "Restore DB and SysDB" button, the above window will open. The Backup Files List should show the two files you have copied in prior steps.

To Restore:

1. Click on the Backup file for the main database, and click the "Restore Main Database" button.
2. Click on the Backup file for the SystemDB database, and click the "Restoure "SystemDB" Database button.
3. Almost all Orixa Systems' main database is just called "Data", if this is the case for your database, leave the "Name of Main Database" Field unchanged. If your main database has a different name you must change it.

 

Once these steps are completed the system should be set up and operational. You can run the Orixa executable, and test it is working as expected. In some systems the installer may fail to add the OrxServer.exe to the "Startup" folder of Windows. If this happens, the OrxServer will not start when the user restarts their computer, and their Orixa App will give a "Connection Refused" error message. In this case add the OrxServer to the Startup folder of Windows manually, by copying a short-cut into the folder.

Note, as with the upgrade process the "Change Log" page will show a list of actions undertaken by the Upgrader / Installer. You can switch to this page to see the results of the installation. Any errors which have occurred during the process will be shown with messages on this page.

How the files on a users computer should look once the installation is completed

Base Application Folder	The Orixa App file, together with dictionary, and logo files are in the base directory used by the Developer. Click on the "TestSys.exe" to run the App. Right click on "TestSys.exe" and select "Pin to Start" "Pin to Taskbar" or "Send To" / "Desktop Create Shortcut" to add the App to your Start Menu, Taskbar or Desktop.
Base Database Folder	The "Database Folder, which contains the newly created database catalog files. The "Data" folder should contain all the data-table files for your database. The "Stores" folder should contain sub-folders for the "Backup", "Uploads" and "Downloads" stores The "SystemDB" folder should contain the data-table files for the SystemDB. The "Temp" folder will contain temporary files when the App is in use.
The "Utils" folder with the OrxServer and its Ini File	The Utils Folder, which contains the OrxServer, which is used by the App to access the database. Note that the "OrxServer.ini" file is a simple text file which contains the settings for the Orixa Server program. These can be manually edited if necessary.
The OrxServer Running on the test machine	The Installation process sets the OrxServer running, and sets it to run at start-up on the machine. This allows the Orixa App and any other ODBC connected App (such as Excel) to access the database. Click on this icon to open the OrxServer window. From this window a number of admin tasks can be undertaken. There are separate Help-topics covering the OrxServer.

Extra features of the Upgrader, and additional information

 

Upgrader / Installer "SQL Script Runner" Page

SQL Script Runner Page

As well as the automated Upgrade and Installation pages, the Utility also includes a page with a SQL Script window in which you can run scripts to perform admin and make changes to a system.

1. SQL Script runner page.
2. SQL editing window.
3. Button to load SQL from a file you have accessible.
4. Button to execute the script.

Upgrader / Installer "Change Log" page

Change Log Messages

When you undertake actions in the Upgrader / Installer the program will add messages indicating that each step has been completed. The Developer should take time to review this page at the end of an installation process to make sure that all parts have executed correctly.

How to Create a new Downloads store on the Server for a New User 

New User's Downloads store

1. On a Computer linked to your main server-machine, open the DB Utility in your main application, or open the Orixa Management Database Utility, and connect it to your database.
2. Create a new store, with the name "Downloads-User1" replacing User1 with the name you want to use to identify the store.

Once this store has been created it will start to fill with Update files as your system swaps data between users. You can add the installation files (including database backup files) to the store so they are ready to be use in the installation.

Note that the backup-files must be created so that they synchronize with new update-files that are created by the system. In other words, create the backups and delete all update files which are older than the backup file from the store, as their data has already been incorporated.

Manually Resetting Registry Settings if the Server Address Changes

When a completely new system is installed, no registry settings will have been added, they will be created by the installation, and there is no need to reset them as shown below.

Manually Resetting the Registry Settings on a Computer

If the IT department have to change the remote server that holds the Orixa Database, or they have to change the Server's IP Address, Port or database-password then the "Registry Settings" on each computer need to be changed. In this case Open the Upgrader / Installer and: Click the Check Registry button. Enter new details and click "Save Settings." Note that no text is shown in the "System Password" field, this is normal. If you need to change the log-in password, type it into the "System Password" field and click "Save Settings". Remember that the database-password is NOT the same as the User-password that each person uses when they log-on to the Orixa App.

Orixa Registry Settings

Orixa Registry Settings Orixa stores the Database Folder, Database Name, Remote IP Address, Server Port and Password in the Registry at the location: Computer\HKEY_CURRENT_USER\SOFTWARE\Orixa\[SysName] (shown at 1., in the image on the left) You can open the Windows Registry Editor to review the details there. (shown at 2.) Details on how to edit and update these settings manually are given in this Help-topic: Orixa Registry Settings

Upgrade Steps on each user machine

Select your Orixa App from the drop-down	Run the Orixa Upgrader. The program can be stored in the same folder as the Orixa App to make it easier to find during the upgrade process. Navigate to this folder and run the program. Once it is open, select your Orixa App from the Drop-down, and click "Find Files" Note that on most systems there is only one Orixa App stored, so there will only be one item in this list.
Steps to use the Upgrader Utility	If a new database backup file is present in the backup store, click on it, and drag it to the "Database Backup File" field. You can also type in the name of the file. If a new "Exe" file is present, click on it and drag it to the "Exe File-Name" field. You can also type in the name of the file. Click the "Copy New Files ..." button, an the Upgrader will carry out the upgrade. Once it is finished you can close the Upgrader Utility and restart your Orixa App.
Change Log Messages	The upgrade will take some time, depending on the size of back-up files and the speed of the network. The back-up file must be copied from the user's ServerDownloads store onto their own machine, and then used to restore the database. If the backup file is large this can take several minutes over a slow connection. For smaller systems over a fast LAN the file-transfer should only take a few seconds. During the process each step of the process will be detailed on the "Change Log" (1.) Page. installation and its result. If the user has any doubts about what has happened they can copy the content of this message-window (using Control+C) and send it to the Administrator or Developer by email. Common issues: A backup file with exactly the same name is already present on the local machine. In this case the Upgrader / Installer will refuse to continue. The Developer should delete or rename the file in the backup store using Window Explorer.