BPC RiskManager - Install The SurveyManager

From RiskWiki
Jump to: navigation, search


If you will be using the BPC SurveyManager components, you should install the survey libraries on the web site. The BPC SurveyManager system is an extremely powerful highly scalable stateless survey engine, capable of hosting thousands of users simultaneously. It contains built in reports and might be better described as a web-forms engine.

The BPC RiskManager suite surfaces only a tiny portion of the real capabilities of the survey engine, although you have the full engine supplied as part of your BPC RiskManager system. For the purposes of the RiskManager install we will demonstrate installing it on the same web server as the RiskManager components have been installed, but in reality you could easily host the SurveyManager libraries on a web farm. Your license entitles you to unrestricted use of the SurveyManager engine.

In addition to the simplified survey creation and maintenance tools built in to the RiskManager client, for more generalized use there are additional survey creation and maintenance clients available, including a pure HTML/Javascript client. You should contact Bishop Phillips directly if you wish to explore these options.

For now we will install the SurveyManager engine as it is used in BPC RiskManager.

The first thing to understand is the unusual way that SurveyManager matches a database to a survey library. When a respondent completes a survey, at no stage do they ever see the underlying database name. It is not included in any session information, at least not directly.

This is because a unique copy of the BPCSurveyManager dll is created for each database the survey engine accesses. Each copy of the BPCSurveyManager.dll therefore gets a unique name.

When the library launches it uses its name as the key to an entry in the local computer registry to collect all the information it needs to access the associated database containing the survey. This means that a number of website configurations are possible, and more importantly ALL survey libraries can be stored in a single virtual folder on the website without interfering with eachother.

Here we shall consider two broad options configuration options:

  1. You could put the surveymanager library for a specific risk database in the same directory as the associated RiskManager web page and cab files were put. (Most appropriate if you have a single RiskManager web page from which many or all of your databases are available).
  2. You could create a single dedicated folder for all surveys regardless of system or database to which they belong. (Most appropriate if you have many riskdatabases with web pages in unique directories).

By far the majority of sites should use Option a. Option b is typically the centrally hosted / multi-organisation scenario with many separate risk management teams working in self contained and distinct databases.

In truth it really doesn’t matter. If you choose to put the surveymanager libraries into their own shared folder, it means you have all surveylibraries, whether for riskmanager or other purposes neatly contained in one spot – but you will have to create another web folder. If you put your surveymanager library (ies) in the riskmanager directory, you don’t have to create an extra folder but, if you have more than one riskmanager folder you will need to individually configure the survey libraries rather then use the bulk configurer.

Preliminary Steps

  • Locate the SurveyManager Files

If you examine your “Publish_On_Intranet” folder your will note two files additional files that we have not yet used:

  1. BPCJavaScriptLib2.js
  2. BPCSurveyManager1.dll

These are the two parts of the SurveyManager we now require.

  • Decide On Your Website Layout

Read the comments in the introduction and decide whether you want to re-use your riskmanager website folder (suggested if you have only one) or create a dedicated surveymanager folder (suggested if you have more than one riskmanager folder).

In either case you will need to enable the folder for execution. We will assume you will be creating a dedicated folder called “surveymanager” and mapping it to your website.

  • Create the SurveyManager web site in IIS
  1. Create an appropriate directory to house the SurveyManager libraries in a folder of your choosing and map that directory to IIS. We will call our folder “surveymanager” 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.
  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”

    SMWS SetUp2.png

    • A window will open, enter “surveymanager” (or your preferred virtual directory name) in the Alias field. Tick “Read” and ensure the other check boxes are unticked, and select the “Execute (includes sciptrs)” radio option and choose “Ok”.

    SMWS SetUp3.png

    • 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.

    SMWS SetUp4.png

  4. Right click on the “surveymanager” object and choose “properties”.
    • On the properties window select the “Virtual Directory Tab” and enter an Application Pool name (such as surveymanager):

    SMWS SetUp5.png

  5. On the properties window, select the “Directory Security” tab and select the edit button in the “Authentication and access control”:

    SMWS SetUp6.png

  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.

    SMWS SetUp7.png

  7. Select “OK” to close the properties window
  8. (IIS 6+ / W2003+ ONLY) The final step is to grant permission to IIS to run the surveymanager ISAPI dll. You should now be back at the general IIS management console window (if not then press OK until you have closed all the property windows).
  9. Scroll down the tree on the left hand panel until you can see the "Web Service Extensions" folder.
  10. Select it and you should see the Werb Service Extensions properties appear in the right hand panel as shown below:

    SMWS SetUp8.png

  11. In the right hand panel. Select "All Unknown ISAPI Extensions" at the top of the list and then select "Allow".
  12. You can now close the IIS management console.
  • Once you have created completed this part you are now ready to configure the surveymanager in the application server and publish the surveymanager libraries.

Configure and Publish SurveyManager

Initially, and very rarely if the surveymanager libraries are patched or you add databases will you be repeating these steps. They are never-the-less 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 RM App Server SysTrayIcon.png to interact with this program.
  3. On the configuration window, select the “Survey Manager” tab and “Individual Database Configuration.”. All the settings are on the one page. Follow the number steps in order:

    RMDS SM1.png

  4. From the drop box in step 1on the screen, choose the database connection with which you will work. The word “connected” will display when you select a database and a successful connection is established.
  5. Unless you are sending the surveys to a different database that the riskmanager database, skip step 2 on the screen (contact BPC if you want to set your system up with a separate survey database for the risk system).
  6. Accept the default group configuration code in step 3. (This can be any four character string, but it is used only to store multiple configurations for different servers accessing the one database – so you do not need to do that in the current scenario. It is used for things like web farms, or distributed database configurations of SurveyManager).
  7. In the edit box of step 4 on the screen enter the FULL URL of your surveymanager web site. Clicking on the “Launch Browser” string will open a browser so you can navigate there to get the string right if you want – but you will have to copy and paste the address once you have found it.
  8. Click on the yellow folder icon of step 5 on the screen and navigate to the folder on your computer that will contain the surveymanager library(ies) – i.e. the path of the URL referenced in step 7 above.
  9. Accept the defaults in steps 6 and 7 on the screen.
  10. If you are using a proxy server that requires configuration settings tick the check box in step 8 on the screen and click on the button and add your proxy server details. It is VERY rare to have to configure this on modern networks (in fact no current client is known to need it – even those with reverse proxies running).
  11. If you are satisfied that the settings are right, click “Save Settings”.
  12. A wizard will automatically open to facilitate distribution of the survemanager and javascript support libraries.
  13. Tick the “Create BPC SurveyManager ISAPI and Javascript libraries” and then select “Next”. We will not be using the second check box. This check box enables a page for saving the registry records to a file so they can be moved to a different server – such as where the IIS server is on a different machine(s) from the application server.

    RMDS SM2.png

  14. Using windows explorer locate the BPCSurveyManager1.dll in the “Publish_On_Intranet folder and drag and drop it on the panel (or use the folder icon on the path edit box to browse and select the file).
  15. Then select “Next”.

    RMDS SM3.png

  16. Confirm the default setting by ticking the two “Confirm” check boxes (unless, of course, you see an obvious error!).
  17. Then select “Next”.

    RMDS SM4.png

  18. Using windows explorer locate the BPCJavaScriptLib2.js in the “Publish_On_Intranet folder and drag and drop it on the panel (or use the folder icon on the path edit box to browse and select the file).
  19. If the “Confirm the new library name” check box is not ticked, then tick it.
  20. Then select “Next”.

    RMDS SM5.png

  21. Select the “Create Now” button and the surveymanager library will be created and the BPCJavascript library will be deployed to the target web site.
  22. Select Finish and close the Wizard.

    RMDS SM6.png

  23. Close the RiskManager Dataserver by choosing “End Process”