Tenjin Icon

Installing and Upgrading Front Office

There are four components in a Front Office installation:

  1. Portal
  2. Web Service
  3. Windows Service
  4. Database

There are several different ways the components can be distributed, but the primary focus of this guide is the two-server installation method. A Web Server hosts the portal, web service, and windows service, and a database server hosts the database; as below.

mceclip0.png

Other configurations are supported, in particular:

  1. Side-by-Side installation – Multiple independent Front Office systems installed on the same hardware. 
  2. Load balanced installation – A load-balanced installation has a single database server and database, but multiple instances of the portal, public web service, and windows service, which provides load balancing and redundancy. 

Please contact support if you have any questions about the installation process, including details of specific alternative implementation models.

Please see this article for a list of prerequisites.

 

This article covers the following topics:

Installing Front Office 9.6

Installing and Configuring Front Office is a three-step process:

mceclip1.png

This section focuses on the first two steps of this process. Post-installation configuration of Front Office is covered in post-install and upgrade validation.

The Front Office installation is packaged as a single executable, Front Office 9.6.exe. Double-clicking on the exe launches windows installer, which copies all the relevant files to disk. The default install location is C:\Program Files\Biomni\Front Office 9.6, though this can be changed.

The installation produces the following folder structure; as below.

mceclip2.png

After the windows installer has run, the Configurator is launched automatically. If the configurator needs to be started manually, double click on Configurator.exe in the root of the installation location. The configurator is a wizard which asks for several parameters required to configure the system, such as Database name, Portal name, etc. Once these parameters have been entered the configurator configures IIS, and installs the database and windows service.

Security and IIS Configuration

It is worth thinking a bit about how IIS will be configured. Two components are installed within IIS:

  1. Portal
  2. Web Services

The security considerations for these two components are different. The portal needs to be visible to all users of the system, which could mean exposing the portal over the public internet. The web services provide an integration point and need only be visible to internal systems.

Therefore, the recommended configuration is to create two IIS websites for the two components. The first IIS website hosts the portal, and the second IIS website hosts the web services.

mceclip3.png

The security of the IIS websites can then be configured appropriately, restricting the visibility of the web services, and not exposing them over the public internet.

HTTPS

A further level of security can be provided by configuring the websites to use HTTPS. If you want to use HTTPS, it is best to configure it before installing Front Office.
To set up an IIS Website with HTTPS:

  • Import SSL Certificate into IIS
  • Configure the Website to use HTTPS
    1. In IIS navigate to the Website where Front Office will be installed.
    2. Right Click > Edit Bindings…
    3. Click Add.
    4. Select Type HTTPS, and choose the SSL certificate, click OK.
    5. On the bindings page, choose HTTP and click Remove; accept the confirmation.

Installation Process

The installation process is as follows:

  1. Install the new version of Front Office using Front Office 9.6.exe. Installation should be run on the web server or application server. Installation must NOT be run on the database server.
  2. Configurator: click on Install a New Front Office System.
  3. Select Components: leave all checkboxes checked; click Next.
  4. Install Web Server Features: if you are installing the portal or web service, this page installs and configures IIS to work correctly with Front Office.
  5. New Installation Configuration Options:
    1. Enter your Company Name.
    2. Enter the Portal Name, which will be used for the virtual directories and windows service name.
    3. Select whether to install the portal in an IIS application or directly under the root of the IIS website. This affects the URL of the website once it is installed.
    4. Select the IIS websites for the portal and web service. For security reasons, it is recommended to install the web service under a different IIS website, which is not exposed over the internet.
    5. Select a Base Currency and Language. The base currency cannot be changed after installation, so this must be carefully considered.
    6. Sample Data may also be installed, which will populate the database with preset data to showcase some of the capabilities of Front Office.
  6. Database Installer Connection: select the credentials that the installer will use to create and build the database. The user may have either Windows or SQL Server authentication but must have the ‘sysadmin’ database role. The configurator will create the database during the installation.
  7. Application Connection: enter an application username and password. These credentials will be used to create a database login and database user, and in the connection strings for the portal, web service, and windows service. The domain policy password complexity rules are applied to the password you enter here.
  8. Application Security: The application key is used to encrypt third-party passwords in the system. If you are installing a new system, click the Generate Key button to create a new key. If you are installing a new component for an existing system, paste the key from the original installation into the box; for example, you are installing a second portal in a load balance system or a second windows service for redundancy. Click here for more information about the application key. 
  9. Validate Installation Parameters: performs validation to make sure that the installation parameters are correct.
  10. Confirm Options: this screen provides a summary of what the configurator is going to create. If If you are satisfied, click Install to begin the installation.
  11. Login: Once the installation is complete, click the link to login, or use the link in All Programs/Biomni/Front Office 9.6/. Login using:
    1. User ID: Admin
    2. Password: password
      You will be forced to change the password after the first login.
  12. Configuration Check: In the portal, navigate to Admin > Support > Configuration Check. See the post-installation and upgrade validation section for detailed information about checking the configuration. 

Upgrade

Upgrading Front Office is a three-step process:

mceclip4.png

This section focuses on the first two steps of the process. Post upgrade validation of Front Office is covered in the post-installation and upgrade validation section. 

An upgrade of Front Office uses the same executable as a new installation, Front Office 9.6.exe. Double-clicking on the exe file launches the Windows installer, which copies all the relevant files to disk. By default, the installation location is C:\Program Files\Biomni\Front Office 9.6, though this can be changed. An upgrade of Front Office puts a new set of files on the hard disk in a new location, it does not replace the existing installation. 

After the windows installer has run, the Configurator is launched automatically. If the configurator needs to be started manually, double click Configurator.exe at the root of the installation location.

The configurator is a wizard which asks for several parameters required to upgrade the system, such as Database name, Portal name, etc. Once these parameters have been entered, the configurator configures IIS, and upgrades the database and windows service if required.

In detail, the upgrade process is as follows:

  1. Back up the existing database.
  2. Recovery Mode: Set the database recovery model to Simple.
  3. Growth Settings: For large databases (10GB plus) the upgrade may take several hours to complete. It is recommended to set file growth for both mdf and ldf files to 500MB for a balance between speed of upgrade and disk space usage.
  4. Email (optional): If the system should not start sending emails immediately after the upgrade, deactivate emails via Admin > Email Templates.
  5. Install the new version of Front Office using Front Office 9.6.exe.
  6. Configurator: At the Configure stage, click Upgrade a Front Office System.
  7. Select Components: Select the components which are installed on the server. Click Next.
  8. Upgrade Portal and Web Service: Select the IIS Applications of the Portal and Web Service to upgrade. Click Next.
  9. Upgrade Windows Service: Select the existing windows service to be upgraded. Click Next. On upgrade, a new windows service will be created and the old one deleted. The connection string will be copied from the existing windows service.
  10. Upgrade Database: Choose the database server and database to be upgraded. Select the authentication method for the upgrade (the user that the installer will use for the upgrade). The user should have the ‘sysadmin’ database role. It is possible to perform an upgrade with a reduced permission set, see Installing Database with Reduced Permission Set section. Click Next. 
  11. Application Security: If the upgrade passes through version 8.1 then the application security page is displayed. If this is the first component upgraded, click the Generate key button to make a new key. If a component of this system has already been upgraded, then paste the key from the original upgrade into the input. (For example, when upgrading a second portal in a load-balanced system or a second windows service for redundancy). For more information about the application key see section. 
  12. Validate Installation Parameters: runs validation checks on the installation.
  13. Confirm Options: This screen summarizes the parameters that have been entered. Check the details carefully. If edits are required, click the <- (back) button in the top left corner to go back through the configurator wizard. If no changes are required, click Install to begin the upgrade.
  14. Login: Once the installation is complete, click the link to login, or use the link in All Programs/Biomni/Front Office 9.6/. Log in as Admin.
  15. Configuration Check: In the portal, navigate to Admin > Support > Configuration Check. See the post installation and upgrade validation section for detailed information about checking the configuration.
  16. Shrink the database.
  17. Recovery Model: Revert recovery model and file growth settings to their previous values.
  18. Email (optional): if you disabled emails in step 4, re-enable them.
  19. Custom stored procedures: If there are custom stored procedures in the main Front Office database, they will need to be re-created after the database upgrade. Note that it is best practice to put custom stored procedures in a separate schema or database to avoid this issue.
  20. Uninstallation: Once you are confident that the system has upgraded correctly you may uninstall the old version via Control Panel > Add or Remove Programs. This will remove the old files on the hard disk.

Post Installation and Upgrade Validation

Configuration Check

After installation or upgrade, check that the system is configured correctly with the Configuration Check screen (Admin > Configuration Check).

Server Tab

  • Windows Service: This shows the status of windows services that are pointing at the Front Office
    database. Each windows service writes heartbeat information into the database every 5 minutes. If the database has not received a heartbeat within 7 minutes the service will be highlighted in red.
  • It is possible to configure the system with multiple windows services pointing at a single database, a configuration useful for redundancy. Each windows service writes three records into the windows service table, so if for example there are two windows services, six records will be displayed.
    After the upgrade, the table may contain records for services that no longer exist. To remove these records, click the Clear All button. This clears the entire table, but active services will insert new records when they next update their heartbeat.
    The Windows Service section describes checking the configuration of the windows service on the server where it runs. 
  • Database: Shows the database version and most recent database change. These fields are useful in support scenarios.
  • Web Server: The critical field is the Web Root Address. This should be the URL of the home page of Front Office, as seen by a user of the system. This setting is used when constructing emails with hyperlinks into Front Office.
  • Public Web Service: If the Public Web Service URL is incorrect the web page will display an error message. 
  • Table: The table at the bottom of the page shows the version numbers, connection strings, and application encryption status of all the components in the system. All the version numbers and connection strings must match, if they do not an error message is displayed. If the application key is incorrect, the application encryption status will indicate this, and an error will be displayed.

Base Settings Tab

  • Check that the base settings for Front Office are appropriate:
    • System Language.
    • System Time Zone – choose a time zone that will be an acceptable default for most
      users.
    • Country Code.
      The base system currency is also shown, however, this is set at installation time and must not be changed after a request has been raised, as this will cause major data issues.
  • Image Upload: Click the image button to open the Image Manager. When correctly configured, the Image Manager should list a folder named UploadedImages. Select the UploadedImages folder and click the Upload button. Browse to an image file and upload, if successfully uploaded the image should appear on the right-hand side of the Image Manager dialog.

Email Tab

  • Configure SMTP settings for outbound email by clicking Edit SMTP Settings. On upgrade, these settings should be migrated forward, though it is still worth checking that they are correct.
  • Review core email addresses for the system.
  • Send test email: Click on the Send Test Email button to send a test email from the Front Office system. For the email to be sent successfully a windows service must be running, the email task must be enabled, and the SMTP settings must be correct.
  • Check the Email Queue: Queued emails can be viewed via the Email Queue button. The email queue will show any error encountered whilst sending the email. When the email is sent successfully it is removed from the queue.

Windows Service

After an installation or upgrade, it is advisable to check that the windows service is running correctly on the server where it is installed:

  1. Open Event Viewer and navigate to the Application Log.
  2. Find messages with a Source of ‘DirectaService9.6$FrontOffice’. The name may vary slightly - the naming convention is ‘DirectaService9.6$’, which is the name of the portal.
  3. If the windows service has logged any errors, then it is possible there is a configuration
    problem. Examine the detail of the error.

There are two common types of configuration problems that can occur with the windows service:

  1. Windows service cannot connect to the database. The windows service checks connectivity to the database defined in the config file. If the service cannot connect, it will log an error in the windows event log.
  2. Windows service and database at different versions. The windows service is tied to a specific version of the Front Office database. So, for example, a Front Office 9.1 service will work with a Front Office 9.1 database, and a 9.0 service will work with a 9.0 database. If the service detects that it is pointing at a database that is a different version of Front Office, it will log an error in the windows event log and shut down.

Application Key

An application key is created during the configuration of the portal. The application key is used to encrypt third-party passwords which are stored in the database; for example, the passwords for adapters and integration settings. The application key is not used for the encryption of user login passwords. The application key is stored in an encrypted section of the config file for the portal, public web service, and windows service.

The application key is critical to the correct operation of the system. If the application key is lost it will not be possible to recover the third-party passwords. Logging on will be unaffected but passwords for adapters and integration settings will need to be re-entered.

In practice, there are two ways the application key could be lost.

  1. The web server fails.
  2. The website is uninstalled.

To mitigate the first issue, a backup of the web server should be kept. For the second scenario, if, for example, the web server needs to be moved to a different physical machine, the application key should be copied from the config file on the old server and the new website installed using the application key. Test that the new server is working correctly and verify that there is a valid backup of the server. Once complete, uninstall the website from the old server.

The application key, as well as the database connection strings, are stored in an encrypted section of the config files for the components. There are two helpers to decrypt and encrypt the config files:

  • <Install Location>\MsBuild\ConfigEncrypt.bat
  • <Install Location>\MsBuild\ConfigDecrypt.bat

The files which are encrypted/decrypted are:

  • <Install Location>\WebSite\web.config
  • <Install Location>\PublicWebService\web.config 
  • <Install Location>\ServiceHost\DirectaSvcHost.exe.config

Applying a Service Pack

The Front Office Service Pack updates a single Front Office instance to the latest service pack release. Details of the service pack changes can be found in the latest Front Office Service Pack
Contents.pdf file.

There are two different methods to apply a Service Pack, depending upon whether the original installation was via the Windows installer (exe) method or the zip file (manual) method.

Applying a Service Pack to an exe Installation

  1. Login to the web server as Administrator.
  2. Copy the Service Pack onto the web server.
  3. Run Front Office 9.6.xxxx Service Pack.msp.
  4. For each load-balanced web server repeat steps 1 to 3.
  5. Login to Front Office as a supervisor and check that the site loads correctly; this step updates the database with any changes. Once the update is complete the site is presented and ready for use. If any problems updating the database are found, an error will be displayed on the home page, with a reference to the Error Log (available via the Admin > Support menu).

Applying a Service Pack to a zip (Manual) Installation

  1. If the Front Office Service has been installed, the service should be stopped (Biomni Front Office Service 9.6 in services).
  2. Copy the contents of the Front Office 9.6.xxxx Service Pack for Manual Install folder over the Front Office 9.6 site, but first, unblock the zip file before uncompressing by right-clicking on Properties > Unblock.
  3. Restart the Biomni Front Office Service 9.6 service.
  4. Login to Front Office as a supervisor and check that the site loads correctly; this step updates the database with any changes. Once the update is complete the site is presented ready for use. If any problems updating the database are found, an error will be displayed on the home page, with a reference to the Error Log (available via the Admin > Support menu).

Applying a Service Pack when Windows Service is Running on a Separate Server

If running a separate application server for the Biomni Front Office Service, the service pack must also be applied to this installation.

Uninstallation

To uninstall a Front Office system:

  1. Navigate to Control Panel > Programs and Features
  2. Locate the Front Office System to be uninstalled
  3. Click Remove

The uninstallation process will remove the windows service, the portal, and the public web service, which are pointing at the installation location. It will then delete the software from the hard disk and the start menu shortcut. The uninstallation will NOT delete the database, this must be done manually.

If you have installed Front Office with the zip file (manual installation):

  1. In Windows Explorer, navigate to the root installation folder.
  2. Double click on the uninstall.bat file and follow the instructions. This will uninstall the web components and windows service. It will not delete the database.
  3. In Windows Explorer, delete the root installation folder.

Software Requirements

It is recommended that the latest service pack should always be used for all software.

Server Operating System

The following operating systems are supported:

  • Windows Server 2012 R2
  • Windows Server 2016
  • Windows Server 2019
  • Windows Server 2022

SQL Server

The following versions of SQL Server are supported:

  • SQL Server 2014
  • SQL Server 2016
  • SQL Server 2017
  • SQL Server 2019
  • SQL Server 2022
  • Azure SQL database
  • Microsoft SQL Server on Amazon RDS

Client Browsers

The following client browsers are supported:

  • Edge
  • Firefox
  • Chrome
  • Safari

Customizing Image Upload

Image upload is configured automatically. By default, uploaded images are stored at: C:\inetpub\Biomni\Images. This section describes how to change this storage location:

  1. Launch Internet Information Services (IIS) Manager.
  2. Navigate to the Front Office Application.
  3. Expand the view and locate the UploadedImages virtual directory.
  4. Right-click Manage Virtual Directory > Advanced Settings.
  5. In the ‘physical path’ text box, enter a path to where the virtual directory will exist on disk. This path is where any uploaded images will be stored. The path can either be a path on the local server; for example, c:\uploadedimages; or a UNC share; for example, \\myshare\uploadedimages.
  6. By default, the connection to the physical directory is set to be ‘pass-through authentication'. If a UNC Share was chosen, click Physical Path Credentials, followed by Specific User, and enter the required credentials.
  7. In either scenario, the connecting credentials will require read and write access to the physical location.

Once the UploadedImage virtual directory has been created, it can be verified in the portal in the Configuration Check pages.

  1. Login to the portal as Admin
  2. Goto Admin > Configuration Check > Base Settings.
  3. Click the image button.
  4. When correctly configured the Image Manager should list a folder named UploadedImages
  5. Select the UploadedImages folder and click the Upload button.
  6. Browse to an image file and upload, if successfully uploaded the image should appear on the right-hand side of the image manager dialog.

Side-by-Side Installation

A side-by-side installation has multiple independent Front Office systems installed on the same hardware.

mceclip5.png

Due to technical limitations of the Windows installer technology, only a single instance of Front Office can be installed with the windows installer (exe) method. However, Front Office can also be installed from a zip file, which is available from the Download website.

  1. Create a folder on the web server where Front Office is being installed.
  2. Copy the Front Office install zip file into this location. Unblock the file before uncompressing it, right-click the file and select Properties, then Unblock.
  3. Extract the file to this location.
  4. Double click on Configurator.exe to run the configurator.
  5. Follow the on-screen instructions.

To uninstall a Front Office installed from a zip file:

  1. In Windows Explorer, navigate to the root installation folder.
  2. Double click on uninstall.bat and follow the instructions. This will uninstall the web components and windows service. It will not delete the database.
  3. In Windows Explorer, delete the root installation folder

Load Balanced Installation

A load balanced installation has a single database server and database, but multiple instances of the portal, web service, and windows service, which provide load balancing and redundancy.

mceclip6.png

It is possible to run the installation on any web server or application server. The installation process copies all the required files onto the server. The components to install or upgrade can be selected at the Configurator stage; for example, if configuring an application server that will host the windows service, simply choose to configure only the windows service.

When creating a load balanced installation, all the components must be installed with the same application key. On the first installation of the system, generate a new application key. On subsequent installations, copy the application key rather than generate a new key. The application key is explained in more detail in the Application Key paragraph.

When configuring a load balanced installation, the machine key must be manually configured for both the portal and public web service on both web servers. The machine key should be the same for both IIS applications on both web servers. To manually configure the machine key:

  • In IIS, navigate to the FrontOffice application and then Machine Keys
  • Untick automatically generate machine key
  • Untick automatically generate validation key
  • Click Generate Keys
  • Click Apply
    The web.config file is updated with a machine key section containing the generated values.
  • Repeat the process for the WebService application, but rather than generating keys use the previous values.
  • Repeat the process on the second web server, but rather than generating keys use the same values as used on the first web server.

When upgrading, the machine keys are copied forward to the new IIS applications, so this process should only be necessary on the first install.

Installing Database with Reduced Permission Set

When upgrading the database, it is necessary to choose a database login to perform the database upgrade. The simplest choice is to use a user who has the ‘sysadmin’ role.

However, if your DBA is unwilling to grant the sysadmin role to you, you can do a database upgrade with a reduced permission set. This appendix describes the process.

The SQL script below creates a Login ‘UpgradeUser’ which is suitable for upgrading the database:

  1. Run the script in SQL Management Studio to create a login and user suitable for upgrading the database.

  2. When you run the configurator and are selecting the database to upgrade, choose Authentication Mode ‘SQL’ and enter the following values:
    • DB User: UpgradeUser
    • DB Password: password
  3. Once installation is complete, you can disable or delete the ‘UpgradeUser’ since it is only used during the upgrade process
    -- Create a login for upgrading the database
    use master

    Create Login UpgradeUser WITH PASSWORD = 'password', Check_Policy = OFF

    GO

    -- Make a database user for the login

    -- and give them db_owner role on the target database

    USE FrontOffice

    CREATE USER UpgradeUser FOR LOGIN UpgradeUser

    GO

    ALTER ROLE db_owner ADD MEMBER UpgradeUser

    GO

    -- Allow ownership of database to be transferred to sa.

    -- The sa login can be disabled as per good dba practice,

    -- and everything will still work ok.

    use master

    GRANT IMPERSONATE ON LOGIN::sa to UpgradeUser

 

Share this article

Comments

0 comments

Please sign in to leave a comment.