OnGuard
Overview
Integration of OnGuard with Irisity's IRIS+™ offers a video analytics solution/service whereby events of interest are detected through real-time analysis of multiple video sources and sent to OnGuard. This guide outlines how to deploy and configure the integration of IRIS+™ and OnGuard.
OnGuard configuration verification
The following OnGuard versions are supported:
- OnGuard 7.6, 8.0, 8.1 and 8.2
The following license features are required:
- OnGuard Subscription Software Modules (SWM-xxx)
- Partner Integration (IPC-094-AGNTV01-B)
Verify that the following Windows services are running in the OnGuard server:
- LS Communication Server
- LS Message Broker
- LS Open Access
Enabling OnGuard Integration in IRIS+™ Portal
Before you start
These steps assume that your IRIS+™ account has been set up and that folders, devices, and cameras have been configured. If that is not the case, first access IRIS+™ tutorials from the IRIS+™ Support hub to configure your account.
In IRIS+™, a service account is required to later link OnGuard to IRIS+™. The IRIS+™ service account provides a token, which is the identifier used to link the IRIS+™ account to OnGuard.
To generate an IRIS+™ Service Account token, perform the following
- Browse to your IRIS+™ account, Settings tab
- Click the Users tab
- Click the Add button, select Create service account
- Enter a meaningful Service Account name such as “Customer 1”. Enter a description (optional)
- Click Create Service account
- From the user's list, select the created Service Account user, click the arrow next to the Edit button, and select Get Token
- Define token expiration if required (by default the token never expires)
- Click Get token and copy and save the generated token (to be used in the IRIS+™ VMS Gateway configuration in the next chapter):
- Close the window
Installing IRIS+™ VMS Gateway Service
The IRIS+™ VMS Gateway is a Windows service connecting IRIS+™ to OnGuard, transferring the IRIS+™ generated events to OnGuard. The service should be installed on a server connected both to OnGuard and to IRIS+™ Edge device/s.
When installing the IRIS+™ VMS Gateway, or troubleshooting connectivity problems, it is important to understand that the gateway can be both a client and a server:
- The gateway is a client of OnGuard
- When using Edge Integration, the gateway is a server to which IRIS+™ edge devices connect to push analytics events to the gateway
- When using Core Integration, the gateway is a client connecting to the IRIS+™ Core service
- When installing the gateway and entering its configuration settings, or when opening ports in the firewall of the servers hosting the gateway and/or the VMS server, it is important not to confuse the different functions and client/server incoming/outgoing call direction of the various ports and URLs
To install and configure the IRIS+™ VMS Gateway perform the following steps:
- Download the IRIS+™ VMS Gateway Installer from this link: https://bit.ly/4bfjrfQ
- Run the installer on either the OnGuard server or on a separate Windows server with connectivity to OnGuard. If a previous version of the gateway is already installed, uninstall this version. Run the installer file as administrator. Two options are available for the gateway to integrate with IRIS+™:
- Edge Integration Events are sent from IRIS+™ edge devices to the IRIS+™ VMS Gateway and then delivered to OnGuard
- Core Integration Events are received by the IRIS+™ VMS Gateway from the IRIS+™ Core and then delivered to OnGuard
- When the following window is displayed, populate the relevant fields:
- VMS Settings (relevant for both Edge and Core Integration options)
- VMS Type - select OnGuard
- Address - IP address of the OnGuard server
- Port - Port to communicate with OnGuard. The default port is 8080
- User - username to log in to OnGuard
- Password - password to log in to OnGuard
- Integration Settings
- Events Integration Type – Select Edge or Core
- IRIS+™ URL - the default URL (https://api.irisity.io) is for an Irisity cloud-hosted deployment. For a Customer Hosted deployment, replace this URL with the applicable URL assigned for your deployment
- IRIS+™ Account Token - paste the token you have generated in the previous section
- Events Integration Port - applicable only for Edge Integration. This is the IRIS+™ VMS Gateway port on the Windows server. The value is automatically populated with a default value and is editable
- Events Integration URL – applicable only for Edge Integration. The URL field is read-only and cannot be updated. This is the IP address of the Windows server on which the IRIS+™ VMS Gateway is being installed. The value of the port number is automatically populated. Keep the IP address to be used later on when configuring an IRIS+™ Integration Target
- Metadata Integration Port & Metadata Integration URL - not applicable
- Click Next to proceed with the installation until finished
- Once the installation is complete, the service is started. The gateway service will then connect to OnGuard to fetch cameras
- Follow these steps to verify the gateway service successfully communicates with the VMS:
- Wait one minute to allow the service to communicate with OnGuard
- Open the file "C:\Program Files (x86)\Irisity AB\IRIS+ VMS Gateway\logs\VMSAdapter.log". See if it contains a list of camera names fetched from the VMS, or otherwise error notifications indicating a problem
- Possible errors:
- Wrong details were entered during the IRIS+™ VMS Gateway installation (examples: IP, port number, credentials). To change any of the required parameters, refer to the “Updating configuration parameters” section below
- Wrong or incomplete configuration of the VMS server (license, firewall, configuration, cameras not yet added, some VMS services are down, etc.)
- Connection is successful; however, a functional failure of the gateway occurs due to the refusal or failure of the VMS to correctly respond to the gateway. Verify the installed gateway Windows service has sufficient Windows permissions. If not, change the gateway service settings to log on as a Windows user with the necessary permissions. Restart the service and verify (in the VMSAdapter.log) that the gateway service operates properly
Updating configuration parameters
If you need to change any of the integration parameters following the installation, there is no need to uninstall and reinstall the IRIS+™ VMS Gateway. A dedicated utility is available to update the parameters. Run the utility as administrator from the shortcut here:
"C:\Program Files (x86)\Irisity AB\IRIS+ VMS Gateway\IRIS+Gateway.Service.exe"
Following any relevant changes in IRIS+™ Portal, IRIS+™ VMS Gateway, or OnGuard, restart the IRIS+™ VMS Gateway service for the changes to take effect.
Port Setup on IRIS+™ VMS Gateway Service server
For Edge Integrations port 8098 needs to be open for both TCP and UDP traffic on the IRIS+™ VMS Gateway server to be able to receive events from IRIS+™ edge devices. Make sure that relevant edge devices have connectivity to the IRIS+™ VMS Gateway on this port.
OnGuard Setup
After installing the gateway, a “Logical Source” named “IRIS+” is automatically added to the OnGuard configuration. For the received events to appear in the Main Alarm Monitor, the IRIS+ Logical Source (and its ‘child’ Logical Devices) must be added to the Monitor Zone.
Perform the following steps in OnGuard:
- Open OnGuard License Administration. Select OnGuard Subscription Software:
- Scroll down until you see the Partner Integrations section: *Ensure the displayed Irisity Partner Integration appears *
- Open OnGuard System Administration. Select Video. From the opened menu select Digital Video
- In the opened window, click Add
- Add a Recorder: populate the required fields and click OK
- A list of available Monitor Zones is displayed. Select the relevant Monitor Zone to add the Recorder to:
- The Recorder is added to the Video Recorder section:
- Select Monitoring. From the opened menu select Monitor Zone.
- Click Modify
- Select Logical Sources
- Select the Device – click the Device icon
- The Device is marked. Click Assign and then click OK
- The Device is added to the right-hand column
OnGuard Segments Support
The IRIS+™ VMS Gateway supports OnGuard Segments in the following way:
- On startup, it checks if segments are enabled in the OnGuard system (otherwise runs as before) and logs it. Example log: DBG Segmentation setting: ENABLED.
- It logs the available segment IDs and names.
- It also logs in which segment the gateway will add logical entities if not already added.
Example log: DBG ----- Segments list START ----- DBG Segment #0: 'first Segment'. <== SELECTED (auto) DBG Segment #1: 'second_segment'. DBG ----- Segments list END -----
The gateway will automatically add logical entities in the first segment in the list, as in the example above. But if the user wants the logical entities to be added in a specific segment, the user can do that by:
- Creating a file named "custom.ini" in the IRIS+ VMS Gateway installation folder (typically C:\Program Files (x86)\Irisity AB\IRIS+ VMS Gateway)
- The content of that INI file should indicate the ID of the segment to be selected. Example custom.ini file contents:[OnGuard] SegmentID=4
- Stop the gateway service
- Delete the IRIS+ logical entities that were automatically added in the 1st segment (if any).
- Start the gateway service again. This will add the logical entities in the custom-selected segment.
Example log: DBG ----- Segments list START ----- DBG Segment #0: 'first Segment'. DBG Segment #1: 'second_segment'. <== SELECTED (custom.ini) DBG ----- Segments list END -----
Mapping OnGuard cameras in IRIS+™
Each camera in OnGuard has a numeric channel number which needs to be mapped to the corresponding cameras in IRIS+™.
To associate the selected camera with the corresponding camera defined in IRIS+™, do the following:
- Log in to your IRIS+™ account
- From the top module bar, select Administrator
- In the device tree select the relevant camera
- In the device submenu click Settings
- Click the Edit button
- Enter the channel number in the External ID field
- Click Save
Note: if you integrate IRIS+™ to both Genetec and OnGuard – place the Genetec External ID first to be followed by the OnGuard External ID, separated by a comma.
Configuration of Edge Integration in IRIS+™
The recommended method is to transfer the events to OnGuard via IRIS+™ Core. The Edge Integration should be used only if timing issues (delays) are encountered in event transfers.
For Edge Integration additional configuration is needed in the IRIS+™ system, see below.
Define Integration Targets
The Integration Targets in IRIS+™ are the system-wide definitions specifying the endpoints that can receive the events sent by IRIS+™. For the OnGuard integeration, an Integration Target pointing to the IRIS+™ VMS Gateway server is needed. To define this, do the following:
- Log in to your IRIS+™ account
- From the top module bar, select Settings
- Select Integration Targets
- Click the Add button. The Integration Target screen appears:
- Target name: Define a meaningful name such as OnGuard
- Ensure the toggle switch is Enabled
- Type: Keep default values HTTP and POST
- URI: Paste the Events Integration URL as specified by the IRIS+™ VMS Gateway installer, see the "Installing IRIS+™ VMS Gateway Service" section. If the gateway and the edge devices are NOT on the same LAN, then you should replace the internal IP in the URI with the public IP of the IRIS+™ VMS Gateway server. Make sure that any relevant IRIS+™ Edge devices can reach this IP and that port 8098 is open, see the "Port Setup on IRIS+™ VMS Gateway Service server" section.
- Click Save. The integration Target is defined and is listed in the Integration Targets list
Define Edge Integrations in IRIS+™
The Integration Target needs to be enabled on each IRIS+™ Edge device which should transfer events to OnGuard. To do that follow these steps:
- Log in to your IRIS+™ account
- Select Physical View
- Select the IRIS+™ Edge for which you want to define the integration
- Select Integrations
- Click Edit
- Enable Events Integration and select the Integration Target you have previously defined (in this example – OnGuard)
- Click Save
Advanced configuration
It is possible to tweak certain configuration options using the custom.ini file which is typically located here:
“C:\Program Files (x86)\Irisity AB\IRIS+ VMS Gateway”.
The IRIS+™ VMS Gateway will read the custom.ini file during startup
The following is an example of the file content:
[OnGuard] SegmentID=1 SubstringToFilterCameraNames=IRIS+ TimeZoneNameSubstring=Eastern Time LogicalSourceName=IRIS+
All parameters are optional.
SegmentID See the "OnGuard Segments Support" section above
SubstringToFilterCameraNames This parameter is used to identify cameras in OnGuard for which events will be sent from IRIS+™ to OnGuard. Add the string defined for this parameter to e.g. the end of the camera name in OnGuard. For each defined camera that contains the string, IRIS+™ creates a logical device in OnGuard.
As a default, this parameter has no value, so events can be transferred to all OnGuard cameras.
TimeZoneNameSubstring This is the OnGuard time zone for your deployment. Set the value to an OnGuard time zone matching your deployment time zone. See a list of time zones in Appendix A - Timezones
LogicalSourceName By default, the IRIS+™ VMS Gateway will create a Logical Source device in OnGuard with the name "IRIS+". This can be overridden using this parameter.
If you have made any changes to the custom.ini file, restart the IRIS+™ VMS Gateway Service for the changes to take effect
Troubleshooting
The logs for the IRIS+™ VMS Gateway Service are available as follows:
- Installer log name: ” VMSGatewayInstall.txt"
- Installer log path: “C:\VMSGatewayInstallation\logs”.
- IRIS+™ VMS Gateway Service logs path: “C:\Program Files (x86)\Irisity AB\IRIS+ VMS Gateway\logs”.
Irisity Customer Support may ask for these logs for further troubleshooting
Contact Irisity Support
Customer Support: [email protected]