Export of audit trail events from Salto software. Version 2.0

Transcription

1 Export of audit trail events from Salto software Version 2.0

2 Historic of changes Version Status Date Author Change description 1.0 Stable 20/12/2011 Mikel Larreategi First version of the specs. 2.0 Stable 29/12/2011 M. L. New field added to the data model of an audit trail event, namely, OperationDescription. Table of contents 1. Introduction Overview Data model of the Salto audit trail events Audit trail operation list CSV file format Macros for time-varying file names Scheduling parameters...8 Appendix A. Data types

3 1. Introduction This document is aimed at explaining the specifications of the audit trail export tool within the Salto software. This tool allows third parties to easily access audit trail information in the form of CSV files. Note that this is not a closed document and, as such, new features will be added in so far as new necessities arise. 2. Overview Audit trail events produced by Salto access control devices are stored within the Salto DB. This information, however, cannot be directly accessed by third parties. To overcome this issue and facilitate access to audit trail information, the Salto software includes a tool for exporting audit trail events. The main characteristics of this export tool are as follows: Audit trail filter: it is possible to specify selection criteria to filter out undesired events and export only the interesting ones to the output files. For example, you may want to export audit trail events produced in a certain door or by a certain cardholder. Customised content: it is possible to customise the content of export files. For example, you may specify which of the audit trail data fields to include within the export files and which to leave out, the order of the columns, the separator character, etc. Scheduled export: it is possible to schedule an export task according to a specific date/time planning. For example, you may export audit trail events every day at 12:00. CSV file format: the export tool produces CSV files, which is a well-known format for data analysis. The following sections will explain in more details the export tool. 3. Data model of the Salto audit trail events Salto access control devices (such as standalone escutcheons and online doors) are prepared to record all the incidences regarding access control such as opening of doors and rejections. These incidences are called audit trail events. In its basic format, an audit trail event conveys information regarding who, when, where and what: who did produce the incidence? When was it produced? Where or in which door was the incidence produced? And finally, what kind of incidence was it? Was it an opening, a rejection,? Apart from this basic information, the data model of a Salto audit trail event includes further information: for example, the serial number of the card producing the event, the UTC time, some general purpose fields of the door, etc. The table below shows all the data fields a Salto audit trail events is comprised of. Note that not all these fields needs being exported but you are free to select any set of them to ultimately be included in the export file

4 Field name Type Description EventDateTime Datetime (see Appendix A) Local date/time at which the event was produced. EventDateTimeUTC Datetime Date/time at which the event was produced regarding the UTC+0 timezone. OperationID Integer Operation code (opening, rejection, etc). See Table 2 for the list of Salto event codes. IsExit Boolean In case the event is an opening, this field indicates whether it has been produced in the entry reader (0) or the exit reader (1). OperationDescription Alphanumeric Description, in English, of the audit trail operation. UserType Integer Indicates the type of user that produced the incidence: 0: cardholder. 1: door. 2: software operator. UserName Alphanumeric Textual representation of the user ID that produced the event. Its content depends on the type of user: - If UserType= 0, then UserName= name of the cardholder. - If UserType= 1, then UserName= blank. - If UserType= 2, then UserName= name of the software operator. UserExtID Alphanumeric If UserType=0, then this field contains the ExtID of the cardholder. Blank, otherwise. UserGPF1 Alphanumeric If UserType=0, then this field contains a general purpose field (#1). Blank, otherwise. UserGPF2 Alphanumeric If UserType=0, then this field contains a general purpose field (#2). Blank, otherwise. UserGPF3 Alphanumeric If UserType=0, then this field contains a general purpose field (#3). Blank, otherwise. UserGPF4 Alphanumeric If UserType=0, then this field contains a general purpose field (#4). Blank, otherwise. UserGPF5 Alphanumeric If UserType=0, then this field contains a general purpose field (#5). Blank, otherwise. UserCardSerialNumber Alphanumeric Serial number of the card. UserCardID Alphanumeric ID of the card (by defaults, equals to the card serial number). DoorName Alphanumeric Name of the door where the incidence was produced. DoorGPF1 Alphanumeric General purpose field (#1) of the door. DoorGPF2 Alphanumeric General purpose field (#2) of the door. Table 1: data model of the Salto audit trail event. See Appendix A for further information about data format. Each of these fields is explained in more details in the following paragraphs: EventDateTime: date and time when the event was produced regarding the timezone of the door. See see Appendix A for further information about how datetime data type is actually represented within the export file. EventDateTimeUTC: date and time when the event was produced regarding the UTC+0 timezone. This field must only be considered when the Salto software has been configured as having multiple timezones

5 OperationID: contains a numeric code representing the action performed on a given door. See Table 2 for the list of available operations. IsExit: certain access point devices (such as IP doors) may include up to two readers (entry and exit) both for controlling access when entering or leaving. This boolean field indicates whether the action was performed on the Entry reader (0) or on the Exit reader (1). OperationDescription: contains a description in English of the audit trail event operation or action. UserType: this field indicates the type of entity that produced the event. Three types of entity exist: cardholders (UserType=0) who produce events by means of their cards, doors (UserType=1) which produce events in an automatic fashion, for example, automatic openings and software operators (UserType=2) who produces events by means of portable programmer devices or remotely from the Salto software. UserName: textual representation of the identity of the subject who produced the event. In case the event was produced by a cardholder (UserType=0) or a software operator (UserType=2), this field contains the name of the respective entity. Otherwise, this field is blank. UserExtID: secondary user ID in alphanumeric format for integration with 3rd parties. This field is only meaningful for cardholders (UserType=0) and is blank for the rest. UserGPF1, UserGPF2, UserGPF3, UserGPF4 and UserGPF5: general purpose fields of cardholders (UserType=0). For non-cardholders this field is blank. UserCardSerialNumber: serial number of the card that produced the event. It is represented in Salto format, that is, 14-digit long hexadecimal string. For non-cardholders this field is blank. UserCardID: ID of the card whose owner produced the event. Generally, card ID equals the card serial number but in certain installations it may refer to a code stored within the card s memory. For non-cardholders this field is blank. DoorName: name of the door in which the event was produced. DoorGPF1, DoorGPF2: general purpose field of the door in which the event was produced. Note the different types of subjects capable of producing audit trail events at doors. The most obvious one is the cardholder type (UserType=0), which takes place when cards are presented at doors. However, doors themselves may automatically produce audit trail events (UserType=1), for example, when changing clock due to summer/winter daylight saving time. In this case, the UserName field is left blank. Finally, audit trail events may also be produced by software operators (UserType=2) with no card involved, either via online commands from PC or via portable programmer devices (PPD)

6 4. Audit trail operation list The following table enumerates all the possible event codes implemented by Salto access control devices. Operation Description Category 16 Door opened: inside handle Door opened: key Door opened: key and keyboard Door opened: multiple guest key Door opened: unique opening Door opened: switch Door opened: mechanical key Door opened: PPD Door opened: keyboard Door opened: spare card (hotel) Door opened: online command Door most probably opened: key and PIN Door closed: key Door closed: key and keyboard Door closed: keyboard Door closed: switch Key inserted (energy saving device) Key removed (energy saving device) Room prepared (energy saving device) Start of privacy End of privacy Start of office mode End of office mode Hotel guest cancelled Door programmed with spare key New hotel guest key Start of office mode (online) End of office mode (online) Start of forced closing (online) End of forced closing (online) Alarm: intrusion (online) Alarm: tamper (online) 8 62 Door left opened (DLO) End of DLO (door left opened) End of intrusion Start of office mode (online) End of office mode (online) End of tamper Automatic change Expiration automatically extended (offline) Online peripheral updated Key updated (online) Key deleted (online) Communication with Salto software lost Communication with Salto software established Opening not allowed: key no activated Opening not allowed: key expired Opening not allowed: key out of date Opening not allowed: key not allowed in this door Opening not allowed: out of time Opening not allowed: key does not override privacy Opening not allowed: old hotel guest key

7 89 Opening not allowed: hotel guest key cancelled Opening not allowed: antipassback Opening not allowed: no associated authorization Opening not allowed: invalid PIN Opening not allowed: door in emergency state Opening not allowed: key cancelled Opening not allowed: unique opening key already used Opening not allowed: key with old renovation number Warning: key has not been completely updated (online) Opening not allowed: run out of battery Opening not allowed: unable to audit on the key Opening not allowed: locker occupancy timeout Opening not allowed: denied by host Blacklisted key deleted Closing not allowed: door in emergency state New renovation code PPD connection Time modified (daylight saving time) Low battery level. 7 Table 2: operation codes (in decimal notation) for Salto audit trail events. Category 1: openings and closings; category 2: actions; category 3: door status changes; category 4: online commands from host; category 5: key modifications (mostly in online units); category 6: Rejections; category 7: maintenance; category 8: alarms and warnings. 5. CSV file format Currently, CSV text file is the only supported format for exporting audit trail events from the Salto DB. It is expected that, in the future, other formats will be considered, such as Excel files or DB tables. What follows are the CSV parameters to be specified within the Salto software for a correct export operation: File name: indicates the name of the file in which the exported audit trail events will be stored. It may contain special placeholders (also known as macros) in order to produce a different file name for each export file (more on this below). Column delimiter: indicates the character that will serve as a delimiter between consecutive columns within rows. It defaults to semicolon (;). Text qualifier: specifies which character mark is used to qualify text. It defaults to double quotes ( ). Column titles: indicates whether or not the first row in the export file will contain the title of the columns. It defaults to false. 6. Macros for time-varying file names In general, the Salto software does not produce a single export file but seve ral. The frequency at which these files are produced depends on the specified planning. If all the resulting files are named the same, file overwriting will occur and hence data lost. This problem can be avoided by means of macros

8 A macro is nothing more than a placeholder within the File name parameter. At export time, this placeholder is replaced by a string containing time-related information, for example, current date or time. The table below enumerates the currently supported macros: Macro ($YEAR) ($MONTH) ($DAY) ($HOUR) ($MINUTE) ($SECOND) Description Current year (4 digits). Current month (2 digits). Current day (2 digits). Current hour (2 digits). Current minute (2 digits). Current second (2 digits). Table 3: list of macros for the name of the export file. For example, the following file name contains two macros, namely, HOUR and MINUTE : Salto_Audit_Trail_($HOUR)($MINUTE).csv Let s imagine that the corresponding export task within the Salto software has been defined in such a way that produces an export file every half an hour starting from 12:00:00 till 15:00:00. This will result in six files with the following names: Salto_Audit_Trail_1200.csv, Salto_Audit_Trail_1230.csv, Salto_Audit_Trail_1300.csv, Salto_Audit_Trail_1330.csv, Salto_Audit_Trail_1400.csv, Salto_Audit_Trail_1430.csv, Salto_Audit_Trail_1500.csv. 7. Scheduling parameters Export jobs within the Salto software are executed automatically according to a pre-defined day/time scheduling. The parameters for configuring the day/time scheduling are as follows: Valid time interval: specify the time interval during which the import job is allowed to be executed. For example, no sooner than 10 AM and no later than 11 PM. Execute once: specify whether the import job should be performed just once or several times during the valid time interval in the same day. Execution time frequency: if the job is allowed to be executed several times in the same day, then this parameter specifies the time to wait for since last execution before trying again. For example, every 10 minutes. Day frequency: specify how often (in terms of days) the sync job will be executed. If this parameter is set, you need also to provide the starting date. For example, every 2 days starting from 1/1/

9 Appendix A. Data types Field values within CSV files must conform to one of the following types: Type Format Boolean The false value is represented with the zero value (e.g., 0 ). The true value is represented with any integer value different from zero (e.g., 1 for true). Integer An integer value is 4 bytes long and it ranges from to (e.g., 1234 ). Alphanumeric A string of any readable ASCII character (e.g., John Smith ). Date or Format: YYYY-MM-DDThh:mm:ss DateTime where YYYY means the year, MM the month, DD the day, hh means hours (from 0 to 24), mm the minutes and ss the seconds. The - character is used as a date separator, : as a time separator and T is the separator between date and time. E.g.: T14:45 represents May 10th 2005 at quarter to three in the afternoon. Note that time value can be omitted and it defaults to either 00:00 or 24:00 depending on whether it represents a starting date/time or an ending date/time value. Time Format: hh:mm:ss where hh are the hours (from 0 to 24), mm the minutes and ss the seconds. The : character is used as separator. E.g.: 23:30:00 represents half past eleven in the night. Table 4: format of basic data types