BPC RiskManager - Distribution of Client Components

Introduction

Two methods of distributing client components are available. You will need to select the one which best suits your requirements.

Distribution Method	Discussion
Internet Information Server	Browser Plugin ActiveX (code signed by Verisign) (ocx) Risk Manager components are published on a web server and downloaded with a web page. This method uses ActiveX frameworks. Users do not need to manually install any software components and distribution of updates is automatic. ActiveX controls are signed with a digital certificate. Assuming the web server that will serve the activeX cab file is on your intranet, you should allow installation / execution (prompted is wisest) of signed ActiveX components for the intranet zone ON YOUR client browsers. Users must be operating Internet Explorer 5 or above OR Netscape Navigator (any version) or FireFox 1.5 with ActiveX plug-in (provided with install set). Note: version 2+ of FireFox do not (to our knowledge) support the ActiveX plugin extension due to a deliberate rewrite and exclusion of the necessary libraries. There is a FireFox extension available that allows the launching of IE in a FireFox container for web sites requiring IE compatible browsing, which would solve the problem of ActiveX hosting, but requires IE to be installed on the client machine as well as FireFox. We advise, in this circumstance using IE directly or the Client Program (below) instead.
Client program install set	Non Browser Windows32 Application (executable) Risk Manager client components can be installed on a client PC merely by copying the “.exe” file in the “NonBrowserClient” directory to a target directory on a client computer. The RiskManager client is completely self contained and requires no separate install, nor do they register themselves in the local registry, although the registry is used to store user specific settings and options. The disadvantage of a non-install client is that it does not, by default, install menu and desktop shortcuts. For those wishing for these features to be automatically added during the distribution phase of the non-browser client, an installer for the non-browser client is available that will create menu and desktop shortcuts.

Client Registry Access

Both client components will require registry read/write access on the client machine for HK_LOCAL_MACHINE and HK_CURRENT_USER.

Under Vista SP1 with UAC enabled the default Vista installation will allow the access used in the BPC RiskManager client and automatically map the registry access to the current user’s HK_LOCAL_MACHINE space. Both clients will therefore work correctly under Vista SP1.

The ActiveX browser plugin will require OCX registration rights in the client computer registry (the default windows setup), and DLL registration rights for the supporting Midas.dll automatically installed with the OCX. The ActiveX also uses the registry to store and access local user settings.

The Windows Non-browser client is not an ActiveX and has no separate supporting Midas.dll. It does NOT therefore need to register itself to run, but does use the registry to store local user settings, however if access is not available the non-windows client should still work, but will not “remember” any user settings.

You need only think about the Registry access requirements if you are using an unusual lockdown scenario – such as where no local user level writes are allowed.

Which Method Should I Use?

1. The first thing to note is that you can, and probably will, use BOTH methods simultaneously. You can even use both methods simultaneously from the same client computer, and they will share the registry settings.
2. The second thing to note is that there is absolutely NO difference between the functionality, look and feel and appearance of the two clients. In fact they are exactly the same programmes in two different wrappers.
3. If you desire the simplest single point of publication distribution, with clients automatically updating when you publish a new client component to a single location, then the browser plug-in is the best solution – as all you have to do to release a new version is use the built-in web page generation and cab file distribution tool (or manually copy) to a single intranet/internet location and all clients will update the next time they access.
4. If you have extreme PC lockdown configurations with no access to registry for registering components then you will have to use the non-browser client.
5. If you do not have IE as a browser on your network you will have to use the non-browser client.
6. If you do not allow signed ActiveX plugin’s under any condition in IE, you will have to use the non-browser client.
7. If you prefer windows applications to browser plug-in applications then the non-browser client is preferred.
8. The Browser client (ActiveX) has a slightly simpler way of specifying the list of connections for a user than the windows client, as they can be listed in the hosting web page. This alone may be the a good argument for using the browser plug-in.
9. If you have legacy applications with a dependence on older versions of the Midas.dll – you *may* have to use the non-browser client, as only one version of Midas can be registered on a computer at once. However, in this event you can (and probably should) contact BPC directly for an alternative solution. This is an extremely rare scenario, and to date has not been reported by any client.

Distributing the Windows Non-browser client

There are two methods available. The first is to merely copy the exe file to an appropriate location on the target computer, and manually set a shortcut to it on the desktop, the second is to run the supplied .msi installer, which essentially does the same thing, but will automatically add a Start Menu entry and desktop icon.

The installer application is shipped with the string “install” in it, while the raw exe does NOT have the word “install” in the name.

The Risk Manager client program can be distributed as a Windows install set. The install set is available as a single file install (‘exe’) or Windows install file (‘msi’).

Option 1:

1. The copiable install set is located in the folder:
   ‘[InstallDir]\DistributeWin32Client\Install’.
   
2. Copy the installer to the target computer and double click on it. Accept all defaults.

Option 2:

1. The copiable executable version is located in the folder:
   ‘[InstallDir]\DistributeWin32Client\Exe’.
2. Create an appropriate folder to house the executable under c:\Program Files or similar location (or place it on a network drive for shared access)
3. Right click on the icon in windows explorer and choose copy
4. Click anywhere on your desktop and then right click and choose “Paste as ShortCut” (this will put a shortcut on your desktop)
5. Optionally create an appropriate menu entry in the start menu, again pasting into the menu folder as a shortcut (NOT using the full paste option – or you will copy the entire program rather than just a short cut)

In both options you can also edit the shortcut command line in the properties of the shortcut and add various command line properties such as the list of database connections to be available to the user (OPTIONAL).

Note, on a 64 bit client computer, you would need to right click on the application icon (not the shortcut) and select a W32 compatible execution mode in the properties window.

Test The Non Browser Client Connection:

1. From a client computer (or from the application server computer if no client computer is easily available) open the BPC RiskManager Client. If you have set up a start menu or used the installer you will have a menu option available called something like “BPC RiskManager”. Otherwise the executable file is called “RiskManagerW32V625Clent.exe” or similar (depending on the version you have installed).
2. You should be able to connect using the Root Administrator ID you established earlier. We will assume that ID is “Administrator”.
3. When the program starts you will see a login screen as follows:
   
   
   
   
4. Select “Specify Account” and enter the username “Administrator” and the password you defined earlier
5. Set the connection protocol to “Normal” – this will connect using the socket server port 211 connection.:
6. Enter the name of a database connection (not a database) in the “Select Database Connection” field that you set up in Step 3.
7. Ensure the correct computer name is in the “Risk Server Name” field. If not click on the “Select” button and a network browsing window will appear.
   
   
   
   
8. Type the correct computer name is in the “Risk server computer name” field, or if this is on a windows intranet you may be able to locate the computer using the “Browse” button.
9. Select “OK”.
10. Now, on the login window choose “Connect”.
11. If you see the window below, you have successfully connected to the RiskManager Dataserver, but you username and password are not valid in the database. The test for our purposes right now has been passed, but you should probably try again with the the correct Username and password, or make reset the root administrator user name and password in the appropriate earlier step. (It is ok to do it again).
    
    
    
    
12. If you are successful you will see a screen similar to this:
    
    
    
    
13. Close the window and continue.:

Distributing the Browser Client

Introduction

Firstly, you should be aware that the brand of web server is irrelevant to BPC RiskManager for the purposes of distribution of the browser client. You could as easily host the client components on an apache server running on a Sun box as on an IIS Server. With respect to the browser client, all the webserver does is provide the pages and cab image to the client when it is required. After that point the programmes ignore the webserver. We suggest IIS, because that is already present on Windows, we test on it, we provide files that work on it, the surveymanager components require it and we support it.

The following configurations will publish Risk Manager on your intranet. All files for publication are available in folder:

<install dir>\Publish_On_Intranet\

This directory contains a complete intranet/internet page that you can edit by hand and associated signed cab file set containing the RiskManager OCX, and helpfiles that you can copy to your web site. (This is NOT the recommended method of deployment). If you REALLY want to edit you own web page, there are instructions at the end of this section on the content and requirements of the default web page – but as there is provision for creating a template for the built-in publishing tool to use, there is really very little likelihood that you would need to go this route.

The BPC RiskManager DataServer contains built-in a web page publication system that will handle a variety of simple and complex scenarios:

1. A single web page named ‘default.htm’ (or other name of your choice) in a single generic folder with one or more database connections
2. Multiple web pages named uniquely with the connection name and stored in a single folder of your choice.
3. A single web page named ‘default.htm’ (or other name of your choice) in multiple folders named uniquely with the name of the connection and with each page containing a connection to a unique database matching the folder name.

The most common scenario is option 1. As BPC RiskManager is designed to handle many complex set up arrangements, including multi-organisational hosting, the other scenarios allow for sites with a very large number of databases and a large number of separate organizations being centrally hosted.

With Option 3, if you have, say, 40 client organizations with a training and production database per client, with intelligent structured use of connection names, and matching folder names, you can publish (or update) the clients for all organizations in 2 or 3 minutes using the built-in publication tool.

Let us assume that your web site is referenced like this:

Http://myorg.com/

Under option 1, you might decide that your decide that your BPC RiskManager web page will be:

Http://myorg.com/ERMS/default.htm

In this Http://myorg.com/ERMS/ location you will have:

1. a default.htm page containing the reference to the embedded BPC RiskManager ActiveX cab file (supplied), and a list of the database connections, and a set of links to help materials.
2. a riskmanager_download.cab file (supplied). This file contains the information for the browser on where to find the BPC RiskManager OCX and the Midas.dll
3. a riskmanager cab file (supplied) that contains the actual RiskManager OCX and the Midas.dll
4. a folder containing various help materials and manuals.

This is the generic most common scenario.

Under Option 2, in a multi organization setup, you might still use a single virtual folder:

Http://myorg.com/ERMS/

But instead of having a single default.htm file with all the database connections, you might instead have multiple web pages, each named with the name of the connection, but otherwise the same as the standard default.htm file, and one copy of the cab and help files. Eg. If my connections were OrgA and OrgB, I would end up with two pages:

Http://myorg.com/ERMS/OrgA.htm
Http://myorg.com/ERMS/OrgB.htm

Under Option 3, in a multi organization setup, you might still use single virtual folder as your root:

Http://myorg.com/ERMS/

But from there you would have a unique folder for each organization (generated from the connection names you set up in the RM Database Configuration tab):

Http://myorg.com/ERMS/OrgA/
Http://myorg.com/ERMS/OrgB/

In each folder you would then have a single default.htm file containing the database connection corresponding to the folder name, but otherwise the same as the standard default.htm file, and one copy of the cab and help files in each folder.

In the majority of cases you will be using option 1. 

In the following steps we will assume Option 1. In any of the cases, the first step is to create ALL your virtual directories on the web server. If you are using option 2 or 3, there is one point at the end of the process where you choose a different option and the RM Dataserver will perform the appropriate configuration for you.

The built-in publisher contains a generic (plain) web page, but you can just as easily use your own template and drag and drop it into the publisher if you wish. To do this just insert a [#RMOBJECT#] string into your page where you want the BPC RiskManager component to appear and supply that to the publisher when asked. If this is you first installation, however, we suggest that you run with the built-in version for now – you can change it in only a few minutes later on.

Internet Information Server (IIS) Configuration (FIRST TIME INSTALL)

You can publish Risk Manager from this install location (if you are using a single user installation) or you can choose to move or copy this folder to your standard intranet publications area of your network server. In any case the first time you install riskmanager you will need to create a virtual directory on the web server:

1. Create an appropriate directory to house the RiskManager web page in a folder of your choosing and map that directory to IIS. We will call our folder “Bpcrms” and use that as our virtual directory name. Our advice is that you do NOT simply map the installation folder to the web site as future patches will directly update the installation directory publish_on_intranet folder, effectively instantly setting the new patched files to “live” mode (complete with incorrectly configured default page thus destroying your existing web site & confusing the built-in publishing tool).
2. To map the newly created folder to your web server right click on the folder and choose properties from the context menu.
   
   • On the properties window select the “web sharing” tab. In the “web sharing” tab select “Share this folder”
   
   
   
   
   
   • A window will open, enter “Bpcrms” (or your preferred virtual directory name) in the Alias field. Tick “Read” and ensure the other check boxes are unticked, and select the “none” radio option (or scripts if you will be using php or other server side scripted pages in the folder) and choose “Ok”.
   
   
   
   
   
   • Select OK again on the folder properties window to close the window.
   
   
   
3. Open the IIS Manager (or right click on My Computer) and expand the “Internet Information Services”/”Web Sites”/”Default Web Site” tree.
   
   
   
   
4. Right click on the “bpcrms” object (or whatever your website folder was called) and choose “properties”.
5. On the properties window, select the “Directory Security” tab and select the edit button in the “Authentication and access control”:
   
   
   
   
6. On the Authentication methods tab:
   1. If you wish to allow anonymous access (the normal scenario), tick “Enable anonymous access” and untick any other options. You should leave the user name as the built-in anonymous user account
   2. If you wish to have secured access then we suggest:
      1. Untick “Enable anonymous access”
      2. Tick Integrated windows authentication (or other security model or your choice)
   3. Select “OK” to close the window.

   
   
   
   
   

   
   

7. Still in the properties window, select the “Documents” tab and ensure that “default.htm” is listed as a default document page (or which ever page name you will be using). (You should not worry about connection named pages here).
8. Select “OK” to close the properties window

• Once you have created completed this part you are now ready to publish the web page client.

Publish the Web Client (FIRST TIME INSTALL & ON PATCH/UPGRADE)

Both initially, and on every patch or upgrade you will be repeating these steps. They are designed to be very fast, and all the instructions are on the screen. Read the screens and you will probably not need to refer to these instructions again.

1. Open BPC RiskManager from the start menu. Either:
   1. Select the “Start”button and choose the RM DataServer from the BishopPhillips folder in the programs menu, or
   2. In Windows explorer, navigate to [RMInstallDir]\ApplicationFiles\RiskManagerDataServer.exe (or RiskManagerDataServer6xx.exe).
2. The application server appears as a service in the Windows system tray, typically located in the lower right hand corner of your screen. Please double click on the icon to interact with this program.
3. On the configuration window, select the “RM Web Distribution” tab and “Step 1.”
   
   
   
   
4. On this page you choose between the generic web page or you own template.
   1. If you want to use your own template, either tick the “Enable Drag-Drop of my template web page” check box and drag your template page onto the “Drop HTM Page Template Here” panel, or use the browse button (the yellow folder) and locate the file. (If you are using Vista, you will probably find you have to do use the browse method)
   2. If you want the generic web page, just tick the “Request a generic web page”. When you do this, a window with some notes will appear. Select “Ok”

   
   
   
   
   

   
   

5. In either case the right hand panel will be populated with the text of your page:
   
   
   
   
6. Select “Step 2”. On this tab, all the default settings should be correct, except possibly the application server computer name. Enter the fully qualified domain name that a user on a remote computer would need to use to access the application server computer. (On an internet site, for example this would need the “.com” part of the domain as well as the computer name).
   
   If you change the plugin dimensions by accident you can restore them to the default values by selecting the “Restore” button. The values on your screen may be different from those in the screen shot due to version changes.
   
   
   
   
7. Select “Step 3”. Tick the “Enable Drag-Drop check box and locate the “RiskMan_Dwonload.cab” file from the “Publish_On_Intranet” directory of the <install dir> using windows explorer and drag and drop it on the drop panel. (Vista users may have to use the browser folder button instead). There are two cab files in the publish on intranet folder. Only ONE has the word “download” in it’s name. This is the one you want. If the drop panel received a file you will see the following window:
   
   
   
   Select OK and if the file contains the correct information you will see this window next:
   
   
   
   Select OK and you should see the CLSID and CodeBase information appear in the appropriate windows on the screen:
   
   
   
   
8. The information required to set up the web page has been collected, so now just select “Apply Attributes” to populate the page template.
9. Next choose the “Step 4.” Tab. In the “Select all connections for which to generate web pages”, tick each connection you want available through the web pages. If you have multiple databases you will generally not be using the default connection.
10. Decide your page model. In most cases the default selection will be correct: “Make one page with all these connections listed”. This will make all the connections available from one page in one folder. The other options are described in the introduction section of this part of the manual. (“One page per connection” will make a page for each connection named with the connection name, while “Make one page per connection in its own folder” will create a default.htm page in a unique folder path and insert it in the folder named for that connection).
    
    
    
    
11. Browse to the location on the web server where you want the page(s) to by created by clicking on the yellow folder icon
12. When everything is done, select “Generate Web Pages”. This will cause the appropriate web pages to be created and copied to the target location.
13. Select Step 5. The “download” cab file (the top drag-drop panel and folder edit field) should already be correct and populated from the earlier screen. Tick the second “Enable Drag-Drop of the BPC RiskManager cab file” check box and, using windows explorer, locate the “RiskManagerXVxx.cab” file in the “Publish_On_Intranet” folder. (The other cab file in that folder.)
    
    
    
    
14. Finally, select the “Distribute Cab Files” button, and the cab files will be copied to your web site(s).
15. Close the RM DataServer application by choosing the “End Process” button.
16. From a client computer, open you web browser and navigate to your new web site and test the connection. You should be able to connect using the Root Administrator ID you established earlier. The web page should load, and the cab file install and the green disk appear on the Application Server system tray. (See the next section – Test the Browser Plugin Client)

Test The Browser Plugin Client Connection:

Browser Setup For ActiveX Plugins (IE 7 shown)

1. From a client computer (or from the application server computer if no client computer is easily available) open Internet Explorer.
2. Choose “Tools” from the menu bar and “Internet Options” from the menu that appears.
3. Select the “Security” tab.
   
   
   
   
4. Select the zone in which your risk manager application server resides relative to you client computer on the “Select a zone to view or change settings” tool bar
5. Select “Custom Level”
6. On the “Security Settings” window scroll through the settings list until you find the “Download signed ActiveX Controls” setting. Enable the “Prompt” option (which is Microsoft’s recommended setting). Our ActiveX controls are signed with current Verisign ceritificates. Administrators can achieve higher level of security by also flagging controls from Bishop Phillips Consulting as being trusted, or from the riskmanager application server web site as being trusted – but the recommended setting should be enough.
   
   
   
   
7. We also set the automatic prompting for ActiveX controls to enable, but this may not be required in all scenarios.
8. Scroll a little further down the list and enable the running of ActiveX plugins as follows:
   
   
   
   
9. Now select OK and close the security settings window, and select OK again and close the Internet Options window. You should now be back at your browser window.

Test the SocketServer Connection

1. Enter in the web address of the BPC RiskManager website just created and and a web page should appear and a prompt to download a signed authenticated ActiveX component from “Bishop Phillips Consulting”.
2. Select OK.
3. A second prompt should appear to download another signed ActiveX component from “Bishop Phillips Consulting”. Select OK to that as well.
4. The components will now download from the web site and install themselves on your computer. Once this is completed you should see a login window as below.
5. You should be able to connect using the Root Administrator ID you established earlier. We will assume that ID is “Administrator”.
6. When the program starts you will see a login screen as follows:
   
   
   
   
7. Select “Specify Account” and enter the username “Administrator” and the password you defined earlier
8. Irrespective of whether you are going to use the HTTP/HTTPS protocols to connect ultimately, this first test should ideally be done using the low-tech socket server port 211 connection. Set the connection protocol to “Normal” – this will connect using the socket server port 211 connection.:
9. Enter the name of a database connection (not a database) in the “Select Database Connection” field that you set up in Step 3.
10. Ensure the correct computer name is in the “Risk Server Name” field. If not click on the “Select” button and a network browsing window will appear.
    
    
    
    
11. Type the correct computer name is in the “Risk server computer name” field, or if this is on a windows intranet you may be able to locate the computer using the “Browse” button.
12. Select “OK”.
13. Now, on the login window choose “Connect”.
14. If you see the window below, you have successfully connected to the RiskManager Dataserver, but you username and password are not valid in the database. The test for our purposes right now has been passed, but you should probably try again with the the correct Username and password, or make reset the root administrator user name and password in the appropriate earlier step. (It is ok to do it again).
    
    
    
    
15. If you are successful you will see a screen similar to this:
    
    
    
    
16. Close the browser and the connection will be terminated and continue with the install.

Test the HTTP / HTTPS Connection (Optional)

1. If you have completed the socketserver connection test and you will be using the HTTP or HTTPS connection methods, and you completed the HttpSrvr setup in the earlier section, you may wish to test this now.
2. Simply open the browser again and navigate to the web page again as before.
3. When the login prompt appears, change the connection protocol from Normal to HTTP or HTTPS as appropriate. You will see a new button labeled “Set Path” appear on the login page:
   
   
   
   
4. If you used the recommended default path (i.e. “Scripts”) the path will be correct and you can ignore this option. If you need to override it, then select the button (you only need to do this the first time as BPC RiskManager will remember it) and a configuration window will appear:
   
   
   
   
5. In the edit box enter the correct sub path as shown (note the slashes should be in “/” not “\”….and select “OK”
6. At the login window, enter the rest of the login details if they are not already correct, (if in doubt refer to the steps in the socketserver test above) and select “Connect”.
7. You should see the first screen of the application as before.
8. Close the browser and the connection will terminate and continue with the installation on the application server.

Creating your own template page - OPTIONAL

If you want a custom look and feel to the page you should create a page with [#RMOBJECT#] where you want the BPC RiskManager object to be inserted and then drag and drop the page onto the appropriate panel of the publishing tool. It will then use your template, rather than the built-in version to generate the default web page(s).

On VISTA you will have to use the browse button to search for your page as the “Drag and Drop” functionality will not work because the application is executing as Adninistrator and you are probably not.

Editing the supplied Default.htm page – OPTIONAL – NOT PREFERRED

This section includes the notes for editing the default web page supplied in the “Publish_on_intranet” folder. This is an extremely unlikely scenario, but might be appropriate where you wish to embed the RMS in your own content managed web site. The web page downloads and initialises the ActiveX control. This is the Default.htm file. Please set the following parameters on the ActiveX control:

ApplicationServer	Set the value to the name of the network server on which you have installed the application server. This value will be used as a default for the risk computer server name option in the connection screen. This value can be changed by users when connecting. The default value is ‘<Risk Server Name>’
RiskManagerEdition	Do not modify this value. The default value is ‘WEB’ for Web edition.
ShowLoginScreen	The default value is ‘YES’. You can set this to ‘No’ if you do not want users to see the connection screen. When this configuration is set to ‘No’ the application server and database connection values use their assigned defaults. Users are not able to select an alternate database to connect to. A ‘No’ setting is recommended when there is only a single risk database to connect to and/or when IIS Integrated Windows Authentication is used so that users only see the one login screen (from Windows) and don’t need to interact with the connection screen.
DatabaseConnections	The default value is blank. This parameter enables a user to select from a list of available database connections in the client program connection screen. Some sites have many risk databases in use such as a production database to house the ‘live’ data and additional databases for training and/or testing. Multiple databases can also be used to house separate risk data and compliance data. Set this value to a comma delimited list of connection names created in step ‘6. Database Configurations’ ealier. EG: <PARAM NAME="DatabaseConnections" VALUE=" ProdSQLDB, TrainSQLDB"> If no connections are entered then the default connection will be used.

BackLinks

• BPC RiskManager Frequently Asked Questions
• BPC RiskManager Quick Help With Common Tasks
• Configure the BPC RiskManager & BPC SurveyManager Application Server
• RM625ENT Installation Instructions
• Steps For Migrating RiskManager V6.x from Test To Production