Set up integration with SiPort

This article is valid for Smart ID 21.04 and later.

This article describes how to configure the SiPort Service, to enable integration between Smart ID Identity Manager, Physical Access and SiPort.

SiPort is an Access Control System provided by Siemens Software and ODBC Connectivity to interact with SiPort through the ODBC connectivity. After integration, all administration of Users, Access Token and Entitlements (besides defining them) should be done in Identity Manager, never in SiPort.

For details on which data can be imported and exported from SiPort, see About import and export to Physical Access.

Prerequisites

The following prerequisites apply:

Physical Access and SiPort Docker container/service are installed. See Deploy Smart ID.
ODBC Connectivity is required to interact with SiPort.
The message queue server must be running.
If MIFARE card technology is used, the PACS MIFARE number must be available as raw data (not encrypted, truncated, or similar).
A working network connection to the connected physical access control systems (PACS) must be in place.

Configure SiPort Service data fields

The SiPort data is configured in the configuration table in the Physical Access database. All configuration is cached when the service starts so any configuration changes will require the service to be restarted in order to take effect.

Configure database

For information about how to connect to a PACS system, see Connect to a PACS system in PACS admin panel.

For information about group: messagingqueue, see Physical Access database - common parameters.

group: general

key

Data type

Required or Optional

Description

updatesPerPoll

int

Optional

The maximum number of messages read from the message queue.

Default: 100

group: siport.general

key	Data type	Required or Optional	Description
connectionstring	string	Required	Connection string to connect to SiPort using ODBC connectivity.

Example

Id	Group	Key	system	value
1	siport.general	connectionstring	SIPORT	Data Source=server; Initial Catalog=dbname;User ID=sa;Password=changeme
2	general	updatesperpoll	SIPORT	100
3	messagingqueue	server	SIPORT	Localhost
4	messagingqueue	username	SIPORT	Guest
5	messagingqueue	password	SIPORT	Guest

group: export

key	Data type	Required or Optional	Description
TenantId	int	Required	Id of tenant which we want to use. We can find id of tenant in the Tenant table of the SiPort database.
cardNumberIdentifierTypes	string	Required	This is the type of identifier which we want to use for card number.
siPortImportTime	int	Required	`SiPortImportTime` is the time required to SiPort import process to import record send by SiPort connector. This time is in seconds. Default value is 10 seconds.
siPortDataValidation	bool	Required	`siPortDataValidation` is a flag which defines if the export process shall include an additional validation on each request to check if the data (users, access tokens and entitlements) is processed to Siport or if the data fails to sync. If data fails to sync, then the system tries to resync the data ten times. If it still fails, then the failure is logged in the `synchronizationstatus` table. If `siPortDataValidation` is set to `false`, then the system will sync data to Siport import process and skip the additional validation. If there is any error while syncing the data into Siport import process, then the system tries to resync the data ten times. If it still fails, then the failure is logged in the `synchronizationstatus` table. Default: false
userfieldmappings	string	Optional	`userfieldmappings` is the combination of all additional fields which can be sent to SiPort. Bold fields in the table below are standard columns which can be sent for each request. Other columns can be configured as additional fields. User column fields can be sent by adding the configuration `user.column_name_of_user_table, column`, as described in the table below. The value in Column Name is the name of the column in the table SIST_Pers_Import. This column name can be used for extra field configuration like `ManagerEmail`, `DATA_BirthDate`, `DATA_20_Version_VN`, `DATA_20_Sex_GS`, etc. For more information, see the SiPort import document. Before starting to configure or export additional fields, the number of exported columns must be configured with the help of SIPORT Personnel Data Import.

Columns in userfieldmappings

Here are the descriptions of the columns of userfieldmappings:

Bold fields in the table below are standard columns which can be sent for each request. Don’t use standard columns to configure additional fields. They will not be exported.

Column Name	Type	Size	Description
DATA_20_Ident_no_CN	NVARCHAR	6	Card number
DATA_20_Person_no_PN	NVARCHAR	14	Personnel number
DATA_20_Version_VN	SMALLINT		Version
DATA_20_Name_NA	NVARCHAR	30	First name
DATA_20_Surname_NA	NVARCHAR	30	Surname
DATA_20_Sex_GS	NVARCHAR	1	Gender
DATA_20_OperatorCode_BC	NVARCHAR	1	Branch code
DATA_20_OnlineProfil_P1	INT		Online profile ID
DATA_20_Validfor_D1	DATETIME		Valid from (date/time)
DATA_20_Validto_D2	DATETIME		Valid to (date/time)
DATA_20_Pincode_CO	NVARCHAR	6	PIN code
DATA_20_Stresscode_SC	BYTE		Stress code
DATA_20_Lockflag_OF	NVARCHAR	1	Block flag (empty = not locked)
DATA_20_Group1_G1	BYTE		Active pers. limiting
DATA_20_Group2_G2	BYTE		Visitor / guard card
DATA_20_Group3_G3	BYTE		Time enable
DATA_20_Group4_G4	BYTE		Terminal enabling
DATA_20_SpecialFlags_FL	BYTE		Special flags
DATA_20_DateLastBook_DO	DATETIME		Date of last card transaction
DATA_20_PortLastBook_PO	BYTE		Port of last booking
DATA_20_ReaderLastBook_RD	BYTE		Last booking at reader
DATA_20_Room_RN	SMALLINT		Room number
DATA_20_ErrorCount_ZC	SMALLINT		Error counter
DATA_20_Parking_no_PA	SMALLINT		Parking space number
DATA_30_Keygroup_TG	NVARCHAR	1	Group of keys
DATA_30_Accessright_TB	NVARCHAR	1	Keypad authorization
DATA_30_Fktkeyright_FB	NVARCHAR	1	Function key authorization
DATA_30_Mailbox_Text_MT	SMALLINT		Mailbox text
DATA_30_Free_Display_Text_FT	NVARCHAR	20	Free display text
DATA_130_Date_D4	DATUM		Date
DATA_130_Date_D5	DATUM		Date
DATA_130_Info1_I1_Balance_S1	NVARCHAR	10	Balance 1/ Information field 1
DATA_130_Info2_I2_Balance_S2	NVARCHAR	10	Balance 2 / Information field 2
DATA_130_Info3_I3_Balance_S3	NVARCHAR	10	Balance 3 / Information field 3
DATA_130_Info4_I4_Balance_S4	NVARCHAR	10	Balance 4 / Information field 4
DATA_130_Info5_I5_Balance_S5	NVARCHAR	10	Balance 5 / Information field 5
DATA_130_Info6_I6_Balance_S6	NVARCHAR	10	Vacation balance 1 / Info field 6
DATA_130_Info7_I7_Balance_S7	NVARCHAR	10	Vacation balance 2 / Info field 7
DATA_130_InfoA_IA_Balance_SA	NVARCHAR	10	Balance (flextime balance) / Info field 10
DELETED	INT		0 = Normal, -1 = deleted
TS	DATETIME		Date of last modification (updated by SIPORT when data is imported)
DATA_Title	NVARCHAR	30	Title
DATA_Rank	NVARCHAR	30	Position
DATA_BirthDate	DATETIME		Birth date
DATA_EntryDate	DATETIME		Start date
DATA_LeaveDate	DATETIME		End date
DATA_Code	NVARCHAR	30	Code
DATA_Gaz	SMALLINT		Gaz
DATA_Status	NVARCHAR	30	Status
DATA_Pictogramm	INT		Pictogram
DATA_LayoutID	INT		Layout ID
DATA_PrintData	DATETIME		Printer data
DATA_PrintVersion	SMALLINT		Printer version
DATA_PrintUser	NVARCHAR	20	Printer user
DATA_PrintStatus	INT		Printer status
Card_Type	NVARCHAR	2	Card type
Orig_Keyfield_CN_PN	NVARCHAR	14	Original key field personnel number
Orig_OnlineProfil_P1	INT		Original online profile P1
Orig_Validfor_D1	DATETIME		Originally valid from
Orig_Validto_D2	DATETIME		Originally valid to
MIFCodingDefinitionID	INT		Mifare coding definition ID
Location	NVARCHAR	255	Place
DATA_NOT_SYNC	INT		Do not load to kernel
CompanyID	INT		ID of the company
AW146_CardNumber_1	NVARCHAR	14	14-digit card number 1
AW146_CardNumber_2	NVARCHAR	14	14-digit card number 2
AW146_CardNumber_3	NVARCHAR	14	14-digit card number 3
AW146_CardNumber_4	NVARCHAR	14	14-digit card number
AW146_Mode_1	SMALLINT		Operation mode
AW146_Mode_2	SMALLINT		Operation mode
AW146_Mode_3	SMALLINT		Operation mode
AW146_Mode_4	SMALLINT		Operation mode
AW146_Flag_1	SMALLINT		0 = Only for SIPORT 256 = Use for ELD
AW146_Flag_2	SMALLINT		0 = Only for SIPORT 256 = Use for ELD
AW146_Flag_3	SMALLINT		0 = Only for SIPORT 256 = Use for ELD
AW146_Flag_4	SMALLINT		0 = Only for SIPORT 256 = Use for ELD
AW146_Data_Not_Sync_	SMALLINT		Load 14-digit card number into kernel 0 = Do not delete -1 = Delete
AW146_Data_Not_Sync_	SMALLINT		Load 14-digit card number into kernel 0 = Do not delete -1 = Delete
AW146_Data_Not_Sync_	SMALLINT		Load 14-digit card number into kernel 0 = Do not delete -1 = Delete
AW146_Data_Not_Sync_	SMALLINT		Load 14-digit card number into kernel 0 = Do not delete -1 = Delete
AW146_Deleted_1	SMALLINT		Load 14-digit card number into kernel 0 = Do not delete -1 = Delete
AW146_Deleted_2	SMALLINT		Load 14-digit card number into kernel 0 = Do not delete -1 = Delete
AW146_Deleted_3	SMALLINT		Load 14-digit card number into kernel 0 = Do not delete -1 = Delete
AW146_Deleted_4	SMALLINT		Load 14-digit card number into kernel 0 = Do not delete -1 = Delete
DATA_FreeDef1-60	NVARCHAR	255	User-defined field 1-60
Prof_DeleteAll	Number (long)	1	All existing profiles are deleted before import.
Prof_Action	NVARCHAR	1	Action performed with the profile I = Insert D = Delete U = Update
Prof_Name	NVARCHAR	400	Name of profile to be imported. More than one profile can be indicated. Separator: comma.
Prof_ValidFrom	NVARCHAR	16	Start of profile validity dd.mm.yyyy) NULL = Always valid Applies to all profiles Prof_Name
Prof_ValidTo	NVARCHAR	16	End of profile validity (format: dd.mm.yyyy) NULL = Always valid Applies to all profiles from Prof_Name
DATA_30_AS	BYTE		Attendance status
DATA_20_FreeDef_FD	NVARCHAR	10	Freely definable field
TenantID	INT		ID of the tenant
CardStatus	INT		Status of the card
DATA_30_Company_FA	NVARCHAR	32	Company
DATA_30_Firm_BT	NVARCHAR	6	Branch
DATA_30_Department_AB	NVARCHAR	8	Department
DATA_30_Cost_KS	NVARCHAR	8	Cost center

Example

Id	Group	Key	system	value
17	export	userfieldmappings	SIPORT	email.ManagerEmail,ManagerEmail
18	export	userfieldmappings	SIPORT	email.Work,Email
19	export	userfieldmappings	SIPORT	useradditionalfield.Gender, DATA_20_Sex_GS
20	export	userfieldmappings	SIPORT	useradditionalfield.Version, DATA_20_Version_VN
21	export	userfieldmappings	SIPORT	useradditionalfield.BirthDate, DATA_BirthDate
22	export	cardNumberIdentifierTypes	SIPORT	Mifare
23	export	TenantId	SIPORT	65
24	export	siPortImportTime	SIPORT	10

SiPort field mapping

The service mainly transfers user data including related access tokens and entitlement assignments. The tables below show the default field mapping.

If needed, additional fields can be configured, using the SCIM API and useradditionalfield in the database configuration.

User field mapping

By default, the following data is mapped between the USER table in the Physical Access and the SiPort service:

SR No	Physical Access field (Web API)	SiPort field (UI)
1	givenname (givenName)	FirstName
2	familyname (FamilyName)	Surname
3	Check userfieldmappings Configuration and then map actual “Email” Type(emails-type-value)	Email
4	Check userfieldmappings Configuration and then map actual ManagerEmail Type	ManagerEmail
5	Ssn (SSN Birthdate Part)	Personnel no
6	Title	Title

Access token field mapping

By default, the following data is mapped between the ACCESSTOKEN and ACCESSTOKENIDENTIFIER tables in the Physical Access and the SiPort service:

SR No	Physical Access field (Web API)	SiPort field (UI)
1	Value of Access Token Identifier which is configured in configuration setting cardNumberIdentifierTypes	14-digit badge No

Entitlement assignment field mapping

By default, the following data is mapped between the ENTITLEMENTASSIGNMENT table in the Physical Access and the SiPort service:

SR No	Physical Access field (Web API)	SiPort field (UI)
1	ExternalId (ExternalId)	ProfileID of table SIST_Prof2_XYProf
2	DisplayName (entitlement-DisplayName)	Tenant-ProfileId-Short Text

Restart service

Restart the SiPort connector service:

Restart Physical Access SiPort connector

CODE

cd <SMARTIDHOME>/compose/physicalaccess
docker-compose restart smartid-pa-siport