Installing the EasyLobby / WinDSX Integration

Transcription

1 I) System Requirements This version of the EasyLobby / WinDSX integration has been developed for EasyLobby version 9.0 and WinDSX version It has not been tested with any other configurations. II) Install and Configure WinDSX Install and configure the WinDSX product. There are a few specific WinDSX configuration settings to be aware of as follows: 1) Any access level that may be assigned to a visitor must have the can be assigned to visitors attribute enabled in the WinDSX access level setup screen. 2) You need to add a user-defined field to WinDSX (for the location group associated with EasyLobby) to hold the EasyLobby visitor id. The name of the UDF is not important ( EasyLobby Visitor Id for example) but the UDF must have both the Data Must be Unique and Name ID attributes selected. Please record the UDF number of this field, as it will be used later in the configuration of the solution. By default the integration uses UDF field number 7. 3) WinDSX requires the company field when registering a cardholder. There are several options on how EasyLobby determines the company name to use (see below) but the names used in EasyLobby must match those in WinDSX. 4) The current solution supports integration into a single building group and optionally supports specifying a single output linking level for the visitor s card. It can be customized to support multiple building groups and/or multiple output linking levels if this customization is needed please contact EasyLobby technical support (see Section IX below). III) Install and Configure the EasyLobby SVM 9.0 database To use this integration, the EasyLobby 9.0 database must be installed on either MSDE or SQL Server (the integration is not supported on Oracle or local Access databases). You may install the EasyLobby database onto the same physical server as the WinDSX installation, or alternately you can install the EasyLobby database onto a separate database server. If the EasyLobby database is installed on a separate system, you must provide a shared folder on the WinDSX server where the integration files will be written, The EasyLobby 9.0 Product CD comes with a database installer. For complete database setup instructions, please read the database setup documentation found in the SQL folder of your EasyLobby Product CD, EasyLobby MSDE Setup.pdf (for MSDE) or EasyLobby SQL Server Database Setup.pdf (for SQL Server).

2 Once you have installed the EasyLobby 9.0 database, you can proceed with the installation instructions starting with the next section below. Note: The integration solution creates import files in the WinDSX database folder, by default C:\WinDSX. The EasyLobby database server must have access to this directory (either by running on the same system or else via a file share of the WinDSX folder). Additionally, if you enable the visitor photo option you will need to specify a directory to hold the photo files, which must be accessible to the EasyLobby database server and to the WinDSX server. IV) Install the Integration Solution To install the integration solution, on the system where the EasyLobby 9.0 database is installed, run the installer program called EasyLobby90WinDSXSetup.exe from the WinDSX folder on your EasyLobby product CD. This will install the integration files into the folder C:\Program Files\EasyLobby\WinDSX Integration. V) Configure and Install the Integration Trigger This solution comes with a utility that allows you to configure and install the integration trigger into your EasyLobby database. To run this utility, choose the command called Start Programs EasyLobby 9.0 WinDSX Integration Config 9.0. The utility has a single screen interface as shown in the graphic below. The individual settings are described in the sections following. 08/30/2011 Page 2

3 Integration Trigger Script This is the script file to use to install the integration trigger into the EasyLobby database. This standard script file is located in the installation folder called C:\Program Files\EasyLobby\WinDSX Integration\TriggerWinDSX.sql. You can click the Browse button to select another file. This utility loads and saves the various trigger parameters and account credentials to and from this file. Target Database This section allows you to select the target database server on the local system where the EasyLobby database is installed. If you have installed the EasyLobby MSDE database from the EasyLobby Product CD, select the first choice. If you are using the default instance of MSDE or SQL Server, select the second choice and specify the account you will use to install the trigger, normally the sa account or equivalent (if you are using the WinDSX MSDE, the sa password is master by default). If you are using a named instance of SQL Server select the third option and specify the credentials and the name of the instance. The utility will automatically detect when the EasyLobby MSDE or SQL Server default instance is installed and enable those choices. Windows Account Credentials In this section you must supply the credentials to a Windows account with enough privileges on the system to be able to run the xp_cmdshell stored procedure in SQL Server or MSDE. Normally this should be a local administrator account. Trigger Parameters The selections in this section govern the behavior of the integration trigger once installed and running with EasyLobby. Badge Type If using barcodes, the visitor Custom Id number that is printed on the EasyLobby badges is used for the card number in WinDSX. For prox cards, the number in the visitor Prox Card field on the Badge tab of the visitor form (Full View) is used for the card number. In this case, if the Prox Card number field is blank, the visitor record will not be transferred to WinDSX. Access Level Map Field If set to Default, the trigger will use the access level name from the Access Level Default field as the access level to assign to the card in WinDSX. Set this to Category to use the EasyLobby visitor category (from the category drop down on the visitor form) as the access level, or Clearance to use the clearance value from the clearance drop down. Set this to Company to use the company of the employee being visited as the access level. Set it to User Defined 1 to use the value of the user defined 1 field as the access level. Access Level Default If the Access Level Map Field is set to Default the trigger will always use this value as the access level to assign to the card in WinDSX. The initial value is Visitor. 08/30/2011 Page 3

4 Company Map Field If set to Default, the trigger will the name from the Company Default field (below) as the company to assign to the card in WinDSX. Set this to Company to use the company of the employee being visited as the company. Set this to Category to use the EasyLobby visitor category (from the category drop down on the visitor form) as the company, or Clearance to use the clearance value from the clearance drop down. Set it to User Defined 1 to use the value of the user defined 1 field as the company. Company Default If the Company Map Field is set to Default, the trigger will always use this value as the company assign to the card in WinDSX. The initial value is blank. Location Group This field must be set to the number of the location group to use in the WinDSX system. The default value is 1. This value must be an integer. Output Linking Level This field is optional and can be set to the output linking level assigned when a visitor card is created. The default blank value specifies that no output linking level is assigned in WinDSX. If non-blank, this value must be an integer. DSX UDF Index This field must contain the User Defined Field # of the field where the EasyLobby visitor id is to be stored in WinDSX. The default value is 7. This value must be an integer. DSX Record Type Set this to specify whether the cardholder record will be set to be a visitor or a standard employee record. Output Directory This field must contain the path to the database folder of the WinDSX installation where the import files are written (this is typically the main program installation folder, C:\WinDSX). If you want to run the EasyLobby database on a different server than the WinDSX import service, then you must share the C:\WinDSX folder from the WinDSX system and, on the EasyLobby database server, save the.txt files to that share instead. Send Photo Check this box to send the visitor photo, if there is one, to WinDSX. Photo Directory If Send Photo is checked, this field contains the path to the directory where the photo files will be written. You may click the Browse button to browse to and select a directory. Utility Buttons The selections in this section describe the behavior of the buttons at the bottom of the configuration utility. Help Displays the help document in WordPad. 08/30/2011 Page 4

5 Factory Settings Will reset all the settings on the current form to the factory settings. Note that these settings will not be saved to the trigger file unless you click the Save Settings button. Save Settings Will save all the current trigger parameter settings and windows credentials to the current script file (as indicated by the Integration Trigger Script field at the top of the form). Remove Trigger Removes the trigger from the EasyLobby database. Note that this function uses the script file called RemoveTrigger.sql from the config utility installation folder. Install Trigger Will save the current settings and install the trigger to the EasyLobby database as selected in the Target Database section. Exit Quit the application VI) Format of the Integration Trigger SQL Script File Note: Normally you will use the EasyLobby WinDSX Configuration utility to install the integration trigger, as described in the section above. This section documents the format of the trigger script file should you need to edit it directly and install it manually. To manually install the integration solution, you edit and run the script file called TriggerWinDSX.sql, which adds a trigger to your EasyLobby 9.0 database. This trigger runs after the Check In, Check Out and Delete actions in EasyLobby SVM, and is responsible for moving the visitor information to the WinDSX system. Before running the TriggerWinDSX.sql script you will need to set some specific options controlling the behavior of the integration. You don t have to worry about getting the configuration exactly right the first time, as you can always edit the script and load it again. You may edit the TriggerWinDSX.sql script with Notepad or similar text editor. After you open the script in Notepad, locate the line that reads [Start Variables Section] a little way down in the file. You may edit any of the variables between the [Start Variables Section] comment and the [End Variables Section] comment. The following describes the variables and their Set this to 0 if you wish to use barcodes printed on the EasyLobby badges, or 1 (the default) if you will use prox cards to give to some or all of your visitors. Note that when using prox cards, visitor records are only transferred to WinDSX when the prox card field of the visitor form is populated with a numeric The default is a blank string ( ), in which case the trigger will use the access level in variable as the access level to assign to the cardholder in WinDSX. Set this to 'CATEGORY' to use 08/30/2011 Page 5

6 the EasyLobby visitor category (from the category drop down on the visitor form) as the access level in WinDSX, or 'CLEARANCE' to use the clearance value from the clearance drop down. Set this to 'COMPANY' to use the company of the employee being visited as the access level. Set it to 'USERDEF1' to use the value of the user defined 1 field as the access Used variable is blank ( ). In this case, the trigger will always use this value as the access level to assign to the visitor (cardholder) in The default is COMPANY, which uses the company of the employee being visited. When a blank string ( ) the trigger will use the company in Set this to 'CATEGORY' to use the EasyLobby visitor category (from the category drop down on the visitor form) as the company in WinDSX, or 'CLEARANCE' to use the clearance value from the clearance drop down. Set it to 'USERDEF1' to use the value of the user defined 1 field as the Used variable is blank ( ). In this case, the trigger will always use this value as the company to assign to the visitor (cardholder) in This variable must be set to the number of the location group to use in the WinDSX system. The default value is This variable is optional and can be set to the output linking level assigned when a visitor card is created. The default value of (empty string) specifies that no output linking level is This variable must contain the UDF # of the field where the EasyLobby visitor id is Set this variable to 1 to specify that the cardholder record added to the DSX database is a visitor, otherwise set it to This variable must contain the path to the database folder of the WinDSX installation (this is typically the main program installation folder, C:\WinDSX). If the EasyLobby database is running on the same system as WinDSX, then the default value of 'C:\WinDSX' would be correct (note that this path must be in 8.3 name format). For each check in (or check out) in EasyLobby that will result in a cardholder record being created (or deleted), a.txt file will be created in this folder. This file contains the information that tells the WinDSX import service the information about the cardholder and card. Once WinDSX has processed to information in the import file it will delete it. 08/30/2011 Page 6

7 If you want to run the EasyLobby database on a different server than the WinDSX import service, then you must share the C:\WinDSX folder from the WinDSX system and, on the EasyLobby database server, save the.txt files to that share instead. In this case you must determine the proper 8.3 format path to the share, and set this variable The default value is 0, set this variable to 1 to enable transfer of the visitor photograph to WinDSX. If you to 1, there is some further setup required. Transfer of photos requires the SQL Server utility file textcopy.exe, which must be located in the SQL Server Binn folder (typically C:\Program Files\Microsoft SQL Server\80\Tools\Binn). This is typically present in full SQL Server installs but not in MSDE installs. If this file is not present on your system, we have provided it with the solution files in the folder called Integration Files. Copy this file to the Binn folder of your SQL Server or MSDE installation. The utility textcopy.exe also requires the DLL file called ntwdblib.dll. SQL Server typically installs this file into the Windows System32 folder. If this file is not present on your system, copy it either to the System32 folder or to the Binn Set to a directory on the server to hold the temporary image files. The images are placed here before the import into WinDSX and then removed when the visitor is checked-out or deleted (although the images are only needed until after WinDSX has processed the cardholder add operation). The path in this variable must be in 8.3 filename format. Providing a proxy account You must supply the credentials of an account with enough privileges on the WinDSX system to be able to write out the.txt import files or photos. You set these account credentials toward the bottom of the trigger script. You will see the following lines of code: EXECUTE xp_sqlagent_proxy_account N'SET', N'<DomainName>', N'<WindowsAccount>', N'<WindowsPassword>' GO You must replace <DomainName>, <WindowsAccount> and <WindowsPassword> with the appropriate values for your account. The domain name can be the name of the local system or the name of your domain. The account and password are the same as those you would use to log in to the system. VII) Manual Loading of the Integration Database Trigger Note: Normally you will use the EasyLobby WinDSX Configuration utility to install the integration trigger, as described in the section V above. This section describes how to install the trigger manually. 08/30/2011 Page 7

8 After modifying the script, you run the script to load the trigger and associated stored procedures into the EasyLobby9 database. Note that if you need to change one of the parameters, you may edit the script and run it again without any problem. If you are using Microsoft SQL Server for the EasyLobby database, run the MS Query Analyzer tool, sign in as sa, load the TriggerWinDSX.sql script and execute it by clicking the right-pointing green triangle icon on the toolbar or by choosing the Query Execute menu command. If you are using the EasyLobby MSDE you can use the MSDE OSQL utility, typically found in the C:\Program Files\Microsoft SQL Server\80\Tools\Binn folder. You must run OSQL from the DOS command prompt. Note that with OSQL, you will need to use the sa account and password (default is doorman ) assigned when you installed the EasyLobby MSDE. The command line is: > OSQL U sa P doorman S [server]\easylobby i [path]triggerwindsx.sql Note that the arguments to this command are case sensitive. You must replace the values for password and server. You must also supply the [path] to the trigger file unless it is in the Binn directory, in which case you can omit the path. VIII) Operation of the Solution When a visitor is checked in using EasyLobby SVM, the trigger in the EasyLobby9 database is executed which generates the import.txt file. WinDSX checks for new import files every 15 seconds and when if finds the new file it creates a new cardholder and card in WinDSX. The card number will be either the custom id or the prox card number from the EasyLobby visitor record, depending on the configuration of the solution. Note that when using prox cards, the cardholder record is only created when the prox card field is populated in the EasyLobby visitor form. EasyLobby has support for two USB attachable prox card scanners: The RF Ideas pcprox device and the Hirsch HID device. These can be used to scan the card number directly into EasyLobby, and also the card can be scanned for check out. When using barcodes, EasyLobby offers two options for how the barcode number is generated. You can set these options in the Edit Program Options, Defaults tab. The default setting, Auto Increment Custom Id, will create an id number that increases by one with each visitor. This number is generated by taking the visitor record id and adding the site id number plus 100. Thus, if the site id is 101, and the record id is 1, then the custom id number will be This number will increase by one for each new visitor. If you would like to confine your custom id numbers to an assigned range, change this setting to Generate custom id in range and set the numeric values for the range of ids 08/30/2011 Page 8

9 that you would like to assign to visitors. EasyLobby will map the visitor record id into this range of numbers, wrapping when it reaches the top. When a visitor is checked out in EasyLobby SVM, the trigger is also executed, which generates a.txt file that, when imported, deletes the visitor and badge from the WinDSX database. If a visitor record is deleted in EasyLobby SVM before the visitor has been checked out, this action also causes the trigger to remove the cardholder and card from WinDSX. IX) Technical Support For more information or support on this solution, please contact at support@easylobby.com or at /30/2011 Page 9