Database Gateway Guide

Transcription

1 Database Gateway Guide March 2016

2 SATEON Database Gateway Guide Issue 0.1, released March 2016 Disclaimer Copyright 2016, Grosvenor Technology. All rights reserved. SATEON and the SATEON logo are trademarks or registered trademarks of Grosvenor Technology. All other brands, names, or trademarks appearing in this document are acknowledged as the trademarks of their respective owners. No part of this document may be reproduced in any form or by any means for any purpose without the written permission of Grosvenor Technology. Whilst we make every effort to ensure the accuracy of our publications, Grosvenor Technology assumes no responsibility or liability for any errors or inaccuracies that may appear in this document. Sateon 2 Issue 0.1

3 Contents Preface... 5 About the Database Gateway... 5 About this guide... 5 Related documents... 6 Technical support... 6 Introduction to the Database Gateway... 7 Overview of the Database Gateway... 7 How it works... 8 Installation and licensing... 8 Stored procedures... 9 Operations permitted Format of data The eds.importsource table Format Explanation of database fields The ac.user table Format Operations and example scripts List of operations I Insert IT Insert Token IAPG Insert Access Permission Group II Insert Image M Modify MAPG Modify Access Permission Groups MT Modify Token MI Modify Image D Delete Sateon 3 Issue 0.1

4 DT Delete Token DAPG Delete Access Permission Group Troubleshooting Editing data Checking logs The Database Gateway stored procedures Procedure eds.assignaccesspermissions Procedure eds.createpersonnelandtoken Procedure eds.createtokenattachpersonnel Execute procedure Procedure eds.deletepersonnel Procedure eds.deletepersonneltokensaccess Procedure eds.deletetoken Procedure eds.revokeaccesspermissions Procedure eds.liststaticdata SQL Table API Overview... Error! Bookmark not defined. Format of the eds.import row Format of data payload (JSON) Format of eds.importresult table Example import script Important notes... Error! Bookmark not defined. Sateon 4 Issue 0.1

5 Preface This document provides information on the Database Gateway module of Sateon, which allows personnel data from external systems, such as HR systems, to be integrated into the Sateon database. The integration has been documented for Sateon Release 2.9: it may not include changes incorporated in later versions of the software. Representations of screens and other illustrations in this document are shown for general illustration only. Date of latest update: March About the Database Gateway The Database Gateway is an optional, separately licensed module that provides an interface between the Sateon system and a third-party system. It allows Personnel, Token and Access Group data to be imported from external databases. About this guide This document provides details on setting up and configuring the Database Gateway. It is aimed at system integrators with a good knowledge of SQL Server who are responsible for integrating external data into Sateon. This guide includes the following information: Section 1 Introduction to the Database Gateway. This section provides an overview of the Database Gateway including installation details. Section 2 Format of data. This section details the format of the required tables in the Sateon database. Section 3 Example SQL scripts. This section provides examples of scripts that could be used to set up database entries. Section 4 Troubleshooting. This section includes information about potential problems and fixes Sateon 5 Issue 0.1

6 Appendix A The Database Gateway Stored Procedures. This section details the set of stored procedures provided with the integration. These can be used to update the database. Appendix B SQL Table API. This appendix describes an alternative method of importing data into the Sateon database using an API. Related documents The following Sateon documents may also be useful: The Sateon Installation Guide. This guide explains how to install Sateon, including details of hardware requirements and software prerequisites. The Sateon Personnel Module Guide. Explains how to set up the people who will use the system and the tokens they use to gain access to the site. The Sateon Access Control Guide. Explains how to set up the data in the access control module of Sateon which includes access permissions, time patterns, areas and system hardware. Technical support For further assistance with Sateon, please contact Grosvenor Technology Technical Support as follows: (EMEA): (US): (APAC): Website: ac-support@grosvenortechnology.com ac-ussupport@grosvenortechnology.com apacsupport@grosvenortechnology.com Sateon 6 Issue 0.1

7 Section 1 Introduction to the Database Gateway Overview of the Database Gateway The Database Gateway allows data from external systems such as HR databases to be integrated into Sateon. It supports the following: The import of Personnel and Token data, including links between these data objects. The adding of Access Groups to Personnel records in order to define a person s permitted access. The attaching of images (photographs) to Personnel records and the later modification of images. The modification and deletion of Personnel and Token data. All changes made are logged and audited, and Sateon events are created to ensure that all the Sateon services are updated with the changes being made. Note: For users who wish to use import data other than personnel, tokens and access permissions, the SQL Table API provides an alternative method that allows the import of any other data. For details, see SQL Table API on page SQL Table API37. Sateon 7 Issue 0.1

8 How it works The System Agent service within Sateon is responsible for handling and processing all requests from the Database Gateway. The System Agent service checks the eds.importsource table in the Sateon database every 10 seconds for any requests. Each request is then processed; the data is loaded into Sateon and the entry in the eds.importsource table is deleted. In the case of problems during operation, such as data not being saved in the Sateon database, we recommend that you check the System Agent logs. For details, see Checking logs on page 24. Installation and licensing The Database Gateway module is an optional, separately licensed Sateon feature. For a new installation you need to ensure that the licence includes support for the Database Gateway. If you have added the Database Gateway to an existing installation, you will need an updated licence file. The licence will allow the System Agent to process the records in the eds.importsource table. Without a valid licence file, you will be able to save data to the database and use the stored procedures but no records will be processed by Sateon. You can add a new licence from the System Configuration > System Administration > Licensing page within Sateon. For full details on how to add a licence file, see the Sateon Installation Guide. The Licencing page shows whether the Database Gateway is licenced: Sateon 8 Issue 0.1

9 For a new installation the licence needs to be verified within 30 days for Sateon to continue to work. Note: If you do not have a valid licence file yet, contact Grosvenor Technical Support as soon as possible. Stored procedures A set of stored procedures to create and manage data is available as an alternative method of using the Database Gateway. The stored procedures write to the eds.importsource table in a format required by the System Agent service. This consists of an instruction, the key field (a GUID) and associated parameters. These stored procedures are provided as part of the integration and details are given in Appendix A - The Database Gateway stored procedures on page 26. Sateon 9 Issue 0.1

10 Operations permitted The following operations can be performed: Insert (Personnel data) Modify (Personnel data) Delete (Personnel data) Insert Token Modify Token Delete Token Insert Access Permission Group Delete Access Permission Group Modify Access Permission Group Insert Image Modify Image Sateon 10 Issue 0.1

11 Section 2 Format of data The Database Gateway uses the eds.importsource table in the Sateon database. The eds.importsource table Format The schema of the eds.importsource table is as follows: [eds].[importsource] ( [SequenceId] [bigint] IDENTITY(1,1) NOT NULL, [Operation] [nvarchar](10) NOT NULL, [ContainsToken] [bit] NOT NULL, [User_Id] [uniqueidentifier] NULL, [User_Title] [nvarchar](50) NULL, [User_Surname] [nvarchar](128) NULL, [User_FirstName] [nvarchar](128) NULL, [User_EmpNumber] [nvarchar](50) NULL, [User_DepartmentId] [uniqueidentifier] NULL, [User_Comment] [nvarchar](max) NULL, [User_IsEscorted] [bit] NULL, [User_ExtendUnlock] [bit] NULL, [User_APBExempt] [bit] NULL, [User_AllowedToCommandReader] [bit] NULL, [User_AccessStart] [datetime2](7) NULL, [User_AccessEnd] [datetime2](7) NULL, [ContainsImage] [bit] NOT NULL, [Image_Path] [nvarchar](300) NULL, Sateon 11 Issue 0.1

12 ) [Image_Data] [varbinary](max) NULL, [User_UnusedTokenExempt] [bit] NULL, [User_PartitionId] [uniqueidentifier] NULL, [User_SecurityContextId] [uniqueidentifier] NULL, [User_IsLinkableOutsidePartition] [bit] NULL, [Token_Id] [uniqueidentifier] NULL, [Token_TokenTypeId] [uniqueidentifier] NULL, [Token_TokenData] [nvarchar](50) NULL, [Token_ValidationData] [nvarchar](50) NULL, [Token_ValidFrom] [datetime2](7) NULL, [Token_ValidTo] [datetime2](7) NULL, [Token_TokenStatusId] [uniqueidentifier] NULL, [Token_CardDesignId] [uniqueidentifier] NULL, [Token_PoolId] [uniqueidentifier] NULL, [Token_IsPrinted] [bit] NULL, [Token_IsTemporary] [bit] NULL, [Token_DeactivateExempt] [bit] NULL, [Token_PartitionId] [uniqueidentifier] NULL, [Token_SecurityContextId] [uniqueidentifier] NULL, [Token_IsLinkableOutsidePartition] [bit] NULL, [AccessPermissions] [nvarchar](max) NULL, [AccessPermissions_Start] [datetime2](7) NULL, [AccessPermissions_End] [datetime2](7) NULL, [SystemId] [uniqueidentifier] NULL, [User_Extra01] [nvarchar](256) NULL, [User_Extra02] [nvarchar](256) NULL, [User_Extra03] [nvarchar](256) NULL, [User_Extra04] [nvarchar](256) NULL, [User_Extra05] [nvarchar](256) NULL, [User_Extra06] [nvarchar](256) NULL, [User_Extra07] [nvarchar](256) NULL, [User_Extra08] [nvarchar](256) NULL, [User_Extra09] [nvarchar](256) NULL, [User_Extra10] [nvarchar](256) NULL, [User_Extra11] [nvarchar](256) NULL, [User_Extra12] [nvarchar](256) NULL, [User_Extra13] [nvarchar](256) NULL, [User_Extra14] [nvarchar](256) NULL, [User_Extra15] [nvarchar](256) NULL, [User_Extra16] [nvarchar](256) NULL, [User_Extra17] [nvarchar](256) NULL, [User_Extra18] [nvarchar](256) NULL, [User_Extra19] [nvarchar](256) NULL, [User_Extra20] [nvarchar](256) NULL, Note: The term User appears in the database; note that this corresponds to the term Personnel within the Sateon user interface. Sateon 12 Issue 0.1

13 Explanation of database fields SequenceId Operation Field ContainsToken User_Id User_Title User_Surname User_FirstName User_* ContainsImage Image_Path Image_Data Token_Id Token_TokenTypeId Token_TokenData Token_TokenStatusId Token_PoolId Token_* AccessPermissions User_Extra01 to User_Extra20 Explanation A sequential number allocated by the system that uniquely identifies the operation. Identifies the operation being carried out, e.g. I for Insert, MAPG for Modify Access Permission Group. If 1 (True) the Token data associated with this person is also to be inserted/modified in a single operation, with the data depending on the fields included in this operation. If 0 (False) any fields starting with Token_ are ignored. A GUID that uniquely identifies the user/person. The person s title. The person s surname. The person s first name. Other fields in the User table starting with User_ can be included when creating and modifying user records. If 1 (True) the image associated with this person is to be inserted/modified in a single operation, according to fields included in this operation. If 0 (False) any fields starting with Image_ are ignored. The full path that specifies the location of an image, including the file name. An actual image held as a byte array. A GUID identifying a new or existing token. A GUID identifying an existing Token Type. The Token number. A GUID identifying an existing Token Status. A GUID identifying an existing Token Pool. Additional data in the Token table starting with Token_ can be included when creating and modifying token/card records. The access permissions of a person, as a comma-separated list of AccessPermissionGroupIds (GUIDs) Up to 20 additional personnel fields, specific to the installation, which can be used to provide extra information. Sateon 13 Issue 0.1

14 The ac.user table Data imported from external systems is stored in the User, Token and APG tables in the Sateon database. For information the format of the User table is described here. Note that the term User corresponds to the term Personnel within Sateon. Format The schema of the User table is as follows: [ac].[user] ( ) [UserId] [uniqueidentifier] NOT NULL, [Title] [nvarchar](50) NULL, [Surname] [nvarchar](128) NULL, [FirstName] [nvarchar](128) NULL, [EmpNumber] [nvarchar](50) NULL, [DepartmentId] [uniqueidentifier] NULL, [Comment] [nvarchar](max) NULL, [IsEscorted] [bit] NULL, [ExtendUnlock] [bit] NULL, [APBExempt] [bit] NULL, [AllowedToCommandReader] [bit] NULL, [Version] [timestamp] NULL, [AccessStart] [datetime2](7) NULL, [AccessEnd] [datetime2](7) NULL, [SecurityContextId] [uniqueidentifier] NULL, [SystemId] [uniqueidentifier] NULL, [UnusedTokenExempt] [bit] NULL, [Extra01] [nvarchar](256) NULL, [Extra02] [nvarchar](256) NULL, [Extra03] [nvarchar](256) NULL, [Extra04] [nvarchar](256) NULL, [Extra05] [nvarchar](256) NULL, [Extra06] [nvarchar](256) NULL, [Extra07] [nvarchar](256) NULL, [Extra08] [nvarchar](256) NULL, [Extra09] [nvarchar](256) NULL, [Extra10] [nvarchar](256) NULL, [Extra11] [nvarchar](256) NULL, [Extra12] [nvarchar](256) NULL, [Extra13] [nvarchar](256) NULL, [Extra14] [nvarchar](256) NULL, [Extra15] [nvarchar](256) NULL, [Extra16] [nvarchar](256) NULL, [Extra17] [nvarchar](256) NULL, [Extra18] [nvarchar](256) NULL, [Extra19] [nvarchar](256) NULL, [Extra20] [nvarchar](256) NULL, [ExtUserId] [nvarchar](256) NULL, Sateon 14 Issue 0.1

15 Section 3 Operations and example scripts This section details the operations that are possible using the Database Gateway. Example SQL scripts are provided. List of operations The following table summarises the possible operations: I Insert Inserts a new User (Personnel) record and (optionally) a Token record. IT Insert Token Inserts a Token record and associates it with an existing User (Personnel) record. IAPG Insert Access Permission Group Associates an existing access group with an existing User (Personnel) record. II Insert Image Associates an Image (photo) with an existing User (Personnel) record. M Modify Modifies a User (Personnel) record, optionally including amending the associated Token and Image data. MAPG Modify Access Permission Groups Modifies the access groups that are associated with an existing User (Personnel) record. MT Modify Token Modifies the Token associated with an existing User (Personnel) record. Sateon 15 Issue 0.1

16 MI Modify Image Modifies the Image (photo) associated with an existing User (Personnel) record. D Delete Deletes a User (Personnel) record including all tokens associated with it, and unlinks attached access groups. DT Delete Token Deletes a token. DAPG Delete Access Permission Group Deletes the link between a User (Personnel) record and one or more access groups. I Insert Inserts a User (Personnel) record and optionally a Token record in the Sateon database. Parameters Operation ContainsToken User_Id User_Surname User_Firstname User_* AccessPermissions Token_Id Token_TokenData Token_TokenTypeId Token_TokenStatusId Token_PoolId Must be I Required. If True (1) a Token record will also be created, using the data provided in the Token_ fields. If False (0) all Token_ fields are ignored. Optional. If not supplied, a new User Id will be created. Required Required Any other columns in the User table can also be included. See The ac.user table on page 14 for details of valid fields. Optional. If included, must contain a commaseparated list of AccessPermissionGroupIds. Optional. If not supplied, a new Token Id will be created. Required if ContainsToken is True. Required if ContainsToken is True. Required if ContainsToken is True. Required if ContainsToken is True. Sateon 16 Issue 0.1

17 Example SQL statement INSERT INTO EDS.ImportSource (Operation, ContainsToken, User_Title, User_FirstName, User_Surname, User_EmpNumber, AccessPermissions, Token_TokenData, Token_TokenTypeId, Token_TokenStatusId, Token_ TokenPoolId) VALUES ('I', 1, 'Mr', 'Joe', 'Bloggs', 'Emp1701', '9633EC50-684E-4E8B-B817-57C0AC149D23,4CB6FA07-BDAB-43CF-880F-BF2091B0BF13',' ', 'BB9CCCCC-8C15-4D65-8FD1-7625DFAB6A19', 'E2B2ABDF-76EE-498D FBC8D9EE9E', ' E5-421B-BC D4C00C55') IT Insert Token Creates a Token record and associates it with an existing User (Personnel) record. Parameters Operation ContainsToken User_Id Token_Id Token_TokenData Token_TokenTypeId Token_TokenStatusId Token_PoolId Must be IT Required, must be set to True (1) in order to create a token. If False (0) all fields starting Token_ are ignored. Required, identifies the existing user/person. Optional. If not supplied a new Token_Id will be created. Required if ContainsToken is True. Required if ContainsToken is True. Required if ContainsToken is True. Required if ContainsToken is True. Example SQL statement INSERT INTO EDS.ImportSource (Operation, ContainsToken, User_Id, Token_Id, Token_TokenData, Token_TokenTypeId, Token_TokenStatusId, Token_PoolId) VALUES ('IT', 1, 'C3E3E8C6-D828-4D26-91C7-6480E32EBDE1', 'C1FBD912-CED1-48E3-82BE- F20F29BC0D18', ' ', 'BB9CCCCC-8C15-4D65-8FD1-7625DFAB6A19', 'E2B2ABDF-76EE-498D FBC8D9EE9E', ' E5-421B-BC D4C00C55') Sateon 17 Issue 0.1

18 IAPG Insert Access Permission Group Attaches an existing Access Group to an existing User (Personnel) record. Parameters Operation ContainsToken User_Id AccessPermissions Must be IAPG Required; must be set to 0 (False). Required, identifies the existing user/person. Required. The access permissions of the person, as a comma-separated list of AccessPermissionGroupIds. Example SQL statement: INSERT INTO EDS.ImportSource (Operation, ContainsToken, User_Id, AccessPermissions) VALUES ('IAPG', 0, 'C3E3E8C6-D828-4D26-91C7-6480E32EBDE1', '93E45B40-C733-41D4-9EF0-749A C') II Insert Image Associates an image with an existing User (Personnel) record. If there is already an image associated with this person, the image specified will replace the existing primary image. Note: The image can be in.jpg,.png or.bmp format. Note that although there is no theoretical limit to the size of image files that Sateon can handle, we advise a maximum of 1.5 MB to ensure good performance. Parameters Operation ContainsToken User_Id ContainsImage Image_Data Image_Path Must be II Required; must be set to 0 (False). Required, identifies the existing user/person. Required. This must be set to 1 (True). The actual image as a byte array. The full path of a file identifying the image, including the file name. Note that you must provide either the Image_Data OR the Image_Path but not both. Sateon 18 Issue 0.1

19 Example SQL statement: INSERT INTO EDS.ImportSource (Operation, ContainsToken, User_Id, ContainsImage, Image_Path) VALUES ('II', 0, 'C3E3E8C6-D828-4D26-91C7-6480E32EBDE1', 1, 'c:\myimages\joebloggs.jpg') M Modify Modifies a User (Personnel) record, including associated Token data and Image data if required. Parameters Operation User_Id User_Surname User_Firstname User_* AccessPermissions ContainsToken Token_Id Token_TokenData Token_TokenTypeId Token_TokenStatusId Token_PoolId ContainsImage Image_Data Image_Path Must be M Required, identifies the existing user/person. Required Required Any other columns in the Sateon User table can also be provided. See The ac.user table on page 14 for details of valid fields. Optional. If supplied, this identifies the access permissions of this person as a comma-separated list of AccessPermissionGroupIds. Required. If True (1) the Token record will also be modified, using the data provided in the Token_ fields. If False (0) all Token_ fields are ignored. Optional. If not supplied a new Id will be created. Required if ContainsToken is True. Required if ContainsToken is True. Required if ContainsToken is True. Required if ContainsToken is True. Optional, must be set to True (1) in order to create an image. Optional Optional Note that if adding an image you must provide either the Image_Data OR the Image_Path but not both. Sateon 19 Issue 0.1

20 Example SQL statement INSERT INTO EDS.ImportSource (Operation, ContainsToken, User_Id, User_Title, User_FirstName, User_Surname, User_EmpNumber, AccessPermissions, Token_TokenData, Token_TokenTypeId, Token_TokenStatusId, Token_PoolId, ContainsImage, Image_Path ) VALUES ('M', 1, 'C3E3E8C6-D828-4D26-91C7-6480E32EBDE1', 'Mr', John, 'Doe', 'Emp1701', '9633EC50-684E-4E8B-B817-57C0AC149D23,4CB6FA07-BDAB-43CF-880F- BF2091B0BF13', ' ', 'BB9CCCCC-8C15-4D65-8FD1-7625DFAB6A19', 'E2B2ABDF-76EE-498D FBC8D9EE9E', ' E5-421B-BC D4C00C55', 1, 'c:\myimages\joebloggs.jpg')) Note: Use the Modify command with caution. If any fields are not provided, it is assumed that these are no longer required and they are set to Null. For example, assume you have an employee, John Doe, with an employee number of If you modify this record and do not provide the User_EmpNumber in the Modify statement, the employee number will be set to null. MAPG Modify Access Permission Groups Modifies the access permissions of an existing User (Personnel) record. Parameters Operation ContainsToken User_Id AccessPermissions Must be MAPG Required; must be set to 0 (False). Required, identifies the existing user/person. Required. Defines the access permissions as a commaseparated list of AccessPermissionGroupIds. Example SQL statement: INSERT INTO EDS.ImportSource (Operation, ContainsToken, User_Id, AccessPermissions) VALUES ('MAPG', 0, 'C3E3E8C6-D828-4D26-91C7-6480E32EBDE1', '93E45B40-C733-41D4-9EF0-749A C') Sateon 20 Issue 0.1

21 MT Modify Token Modifies the Token associated with an existing User (Personnel) record. Parameters Operation ContainsToken User_Id Token_Id Token_TokenData Token_TokenTypeId Token_TokenStatusId Token_PoolId Must be MT Required; must be set to 0 (False). Required, identifies the existing user/person. Required, the new Token ID. Required Required Required Required Example SQL statement INSERT INTO EDS.ImportSource (Operation, ContainsToken, User_Id, Token_Id, Token_TokenData, Token_TokenTypeId, Token_TokenStatusId, Token_PoolId) VALUES ('MT', 0, 'C3E3E8C6-D828-4D26-91C7-6480E32EBDE1', 'C1FBD912-CED1-48E3-82BE- F20F29BC0D18', ' ', 'BB9CCCCC-8C15-4D65-8FD1-7625DFAB6A19', 'E2B2ABDF-76EE-498D FBC8D9EE9E', ' E5-421B-BC D4C00C55') MI Modify Image Modifies the Image (photo) associated with an existing User (Personnel) record. The Modify Image command will replace the existing primary image. Parameters Operation ContainsToken User_Id ContainsImage Image_Data Image_Path Must be MI Required; must be set to 0 (False). Required, identifies the existing user/person. Required. This must be set to 1 (True). The actual image as a byte array. The full path of a file identifying the image, including the file name. Sateon 21 Issue 0.1

22 Note that you must provide either the Image_Data or the Image_Path but not both. Example SQL statement: INSERT INTO EDS.ImportSource (Operation, ContainsToken, User_Id, ContainsImage, Image_Path) VALUES ('MI', 0, 'C3E3E8C6-D828-4D26-91C7-6480E32EBDE1', 1, 'c:\myimages\joebloggs.jpg') D Delete Deletes a User (Personnel) record including all attached tokens, and unlinks attached access groups. Parameters Operation ContainsToken User_Id Must be D Required; must be set to 0 (False). Required, identifies the existing user/person. Example SQL statement INSERT INTO EDS.ImportSource (Operation, ContainsToken, User_Id) VALUES ('D', 0, 'C3E3E8C6-D828-4D26-91C7-6480E32EBDE1') DT Delete Token Deletes a token. Parameters Operation ContainsToken User_Id Token_Id Must be DT Required; must be set to 0 (False). Required, identifies the existing user/person. Required, identifies the token to be deleted. Sateon 22 Issue 0.1

23 Example SQL statement INSERT INTO EDS.ImportSource (Operation, ContainsToken, User_Id, Token_Id) VALUES ('DT', 0, 'C3E3E8C6-D828-4D26-91C7-6480E32EBDE1', 'C1FBD912-CED1-48E3-82BE- F20F29BC0D18') DAPG Delete Access Permission Group Deletes the link between a User (Personnel) record and one or more access groups. Parameters Operation ContainsToken User_Id AccessPermissions Must be DAPG Required; must be set to 0 (False). Required, identifies the existing user/person. Required. The access permissions to be deleted, as a comma-separated list of AccessPermissionGroupIds. Example SQL statement INSERT INTO EDS.ImportSource (Operation, ContainsToken, User_Id, AccessPermissions) VALUES ('DAPG', 0, 'C3E3E8C6-D828-4D26-91C7-6480E32EBDE1', '93E45B40-C733-41D4-9EF0-749A C') Sateon 23 Issue 0.1

24 Section 4 Troubleshooting Editing data Although Sateon is based on Microsoft SQL Server, users should never modify the data in the databases directly. This is because each Sateon service maintains its own state and has its own data store. Whenever any change is made, a database change record is sent to each of the affected services, advising of the change, which is then processed by that service. If the Sateon database is updated directly, the database change process is bypassed, with potentially erratic results and functionality not working as expected. Grosvenor Technology reserves the right to charge for any corrections caused by databases being updated directly. Checking logs In the case of problems during operation, such as data not being imported, we recommend that you check the System Agent logs. You can configure and monitor the logs using the Sateon Real-Time Diagnostics Tool. This utility is installed as part of a standard Sateon installation and is located in the..grosvenor Technology Ltd/Sateon/Utilities folder. To set up logging using the Real-Time Diagnostics tool 1. Locate and open the Sateon Real Time Diagnostics (by default installed in Program Files (x86) Grosvenor Technology Ltd > Sateon > Utilities). 2. In the Sources pane, select the checkbox for the System Agent. Sateon 24 Issue 0.1

25 3. In Event options, select checkboxes against options that allow more detailed logging. Enable Debug Channels Enable Verbose Messages Enable Raw Exceptions Select if you want detailed Debug messages Select if you want verbose logging (more detailed messages) logging Select this if you want to display exceptions raised by Sateon. 4. Once options are set, events will appear in the main screen as they occur. When you select a specific message, more information will appear in the pane at the bottom of the page. Note: Once any issues are resolved, you can clear the Debug and Verbose checkboxes if you no longer need this level of reporting. You can also monitor the logs raised using the Windows Event Viewer (Control Panel > System and Security > Administrative Tools). Sateon 25 Issue 0.1

26 Appendix A The Database Gateway stored procedures A number of stored procedures are also provided in the Sateon database as an alternative method of using the Database Gateway. The procedures allow you to add and remove Personnel and Token objects and to manage the links between these objects. The following table summarises the available stored procedures: Stored Procedure AssignAccessPermissions CreatePersonnelAndToken CreateTokenAttachPersonnel DeletePersonnel DeletePersonnelTokensAccess DeleteToken Description Assigns access permissions to a specified personnel record. Creates personnel and token records within the Sateon database. Creates a token record within the Sateon database and associates it with a personnel record. Removes a specified personnel record from Sateon. Removes a specified personnel record from Sateon, including its associated tokens and assigned access groups. Deletes a particular token based on the token data provided. Sateon 26 Issue 0.1

27 Stored Procedure RevokeAccessPermissions ListStaticData Description Removes specific access permissions from a person Lists all the static Sateon data that can be used within the Database Gateway. Procedure eds.assignaccesspermissions This procedure assigns access permissions to a person. It uses the list of access permissions provided and assigns these to the specified User (Personnel) record. Parameters Parameter InTitle InFirstName InSurname InEmployeeNumber InAccessPermissions InAccessStart InAccessEnd Description Optional*. The title of the person (personnel record in Sateon). Optional*. The first name of the person (personnel record in Sateon). Optional*. The surname of the person (personnel record in Sateon). Optional*. The employee number of the person (personnel record in Sateon). Mandatory. A list of access permissions, separated by commas. Optional. The date and time that the access permission is to start from. Optional. The date and time that the access permission is to finish. Note: * Although individually the Title, First Name, Surname and Employee Number fields are optional, the system needs enough information to uniquely identify a Personnel record. If a record cannot be uniquely identified the procedure will fail. This occurs if no personnel record is found or if more than one matching person is found. Execute procedure Example of executing the stored procedure: = = NULL, Sateon 27 Issue 0.1

28 @InFirstname = = = = N'Sales, General = = NULL The procedure returns 0 if successful. Error messages If any errors are detected the stored procedure will not execute. The following messages will call the RaiseError SQL function and stop processing: Access Permissions are required. This error message is returned if the stored procedure is called and no access permissions are provided. Duplicate or No Personnel Record found. This error message is returned if either: No personnel record could be identified from the Title, First Name, Surname and Employee Number fields. Multiple records were identified from the Title, First Name, Surname and Employee Number fields. The stored procedure needs to be able to uniquely identify the personnel record. Procedure eds.createpersonnelandtoken This procedure creates User (Personnel) records and Token records within the Sateon database. It does the following: Creates a User (Personnel) record using the information provided. Creates a Token record, if the information has been provided, and assigns it to the Personnel record. If access information has been provided, the Access Groups provided are assigned to the personnel record. Parameters Parameter InTitle InFirstname InSurname Description Optional*. The title of the person (personnel record in Sateon). Mandatory. The first name of the person (personnel record in Sateon). Mandatory. The surname of the person (personnel record in Sateon). Sateon 28 Issue 0.1

29 Parameter InEmployeeNumber InDepartment InTokenData InTokenType InTokenPool InAccessPermissions InAccessStart InAccessEnd Description Optional*. The employee number of the person (personnel record in Sateon). Optional. The department of the person (personnel record in Sateon). Optional. The token data. If the token data is not present the token record will not be created in Sateon. Mandatory when creating a token record. This is the descriptive name for the token type. Optional. The token pool descriptive name can be provided. If not provided the Permanent Token Pool is used. Optional. A list of names of access permission names, separated by commas. There is a 2000 character limit on this field. Optional. The date and time that the access permission is to start. Optional. The date and time that the access permission is to finish. *Note: Although individually the Title and Employee Number fields are optional, the system requires enough information to uniquely identify the Personnel record. Execute procedure Example of executing the stored procedure: = = = = = = = = = = N'Sales, General Access, = = NULL The procedure returns 0 if successful. Sateon 29 Issue 0.1

30 Error messages If any messages are detected the stored procedure will not execute. The following messages will call the RaiseError SQL function and stop processing: Token Type is required. This error message is returned if the stored procedure is called and the Token Type parameter is set to null. First name is required. This error message is returned if the stored procedure is called and the First Name parameter is set to null. Surname is required. This error message is returned if the stored procedure is called and the Surname parameter is set to null. Procedure eds.createtokenattachpersonnel This procedure create a Token record within the Sateon database and allow it to be assigned to a User (Personnel) record. The procedure: Creates a User (Personnel) record using the information provided. Assigns the token to the User (Personnel) record using the information provided. Parameters Parameter InTitle InFirstname InSurname InEmployeeNumber InTokenData InTokenType InTokenPool Description Optional*. The title of the person (personnel record in Sateon). Optional*. The first name of the person (personnel record in Sateon). Optional*. The surname of the person (personnel record in Sateon). Optional*. The employee number of the person (personnel record in Sateon). Mandatory. The token data for the token that is being created. Mandatory. The descriptive name for the token type. Optional. The token pool descriptive name. If this is not provided then Permanent Token Pool will be used. *Note: Although individually the Title, First Name, Surname and Employee Number fields are optional, the system requires enough information to uniquely identify the personnel record. Sateon 30 Issue 0.1

31 Execute procedure Below is an example of how to execute the stored procedure: = = = = = = = N'iClass = NULL The procedure returns 0 if successful. Error messages If any messages are detected the stored procedure will not execute. The following messages will call the RaiseError SQL function and stop processing: Token Type is required. This error message is returned if the stored procedure is called and the token type parameter is set to null. Duplicate or No Personnel Record found. This error message is returned if the stored procedure either cannot identify the personnel record based on the parameters provided; or more than one personnel record is returned. Procedure eds.deletepersonnel This procedure removes a specific User (Personnel) record from Sateon. Parameters Parameter InTitle InFirstname InSurname InEmployeeNumber InUserIDGUID Description Optional*. The title of the person (personnel record in Sateon). Optional*. The first name of the person (personnel record in Sateon). Optional*. The surname of the p person (personnel record in Sateon). Optional*. The employee number of the person (personnel record in Sateon). Optional. The GUID that uniquely identifies the person. Sateon 31 Issue 0.1

32 The stored procedure initially attempts to identify the user from the InUserIDGUID parameter. If this is null, then a combination of the Title, First Name, Surname and Employee Number will be used. *Although individually the Title, First Name, Surname and Employee Number fields are optional, the system requires enough information to uniquely identify the Personnel record. Execute procedure Below is an example of how to execute the stored procedure: = = = = = = NULL The procedure returns 0 if successful. Error messages If any messages are detected the stored procedure will not execute. The following message will call the RaiseError SQL function and stop processing: Duplicate or No Personnel Record found. This error message is returned if the stored procedure either cannot identify the personnel record based on the parameters provided; or more than one personnel record is returned. Procedure eds.deletepersonneltokensaccess This procedure removes the User (Personnel) record from Sateon, including its access. The procedure: Deletes personnel record using the information provided. Deletes any tokens that are assigned to that personnel record Removes any access that has been granted to that personnel record. Sateon 32 Issue 0.1

33 Parameters Parameter InTitle InFirstname InSurname InEmployeeNumber InUserIDGUID Description Optional*. The title of the person (personnel record in Sateon). Optional*. The first name of the person (personnel record in Sateon). Optional*. The surname of the p person (personnel record in Sateon). Optional*. The employee number of the person (personnel record in Sateon). Optional. The GUID that uniquely identifies the person. The stored procedure initially attempts to identify the user from the InUserIDGUID parameter. If this is null, then a combination of the Title, First Name, Surname and Employee Number will be used. *Although individually the Title, First Name, Surname and Employee Number fields are optional, the system requires enough information to uniquely identify the Personnel record. Execute procedure Below is an example of how to execute the stored procedure: = = = = = = NULL The procedure returns 0 if successful. Error messages If any messages are detected the stored procedure will not execute. The following message will call the RaiseError SQL function and stop processing. Duplicate or No Personnel Record found. This error message is returned if the stored procedure either cannot identify the personnel record based on the parameters provided; or more than one personnel record is returned. Sateon 33 Issue 0.1

34 Procedure eds.deletetoken This procedure deletes a specified token based on the token data provided. Parameters Parameter InTokenData Mandatory. The token data. Description Execute procedure Below is an example of how to execute the stored procedure: = = N' ' The procedure returns 0 if successful. Error messages If any messages are detected the stored procedure will not execute. The following messages will call the RaiseError SQL function and stop processing: Token Data is required. This error message is returned if the stored procedure is called and the token data parameter is set to null. Token Data Record not found. This error message is returned if the token record within Sateon could not be found using the token data provided. Procedure eds.revokeaccesspermissions This procedure removes specific access permissions from a person. It uses the list of access permissions provided and revokes these from the specified User (Personnel) record. Parameters Parameter InTitle InFirstName InSurname Description Optional*. The title of the person (personnel record in Sateon). Optional*. The first name of the person (personnel record in Sateon). Optional*. The surname of the person (personnel record in Sateon). Sateon 34 Issue 0.1

35 Parameter InEmployeeNumber InAccessPermissions InAccessStart InAccessEnd Description Optional*. The employee number of the person (personnel record in Sateon). Mandatory. The access permissions that are to be revoked. A list of permissions separated by commas. Optional. The date and time that the access permission is to start from. Optional. The date and time that the access permission is to finish. Note: * Although individually the Title, First Name, Surname and Employee Number fields are optional, the system needs enough information to uniquely identify a Personnel record. If a record cannot be uniquely identified the procedure will fail. This occurs if no personnel record is found or if more than one matching person is found. Execute procedure Example of executing the stored procedure: = = = = = = N'Sales, General = = NULL The procedure returns 0 if successful. Error messages If any errors are detected the stored procedure will not execute. The following messages will call the RaiseError SQL function and stop processing: Access Permissions are required. This error message is returned if the stored procedure is called and no access permissions are provided. Duplicate or No Personnel Record found. This error message is returned if either: No personnel record could be identified from the Title, First Name, Surname and Employee Number fields. Multiple records were identified from the Title, First Name, Surname and Employee Number fields. The stored procedure needs to be able to uniquely identify the personnel record. Sateon 35 Issue 0.1

36 Procedure eds.liststaticdata This procedure returns a list of all the static Sateon data that can be used within the Database Gateway. This procedure can be used at any time. It runs a SELECT statement on the various Sateon objects used and displays the descriptions for each entity type. Parameters This stored procedure has no parameters. Execute procedure Below is an example of how to execute the stored procedure: = [eds].[liststaticdata] The procedure returns 0 if successful. An example of the output would be: Data Type Access Permission Group Access Permission Group Access Permission Group Department Token Pool Token Pool Token Type Token Type Error messages Description Director Sales General Access Sales Permanent Token Pool Visitor Token Pool Key fob Plastic card There are no error messages associated with this stored procedure. Sateon 36 Issue 0.1

37 Appendix B SQL Table API The Database Gateway, as described in the main part of this document, provides a simple method of importing personnel, tokens and access permission data into Sateon. For users who wish to use import data into other Sateon tables, the SQL Table API provides a comprehensive method that uses the same eds.import SQL table but allows the import of any Sateon data objects. The SQL Table API uses two tables, eds.import and eds.importresult. The normal workflow is as follows: A record is inserted into eds.import. The System Agent Service processes the row based on a polling interval. Optionally, a response will be written into the eds.importresult table. Note: The SQL API only allows the import of data. You cannot read data using this method. Format of the eds.import row The following data is required to insert an entity into Sateon: Field Format Explanation SequenceId bigint A sequential number that uniquely identifies the operation. This is allocated by the system and should not be set by the user. Sateon 37 Issue 0.1

38 Field Format Explanation JobId uniqueidentifier If specified this should be created with NewID() or other reliable method. IDs should never be reused. This is used to correlate the job with the entry in the eds.importresults table. Operation nchar(1) Must be I for Insert. This is the only operation supported. Encoding nvarchar(50) Indicates how the data payload is encoded. The only supported encoding for now is json Data nvarchar(max) The entity to be inserted. See Format of data payload (JSON) below for format. RequireResponse bit Indicates whether a results row should be placed in eds.importresult 1 for yes, 0 for no. Important: If you request a result row, you must clean the eds.importresult is table up. It is not maintained by the import service. Format of data payload (JSON) An example of a JSON formatted entity is shown below { "namespace":"accesscontrol", "type":"mode", "id":"2f5d2b79-e4ca-448a-93be-e90ef7ac6014", "securitycontextid":null, "partitionid":null, "islinkableoutsidepartition":false, "fields": { "Description":"My Test Mode", "ActiveByDefault":false, "ActivatePassword":"TurnMeOn", "DeactivatePassword":"TurnMeOff" } Note the following: In each name/value pair, the names are case-sensitive and must appear exactly as specified above. For example "namespace":"accesscontrol" is valid, while "Namespace":"AccessControl" would result in an error. Sateon 38 Issue 0.1

39 The following fields from the payload are optional: id. Only use this if you want to use your own GUID to uniquely identify the object. If this field is omitted Sateon will generate a unique GUID. securitycontextid. Use this if you need to add a specific Security Context for the object being imported. If this field is omitted then the Security Context will be set to null. partitionid. Use this if you are using a Tenanted system and you need to assign the object being imported to a Tenant (Partition). If this field is omitted then the Partition will be set to null and the object will not be assigned to a tenant. islinkableoutsidepartition. Use this if you are using a Tenanted system and the object is to be accessible outside the Tenant (Partition). If this field is omitted then it will be set to null. The fields values should be used with care. The first column must match the column name of the Sateon object or the import will be rejected. All field values for the imported object that are to be specifically set must be passed through the fields property. Any field values not specified will be given their default value as defined in the Sateon metabase. Use the column names of the database object to create the JSON formatted entry and provide the required data for the column(s). The object will be validated based on the rules defined in the meta.entityvalidations table. Any validation errors will result in the entity not being inserted. If RequireResponse is set to 1 (True), the validation results will be written to the eds.importresults table. Format of eds.importresult table If RequireResponse is set to 1 (True), a row will be written into the eds.importresult table. This will contain the following information: JobId uniqueidentifier This will match the jobid used in the eds.import table Successful int Any value greater than zero is a success Message nvarchar(max) A human readable description of any errors encountered. This field will be blank if the insert succeeded. The following are examples of failure messages: [Description : 'My Test Mode 4' : Description has already been used] Unable to validate schema of input: [ActiveByDefault : DataType_Mismatch] Sateon 39 Issue 0.1

40 Unexpected Error while processing jobid: ad44e99b-9de b0dd-b0c4ccf0bcc3 ProcessedAt datetimeoffset The time the import job was processed If RequireResponse is set to 0 (False), no entry will be made in the eds.importresult table, but errors will still be logged into the SystemAgent log file as warnings. Example import script The example below shows a script that will allow the import of a row of data into the Sateon.ac.Department table. The script has been set up to request a response from the operation. USE [Sateon] GO INSERT INTO [eds].[import] ([JobId],[Operation],[Encoding],[Data],[RequireResponse]) VALUES (NewID(),'I','json',N'{ "namespace":"accesscontrol", "type":"department", "fields": { "Name":"R&D" } }',1) Note: The N character that appears before the JSON payload is used to tell SQL Server that the subsequent string is in Unicode (the N stands for National language character set). Unicode is typically used in database applications which are designed to facilitate code pages which extend beyond the English and Western Europe code pages, for example Chinese. Sateon 40 Issue 0.1