Sequoia Client - Connecting to multiple Sequoia servers

This is an advanced topic and following this guide will involve access to the Sequoia Server

Overview

Some users of Sequoia have multiple installations of Sequoia Server. A typical scenario is to have a live server for day-to-day operations and a staging server for ensuring that a newer version of Sequoia doesn't have any unexpected changes, before an upgrade is rolled out to 'live'.

This document describes a process where multiple instances of the Sequoia server can be accessed from a single Windows desktop.

Notes

This is an advanced topic, and you should not attempt to follow these instructions unless you have a good reason to do so.
This guide assumes that you have already installed more than one instance of Sequoia, and that you are licensed to do so.
This process does not affect your licence to use an individual Sequoia (server) installation. You are licensed for a set number of concurrent users connected to a particular Sequoia Server, not the number of desktops you connect from. Additionally, licence allowances for one installation of Sequoia cannot be transferred to another instance of Sequoia.
By following this guide, you should very rarely (if ever) need to re-configure your client installation after an upgrade in the future. The only time you will need to make any changes is if ASM introduces a breaking change to the client launcher application. More on this later.
You can only run one instance of the Sequoia client on your desktop at any given time. It doesn't matter if you have multiple instances pointing at different Sequoia servers - the application will refuse to load more than one instance in a single user environment.

Scenario

This scenario provides a step-by-step guide to setting up the multiple Sequoia clients on a single desktop.

Connecting to 2 Sequoia server installations.

The machine names, DNS names, IP addresses provided in this guide are for illustrative purposes only, and you should use names / IP addresses which suit your organisation.
You are not limited to only 2 instances of the client application - this is an example of how you can setup your Sequoia client to fit your business needs.

Prerequisites

Sequoia Server #1

DNS Name: SequoiaLiveServer
IP Address: 10.0.0.1

Sequoia Server #2

DNS Name: SequoiaStagingServer
IP Address: 10.0.0.2

Client machine

Sequoia Client has been installed. (If you need the Sequoia Client installed, please talk to your IT department).
If using DNS to address Sequoia server (recommended):
- Has DNS entries (or DNS resolves for) both SequoiaLiveServer or SequoiaStagingServer
Has a folder created on the desktop called 'SequoiaClients'
- In this guide, we will refer to the path of this folder as c:\users\Jane\desktop\SequoiaClients.
  - On your computer Jane will be your Windows user name.
- This is just for reference in this guide. You can store the folder wherever you like, and call it what you like, provided the folder doesn't require any special permissions to read/write. You will just need to change the paths provided in this guide wherever it is referenced.

Configure Sequoia client to talk to Server #1

Locate the location where the Sequoia client launcher is installed.
By default this is found here: c:\Program Files\ASM\Sequoia Client, but this directory may have been customised on installation by your IT department.
Copy the 'Sequoia Client' folder to your desktop folder and rename it to 'SequoiaLiveClient'. You should now have all the files within 'c:\users\Jane\desktop\SequoiaClients\sequoiaLiveClient'.
Create a sub-directory within the sequoiaLiveClient folder called 'client'. You should now have an empty directory at this location 'c:\users\Jane\desktop\SequoiaClients\sequoiaLiveClient\client'.
Look inside the folder and find the file named 'ASM.Sequoia.Client.Launcher.exe.config'.

Open this file in an editor such as notepad. Towards the bottom of the file, you will see the following:

<client>
  <endpoint address="net.tcp://SequoiaServer:9099/IUpdateLauncherService"
     behaviorConfiguration="UpdateLauncherClientServiceBehavior" binding="netTcpBinding" bindingConfiguration="UpdateLauncherTcpBinding"
     contract="ASM.Sequoia.Service.Contracts.UpdateLauncher.ServiceContracts.IUpdateLauncherService"
     name="endPointUpdateLauncherServiceNetTcp" />

  <endpoint address="net.tcp://SequoiaServer:9099/IClientDownloadService"
     behaviorConfiguration="ClientDownloadServiceBehavior" binding="netTcpBinding" bindingConfiguration="ClientDownloadTcpBinding"
     contract="ASM.Sequoia.Service.Contracts.ClientDownloadService.ServiceContracts.IClientDownloadService"
     name="endPointClientDownloadServiceNetTcp" />

</client>

_{Original values on line 2 and line 7 are 'SequoiaServer'}

Replace all occurrences of SequoiaServer with either your DNS name OR the IP address. Using the DNS name is recommended as IP addresses can be re-assigned by your network. For the purposes of this guide, the modified file will look like this:

<client>
  <endpoint address="net.tcp://SequoiaLiveServer:9099/IUpdateLauncherService"
     behaviorConfiguration="UpdateLauncherClientServiceBehavior" binding="netTcpBinding" bindingConfiguration="UpdateLauncherTcpBinding"
     contract="ASM.Sequoia.Service.Contracts.UpdateLauncher.ServiceContracts.IUpdateLauncherService"
     name="endPointUpdateLauncherServiceNetTcp" />

  <endpoint address="net.tcp://SequoiaLiveServer:9099/IClientDownloadService"
     behaviorConfiguration="ClientDownloadServiceBehavior" binding="netTcpBinding" bindingConfiguration="ClientDownloadTcpBinding"
     contract="ASM.Sequoia.Service.Contracts.ClientDownloadService.ServiceContracts.IClientDownloadService"
     name="endPointClientDownloadServiceNetTcp" />

</client>

_{Original values on line 2 and line 7 changed from 'SequoiaServer' to 'SequoiaLiveServer'}

Further down, you will see an applicationSettings entry. Change the <value /> tag so that it contains the client directory that you created earlier.
As example of what this should look like:

 <applicationSettings>
  <ASM.Sequoia.Client.Launcher.Properties.Settings>
    <setting name="ClientAppLocation" serializeAs="String">
      <value>c:\users\Jane\desktop\SequoiaClients\sequoiaLiveClient\client</value>
    </setting>
  </ASM.Sequoia.Client.Launcher.Properties.Settings>
</applicationSettings>

_{Original value on line 4 changed from '<value />' to '<value>PATH</value>'}

Save changes to 'ASM.Sequoia.Client.Launcher.exe.config'.
Copy the file 'c:\users\Jane\desktop\SequoiaClients\sequoiaLiveClient\ASM.Sequoia.Client.Launcher.exe'.
- Paste this as a shortcut on your desktop.
- Rename the shortcut to 'Sequoia Live'.
- Optionally change the icon of the shortcut.
Double click on the icon to launch Sequoia. You should be connected to Server #1 (SequoiaLiveServer).

Configure Sequoia client to talk to Server #2

We need to perform almost the same actions as we did when setting up Server #1, with just a few configuration tweaks to access Server #2.

Make a copy of the c:\users\Jane\desktop\SequoiaClients\sequoiaLiveClient folder and paste it in the path c:\users\Jane\desktop\SequoiaClients.

Rename the copy of the sequoiaLiveClient folder to sequoiaStagingClient.
You should now have a directory structure which looks like this:

c:\users\Jane\desktop\SequoiaClients
  L c:\users\Jane\desktop\SequoiaClients\sequoiaLiveClient
  L c:\users\Jane\desktop\SequoiaClients\sequoiaStagingClient

Within your c:\users\Jane\desktop\SequoiaClients\sequoiaStagingClient folder:
- Purge the content of the 'client' sub-folder.
- Make changes to the ASM.Sequoia.Client.Launcher.exe.config as we did before, but using the values for server #2.
  - Your endpoint address sections should be pointing to SequoiaStagingServer rather than SequoiaLiveServer.
  - The ClientAppLocation should be changed:
  - from c:\users\Jane\desktop\SequoiaClients\sequoiaLiveClient\client.
  - to c:\users\Jane\desktop\SequoiaClients\sequoiaStagingClient\client.

The end of the configuration file changes should now look a bit like this:

     <client>
      <endpoint address="net.tcp://SequoiaStagingServer:9099/IUpdateLauncherService"
         behaviorConfiguration="UpdateLauncherClientServiceBehavior" binding="netTcpBinding" bindingConfiguration="UpdateLauncherTcpBinding"
         contract="ASM.Sequoia.Service.Contracts.UpdateLauncher.ServiceContracts.IUpdateLauncherService"
         name="endPointUpdateLauncherServiceNetTcp" />

      <endpoint address="net.tcp://SequoiaStagingServer:9099/IClientDownloadService"
         behaviorConfiguration="ClientDownloadServiceBehavior" binding="netTcpBinding" bindingConfiguration="ClientDownloadTcpBinding"
         contract="ASM.Sequoia.Service.Contracts.ClientDownloadService.ServiceContracts.IClientDownloadService"
         name="endPointClientDownloadServiceNetTcp" />

    </client>

  </system.serviceModel>

  <startup>
    <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.0"/>
  </startup>
  <applicationSettings>
    <ASM.Sequoia.Client.Launcher.Properties.Settings>
      <setting name="ClientAppLocation" serializeAs="String">
        <value>c:\users\Jane\desktop\SequoiaClients\sequoiaStagingClient\client</value>
      </setting>
    </ASM.Sequoia.Client.Launcher.Properties.Settings>
  </applicationSettings>
</configuration>

_{Original values on line 2 and 7 changed to SequoiaStagingServer
Original value on line 22 changed from '<value />' to '<value>PATH</value>'}

Save changes to 'ASM.Sequoia.Client.Launcher.exe.config'.
Copy the file 'c:\users\Jane\desktop\SequoiaClients\sequoiaStagingClient\ASM.Sequoia.Client.Launcher.exe'.
- Paste this as a shortcut on your desktop.
- Rename the shortcut to 'Sequoia Staging'.
- Optionally change the icon of the shortcut.
Double click on the icon to launch Sequoia. You should be connected to Server #2 (SequoiaStagingServer).

What happens when I upgrade the Sequoia Server?

Typically, the client launcher application doesn't change. It's purpose is to dynamically get and launch the Sequoia client application on your desktop machine. The Sequoia client is packaged as part of the Sequoia server, so as long as you use the launcher to run the Sequoia client, you should very rarely (if ever) need to worry about upgrading the Sequoia application on your desktop again.

In very rare cases, ASM may decide to publish an update the launcher application. If your Sequoia server detects that your launcher is out of date, it will prompt you to install the latest client launcher. After this is installed, the steps above will need to be followed again so you can access more than one server.
For reference, ASM haven't needed to publish a new launcher since it's inception.

Multiple connections from another desktop

If you need the same setup as described here, but on another desktop, you need to do the following:

Ensure that the computer meets the requirements of the original computer from which you are copying the Sequoia clients.
For example, it can connect to all Sequoia server machines via DNS, has the Sequoia client already installed etc.
Copy the folder containing the sequoia clients to a location on the destination computer.
Create your shortcuts as described in the scenario above.
Test that you can connect to multiple Sequoia server instances by clicking on the shortcuts.

How to change the shortcut icon

To differentiate between different instances of the Sequoia client application (which may help you identify visually which instance of the Sequoia server you are targeting), you can apply a different icon to the shortcut you have created on your desktop.

There are a number of guides online which will show you how to change the icon for a shortcut. This is the Microsoft guidance.

You can download an alternative icon from here.

Following the guidance, a quick summary of the steps to change your icon are as follows:

Download the icon file from the link above.
- Save this icon in a place where you can easily find it.
- A good place to store it would be in the same location that the copy of the Sequoia launcher (that you want to change the icon for) resides.
Right click on your shortcut.
Click on 'Properties'
Select on the 'Shortcut' tab.
Click the 'Change Icon...' button.
Click the 'Browse...' button.
Select the file you have just saved (you will have to navigate to it using the file browser window).
Accept all changes and your icon should be changed.