Set up integration with Bewator Omnis

This article is valid for Smart ID 21.04 and later.

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

Bewator Omnis is an Access Control System provided by Vanderbilt and managed by a GUI and API to interact with Bewator Omnis through the OmnisAPI.DLL. After integration, all administration of Users, Access Token and Entitlements (besides defining them) should be done in Identity Manager, never in Bewator.

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

Prerequisites

The following prerequisites apply:

Physical Access and the Bewator Omnis Docker container/service are installed. See Deploy Smart ID.
Bewator Omnis server version 6.2.110 or newer is required. The Omnis API (DLL) version 2.2 is required to interact with Bewator Omnis.
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.

Install IIS web server

To host the Bewator Omnis Web Service on the Omnis Server, an IIS server must be installed.

If an IIS server is not installed, then follow Step 1 in https://docs.microsoft.com/en-us/iis/manage/creating-websites/scenario-build-a-static-website-on-iis. to install it.
Host the web service /BewatorOmnisWebService/, according to Step 2 in the lsam article.
Verify that the web service is hosted correctly, by browsing to the URL:
Example: Bewator Omnis web service URL

CODE
```
http://localhost:<port>/BewatorOmnisWebService.asmx
```
Configure the following parameters in the web service configuration file \BewatorOmnisWebService\Web.Config:

key	Data type	Required or Optional	Description
omnisip	string	Required	The `omnisip` is the IP address of Omnis Bewator server where application has been installed.
omnisport	int	Required	The port number where Omnis Bewator server is listening. You can find this in the Omnis application at File > Setting > System Setting in the tab connection TCP/IP-port for the BAPSI-protocols.
Omnisidentifier	string	Required	The Omnis Identifier is a unique identifier which is generated when we install Bewator Omnis and add license key. This identifier is required to connect API to the Omnis Server. You find this identifier at File > Person Registry > Administration tab > External Connection. Double click on the external connection and a popup will appear. In this popup we will get the Identifier.

Configure Bewator Omnis Service data fields

The Bewator Omnis 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: BewatorOmnis

key Data type Required or Optional Description

OmnisWebServiceUrl

string

Required

This is the URL of the OmnisWebService hosted on the Omnis Server.

Example: http://localhost:/BewatorOmnisWebService.asmx

cardnumberpaddinglength

int

Required

This is a default setting which indicates max length of Access Token number and if number is less than 16 then prepend 0 (zero) to that number. For example, If access token is 1234567 and cardnumberpaddinglength is 10 then access token number will look like this 0001234567.

identifiertype

string

Required

Identifier type is the type of identifier which decides which identifier of access token use for access token number.

accessgroupdelimiter

string

Required

Access group delimiter is used to concatenate organization id and department id and same for name of entitlements like 1-2 and My organization – Department.

homeorganization string Required Home Organization is the organization in Bewator Omnis. Home organization is used while creating users.

entitlementimporttype

string

Required

This type is use to set structure of import and export. Possible values are listed in the following table:

import type	Description
Department	Used to manage entitlements as a combination of Organization and Department, while ignoring import of access groups. During export, only the Department entitlement type will be exported. If the entitlement type is not Department, and the entitlement exists in Omnis, then it will be removed from that user.
Organization	Used to manage entitlements by Organization only, while ignoring import of access groups and departments. During export, only the Organization entitlement type will be exported. If the entitlement type is not Organization, and the entitlement exists in Omnis, then it will be removed from that user.
AccessGroup	Used to manage entitlements by AccessGroup only, while ignoring import of organizations and departments. During export, only the AccessGroup entitlement type will be exported. If the entitlement type is not Accessgroup, end the entitlement exists in Omnis, then it will be removed from that user.
AccessGroupDepartment	Used to manage entitlements as a combination of AccessGroup and Department, while ignoring import of organizations. During export, both the AccessGroup and Department entitlement type will be exported. If the entitlement type is not AccessGroup or Department, and the entitlement exists in Omnis, then it will be removed from that user.
AccessGroupOrganization	Used to manage entitlements as a combination of AccessGroup and Organization, while ignoring import of departments. During export, both the AccessGroup and Organization entitlement type will be exported. If the entitlement type is not AccessGroup or Organization, and the entitlement exists in Omnis, then it will be removed from that user.

Example

Id	Group	Key	system	value
1	general	updatesperpoll	BewatorOmnis	100
2	BewatorOmnis	deletepersononnoaccess	BewatorOmnis	false
3	BewatorOmnis	cardnumberpaddinglength	BewatorOmnis	16
4	BewatorOmnis	identifiertype	BewatorOmnis	mifare
5	BewatorOmnis	accessgroupdelimiter	BewatorOmnis	-
6	BewatorOmnis	homeorganization	BewatorOmnis	Home Organization

group: omnis.export

key Data type Required or Optional Description

userfieldmappings

string

Optional

The userfieldmappings is the combination of all additional fields which we can send to Bewator Omnis. Currently, we can configure fields (Address, Email, PhoneHome, PhoneMobile, PhoneOffice and Remark) of Omnis. To export these fields to Omnis, we need to do the following configuration.

The value in configuration setting is a combination of table_name.value_of_type_column,field_name_of_omnis. This configuration setting is the mapping between the Physical Access table field and the Omnis field. We can send user column fields by adding configuration like user.column_name,omnis_field_name.

Example

The following is an example of userfieldmapping:

Id	Group	Index	Key	system	value
14	omnis.export	1	userfieldmappings	BewatorOmnis	phone.mobile,PhoneMobile
15	omnis.export	1	userfieldmappings	BewatorOmnis	Address.work,Address
16	omnis.export	1	userfieldmappings	BewatorOmnis	Email.work,Email
20	omnis.export	1	userfieldmappings	BewatorOmnis	phone.home,PhoneHome
21	omnis.export	1	userfieldmappings	BewatorOmnis	phone.office,PhoneOffice
22	omnis.export	1	userfieldmappings	BewatorOmnis	useradditionalfield.remark,Remark

Bewator Omnis 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 Bewator Omnis service:

SR No	Physical Access field (Web API)	Bewator Omnis field (UI)
1	Service Configuration (homeorganization)	Organization (Organization directory on UI)
2	givenname (givenName)	givenname (givenName)
3	familyname (FamilyName)	LastName (Sirname)
4	pin (Pin)	PIN (PIN)
5	validto (ValidTo)	validTo (Time limit access To)

Access token field mapping

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

SR No	Physical Access field (Web API)	Bewator Omnis field (UI)
1	CardNumber (identifiers-type-value)	CardCode (Kortnummer)
2	assigneeId(assignee)	AssignedPersonId (User)
3	As per ValidTo and Status of Card	Status (Status)

Entitlement assignment field mapping

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

SR No	Physical Access field (Web API)	Bewator Omnis field (UI)
1	assigneeid (assignee -value)	ExternalId (Selected User Name)
2	Entitlement.ExternalId (First part before Group delimitator)	Organization (Organization)
3	Entitlement.ExternalId (Second part after Group delimitator)	Department (Department)
4	Entitlement.EntitlementType	Used to set type of structure we want to use to import and export entitlement assignment.

Restart service

Restart the Bewator Omnis connector service:
Restart Physical Access Bewator Omnis connector

CODE
```
cd <SMARTIDHOME>/compose/physicalaccess
docker-compose restart smartid-pa-omnis
```