Set up integration with UniLock

This article is valid for Smart ID 21.04 and later.

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

UniLock is an Access Control System provided by Unitek and managed by a GUI and a web service on the server. The service interacts with UniLock through a web service and with a direct connection to the UniLock database. After integration, all administration of Users, Access Token and Entitlements (besides defining them) should be done in Identity Manager, never in UniLock.

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

A user can have maximum 4 cards. If more than 4 cards are assigned, the first 4 active cards based on their accesstoken.identifier.id will be transferred, and a warning will be shown for the rest of the cards. If there is any inactive card already present in the Unilock system and Physical Access has 4 active cards, it will be replaced with the active cards.

If OnlyExportActiveCards = false and a person has less than 4 active cards and has some inactive cards, the system will transfer all active cards followed by inactive cards, maximum 4 cards will get transferred.

Prerequisites

The following prerequisites apply:

Physical Access and the UniLock Docker container/service are installed. See Deploy Smart ID.
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 UniLock Service data fields

The UniLock 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: unilock.general

key

Data type

Required or Optional

Description

updatesPerPoll

int

Optional

The maximum number of messages read from the message queue.

Default: 100

group: unilock.export

key

Data type

Required or Optional

Description

connectionString

string

Required

The connection string for the UniLock system.

Example: user id=user; password=password; server=localhost; database=unilockDB; connection timeout=30;

group: unilock.webservice

key	Data type	Required or Optional	Description
host	string	Required	The host (and possibly the port number) address to the UniLock web service
username	string	Optional	The username to use when authenticating to the UniLock web service. It is strongly recommended to use authentication.
password	string	Optional	The password to use when authenticating to the UniLock web service. It is strongly recommended to use authentication.

group: unilock.import

key	Data type	Required or Optional	Description
identificationFieldId	int	Required	The field used in UniLock to insert our identification value, that is, user.id. The value must be in range 2-14.
displayName	string	Required	Display name in UniLock. This field is used as an identifier in UniLock and contains user properties. This setting must start with a valid property name and end with a valid property name. A maximum of four properties with any number of characters in between. If the provided display name exceeds 50 characters, the display name will be adjusted to the first 50 characters. Example: “{user.id} - {user.givenname} {user.familyname}”. Note: Make sure the first 50 characters in the display name are unique otherwise the user and access token may be overwritten in UniLock.
cardDisplayName	string	Required	Holds the value of ‘key text’ field of card in UniLock. This setting must start with a valid property name and end with a valid property name. This property is type of Identifier in Access Token Identifier. A maximum of four properties with any number of characters in between. If the provided display name exceeds 50 characters, the display name will be adjusted to the first 50 characters. Example: “{layout}-{mifare}”.
cardNumberColumn	string	Required	Used to configure which Identifier of “accesstokenidentifier” table should refer to card number. Default: “mifare” column is used.
onlyExportActiveCards	bool	Required	This field is used to transfer person data based on card status and entitlements assigned. If onlyExportActiveCards is set to true then the system will transfer person only if person has at least one active card and active entitlement assigned. In case of existing person, and if all existing cards are blocked or become inactive, the system will remove person’s identity from Unilock. If onlyExportActiveCards is set to false then the system will transfer person data if card is inactive or blocked as existing functionality as it is. Default: set to false.

UniLock field mapping

The UniLock service needs a mapping for each field in Physical Access that should be transferred to UniLock. Only fields that are mapped will be transferred. The mapping must consist of an Physical Access column from User and index of the stamdata-field to use in UniLock. If the specified column does not exist or the stamdata-field index is out of range (valid range is [0, 14]) the service will stop with an error.

Example: The following mapping will map the firstname and lastname to the specified stamdata-fields in UniLock.

Id	group	index	key	system	Value
3	unilock.mappings	0	user.givenname	UniLock	0
4	unilock.mappings	0	user.familyname	UniLock	1

Card format mapping (Optional)

Unilock support card format mapping in HEX and ASCII format with card number length and format type as ‘BigEndian’ and ‘LittleEndian’ for HEX format. To use card format mapping all below fields are mandatory in configuration table (Configuration). If below settings are missing in the configuration then format type will be HEX by default without encoding card number.

key

Data type

Required or Optional

Description

cardNumberFormat

string

Required

Used to set conversion format of card number. Supported formats are HEX and ASCII.

cardNumberMaxLength

string

Required

Used to set maximum length of card number after conversion to specific format.

Default: 8 characters.

cardNumberFormatType

string

Required

Used to formatting type and holds value ‘BigEndian’ or ‘LittleEndian’ for HEX format.

Restart service

Restart the UniLock connetor service:

Restart Physical Access UniLock connector

CODE

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