1 Avigilon Unity Integration Guide

1.1 Introduction

Deploying and configuring SAFR and Avigilon Unity will allow SAFR to import Unity person records and credentials to be used on SAFR SCAN face authentication readers. SAFR SCAN is using the imported face image, converted into a biometric signature, to verify a person identity when presented at a SAFR SCAN reader. When a person’s identity has been verified the SAFR SCAN reader transmits the imported Access Credentials to the access control panel via Wiegand or OSDP signaling.

Please note that SAFR will not import a person record if it does not have a card access credential. Likewise, if the access credential is removed from the person record, SAFR will delete the person record in SAFR. SAFR only supports one card access credential per person record. If multiple credentials exist, the most recently updated credential is imported.

For complete SAFR and SAFR SCAN documentation please visit http://docs.real.com.

1.2 Integration Overview and Requirements

Integrated SAFR - Avigilon Unity is available on Windows and Linux.

Please note that this Guide does not include the Installation of the SAFR Server (SAFR Platform) or the Avigilon Unity. This guide specifically describes:

1. Configure Unity to allow SAFR server to import People and Access Credentials from Unity.
2. Configure the External Identification Synchronization in SAFR server.

A typical integration architecture:

1.2.1 System Requirements

• Windows 10 or Windows Server 2019+
• 50GB free space
• 16GB RAM
• Avigilon Unity 6.34.0.33 or later

1.2.2 Attribute mapping between Unity and SAFR

The following is the current imported and supported attributes/field from Unity

Unity	SAFR (People data record)	Notes
First Name	First Name
Last Name	Last Name
Type	Person Type (default “Card Holder”)	SAFR defaults all Person Type records to “Card Holder” (configurable) for people imported from Avigilon ACM
Photo	Picture
Internal Number	Access Card ID	Only one card format is supported for all users. Card format must be set in SAFR.
Roles	Access Clearance	For each person, one Access Clearance is created if it does not already exist in SAFR. If more than one Role is assigned to a person in Avigilon, SAFR will concatenate all Roles into a single Access Clearance Name with a "+" between each Role name. Example: Person with Role R1, R2 and R3 will have Access Clearance "R1+R2+R3" in SAFR. If the length of the Access Clearance name becomes longer than 64 or 128 (configurable), the Access Clearance in SAFR will be assigned a random unique string 32 characters long.
Access Groups	Zones	For each Access Clearance created in SAFR, one Zone is created in SAFR for each Access Group belonging to the list of Roles that Access Clearance was created from. Example: Access Clearance AC1 was created from Roles R1 and R2. Role R1 has Groups G1 and G2 and Role R2 has Groups G2 and G3. Thus, AC1 will have Zones G1, G2 and G3.

1.3 Unity Configuration

SAFR Integration with Unity implemented with Avigilon Unity Web Services.

An Access Control Manager 6 REST Connectivity Software License is required to be installed on Unity (per appliance) to enable the connection between the SAFR Server and Unity. These are described below.

No additional license or software is required on the SAFR server.

1.3.1 Avigilon Unity Licensing

An Access Control Manager 6 REST Connectivity Software License must be added to your Avigilon Unity Server for SAFR integration. The required part number “AC-SW-LIC-REST-6-P”. Please ask your Avigilon representative for the license.

To install the license

1. Go to Appliance > About
2. Click Add License

1.3.2 Create User

SAFR requires user credentials to access Avigilon REST APIs. You can use an existing user or create a new user. If using existing user, ensure the proper delegations are granted as described below.

1.3.2.1 Create SAFR user in Avigilon

1. Go to Identities
2. Click Add Identity
3. Enter Identity Information as desired (not reqd)
4. Enter following information (reqd). Login can be any value desired.
   
5. Assign a Role to the user. This role must have Delegations indicated below.

1.3.2.2 Add Delegations

Create a new Role and add Delegations as described here or ensure Role assigned to SAFR user has required delegations described below.

The following delegations should be assigned to Avigilon user used for SAFR Integration:

1. Go to Roles > Delegations
2. Select a Role
3. Ensure at least the following are added as Members for the selected Role

1.4 Set up External Identification Synchronization

To set up identity synchronization between SAFR and Unity, do the following:

1. Open SAFR.
2. Click on the Tools menu in the upper left corner of the client and select the System Configuration tool from the drop-down menu.

Check the Set up External Identity synchronization box. The following dialogue will appear:

3. Enter information for the following fields:

• User directory name: The name of your SAFR user directory.
• External identity host: Select Avigilon from the drop-down menu.
• Host Address: The IP address or hostname of the target Unity server
• Host Port: The port number that the target Unity server is listening on.
• Host User Id: The User Id of a user who has the credentials to log into the Unity server.
• Host Password: The Password of a user who has the credentials to log into the Unity server.

4. Click the Apply button.
5. If you’re using IP address on “Host Address” the following configuration need to be changed in SAFR. COVI Service restart is required after the change:
   • Set avigilon.trust.server.certificate:true on C:\Program Files\RealNetworks\SAFR\covi\app\config\covi\avigilon.properties
   • 

2 Avigilon Unity Operation Guide

2.1 Synchronizing People

Person synchronization is automatic. Person records and their credentials are copied from the Physical Access Control System (PACS) to SAFR Server and from there pushed to all readers. Synchronization occurs continually in the background.

SAFR will synchronize people and credentials as follows:

• At initial connection time, all records pre-existing in Unity are copied to SAFR + Avigilon Roles + Avigilon Access Groups
• From then on, records added to Unity are copied to SAFR.
• Records in SAFR are NOT copied to Unity.
• Changes to records in Unity are updated in SAFR.
• If record is changed in SAFR, a message is displayed warning that the changes made in SAFR will be overwritten the next time the record is updated in Unity.
• Only records with access credentials(Tokens) will be copied to SAFR.
• Removing credentials in the Unity results in the record being removed from SAFR.
• Setting record to inactive in Unity removes the record from SAFR.

Below describes the process (which is automatic).

1. Add a person in Unity. Person, Credentials, their Roles and associated Access Groups are migrated to SAFR.

2. That person record and the corresponding credentials are be copied to SAFR and viewable in SAFR Person Window.

3. Roles and Access Groups from Avigilon are imported as Access Clearance and Zones respectively.

4. SAFR SCANs devices need to be manually assigned to the Zones created in order to allow DB Sync between SAFR SCAN and SAFR Server:

5. SAFR SCAN device should have monitoring mode to “Threat/Concern and Stranger Monitoring” or “Disabled” in order to be able to import only the identities with the proper access clearance/zones assigned to that device.

2.2 Unity Sync Server Configuration

Following SAFR Unity Sync configuration properties can be set on SAFR Server. Remove "## " and enable property.

external.sync.avigilon.page.size=1000 ## 2 minutes ## avigilon.read.timeout=120000 avigilon.connect.timeout=120000 ## These two really speed up delta sync of large repositories of identities but can break basic ## functionality such as captuing face changes ## ## external.sync.import.face.updates=false ## external.sync.avigilon.import.face.updates=false ## Default Values: ## ## external.sync.avigilon.default.site:Avigilon ## external.sync.avigilon.default.source:Avigilon ## external.sync.avigilon.default.ptype:Card Holder ## Null by default, setting these will prevent mapping algorithm that makes use of Avigilon RolesA ## ## external.sync.avigilon.override.access.clearance ## external.sync.avigilon.override.access.clearance.level ## Needs to be small enough so that we can process a whole page in < 2 minutes ## ## external.sync.avigilon.page.size:10000 ## Lock down server certificate by setting to false, requiring matching dns name, valid CA, proper date ## ## avigilon.ssl:auto ## avigilon.trust.server.certificate:true ## to enable incremental sync: ## ## avigilon.incremental.sync.enabled:true ## avigilon.incremental.sync.endpoint.enabled:true ## avigilon.incremental.sync.partner:safravigilon ## avigilon.incremental.sync.directory:timed-ten-k ## avigilon.incremental.sync.socket.server.enabled:true ## avigilon.incremental.sync.socket.server.port:8989 ## avigilon.incremental.sync.socket.server.listen.retries:3 ## override facility id ## avigilon.facility.id.override=123 ## avigilon.access.clearance.name.max.length:256 ## Setting extract to false can decrease API pressure on Avigilon (slowing down/serializing sync) ## ## avigilon.parallel.import:true ## avigilon.parallel.extract:true

These properties should always be set on persistent-overrides.properties. Changes to avigilon.properties will be overwritten when doing an upgrade or overinstall of SAFR Platform.

To set properties in persistent-overrides.properties., first rename the file by removing ".example".

avigilon.access.clearance.name.max.length:256 // Values of 64, 128 or 256

3 Troubleshooting

3.1 Troubleshooting Network Connections

Run the following commands from a command prompt on SAFR Server to confirm that Avigilon server is reachable by SAFR.

Get Inputs

curl -v -k -X GET "https://10.10.10.1/rest/inputs.json" -u AVIGILONUSERNAME:PASSWORD -H "Accept: */*"

Get Card Formats

curl -v -k -X GET "https://10.10.10.1/card_formats.xml" -u AVIGILONUSERNAME:PASSWORD -H "Accept: */*"

where 10.10.10.1 is your Aviglon server IP address.

Run the following to verify the same command can be run from SAFRCovi Service:

curl -v -k \ -X GET \ https://10.10.10.2/card_formats.xml \ -u AVIGILONUSERNAME:PASSWORD \ -H "Accept: */*"

where 10.10.10.2 is your SAFR server ip address.

Run the following command to verify tokens:

curl -v -k -X GET https://SERVER/identities/-1/tokens.xml?include_udf=true -u AVIGILONUSERNAME:PASSWORD -H "Accept: */*"

where 10.10.10.1 is your Avigilon server IP address.

3.2 Limiting load on Avigilon

Depending in capacity of the Avigilon system, SAFR requests can result in overload of the Avigilon server and cause Avigilon services to restart. Below provides guidance on how to throttle the SAFR API calls to avoid negative impact to Avigilon operations.

3.2.1 Increase the CoVI Java HEAP Memory

Search "HEAP Memory" on http://support.safr.com

3.2.2 Slow the rate of sync and turn of parallel processing

Open persistent-overrides.properties in C:\Program Files\RealNetworks\SAFR\covi\app\config\covi and add following

1. Set following small enough so that we can process a whole page in < 2 minutes. 500 is a good starting point.

external.sync.avigilon.page.size=500

2. Turn off parallel processing by adding the following

avigilon.parallel.import:false
avigilon.parallel.extract:false

3. Add delay between each full update with following:

external.sync.schedule.fixed.delay = 120000

Value is in milliseconds. 2 minutes (120000) is a good starting point.

4. Restart 'SAFR Covi" Windows Service
5. Observe ACM load and make sure its below 0.4

If load is too high, increase external.sync.schedule.fixed.delay

If load is <0.1, you can increase external.sync.schedule.fixed.delay to speed up how quickly incremental changes are applied.

Questions or comments about the documentation? Email us at [email protected].

1