Cardholder data synchronization between an IDM system and Salto DB based on a staging table

Transcription

1 Cardholder data synchronization between an IDM system and Salto DB based on a staging table Document name: Salto_User_Sync_Staging_Table_1_4.doc Version: 1.4 Last updated date: 8 August 2013

2 Historic of changes Version Status Date Author Change description 0.1 Draft 26/3/2009 Mikel Larreategi 0.2 Draft 29/5/2009 Mikel Larreategi First draft. Staging table: -The ExtGroupID field is replaced by the ExtGroupIDList field, which contains a list of ExtGroupID values separated by comma. -The WiegandCode field now contain an alphanumeric value (max. 16 chars). - Title, FirstName and LastName fields: the uniqueness constraint are now removed. -The staging table may be accessed via an ODBC driver. 0.3 Draft 2/5/2011 M.L. - Cardholder data model revised and extended. Some fields have been renamed, some others added. - Some important business rules documented. - List of error codes included. 0.4 Draft 18/5/2011 M.L. Some typing mistakes fixed: - The term Group has been replaced by the term Access Level. - The size of the Title, FirstName and LastName fields have been enlarged to, respectively, 10, 40 and 40 characters. - The type of the AutoKeyEdit.ROMCode field has been changed to alphanumeric(14). - The ExtUserID field in the staging table should be unique (either as a primary key or unique index). 0.5 Draft 19/5/2011 M.L. - The size of the control field ErrorMessage has been set to Some appendixes added: ODBC data type mapping, ODBC-for-Oracle driver installation, synchronization wizard based on staging table, etc. 0.6 Draft 31/5/2011 M.L. - Appendix about ODBC driver installation modified to take into consideration 64-bit machines. 0.7 Draft 1/6/2011 M.L. - Nullability information: the cardholder data model includes information about which fields are nullable, which are not. 0.8 Stable 16/6/2011 M.L. - Missing action codes have been now included in the specs (see Table 3). 0.9 Stable 5/7/2011 M.L. - The content of the field ToBeProcessedBySalto is slightly modified: 1 indicates that the record must be processed by Salto. Any other value will leave the record unprocessed. 1.0 Stable 27/7/2011 M.L. The document mistakenly included a description of a field (namely PIN.Enabled ), which has never existed within the cardholder data model. Now, this description has been removed. 1.1 Stable 01/02/2012 X.G Added ODBC data type mapping information for Ingres within the Appendix A

3 1.2 Stable 29/10/2012 M.L. The document emphasizes the necessity of having an index on the ExtUserID column within the staging table. 1.3 Stable 10/7/2013 M. L. The size of the WiegandCode and AutoKeyEdit.ROMCode fields has been augmented to 32 characters (hex). 1.4 Stable 8/8/2013 ML Some typing mistakes fixed, mainly in the appendixes. The appendix B has been written due to the fact that the Salto service (starting from version 2.2) may run in 64-bit mode

4 Table of contents 1. Introduction Integration overview Data model of the Salto USER entity Structure of the staging table A day in the life of a sync job Error codes Appendix A. ODBC data type mapping Appendix B. ODBC-for-Oracle driver Appendix C. Creating a scheduled sync job for the staging table Introduction This document contains the specifications about synchronization of cardholder entities between an Identity Management system (IDM system herein) and the Salto access control system by means of a DB staging table. Bear in mind that this not a closed document and, as such, new features will be added in so far as new unforeseen necessities arise. 2. Integration overview There are several ways of data synchronization between two distinct systems, each way with its own trade-offs. One of the most straightforward approach consists of using an intermediary DB table known as staging table, in which the data source (i.e., the IDM system) places its data and from which the data consumer (i.e., Salto system) pulls data and transfer them to its own DB. Due to the complex business rules existing around the Salto cardholder entity, data pulling from the staging table into another part of the Salto DB cannot be implemented in the DB domain by means of triggers or stored procedures. Instead, synchronization of cardholder data must be addressed by the Salto business layer in the form of a Windows application. Consequently, data transfer to the Salto DB does not occur instantly when the IDM system places its data on the staging table. On the contrary, data transfer occurs from time to time when a background process within the Salto application (business layer) wakes up and processes any new data in the staging table. In order for the IDM system to be decoupled as much as possible from the Salto DB, the staging table must be located outside the Salto DB. The IDM system is free to use any desired RDBMS, such as Oracle or MS-SQL Server, so long as it can be accessed through ODBC interface

5 The IDM system will be responsible for both the creation and maintenance of the staging table. However, being Salto as it is the consumer of the staging table, it requires the following conditions to be fulfilled: The DB where the staging table is located must be accessible through ODBC, supported by most well known RDBM systems. Salto software must have Read/Write access privileges on the staging table. On the Salto software, a configuration wizard will be provided for setting up the DB connection parameters and for data mapping between fields in the staging table and attributes in the Salto data model. The following sections explain in detail the data model for the Salto user entity (or cardholder) and the structure of the staging table. 3. Data model of the Salto USER entity The table below represents the data model for a Salto cardholder. Note that the staging table is not required to include all of the attributes declared in the user data model but only a set of them. Attributes that are not included in the staging table will be left untouched in the Salto DB (when updating an existing record) or will be initialized with a default value (when inserting a new record). Field name ExtUserID FirstName LastName Title Office Privacy AuditOpenings ExtendedOpeningTime Antipassback CalendarID GPF1 GPF2 GPF3 GPF4 GPF5 ExtAccessLevelIDList Type (ODBC) See Appendix A Alphanumeric(32) Alphanumeric(40) Alphanumeric(40) Alphanumeric(10) Boolean (SQL_BIT) Boolean (SQL_BIT) Boolean (SQL_BIT) Boolean (SQL_BIT) Boolean (SQL_BIT) Integer (SQL_INTEGER) Alphanumeric(32) Alphanumeric(32) Alphanumeric(32) Alphanumeric(32) Alphanumeric(32) Alphanumeric(1024). Each ID is Alphanumeric(32). Description Default on insert Nullable User s (cardholder) unique ID No value. First name of the SALTO user. Null Yes Last name of the SALTO user. Null Yes Title of the SALTO user. Null Yes Put door in office mode 0 No (permanently opened). Override door s privacy 0 No Enable opening events storage within the user s key. 0 No Extended opening time for 0 No disabled people (ADA). Enable antipassback within the 0 No user s key. Code of the calendar to be used 0 Yes by the user. General purpose field #1. Null Yes General purpose field #2. Null Yes General purpose field #3. Null Yes General purpose field #4. Null Yes General purpose field #5. Null Yes List of access level IDs the cardholder belongs to and from which access rights are inherited. KU Null Yes - 5 -

6 AutoKeyEdit.ROMCode UserActivation UserExpiration.ExpDate ShortTermKeyExpiration. Period ShortTermKeyExpiration. UnitOfPeriod PIN.Code WiegandCode NewKeyIsCancellable ThroughBL Alphanumeric(32) DateTime (SQL_TIMESTAMP) DateTime (SQL_TIMESTAMP) Integer (SQL_INTEGER) Integer (SQL_INTEGER) Alphanumeric(8) Alphanumeric(32) Boolean (SQL_BIT) Serial number of the key to be automatically issued when presented at an online key updater. Starting date of the user. Long term expiration date of the user data. Indicates the period in days for key expiration when being updated/revalidated. Indicates the type of time unit for the above Period parameter: 0=Days, 1=Hours. Customised PIN code to be written on the key. Wiegand code to be written on/read from user cards. Indicates whether or not the key to be encoded will be cancellable through black list. Null Yes (Current date) No (Current Yes date + 1 month) 30 Yes 0 Yes Null Yes Null Yes 1 No Table 1: data model for the Salto user entity. = unique value key; KU = user s Key requires being Updated if the field is modified. In the following paragraphs, each of the fields within the user data model is explained: ExtUserID: this is an alphanumeric ID that uniquely identifies a Salto cardholder. Title, FirstName, LastName: these fields are used for showing user entities within SALTO GUI applications or reports. Office: if true it means that the user will be capable of setting certain doors in office mode (permanently opened). It defaults to 0 (false). AuditOpenings: if enabled (=1) then openings produced by the cardholder are registered within the card memory. ExtendedOpeningTime: extended opening time for people with discapacity. If true, doors accessed by the user will be kept opened longer time than usual. It defaults to 0 (false). General purpose fields GPF1,, GPF5: these three fields may contain any alphanumeric data. CalendarID: this field contains the ID of the calendar to be used by the cardholder. ExtAccessLevelIDList: list of access level IDs the cardholder belongs to and from which access permissions are inherited. Access level IDs are written in a CSV format: use comma as a separator between two groups; use double apostrophe ( ) to qualify a group ID containing blank spaces; blank spaces are removed unless included within two apostrophes. AutoKeyEdit.ROMCode: serial number of the card to be automatically issued when the user presents it at an online key updater. If a null (blank) value is specified, this feature is disabled. Note that this field must contain a unique value, in other words, if the same serial number is assigned to different users, an exception will be raised. UserActivation: indicate the starting date/time of the user s data and access permissions. It defaults to the current date

7 UserExpiration.ExpDate: this field contains a long-term expiration date for the cardholder s data and access permissions. It represents a maximum limit in that keys assigned to the user will never exceed this date. A null value in this field will make the cardholder be non-expirable. ShortTermKeyExpiration.Period: actually, there are two expiration values to take into account. On the one hand, the expiration of the user (represented by the field UserExpiration.ExpDate explained above) and, on the other hand, the actual expiration written on the cardholder s current key, also known as short-term key expiration. In general, cardholders will have got a long-term expiration. However, for the sake of security, it is desirable to restrict the actual expiration of the key to a short-term value. In this way, the system is less vulnerable since lost or stolen keys are supposed to expire soon. When keys get expired, they can have their expiration extended by means of online key updater. In order to enable short-term key expiration (mostly recommended), the field ShortTermKeyExpiration.Period must contain a non-null value: as a result, when the key is placed on an online key updater, its expiration will be extended up to the number of days (or hours, depending on the type of period, see below) specified in this field. KeyRevalidation.UpdatePeriod: if short-term key expiration is enabled (KeyExpirationDifferentFromUserExpiration=1), the new key expiration after revalidation will depend on this value. Antipassback: enable/disable the antipassback feature within the key. Privacy: if this feature is enabled, the user will be capable of overriding privacy in hotel rooms. PIN.Code: apart from the validity of the card and as an additional security feature, certain doors may require a valid PIN code to be typed (on an adjacent keypad) in order to allow access. In this regards, this field contains the cardholder s PIN that must be typed when accessing doors. If no value is specified (empty or null field), no PIN will be required. WiegandCode: some third party systems require a custom code in Wiegand format to be written on/read from user s cards. ExtAccessLevelIDList: contains a list of access level IDs (ExtAccessLevelID) to which the user belongs to. Since it is a multiple-value field (more on this later), each value within the list must be delimited by a separator. NewKeyIsCancellableThroughBL: indicates whether the key assigned to the user can be cancelled through black list. The black list is an internal mechanism used by Salto to make issued keys stop working at standalone or offline locks (should the user s key gets lost or stolen). Note that the black list mechanism is not needed for invalidating keys at online update readers. If this field is True (blacklistable), the next issued key for the user will be cancellable through black list at both offline and online locks; on the contrary, if this field is False, the next issued key will be cancellable at online devices only, such as Salto encoders or Cus, but not at offline locks. There are several considerations to take into account regarding this field: 1) Bear in mind that you may issue up to blacklistable keys, whereas there is no limit for the number of non-blacklistable keys. 2) This field cannot be changed while the user has got a key assigned. You - 7 -

8 must cancel or erase the key first. 3) For the sake of security, if this field is set to false, then it is not allowed to issue a key whose expiration date is too long (one week maximum). The best practice is to use short expiration dates for keys (see the ShortTermKeyExpiration.UpdatePeriod field) and force cardholders to update their key at online update readers frequently. Note that changing certain fields within the user data model may imply the user s current card (if any) to be re-encoded or updated at an online card updater for the modifications to take effect (see column KU in the user data model table). For example, if you change the expiration date for a given user (UserExpiration. ExpDate), most probably her card will need to be re-encoded. The following business rules must be taken into consideration when generating user data in import/synchronization files: The user ID ExtUserID must be unique along the whole SALTO DB. If you try to create two users with the same ExtUserID, an exception would be returned. Apart from ExtUserID, there exists another type of unique ID known as SaltoUserID, which is used by Salto to represent and show cardholders in the Salto software s GUI, windows and reports. By default, SaltoUserID corresponds to the cardholser s name, that is, SaltoUserID= title + first name + last name. Thus, in principle, no more than one cardholder with the same name must exist within the SALTO DB. However, it is possible to avoid this restriction by configuring (within the Salto software) the SaltoUserID with a different set of fields (e.g., SaltoUserID=ExtUserID). A given expirable key will never exceed the expiration date of the user it belongs to. In other words, you may set a very large value in the ShortTermKeyExpiration.PeriodInDays field. However, when it comes to update a key in an online key updater, the new key expiration will be truncated to that of the user expiration if the following condition holds true: CurrentDate+ShortermKeyExpiration.PeriodInDays> UserExpiration.ExpDate The zero-day period in the ShortTermKeyExpiration.PeriodInDays field has got a special meaning: it indicates that the actual key expiration will be set to the midnight of the current date (24:00H). A given user with no expiration and no short-term key expiration must use calendar ID 0. It is not allowed to modify the NewKeyIsCancellableThroughBL field while the user has got a valid key assigned (error code=208). In case the NewKeyIsCancellableThroughBL is disabled, it is not allowed to issue a key whose expiration is longer than 7 days (this limit can even be configured in the Salto software to a lower value). Regarding the ExtAccessLevelIDList field, all the specified access levels within the list must belong to the same department as that of the user s. Regarding the AutoKeyEdit.ROMCode field, it is not allowed to assign the same card serial number to more than one user

9 4. Structure of the staging table Basically, the staging table contains two kinds of field, namely, data fields and control fields. Data fields correspond to the attributes of the Salto cardholder data model (as shown in Table 1). Values placed in data fields are eventually transferred to the Salto DB. On the other hand, control fields indicate how data is to be processed (or was processed) by Salto. The table below enumerates the control fields within the staging table: Field name Type (ODBC) Description Written by Nullable Action Integer (SQL_INTEGER) Action to be performed on the Salto DB. See Table 3. IDM No (Salto cardholder data model) ToBeProcessedBySalto ProcessedDateTime ErrorCode ErrorMessage Integer (SQL_INTEGER) Datetime (SQL_TIMESTAMP) Integer (SQL_INTEGER) Alphanumeric(512) Data fields corresponding to the data model of the Salto cardholder entity (see table 1). Indicates whether the record has already been processed by Salto (=0) or still remains unprocessed (= 1). Date and time when the record was last processed. Resulting error code after processing the record. Descriptive message about the error, if any. Table 2: control fields for managing data synchronization. IDM IDM & Salto Salto Salto Salto See table 1 Yes Yes Yes Yes The following paragraphs explain the meaning of each control field: Action: indicate the DB operation to be performed on the Salto DB regarding the cardholder record. Supported actions are enumerated in Table 3, the most common of which are: 3, transferring the user record from the staging table to the Salto DB, either by inserting a new record or updating an existing one; 4, delete the corresponding user record from the Salto DB. This field is updated by the IDM system. If the Action field does not exist in the staging table, then Salto will assume a default value of 3 (update existing cardholder record if exists, create new one otherwise). Code Action 1 Create new record. 2 Update existing record. 3 Update record if exists, create new one otherwise. 4 Delete existing record. 8 Cancel key Table 3: action codes for the action field

10 ToBeProcessedBySalto: this field indicates whether the record has already been processed by Salto (=0) or is still to be processed (=1). The IDM system must set this field to 1 when placing new data in the record whereas Salto must reset it after processing the record. If the IDM system sets this field to any other value than 1, the record will remain unprocessed. ProcessedDateTime: contains a date/time value that indicates when the record has been processed by Salto. This field is updated by Salto. ErrorCode: contains an error code produced while processing the record (0= no error). This field is updated by Salto. ErrorMessage: contains an error message describing the error (if any) that was produced by Salto while processing the record. This field is updated by Salto. Note that the ExtUserID field and all the control fields (except Action) must exist within the staging table. The rest of the fields are optional. IMPORTANT: the ExtUserID field within the staging table must be unique and its access time as fast as possible. These two requirements are fulfilled either by declaring the ExtUserID column as being the primary key or by assigning it a unique index. 5. A day in the life of a sync job The IDM system is responsible for feeding the staging table with appropriate cardholder data. It must make sure that, on updating or inserting new cardholder data, the new records (or updated ones) are marked as unprocessed (ToBeProcessedBySalto <> 0). Once processed by Salto, the IDM system is free to remove the processed records (those having ToBeProcessedBySalto=0) from the staging table. What follows are the basic steps performed by the business layer within the Salto software: From time to time, the SALTO software will wake up and check whether the time has come for a sync job to be executed according to a predefined day/time scheduling configuration. If the time has arrived, the sync job is considered to be active and the actions below will be carried out. Within the sync job, the SALTO software establishes a connection to the DB where the staging table is located and retrieves those records marked as not being processed (ToBeProcessedBySalto <> 0). For every record in the set, Salto performs the DB operation as specified in the Action field (in case the Action field is missing, it will default to 3, that is, insert or update). Once the DB operation is performed, Salto marks the record as being processed (ToBeProcessedBySalto=0). Additionally, Salto stores error information (ErrorCode and ErrorMessage) and the current date/time (ProcessedDateTime= current date). Finally, once that all the records are processed, the sync job falls asleep until the next scheduled activation time, when the whole cycle starts again

11 6. Error codes As for the error codes, the following codes are contemplated: Error code Description 0 No error. 1 DB connection error. This occurs when the SALTO software can not establish a connection to its own DB. 202 User with the same ID already exists. This occurs when trying to add a new user whose ID is already in use by another user within the same SALTO DB. 203 User with the same name already exists. This occurs when trying to add a new user whose name is already in use by another user within the same SALTO DB. 204 User not found. This occurs when trying to update a specified user that does not exist in the SALTO DB. 205 Access level not found. This occurs, for example, when you specify that a user should belong to a non-existing access level. 206 Card serial number already in used. The card serial number (ROM code) cannot be assigned to the user because it is already in use by another user. 207 User cannot belong to the specified access levels. This occurs when the access levels to which the user must belong are not valid (for example, they belong to a different department from that of the user s). 208 The change is not allowed because the user has already got a key assigned. If the user has already got a key encoded then it is not allowed to modify the NewKeyIsCancellableThroughBL field. 209 Key expiration exceeds the maximum allowed for a non-cancellable key. This error occurs when the NewKeyIsCancellableThroughBL is disabled and the key s new expiration exceeds the maximum allowed for a non-cancellable key. 503 Invalid data format. This occurs when a value within a given column does not conform to the specifications. For example, when an integer value is expected but an alphanumeric character is found. 601 Missing column. This occurs when a specified column does not exist within a given record. 604 Action not supported. This occurs when specifying an action code that is not supported. 605 Null value assigned to a non-nullable field. This occurs when a null value is assigned to a non-nullable data field. 999 General error. An error has occurred unexpectedly or does not correspond to any of the above enumerated error codes. Table 4: list of error codes

12 Appendix A. ODBC data type mapping The following table shows a mapping between the ODBC data types and several RDBM systems. ODBC SQLServer 2000, 2005 Oracle 11g Ingres SQL_BIGINT bigint NUMBER(19,0) BIGINT (Integer8) SQL_BINARY binary, timestamp RAW BYTE SQL_BIT Bit NUMBER(3) BOOLEAN SQL_CHAR Char CHAR CHAR SQL_DECIMAL decimal, money, smallmoney NUMBER DECIMAL SQL_DOUBLE Float FLOAT(53) FLOAT SQL_FLOAT Float FLOAT(53) FLOAT SQL_GUID Uniqueidentifier CHAR(36) CHAR(36) SQL_INTEGER Int NUMBER(10) INTEGER (Integer4) SQL_LONGVARBINARY image, varbinary(max) LONG RAW LONG BYTE SQL_LONGVARCHAR text, varchar(max) LONG LONG VARCHAR SQL_NUMERIC Numeric NUMBER DECIMAL SQL_REAL Real FLOAT(24) REAL SQL_SMALLINT Smallint NUMBER(5) SMALLINT (Integer2) SQL_TINYINT Tinyint NUMBER(3) INTEGER1 (Integer1) SQL_DATE Datetime DATE ANSIDATE SQL_TIMESTAMP Datetime, smalldatetime TIMESTAMP, INGRESDATE DATE SQL_VARBINARY Varbinary RAW BYTE VARYING SQL_VARCHAR Varchar VARCHAR2 LONG VARCHAR SQL_WCHAR NChar NCHAR NCHAR SQL_WLONGVARBINARY NText, NVarchar(max) LONG LONG NVARCHAR SQL_WVARCHAR NVarchar NVARCHAR2 NVARCHAR Table 5: data type mapping between ODBC and some RDBM systems. An example of a SQL script for creating a staging table in an Oracle DB is as follows (note that there is no need to include all the columns, only the ones that are really necessary for your installation): CREATE TABLE SaltoCardholdersOracle( Action NUMBER(10) DEFAULT 3 NOT NULL, ExtUserID VARCHAR2(32) NOT NULL, FirstName VARCHAR2(40) NULL, LastName VARCHAR2(40) NULL, Title VARCHAR2(10) NULL, Office NUMBER(3) DEFAULT 0 NOT NULL, Privacy NUMBER(3) DEFAULT 0 NOT NULL, AuditOpenings NUMBER(3) DEFAULT 0 NOT NULL, ExtendedOpeningTime NUMBER(3) DEFAULT 0 NOT NULL, Antipassback NUMBER(3) DEFAULT 0 NOT NULL, CalendarID NUMBER(10) DEFAULT 0 NULL, GPF1 VARCHAR2(32) NULL, GPF2 VARCHAR2(32) NULL, GPF3 VARCHAR2(32) NULL, GPF4 VARCHAR2(32) NULL, GPF5 VARCHAR2(32) NULL, ExtAccessLevelIDList VARCHAR2(1024) NULL, "AutoKeyEdit.ROMCode" VARCHAR2(32) NULL, UserActivation TIMESTAMP NOT NULL, "UserExpiration.ExpDate" TIMESTAMP NULL, "STKE.Period" NUMBER(10) DEFAULT 30 NULL,

13 "STKE.UnitOfPeriod" NUMBER(10) DEFAULT 0 NULL, "PIN.Code" VARCHAR2(8) NULL, WiegandCode VARCHAR2(32) NULL, NewKeyIsCancellableThroughBL NUMBER(3) DEFAULT 1 NOT NULL, ToBeProcessedBySalto NUMBER(3) DEFAULT 1 NOT NULL, ProcessedDateTime TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL, ErrorCode NUMBER(10) DEFAULT 0 NOT NULL, ErrorMessage VARCHAR2(512) NULL, CONSTRAINT SaltoCardholders_PK PRIMARY KEY (ExtUserID)) The same example but for a SQLServer DB is as follows: CREATE TABLE SaltoCardholdersSQLServer( Action INT NOT NULL DEFAULT 3, ExtUserID NVARCHAR(32) NOT NULL, FirstName NVARCHAR(40) NULL, LastName NVARCHAR(40) NULL, Title NVARCHAR(10) NULL, Office BIT NOT NULL DEFAULT 0, Privacy BIT NOT NULL DEFAULT 0, AuditOpenings BIT NOT NULL DEFAULT 0, ExtendedOpeningTime BIT NOT NULL DEFAULT 0, Antipassback BIT NOT NULL DEFAULT 0, CalendarID INT NULL DEFAULT 0, GPF1 NVARCHAR(32) NULL, GPF2 NVARCHAR(32) NULL, GPF3 NVARCHAR(32) NULL, GPF4 NVARCHAR(32) NULL, GPF5 NVARCHAR(32) NULL, ExtAccessLevelIDList NVARCHAR(1024) NULL, [AutoKeyEdit.ROMCode] VARCHAR(32) NULL, UserActivation DATETIME NOT NULL, [UserExpiration.ExpDate] DATETIME NULL, [STKE.Period] INT NULL DEFAULT 30, [STKE.UnitOfPeriod] INT NULL DEFAULT 0, [PIN.Code] VARCHAR(8) NULL, WiegandCode VARCHAR(32) NULL, NewKeyIsCancellableThroughBL BIT NOT NULL DEFAULT 1, ToBeProcessedBySalto INT NOT NULL DEFAULT 1, ProcessedDateTime DATETIME NOT NULL DEFAULT GetDate(), ErrorCode INT NOT NULL DEFAULT 0, ErrorMessage NVARCHAR(512) NULL, CONSTRAINT SaltoCardholders_PK PRIMARY KEY (ExtUserID))

14 Appendix B. ODBC-for-Oracle driver The staging table may be hosted within an Oracle DB. For such purpose, however, the Salto server machine must have an appropriate ODBC-for-Oracle driver installed. Important: starting from version 2.2, the Salto service (which is a.net application) can run both in 32 or 64-bit mode, depending on the Windows operative system. If Windows is 64-bit then the Salto service will run in 64-bit mode, 32-bit otherwise. Thus, the type of ODBC driver installed in the system must be also in accordance with the system: for a 64-bit Windows, you must install a 64-bit ODBC driver, 32- bit otherwise. One way to know whether the appropriate Oracle driver is installed or not is by exploring the list of drivers shown in the ODBC data source administrator utility (see picture below). This utility can be opened by double-clicking the control panel\administrative tools\odbc data source applet. The picture below, for example, shows that the machine contains an ODBC driver for Oracle 11. Note, however, that each Oracle version/release may require its own driver. In case the appropriate Oracle driver is not found on the list, you should go to the Oracle s web site to learn how to install the one required. There are several ways

15 One possible way is as follows (this example assumes Oracle 11g R2 and a 32-bit Windows machine): Go to the Oracle web site and download the appropriate Oracle Instant Client Libraries depending on the desired Oracle version/release. In this example, we have selected the following the Win32 client libraries for Oracle version 11g R2 (in zip format): instantclient-basic-nt zip and instantclient-odbc-nt zip. Unzip both zip files to the same folder, one of your choice, for example, C:\Oracle\instantclient_11_2. Execute the odbc_install script. After execution, the Oracle Instant Client folder (present folder) name will be part of the driver name in registry. In this case, driver name will be "Oracle in instantclient_11_2". After the installation the environment needs to be configured in the following way: (1) add the folder to the PATH system environment variable, otherwise ODBC manager will be not able to load/find the driver; (2) define the TNS_ADMIN system environment variable to point the.ora files folder

16 Cardholder synchronization based on staging table

17 Appendix C. Creating a scheduled sync job for the staging table This section explains how to create a scheduled job for cardholder synchronization based on a staging table. The Salto desktop software is assumed to be version 10.3.X or similar. The first thing to do is to open the Scheduled job list window (tools\scheduled jobs), which shows all the currently defined jobs. These jobs are executed in the background by the Salto service according to a predefined date/time planning. There are several types of job, such as audit trail purgation, Salto DB backup and cardholder synchronization. Some of them are automatically created by the software and cannot be removed (e.g., DB backup). Some others (such as synchronization jobs) are created manually on demand. By clicking the New button, a wizard is shown, which will guide you towards the creation of a new synchronization job (see picture below)

18 Basically, this wizard is comprised of three steps: (1) data source specification, (2) data mapping between columns in the staging table and the Salto cardholder data model and, finally, (3) date/time scheduling. Data source parameters Data source indicates where the data to be synchronised comes from. Currently, two types of source are supported: CSV text file and DB (staging) table. In this section, the DB staging table will be explained. The parameters to be defined for accessing data stored in a given DB are as follows: DB data source: indicates the type of DB where the staging table is stored. Currently supported DBs are Oracle and Microsoft s SQLServer. Additionally, you may choose an ODBC data source defined in the system (see the Control panel\administrative tools\odbc data source applet). Note that, irrespectively of the selected data source, the Salto software always uses ODBC to access the staging table. Connection parameters: these are used for establishing a connection to the actual DB. The actual set of parameters depends on the selected DB type. Name of the staging table. Miscellaneous: character to be used as separator within the ExtAccessLevelIDList field

19 The following two pictures show connection parameters for the ODBC data source

20 The following two pictures show the connection parameters for Orace data source

21 The following picture shows some miscellaneous parameters, such as the name of the staging table and the separator character for the ExtAccessLevelIDList field: Mapping between columns and data model The second step of the wizard consists of mapping the columns in the staging table with the corresponding fields in the cardholder data model as defined in section 3. This mapping is based on the columns position rather than on the columns name: for each column position (starting from 1), you must indicate whether or not the column is associated with a cardholder field and, if so, which field. For example, let s assume that the schema of a staging table in an Oracle DB is as follows: CREATE TABLE StagingTable( ActionField NUMBER(10) DEFAULT 3, DummyField_1 VARCHAR2(40), ExtUserIDField VARCHAR2(32) NOT NULL, DummyField_2 VARCHAR2(40), FirstNameField VARCHAR2(40), LastNameField VARCHAR2(40), DummyField_3 VARCHAR2(40), ToBeProcessedBySaltoField NUMBER(3) DEFAULT 1, ProcessedDateTimeField TIMESTAMP DEFAULT CURRENT_TIMESTAMP, ErrorCodeField NUMBER(10) DEFAULT 0, ErrorMessageField VARCHAR2(512), CONSTRAINT MIKEL3_SALTOUSERS_PK PRIMARY KEY (ExtUserIDField));

22 The mapping for this staging table will be as follows: Position of the staging table column Cardholder field to which the column is mapped. 1 Action 2 N/A 3 ExtUserID 4 N/A 5 FirstName 6 LastName 7 N/A 8 ToBeProcessedBySalto 9 ProcessedDateTime 10 ErrorCode 11 ErrorMessage In the wizard, this mapping will be expressed as follows: Date/time schedule parameters In the last step of the wizard, you must specify when and how often the synchronization job will be executed

23 Cardholder synchronization based on staging table

24 Finally, the wizard will show a summary of all the specified synchronization parameters, which you may confirm or, if wrong, correct by moving backward. Each time the job is executed, an event is recorded in the Salto auditor table (see tools\auditor )