06-SapphireOne Server Upgrade Reference Guide

SapphireOne Server Update Overview

The SapphireOne Server Update Reference Guide is designed for SapphireOne users as a step by step guide to be followed when upgrading either the 4D application, or SapphireOne’s Server Database.
There are two version numbers, 4D and SapphireOne, so from 18.4.0.1 we extract the following.

  • 4D Version numbers – These the the first two numbers. 18.4
  • SapphireOne Version Numbers – The last two numbers. 0.1

There are two upgrade options, 4D and SapphireOne. A separate reference guide for each will be documented in this article. The user will note that there are four groups of numbers separated by 3 dots, for example 18.4.0.1

  • 4D Full Version – When the 4D version changes from 16 > 17 > 18 >19 > 20.
  • 4D Incremental – When when the 4D version changes from 18.1 > 18.2 > 18.3 > 18.4 >.
  • SapphireOne – When the build number changes from 18.4.0.1 > 18.4.0.2 > 18.4.0.3 >

4D upgrades: The user will have to download 450 to 500Mb of data from the SapphireOne File Station. Then unpack the zip file, unzip it and copy the folder and it’s contents into the SapphireOne directory as seen below. It should end up being displayed where the Blue folder is in the tree below under the yellow SapphireOne folder.

Folder Layout Server Database No Database Folder

Downloading Files SapphireOne File Station.

Please note that we have closed our ftp server and replaced it with a SapphireOne File Station.

Files may now be downloaded from SapphireOne by using a web browser. Documentation for this procedure my be found on this web site by going to our article on the new SapphireOne File Station.

Each of our Clients has access to an individual Client folder where they and they only, may upload or download backup copies of there data files to these folders. There is also a common area where all files in the common area may be down loaded but no uploads are allowed. This is where the files in this article are stored SapphireOne File Station.

For example the 4D Server Application, 4D Client application and SapphireOne builds, are all in separate folders for your convenience. Select and download the required files before starting the upgrade procedure documented from here on in this article.


Before You Start for all Upgrades!

All 4d and SapphireOne build upgrades.

Upgrading both the 4D Application and SapphireOne’s current build is now very similar as a file will have to be downloaded from our SapphireOne File Station and added to or replace folders on the SapphireOne server. For this documentation we will be upgrading 4D’s application/structure file from 18.3 to 18.4.

All of the the tasks listed below should be completed before attempting any 4D or SapphireOne build upgrades. This list includes everything that should be done, so each item on the list below in this article, should be considered before moving on.

While still running the previous version, please follow the points below.


Checking and Backing Up of the Data File.

  1. 4D Application & Live Data Files – If you are unsure of the location of these files, their location may be found by going to the server window and selecting the Applications Server tab.
    • Application & Data File – The location for both of these folders and Live data file are located together in the Configuration area. Select the small down arrow to display their full location.
    • Data File Location – If uncertain look at the Time Stamps on the data file and see when it was last modified.
    • Recording – If necessary, write the locations down or take a screen shot.
  2. Checking the Live data file – The Live Data File should also be checked for errors from the Maintenance tab while the server is still running and before any upgrades are performed.
    • Maintenance Tab – From this tab at a minimum, the Verify the Records and Indexes option should be selected and executed. A compaction of your data should also be considered.
  3. Naming Conventions – The naming for the 4D Application folder on your hard drive is as follows.
    • MacOSX – The 4D Application folder is named SapphireOne xx.x Server.app
    • Windows – The 4D Application folder is named SapphireOne xx.x Server
  4. SapphireOne’s Build – The 4D Application folder will contain a folder named Server Database which contains SapphireOne’s current build or upgrade.
    • Server Database – The name and path of this folder must not be altered!
Folder Layout Server Database
File Layout Server Database
  1. Access Server Locally – Access the server directly from the keyboard or use Remote Desktop/Team Viewer.
  2. Data File Checking – Again, while still using the old server version, perform the usual checks that are available from the server administration function. Verify Indexes and Records is the most important one. These are both available from the Maintenance Tab from the server menu.
  3. Data File Backup – If no errors are found , shut the Server down, back up your data file and then restart SapphireOne.
  4. Errors – If any errors are found in any of the steps above, please make a support booking with SapphireOne Support. Please email through screenshots to Support and detail what step you have encountered the error. SapphireOne Support will have this list and will be able to better help with the error.
  5. Manual Backup – Once any errors have been fixed, shut the server down and make an additional BACKUP of your live data file, especially if any errors were found and corrected in any of the procedures above. Remember that it is very easy to recover by using a backup.

4D Application Update Reference Guide.

While this is a 4D incremental upgrade from 18.3 to 18.4, the procedure would be exactly the same if we were performing a full version upgrade from v18 to to v19 which is being currently being tested in a live environment at SapphireOne.

Preparation for the 4D Update.

Downloading & Unzipping Required files

Download one of these 4D files from the SapphireOne File Station.

  1. 4D Updates – These are found in the SapphireOne File Station folder named, 2 Upgrade 4D Server. These files are platform dependent so select the file that is appropriate for your operating platform.
    • MacOSX File Name – VersionNumberMacServer.zip.
    • Windows File Name – VersionNumberWinServer.zip.
  2. Local File Storage – This file should be downloaded to a specific folder set up on your server for the express purpose of unpacking or unzipping of downloaded files.
  3. Unpacking File – Unzip the file inside the folder as documented above.
Checking Current Version
  1. Checking the Data File – You have used the Initial Checking of the Data File procedure documented earlier in this article to check that all is well with your data file?
  2. Folder layout – Using the chart as seen below, find the location of the folder that you will be placing the new 4D version into.
    • Look carefully at how SapphireOne is displaying the folders to you.
    • In this chart the 4D Application folders are in blue background while the SapphireOne builds or compiles are in green.
    • Mac users remember to right click and select the Show Contents option!
Folder Layout Server Database
  1. Verifying Current Version – Access the server using a Client machine and record the complete version number that is currently running on the server which was 18.3.0.11
    • This would be, 4D application file version 18.3 and SapphireOne’s build 0.11
  2. Checking Folder Locations – These may be checked by going to the Application Server tab on your server. Both the 4D Application and the Live data File locations will be displayed in the configuration area on this screen.
Commencing the 4D Upgrade.
  1. Accessing the SapphireOne Server – Access the server directly from the keyboard or use Remote Desktop/Team Viewer.
    • Shut Down- Shut down the old SapphireOne server.
    • Backup – Make a manual backup of your live data file. This is essential as each new 4D version will make alterations to your data file.
  2. Installation Files – If you have not done so already download and unpack the files required from SapphireOne’s SapphireOne File Station into a folder on the hard drive.
    • Mac Zip File Name – 18.4.0.0MacServer.zip.
      • Mac Actual File Name – SapphireOne 18.4 Server.app
    • Windows Zip File Name – 18.4.0.0WinServer.zip.
      • Windows Actual File Name – SapphireOne 18.4 Server.
  3. Finder & File Manager – Both MacOSX and Windows have file managers. For both platforms you can open multiple instances of them.
    • Single Instance – Use the drag and drop function or copy and paste function to move the unpacked folder to the location as indicated above.
    • Multiple Instances – Open the first window and resize it to the left of your screen and leave it displaying the latest unzipped 4D version folder ready for copying.
    • Second Instance – Re-size it and then position it on the right-hand side of your screen. Next proceed to drill into your folders until you have the yellow SapphireOne folder displayed. You should also be able to see the current 4D application folder hanging just below it.
    • Transferring Folder – Now select and copy the SapphireOne 18.4 Server folder on your left window and copy it directly into the SapphireOne folder in your right-hand window.
  4. Checking Folder Location – The SapphireOne 8.4 Server folder should sit immediately below the SapphireOne 18.3 Server folder as seen below.
Folder Layout 4D Server
  1. Creating Shortcuts- Once the SapphireOne 18.4 Server folder has been installed in the correct location the user will have to create shortcuts for each Operating Platform as follows.
    • MacOSX – Select the SapphireOne 18.4 Server app folder, right click and select the Make Alias option.
    • Windows – in the SapphireOne 18.2 Server folder,drill in and find the .exe executable. Then right mouse click and select a create shortcut option from the mouse context menu.

On a Windows it is critical that the shortcut is always executed as Administrator. It is recommended that the short cut properties are modified by right clicking on the shortcut, selecting properties, then selecting the Advanced tab. While the advanced tab is open select the Run as Administrator checkbox.

  1. Remove Old Shortcuts – Immediately delete any shortcuts to the old 4D application.
    • Dock or Toolbar – Also, check if the shortcut is pinned to the dock and, if so, remove it.
    • Warning – Running up an older version of the 4D application is not recommended as you could trash the data file.
  2. Cleaning Up – Remember to delete old upgrade files and folders. All the files that you download are available from the SapphireOne SapphireOne File Station server again if necessary.
    • Live Data File – That is with the exception of your Live data file.
Restart the Server
  1. New Server Restart – On restart SapphireOne will immediately do one of two things.
    • Log File – If the log file is missing it will ask the user for instructions. Select Create and follow the default options. If it finds a log file it will proceed immediately to ask for the location of the data file.
    • Data File – On restart with either a new 4D Application or Server Database, SapphireOne will ask for the location of your live data file.
    • Navigating – Use the operating platforms search function to tell it where the Live Data File is.
  1. Additional Verification – Once the Live data file has been accessed Immediately perform the following checks.
    • Version Numbers – Once the server is running log into it with a Client and check the 4D version number and SapphireOne’s version number. When a new 4D release is installed, SapphireOne’s will also include the current build or compile as a part of the 4D release. This will be 0.0 or 0.1
    • Upgrading SapphireOne- SapphireOne,s builds may have moved on since the 4D release was compiled and an immediate replacement of SapphireOne’s Server Database folder may be required. If this is required please read on as documentation for this procedure starts immediately below!
  2. User Access – Users may now be allowed to access the server.

Commencing SapphireOne Upgrade Process (Server Database).

These next pages of the documentation will compromise a basic step by step procedure to update SapphireOne’s build or compiles. All we will be doing is replacing a single folder named Server Database.
This file is a fraction of the 4D Application file at currently just under 45Mb in size.
Download this file beforehand from the SapphireOne File Station into the folder on your server that files are placed in from SapphireOne.

Preparation for the SapphireOne Upgrade

Downloading Files
  1. SapphireOne Builds or Compiles – These are in the SapphireOne File Station This file is not platform dependent so there should only be the single file for MacOSX and Windows.
    SapphireOne File Station Folder name is: 1 Upgrade Server Database
    The file is named VersionNumberServer.zip 18.4.0.0Server.zip, 18.4.0.100Server.zip.
  2. Local File Storage – This file should be downloaded to a specific folder set up on your server for the express purpose of unpacking or unzipping of downloaded files.
  3. Unpacking File – Unzip the file inside the folder as documented above.
Checking Current Version
  1. Checking the Data File – You have used the Initial Checking of the Data File procedure documented earlier in this article to check that all is well with your Live Data file?
  2. Folder layout – Using the chart as seen below, find the location of the folder that you will be replacing with the new SapphireOne build version.
    • Look carefully at how SapphireOne is displaying the folders to you.
    • In this chart the 4D Application folders are in blue background while the SapphireOne builds or compiles are in green.
    • Mac users remember to right click and select the Show Contents option!
Folder Layout Server Database
  1. Verifying SapphireOne’s Version – Access the server using a Client machine and record the complete version number that is currently running on the server for example 18.4.0.11. SapphireOne’s build number would then be 0.11 or build 11.
  2. Checking Folder Locations – These may be checked by going to the Application Server tab on your server. Both the 4D Application and the Live data File locations will be displayed in the configuration area on this screen.

Commencing the SapphireOne Upgrade Procedure (Server Database).

  1. Accessing the SapphireOne Server – Access the server directly from the keyboard or use Remote Desktop/Team Viewer.
    • Shut Down- Shut down the SapphireOne server.
    • Backup – Make a manual backup of your live data file. This is essential as each new SapphireOne upgrade will make alterations to your data file.
  2. Installation Files – If you have not done so already download and unpack the file required from SapphireOne’s SapphireOne File Station into a folder on the hard drive..
    • Mac & Windows File – The zip file that you want is named XX.x.x.xServer.zip. It is common to both MacOSX and Windows. The X’s replace the version numbers, the last two x or numbers is SapphireOne’s build number.
    • File Name – XX.x.x.xServer.zip will unpack to a Server Database folder. This folder and the files within are SapphireOne’s files. The folder name Server Database must not be Changed.
    • Installation Options – You have two choices when installing this folder onto the hard drive.
      1. Copy and Paste the Server Database folder directly into the SapphireOne 18.4 Server folder. The user will be asked for permission to overwrite the existing Server Database folder.
      2. Rename Server Database folder to Server Database 11 as this was the build number. Then copy to the Server Database folder into the SapphireOne 18.4 Server folder.
        • The result will be as in the screenshot below. The user now knows the Server Database folder is in the correct location as it will be directly above or below the old Server Database folder.
        • The old folder can be deleted as required.
File Layout SapphireOne Files
  1. Finder & File Manager – Both MacOSX and Windows have file managers. For both platforms you can open multiple instances of them.
    • Single Instance – Use the drag and drop function or copy and paste function to move the unpacked folder to the location as indicated above.
    • Multiple Instances – Open the first window and resize it to the left of your screen and leave it displaying the latest Server Database folder ready for copying.
    • Second Instance – Then re-size it and then position it on the right-hand side of your screen. Next proceed to drill into your folders until you have the yellow SapphireOne folder displayed. You should also be able to see the current 4D application folder hanging just below it.
    • Server Database folder – Now select and copy the Server Database folder on your left window and copy it directly into the SapphireOne 18.4 Server folder in your right-hand window.
    • Checking Folder Location – The Server Database folder should sit immediately below or above the Server Database 11 folder as seen above.
  2. Cleaning Up – Remember to delete old upgrade files and folders. All the files that you download are available from the SapphireOne server again if necessary.
    • Live Data File – That is with the exception of your Live data file.
  1. New Server Restart – On restart SapphireOne will immediately do one of two things.
    • Log File – If the log file is missing it will ask the user for instructions. Select Create and follow the default options. If it finds a log file it will proceed immediately to ask for the location of the data file.
    • Data File – On restart with either a new 4D Application or Server Database, SapphireOne will ask for the location of your live data file.
    • Navigating – Use the operating platforms search function to tell it where the Live Data File is.
  1. Additional Verification – Once the Live data file has been accessed Immediately perform the following checks.
    • Version Numbers – Once the server is running log into it with a Client and check the 4D version number and SapphireOne’s version number.
  2. User Access – Users may now be allowed to access the server

Was this helpful?