AN-016 Protégé Server ODBC Database Connectivity

Transcription

1 AN-016 Protégé Server ODBC Database Connectivity

2 PUBLICATION INFORMATION This application note covers the use of the protégé system to perform a specific function and may be used in conjunction with other publications. Specifications may change without notice, for updates visit the Integrated Control Technology website at No other hardware was used to prepare this application note and will not affect the result of the application using the programming information presented.

3 CONTENTS Contents... 1 Protégé system... 2 Introduction... 2 Application Note Information... 2 Firmware Version... 2 Connectivity... 3 Overview... 3 Database Block Diagram... 3 Enabling MSDE/SQL Network Access... 3 Database Overview... 4 Making The Connection... 6 External User Table Introduction External User Table Structure Example Application Introduction Connecting With ODBC Example MS Access Form Information Introduction Contact AN-015 Protégé Server ODBC Database Connectivity 1

4 PROTÉGÉ SYSTEM Introduction The Protégé System is a powerful integrated alarm and access control management system designed to provide integration with building automation, apartment complex control and HVAC in one flexible package. Communicating through a proprietary high speed protocol across an encrypted RS-485 network using modular-based hardware design, system installers have the flexibility to accommodate any installation from small or large, residential or commercial. Application Note Information Focusing on interoperability and flexible database integration the Protégé System allows Integrated Control Technology to provide access to the external global user table for programming from a remote application or database. Connectivity with remote Microsoft Access, Microsoft SQL Server, MSDE, MySQL and Oracle databases can be achieved using a simple linked table approach. Connections can also be used with any application that is able to utilise SQL and Database connections from a programming environment. The following application note describes the procedures to connect to the Protégé SQL Server Database using an ODBC connection. The example details an interface in to the global external users table which automatically adds and downloads users to the Protégé System Controllers. This example uses a simple MS Access *.MDB file with a linked table. The example can be downloaded from the software download section. Firmware Version This application note does not utilise firmware from the system controller or Protégé Modules. We recommend that this application note is used in conjunction with the latest available release of the Protégé Integrated System Management Suite. 2 AN-016 Protégé Server ODBC Database Connectivity

5 CONNECTIVITY Overview This document describes the methods used to connect an external third party application or database to the Protégé System Management Suite to update and manage users within the protégé installation. Connecting to the Protégé System Management Suite using the external database and ODBC connections requires extensive knowledge of networking, database connectivity and security configuration parameters which are beyond the scope of this document. Database Block Diagram The external users table is provided to allow a remote database (student database, SAP, ERP or custom application) to connect and program users in the Protégé System. Figure 1 Basic Database Structure Enabling MSDE/SQL Network Access Depending on the configuration of your MSDE or SQL Server Database that is installed it may not be possible to connect to the database remotely without enabled the network interface connection. The following procedure explains how to connect to the Protege Instance of the MSDE/SQL Server that is installed as part of the server installation. Other SQL Server installations may require different administration requirements which are beyond the scope of this application note. 1. Using the file explorer browse to the C:\Program Files\Microsoft SQL Server\80\Tools\Binn directory and execute the program SVRNETCN.EXE. Your directory may be different depending on your installation. 2. Before using the application below ENSURE that you have selected the correct SQL Server Instance or configured server. Verify that the correct computer name and database are located at the top right hand side BEFORE proceeding. AN-015 Protégé Server ODBC Database Connectivity 3

6 3. You will be shown the screen above, as in the above screen enable the connection type that suites your environment. If you are not sure then you need to consult a network or database administrator and close this application immediately. 4. In the examples contained in this application note the TCP/IP connection is used to the standard SQL Server Port Close the SVRNETCN.EXE application. Database Overview The ability to connect from remote applications that require user data to be updated in real time allows for many possible interfaces and configurations. In most cases the data connectivity function will allow applications such as an external photo id issuing station, employee database or custom applications to connect to the protégé system. This functionality may be used permanently or only at the initial stages of installation to get all users within a company in to the database in real time. Figure 1 - Basic Database Connection In the above example a remote database is being used to store user data, this database is connected to the protégé external user table allowing data for the access control system to be updated in real time. 4 AN-016 Protégé Server ODBC Database Connectivity

7 In most cases this is the typical use of the database connectivity, the database can be an employee or administration database maintained by a larger company wide application and example of this is SAP, PeopleSoft, DataCard Image Works or similar Photo ID, Company or employee management applications. For an example of a connection using ODBC and Microsoft Access complete with example forms and reports refer to the Example Application Section on Page 13. Figure 2 - Advanced Database Connection In the above example a remote application is being used for Photo-ID and is using data from the remote database to attach additional user information (Photo, Issue Number). This database then uses a trigger or internal update method to send the information to the Protégé System when the data changes. The example is further complicated by the external database being modified and maintained by a distributed data entry application used for the initial entry and data processing portion of the users being added to the system. It is important to note that in the advanced connection the remote database is the primary database and the Protégé System external user table is a secondary portion being updated from data within the remote database. To import users into the Protégé System Management Suite from an external file use the Import User wizard available from the File Menu in the Protégé System Management Application. Many formats are already included and user definable formats available, for more information consult the Protégé System Management Suite Help File. To import users from an existing database use an appropriate update query or code to write the users in to the External Database Table. This will mean the protégé system controllers will be updated at the same time. It is recommended to batch load users in smaller groups. AN-015 Protégé Server ODBC Database Connectivity 5

8 Making The Connection Making the connection to the protégé server is done by a ODBC link. The following example shows how to link a table in Microsoft Access using ODBC and the Protégé System Management Suite. 1. Open MS Access and create a test database, this is typically DB1.MDB, in our example we have used the name ProtégéExternalUsers.MDB 2. As shown in the above example right click in the table window and select the Link Tables option from the context menu. 3. When prompted for the filename scroll the file types and select the ODBC Database() option which will be located towards the end of the available entries. 6 AN-016 Protégé Server ODBC Database Connectivity

9 4. From the select data source screen select the button new located to the right of the DSN Name text box. You will now be presented with the data source type selection. 5. Select SQL Server and then select the next button to proceed with the data source configuration. You will now be prompted to give the connection you are creating a name, this allows the information relating to this connection to be stored so that it can be used when you link other tables or information. In our example we have given it the name ProtégéExternalUsers which clearly describes the use of this DSN file. Select the next button and then select finish. 6. When you have the create new data source to SQL server dialog box presented to you, select the Protégé SQL Server Instance from the drop down selection. AN-015 Protégé Server ODBC Database Connectivity 7

10 7. When you have the create new data source to SQL server dialog box presented to you, select the Protégé SQL Server Instance from the drop down selection. If the instance is not presented in the drop down list type in the name of the computer as shown above (PCNAME) followed by a backwards slash and PROTEGE in capitals. Select the next button to move to the next step. 8. You will now be presented with the Login ID and Password, the default logon ID and Password is ProtegeEx for the User and ProtegeEx for the password, please note the password is case sensitive. Select the next button to proceed. 8 AN-016 Protégé Server ODBC Database Connectivity

11 9. Once the SQL Database is found and the user information verified the above screen will be presented to you. Select the default database as Protege and then select the next button to proceed. 10. The next screen of the process does not get altered and you should select the finish button to complete the creation of the connection. AN-015 Protégé Server ODBC Database Connectivity 9

12 11. Once the connection has been completed you can test the connection by selecting the test data source button. Once the connection has been made the table will be shown as a linked table in the Microsoft database that you have created. For information on the Sample Database refer to the section Example Application on Page AN-016 Protégé Server ODBC Database Connectivity

13 EXTERNAL USER TABLE Introduction The external user table is used by the remote application to write, modify and read the current users. This table is used by the protégé application to activate internal triggers to update the appropriate user within the protégé system. This method protects the system from vulnerability by only allowing access to the database for the specific purpose that is required. This is further enhanced with a password and login name to be entered to gain access. The login and password default to the login id "ProtegeEx" and the password "ProtegeEx". The defaults are stored in the protégé administration settings and it is recommended that these be changed before any connections are made to ensure a high level of security. External User Table Structure The following shows the external user table structure. The structure below is also available in the attachment with this document "exusers.sql", this SQL table details the exact statements used for creation of the table and should provide enough information for the programmer or database administrator. The individual table elements and how they relate to the internal users and local users within the protégé system are detailed in the following section. TABLE Protege.dbo.ExGlobalUsers ( [ExGlobalUsersID] [int] IDENTITY(0,1), [SiteID] int NOT NULL DEFAULT 1, [GlobalUserID] [int] NOT NULL DEFAULT 0, [FirstName] nvarchar(128) DEFAULT '', [LastName] nvarchar(128) DEFAULT '', [DisplayName] nvarchar(128) NOT NULL DEFAULT '', [PinNumber] nvarchar(8) NOT NULL DEFAULT '', [FamilyNumber] int NOT NULL DEFAULT 0, [CardNumber] int NOT NULL DEFAULT 0, [GlobalAccessLevel] int NOT NULL DEFAULT , [GlobalArea] int NOT NULL DEFAULT , [ExpiryDate] datetime NOT NULL DEFAULT GETDATE(), [ExpiryTime] datetime NOT NULL DEFAULT GETDATE(), [ShowAGreetingMessageToUser] bit NOT NULL DEFAULT 1, [GoDirectlyToTheMenuOnLoginNoAreaControl] bit NOT NULL DEFAULT 0, [UserCanAcknowledgeAlarmMemory] bit NOT NULL DEFAULT 1, [ShowAlarmMemoryOnLogin] bit NOT NULL DEFAULT 0, [TurnOffThePrimaryAreaIfUserHasAccessOnLogin] bit NOT NULL DEFAULT 1, [TurnOffTheUserAreaOnLoginIfUserHasAccess] bit NOT NULL DEFAULT 1, [AcknowledgeTroubles] bit NOT NULL DEFAULT 0, [AcknowledgeSystemTroubles] bit NOT NULL DEFAULT 0, [UserIsADualCodeMaster] bit NOT NULL DEFAULT 0, [UserIsADualCodeProvider] bit NOT NULL DEFAULT 0, [UserHasSuperRightsAndCanOverrideAntipassback] bit NOT NULL DEFAULT 0, [UserCanModifyTheirOwnCode] bit NOT NULL DEFAULT 0, [UserCanModifyAnyCodeWithTheirAccessLevel] bit NOT NULL DEFAULT 0, AN-015 Protégé Server ODBC Database Connectivity 11

14 ) [UserLoiterExpiryCountEnabled] bit NOT NULL DEFAULT 0, [UserCanLogInRemotely] bit NOT NULL DEFAULT 0, [UserIsADuressUser] bit NOT NULL DEFAULT 0, [CardMode] int NOT NULL DEFAULT 0, [DownloadType] int NOT NULL DEFAULT 0, [CreatedTime] datetime NOT NULL DEFAULT GETDATE(), [LastModifiedTime] datetime NOT NULL DEFAULT GETDATE() This structure is automatically provided to the connecting database or application when the ODBC link is made. The above and following information is provided for a reference only to the settings and default values. 12 AN-016 Protégé Server ODBC Database Connectivity

15 EXAMPLE APPLICATION Introduction The example application shows the ease at which the external user table can be connected and presented using the Microsoft Access Database. This application was chosen due to the simplicity and wide availability of the application. The example can easily be adapted to ANY database or application. The default login "ProtegeEx" and password "ProtegeEx" have been used for this example and in the files that are supplied. This must be changed when used with a live system and data. Connecting With ODBC Before the example database will operate you must create your own linked table to the Protégé SQL Server that is installed on your machine. To complete the connection follow the details in the Section Making the Connection on Page 6. Example MS Access Form The following figure shows the sample Microsoft Access Form that is provided in the sample database. The customisation of the form is very flexible and as can be seen easily extended to other applications as required. Figure 3 Example MS Access Form AN-015 Protégé Server ODBC Database Connectivity 13

16 INFORMATION Introduction Application notes are provided as is without any implied warranty or intended use and are written by Integrated Control Technology as an aid in programming and connecting devices to the Protégé System. Contact Integrated Control Technology welcomes all feedback. Please visit our website or use the information below. Integrated Control Technology P.O. Box Unit C, North Harbour Post Centre 6 Ascension Place Auckland Mairangi Bay New Zealand Auckland New Zealand Phone: Fax: AN-016 Protégé Server ODBC Database Connectivity

17 Unit C, 6 Ascension Place, Mairangi Bay, P.O. Box North Harbour, Auckland, New Zealand. Phone: +64 (9) Fax: +64 (9)