BPC SurveyManager - Advanced Database Configuration Settings

From RiskWiki
Jump to: navigation, search

BPC SurveyManager Engine Configuration - Introduction

The BPC SurveyManager SurveyEngine and BPC SurveyManager Clients are configured through a single Configuration table. This table includes both locational and behavioural configurations, and a set of properties that act as the universal defaults for key layout components. For this reason the survey database is shipped and/or installed with basic settings already loaded. There are two groups of configurations loaded - the general shared set called "SYS" and a user named set we call the "localisation" set.

The localisation set overrides the SYS set and contains information that is specific to the actual computer on which the survey engine resides. The SYS set contains settings that should be used by every copy of this database (or every instance of the survey engine in a web farm) no matter what machine the server engine resides on.


The BPC SurveyManager is designed as a distributed database and farmed middle tier system. There is no restriction on the number of databases that a survey environment /farm can have. One "implementation" might span both local (desktop) installations with local databases and multiple servers, some single instance web servers and some in a web farm, and each with potentially many databases. Each computer with at least one survey engine is called a "publishing server" (but only one server of a farm with shared databases should have data published to it - at least with respect to efficiency).


The BPC SurveyManager Survey Engine is a small ISAPI dll (library of 2 to 4 MB) "BPCSurveyManager.dll", but many uniquely named copies of the library can exist on the one web server, even in the one virtual directory. You decide what you want each copy to be called, but the name of the library on each server is then uniquely tied to a database through a combination of registry entries and configuration table entries. In fact you will never see a survey manager engine actually called BPCSurveyManager.dll on a server as that is simply the name we give it for distribution. This way no web page or survey form or user ever actually refers to a database by name. All this information is kept exclusively server side.


When the Survey Manager starts it looks in the local registry to find out what localisation group name it is supposed to use on the local server, and then accesses the database tied to the library and loads that localistaion group. A cross check occurs to ensure that the database agrees that this is the library that is supposed to be accessing it for certain operations where this matters.


For this reason there can be multiple localisations of many of the settings in the configuration table of any one database. The versions are distinguished by a group key. On some BPC SurveyManager clients you can choose the localisation group key to load and therefer load different sets of settings, but the survey engine will always find its default group key from the registry when it starts.

There are many advantages in this seemingly complex system. For example:

  • A database can be set up for multiple machines and copied between servers or between a desktop and a server and automatically use the correct localisation in the destination environment with no configuration change.
  • Multiple servers in a web farm can have server specific settings if needed and share the same database.
  • Multiple non farmed web servers can share a database and use server specific settings
  • Multiple non farmed web servers can have non cooperative unique copies of the same database aand be mirrored/replicated with out damaging the local server settings.
  • Users never see the underlying database names so an attack vector is eliminated.
  • A central IT team can setup a standard survey database with survey content and distribute the entire database as a backup to multiple physically isolated organisation units or locations.

The universal group key is 'SYS1'. Any number of uniquely names localisation keys can be used in the one database.


The Settings

The Server Settings

  • DefMailServer - (local) The SMTP server network name or IP address to use for sending emails when a relay server is used
  • DefMailUserID - (local) The login user id for the smtp server if required
  • DefMailUserPwd - (local) The login user pwd for the smtp server if required
  • DefSMLibrary - (SYS) The survey engine library name that should talk to this database
  • DefSurveyPageLayout - This is the default page layout. It is only used if no layout is defined for the survey in the survey header. See the reference on page layouts and the page on tags for more information . It is usually set to something simple like:
<HTML><HEAD><#JVScriptLib1></HEAD><BODY><H1><#SurveyName></H1><BPCDEBUG><#SurveyBody><BPCDEBUG></BODY></HTML>
  • DefSurveyType - (SYS) The default survey layout type if not specified in the survey. This essentially defined the underlying structure of what replaces the <#SurveyBody > tag. This is just a default structure if no tags are overridden at survey or even at the question level. It is quite ok to use the ROWTABLE as the default and then completely re-arrange the layout in the survey itself. The recommended default setting is ROWTABLE . Options iclude:
    • ROWTABLE - Classic table structure with a column each for question numbers, questions, responses, weights and additional columns a required.
    • GRIDTABLE - Table structure with the question text above the response area.
    • DISCUSSION - Question text and response section are merged into a single column
    • CUSTOM - User defined.
  • DefDNSServer - (local) IP address of the preferred DNS server to use. Used by certain EMail modes and advanced operations to lookup URLs.
  • DefMailFromEMail - (local) The default email address to use as the "from" email address in emails sent by the survey engine
  • DefMailFromName - (local) The default email "from" name to use in emails sent by the survey engine
  • DefTestPID - (SYS) Normally set to 'PRVW' this is the ID to preview a survey. Mainly used during survey creation and testing. PRVW inputs are ignored in reports and are liable to be purged from the response table at any time. A property can be set to block PRVW access to a survey. PRVW can access a survey without publication.
  • DefUseMailRelay - (local) also (SYS). True or False. Flags whether emails should be sent via a relay server as defined in the DefMailServer setting. the recommended configuration is "True". The direct connection alternative required the DNS to be properly initialised and is much slower as it handles MX record interogation itself.
  • FriendlyDBName - (SYS) This is a string that can be displayed to identify which database is connected. It would usually be something like "ACME Survey System"


Port & Proxy Settings

The distribution functions of survey manager may have to be routed via a proxy server depending on your network. These settings support that.

  • PortHTTP - (local) Port for HTTP traffic - normally set to 80
  • ProxyAuthenticationRequired - (local) True/False
  • ProxyUserName - (local) Normally blank.
  • ProxyPassword - (local) Normally blank.
  • ProxyPort - (local) Normally blank.
  • ProxyServerURL - (local) proxy URL or IP. Normally blank.

Leaving the items identified as "Normally blank" will ensure the proxy mechanism is not used.

Locations of Support Files

  • URLScriptLibrary - (local) The full disk path of the standard javascript library including path and library name. The standard javascript library shipped with BPCSurveyManager is "BPCJavaScriptLib2.js"
  • URLJVScriptLibrary - (local) The HTTP address of the standard javascript library including path and library name. The standard javascript library shipped with BPCSurveyManager is "BPCJavaScriptLib2.js"
  • URLCSSLibrary - (local) The full disk path of the standard CSS file including path and file name. Can be blank.
  • URLLogo1 - (local) The HTTP address of the standard logo graphic to use for surveys where the sitelogo tag is used. Include path and image file name.
  • URLTestSite - (local) The HTTP address of the default test server including path but excluding the library name. Used by BPC SurveyManager clients to test a survey. Can be the same as the default publication site if the client is working directly on the publication database, but usually it is a local database.
  • URLDefPublicationSite - (local) The HTTP address of the default publication server including path, but excluding the library name.
  • URLMaintExceptSite - (SYS) The HTTP address of the standard error page to use for web client survey manager app session failure. Include path and file name. This should usually be a static web page with a link to re-login to the web client.
  • URLMaintSite - (SYS) The HTTP address of the BPC SurveyManager web client including path, but excluding the library name.


Counter Definitions for Populating the Counters Table

The system uses a vaiety of ID counters. ID counters are alpha-numeric strings designed to allow alpha sorting of IDs. These setting define the masks to be used to initialise the counter table as required.

  • ZCounterDate - DateOp counter prefix. Set to "DAT"
  • ZCounterDateMask - DateOp counter mask for providing a numeric space for the counters. Set to "%.5d" (allows a 5 digit number "00000". So the fist item would be DAT00001
  • ZCounterRating - RatingOp counter prefix. Set to "NUM"
  • ZCounterRatingMask - RatingOp counter mask for providing a numeric space for the counters. Set to "%.5d" (allows a 5 digit number "00000". So the fist item would be NUM00001
  • ZCounterSelect - SelectOp counter prefix. Set to "SEL"
  • ZCounterSelectMask - SelectOp counter mask for providing a numeric space for the counters. Set to "%.5d" (allows a 5 digit number "00000". So the fist item would be SEL00001


SurveyManager does not care what these are. It will increment by replacing numeric fields and then add extra numbers when it runs out.

Survey Body Presentation Tag Defaults where Layout Type Unknown

This group os default tag settings is not a namable group, unlike those that are presented in the following sections. These tag names represent the tags that are overriden in the survey header layout set, and also in the properties of an organisation, question group, or question. This set is only used in the event that the survey header is set to a layout group name that is not recognised by the survey engine and not completely defined in the survey or organisation settings.


It is set to represent mirror the ROWTABLE settings as the standard survey body layout is a row table (ROWTABLE ). This layout puts each question-response on a single row, displayed as the question number - qustion text - response - weight (optional). This is a very classic question - answer structure. Usually the colours of the rows cycle every two rows between light and darker background bands to help the responder's eyes track the line. Since 2005 the standard ROWTABLE has used the "BishopPhillips Blue-Base Number1" colour scheme. Earlier databases used the "Stanton Consulting Burgundy" colour scheme. If you are operating an earlier default colour scheme you can easilly change all your your surveys in one step by replacing these values as shown below. Most recent demonstration surveys use the "BishopPhillips Blue-Base Number2" colour scheme, but this uses some graphic elements rather than plain colours, so is not used in the global database default.


The standard settings which can be, and often are, over ridden at the organisation, survey, questiongroup, or question levels by redefining properties are:


TTSTART ROWTABLE layout page/question group start tag. Normally <table Width="100%" BgColor="white" >
TH ROWTABLE layout headings cell start. Normally <tr><TH BgColor="lightblue" ><font color="darkblue">Number</font></TH><TH BgColor="lightblue" ><font color="darkblue">Question</font></TH><TH BgColor="lightblue" ><font color="darkblue">Response</font></TH></tr>
TRSTART ROWTABLE layout row start tag. Normally <tr>
TREND ROWTABLE layout row end tag. Normally </table></tr>
TCELLSTART This is the HTML tag used to define the start of a ROWTABLE table cell. Note the cellparams tagattribute. This is a reserved word that will automatically be replaced any the calculated BgColor, HAlign, VAlign and any CustomAttributes needed for the specific question. Normally <td cellparams >.
TCELLEND This is the HTML tag used to define the end of a ROWTABLE table cell. Normally </td>.
TTEND ROWTABLE layout page/question group end tag. Normally </table>
TR This is the standard question-response row for the ROWTABLE layout. Normally set to <#QuesDisplayID><#Question><#OpType>.
TRC This is the checkbox input control question-response row for the ROWTABLE layout. Normally set to <nowiki<#QuesDisplayID><#Question align=right><#OpType></nowiki>
TRL This is the long question text row for the ROWTABLE layout. This is usually used for section headings and info blocks. Normally set to

<#QuesDisplayID><#Question align=center colspan=2> here.

TRCOLOUR A list of colours separated by commas representing the colour row cycle for the survey. The standard setting is "#DDDDFF,white" for this type.
TRERROR
TRDTA This is the long question-response row for the ROWTABLE layout. It is used for input controls requiring double column space - such as a large free text entry box. Normally set to <#QuesDisplayID ><td colspan=2 ><table width=100% ><tr ><#Question ><#OpType ></tr ></table ></td >.


Survey Body Presentation Tag Defaults where Layout Type ROWTABLE

The standard survey body layout is a row table (ROWTABLE ). This layout puts each question-response on a single row, displayed as the question number - qustion text - response - weight (optional). This is a very classic question - answer structure. Usually the colours of the rows cycle every two rows between light and darker background bands to help the responder's eyes track the line. Since 2005 the standard ROWTABLE has used the "BishopPhillips Blue-Base Number1" colour scheme. Earlier databases used the "Stanton Consulting Burgundy" colour scheme. If you are operating an earlier default colour scheme you can easilly change all your your surveys in one step by replacing these values as shown below. Most recent demonstration surveys use the "BishopPhillips Blue-Base Number2" colour scheme, but this uses some graphic elements rather than plain colours, so is not used in the global database default.


The standard settings which can be, and often are, over ridden at the organisation, survey, questiongroup, or question levels by redefining properties are:


RT_TTSTART ROWTABLE layout page/question group start tag. Normally <table Width="100%" BgColor="white" >
RT_TH ROWTABLE layout headings cell start. Normally <tr><TH BgColor="lightblue" ><font color="darkblue">Number</font></TH><TH BgColor="lightblue" ><font color="darkblue">Question</font></TH><TH BgColor="lightblue" ><font color="darkblue">Response</font></TH></tr>
RT_TRSTART ROWTABLE layout row start tag. Normally <tr>
RT_TREND ROWTABLE layout row end tag. Normally </table></tr>
RT_TCELLSTART This is the HTML tag used to define the start of a ROWTABLE table cell. Note the cellparams tagattribute. This is a reserved word that will automatically be replaced any the calculated BgColor, HAlign, VAlign and any CustomAttributes needed for the specific question. Normally <td cellparams >.
RT_TCELLEND This is the HTML tag used to define the end of a ROWTABLE table cell. Normally </td>.
RT_TTEND ROWTABLE layout page/question group end tag. Normally </table>
RT_TR This is the standard question-response row for the ROWTABLE layout. Normally set to <#QuesDisplayID><#Question><#OpType>.
RT_TRC This is the checkbox input control question-response row for the ROWTABLE layout. Normally set to <nowiki<#QuesDisplayID><#Question align=right><#OpType></nowiki>
RT_TRL This is the long question text row for the ROWTABLE layout. This is usually used for section headings and info blocks. Normally set to

<#QuesDisplayID><#Question align=center colspan=2> here.

RT_TRCOLOUR A list of colours separated by commas representing the colour row cycle for the survey. The standard setting is "#DDDDFF,white" for this type.
RT_TRERROR
RT_TRDTA This is the long question-response row for the ROWTABLE layout. It is used for input controls requiring double column space - such as a large free text entry box. Normally set to <#QuesDisplayID ><td colspan=2 ><table width=100% ><tr ><#Question ><#OpType ></tr ></table ></td >.


Survey Body Presentation Tag Defaults where Layout Type GRIDTABLE

GR_TTYPE
GR_TTSTART GRIDTABLE layout page/question group start tag. Normally <table Width="100%" BgColor="white" >
GR_TH GRIDTABLE layout headings cell start. Normally <tr><TH BgColor="white" width="10%" ><b>ID</b></TH><TH BgColor="white" ><b>Question (Response)</b></TH></tr>
GR_TRSTART GRIDTABLE layout row start tag. Normally <tr><table width="100%" >
GR_TREND GRIDTABLE layout row end tag. Normally </table></tr>
GR_TCELLSTART This is the HTML tag used to define the start of a Discussion table cell. Note the cellparams tagattribute. This is a reserved word that will automatically be replaced any the calculated BgColor, HAlign, VAlign and any CustomAttributes needed for the specific question. Normally <td cellparams >.
GR_TCELLEND This is the HTML tag used to define the end of a Discussion table cell. Normally </td>.
GR_TTEND GRIDTABLE layout page/question group end tag. Normally </table>
GR_TR This is the standard question-response row for the GRIDTABLE layout. Normally set to <tr><#QuesDisplayID width="10%%" ><#Question width="90%%" ></tr><tr><#OpType colspan=2 ></tr>.
GR_TRC This is the checkbox input control question-response row for the GRIDTABLE layout. Normally set to <tr><#QuesDisplayID width="10%%" ><#Question width="90%%" ></tr><tr><#OpType colspan=2 ></tr>
GR_TRL This is the long question text row for the GRIDTABLE layout. This is usually used for section headings and info blocks. Normally set to

<tr><#QuesDisplayID width="10%%" ><#Question width="90%%" ></tr> here.

GR_TRCOLOUR A list of colours separated by commas representing the colour row cycle for the survey. The standard setting is "white" for this type.
GR_TRERROR
GR_TRDTA This is the long question-response row for the GRIDTABLE layout. It is used for input controls requiring double column space - such as a large free text entry box. Normally set to <tr><#QuesDisplayID width="10%%" ><#Question width="90%%" ></tr><tr><#OpType colspan=2 ></tr>.


Survey Body Presentation Tag Defaults where Layout Type DISCUSSION

DR_TTSTART DISCUSSION layout page/question group start tag. Normally <table >
DR_TH Normally empty in the DISCUSSION layout as this layout has no headings.
DR_TRSTART DISCUSSION layout row start tag. Normally <tr >
DR_TREND DISCUSSION layout row end tag. Normally </tr >
DR_TCELLSTART This is the HTML tag used to define the start of a Discussion table cell. Note the cellparams tagattribute. This is a reserved word that will automatically be replaced any the calculated BgColor, HAlign, VAlign and any CustomAttributes needed for the specific question. Normally <td cellparams >.
DR_TCELLEND This is the HTML tag used to define the end of a Discussion table cell. Normally </td>.
DR_TTEND DISCUSSION layout page/question group end tag. Normally </table >
DR_TR This is the standard question-response row for the DISCUSSION layout. Normally set to <#Question></tr><tr><#OpType>.
DR_TRC This is the checkbox input control question-response row for the DISCUSSION layout. Normally set to <#Question></tr><tr><#OpType>.
DR_TRL This is the long question text row for the DISCUSSION layout. This is usually used for section headings and info blocks. Normally set to

<#Question></tr><tr><#OpType> here.

DR_TRCOLOUR A list of colours separated by commas representing the colour row cycle for the survey. The standard setting is "white" for this type.
DR_TRERROR
DR_TRDTA This is the long question-response row for the DISCUSSION layout. It is used for input controls requiring double column space - such as a large free text entry box. Normally set to <#Question></tr><tr><#OpType>.

Messages

  • AccessNotAllowedMsg - (SYS) The messagre displayed if access is not allowed for the current responder to the survey. Normally:"<H1>Access Not Available.</H1>"
  • XAccessNotAllowedMsg - (SYS) As above.
  • InstanceAccessNotAllowedMsg - (SYS) The messagre displayed if access is not allowed for the current responder to any currently available instance of the survey. Normally:"<H1>Access to the requested survey instance is not available</H1>"
  • XInstanceAccessNotAllowedMsg - (SYS) As Above


BackLinks