In order to integrate with certain external systems, it is sometimes necessary to run an application onsite that will synchronise data held in myClubhouse with the external system. Examples include physical access control systems (for example, door and gate entry systems using fobs or swipecards), and lighting control systems (for example, squash court or snooker table lighting).

The myClubhouse External Integration Tool is an application that is generally installed as a service on a Windows PC. The PC must have access to the internet and be connected with the system that is to be controlled (the target system), generally over the LAN. The tool runs continuously and periodically requests updates from myClubhouse using a simple polling mechanism. As such, it doesn’t generally require any modifications to the firewalls protecting the client’s infrastructure, as it is only making outgoing calls to the internet.

myClubhouse Technical Support will assist with the installation and configuration of the software (remotely).

Supported Systems

The tool can currently integrate with the following systems. This list is being added to on a needs basis. So, if you don’t see your system listed, please contact us.

Access Control

Paxton Net2 V1.3 - https://www.paxton-access.com/systems/net2/
Norpass3 - https://www.nortechcontrol.com/products/access-control/networked/norpass3-access-control-software/
Videx PROS - https://www.videxuk.com/product/portal-plus-pros-server-client-software/

Lighting Control

Aviosys IP Power devices - e.g. https://www.aviosys.com/products/9258.php
Schneider M221-based Controllers V1.3 - e.g. https://www.se.com/uk/en/product/TM221CE40R/controller-m221-40-io-relay-ethernet
Schneider OTB Controllers V1.3 - e.g. https://www.se.com/uk/en/product/OTB1E0DM9LP/i-o-distributed-module-otb-ethernet-tcp-ip-0-100-m/

Installation

The software consists of a single, self-contained executable (myClubhouseAccessControlService.exe) and a configuration file (appsettings.json). These need to be downloaded and placed in a suitable folder (for example: c:\myClubhouse) on the onsite PC.

myClubhouse Technical Support will help with the creation of the configuration file, according to your requirements.

Once downloaded, the application should be added as a Service that starts automatically on system boot:

sc create "myClubhouse Access Control Service" binpath="c:\myClubhouse\myClubhouseAccessControlService.exe" start=auto

myClubhouse Website Configuration

In order for the software to communicate with your myClubhouse website, it needs an API key. API keys are linked to particular users in myClubhouse and inherit the permissions/entitlements of that user. We would generally suggest that a special service user is created with exactly the permissions required by the software to operate.

Once you have created the service user, you should process to the profile page for the user and the API section on that page. There you can create an API key and control which specific APIs the key can access. You will need to include the API key in the configuration file, in the MyClubhouseOptions section (see below).

Supporting Multiple Integrations

When supporting multiple integrations, it will be necessary to install the tool multiple times, using separate configuration files for each target system.

Paxton Net2 - Additional Installation Steps

In addition to the above, the myClubhouse Paxton licence file needs to be installed with your Paxton Net2 install. This is usually placed in the c:\Program Files (x86)\Paxton Access\Access Control\ApiLicences directory. We will supply the licence file when you are ready to install.

Configuration Reference

The appsettings.json file contains several sections:

Serilog - these settings control the generation and output of logs. It is not usually necessary to make any changes to these settings.
MyClubhouseOptions - these settings configure the connection to myClubhouse.
SyncOptions - these settings control how often the myClubhouse system is polled and what information is to be retrieved.
ConnectionStrings - certain integrations require connections to local databases. This section contains the connection strings defining those connections.
<system-specific> - there will be a system-specific section containing the settings needed to connect to the specific target system.

MyClubhouseOptions

"MyClubhouseOptions": {
  "RootApiURL": "https://myclub.myclubhouse.co.uk/api/v1/",
  "SyncHubURL": "https://myclub.myclubhouse.co.uk/syncHub",
  "ApiKey": "xxxxxxxxxxxxxxxxxxxxxx",
  "Users": {
    "Filter": "IsCurrentMember=true"
  },
  "Bookings": {
    "Filter": "BookingSystem=1&IsToday=true"
  }
}

RootApiURL: The URL for the API on your myClubhouse site.
SyncHubURL (optional) V1.3 : The URL to the synchronisation hub on your myClubhouse site. This is required if you need instant update of lighting power in response to booking changes - e.g. when a member checks in to a booking. It is also used to communicate power status changes to myClubhouse for display on the lighting control page. It is not used for access control system integration.
ApiKey: The key to use when accessing the API. See the myClubhouse Website Configuration section above for more details on how you can get this key.
Users (optional): defines the filter that is used when requesting user data from myClubhouse. In the above example, all current members are requested.
Bookings (optional): defines the filter that is used when requesting booking data from myClubhouse. The above example retrieves bookings for today from the booking system with ID 1. This is required if you use the SyncWithBookings option for Videx, or have any Paxton access level mappings which are only active when the user has active bookings.

SyncOptions

"SyncOptions": {
  "PollingInterval": "00:05:00",
  "SyncWithBookings": true
}

PollingInterval: The time between poll requests, specified in hours, minutes and seconds. The above example specifies a polling interval of 5 minutes. This interval must not be too short as it will put undue load on the myClubhouse website. For most use cases, an interval of 5 minutes is more than sufficient.
SyncWithBookings: Controls whether access control is synced with bookings, rather than membership status; i.e. access is only granted if there is a valid booking for that time. Note: this is only supported by the Videx integrations.

PaxtonOptions V1.3

These settings configure the integration with Paxton Net2 access control.

BaseURL: The URL to access the API on the Paxton Net2 server.
Client ID: The ID of this client to the Paxton Net2 server. This value is linked to our licence file and we will supply it.
Username: The username used to login to the Paxton Net2 API.
Password: The password used to login to the Paxton Net2 API.
UserIDCustomFieldID: ID of a custom user field in Paxton Net2 that will be used to store the myClubhouse ID of the user. This is required to ensure that we can unambiguously match users in Net2 to users in myClubhouse.
SyncPhotos: V1.4 (Optional): flag controlling whether user photos should be sync'ed across from myClubhouse to Paxton Net2. Default is false.
PinAttribute: V1.4 (Optional): name of attribute in myClubhouse containing user's PIN number. Sync’ed across into the user’s PIN field in Paxton Net2.
PurgeDelayDays: the number of days after a user’s membership has expired that the matching user record in Net2 should be deleted. When a user’s membership lapses, the Net2 record is not immediately deleted. Instead, the access level of the user is set to “no access”.
AccessLevels: A list of rules mapping from myClubhouse users to particular access levels in Net2. The ordering of these is important as only the first one that matches a given user will be applied. Note that the user must match all of the matching rules specified; for example, if CurrentMember and RoleIDs are defined, then the user must be both a current member and in one of the roles specified. Each mapping can define the following:
- Name: the name of the access level in Net2 that should be assigned.
- CurrentMember (optional): boolean to match against the current member status of the user in myClubhouse. If this is set to true, then only current members will match.
- MembershipCategories (optional): list of names of myClubhouse membership categories that can be matched. The user must have an active membership subscription in at least one of these categories for the rule to match. The names must exactly match the ones specified in myClubhouse.
- RoleIDs (optional): list of IDs (integers) of myClubhouse roles that can be matched. The user must be assigned to one of these roles for the rule to match.
- ActiveBookingsOnly (optional): V1.4 access is only granted if the user has an active booking. Note that you will need to set a Bookings filter in the MyClubhouseOptions for this to work.
- PreBookingAccessMinutes (optional): V1.4 the number of minutes before the start of the booking that access is granted. Only used if ActiveBookingsOnly is set to true.
- PostBookingAccessMinutes (optional): V1.4 the number of minutes after the end of the booking that access is revoked. Only used if ActiveBookingsOnly is set to true.
Departments (optional): A list of rules mapping myClubhouse users to departments in Net2. The ordering of these is important as only the first one that matches a given user will be applied. Note that the user must match all of the matching rules specified; for example, if CurrentMember and RoleIDs are defined, then the user must be both a current member and in one of the roles specified. Each mapping can define the following:
- DepartmentName: the name of the department in Net2 that should be assigned.
- CurrentMember (optional): boolean to match against the current member status of the user in myClubhouse. If this is set to true, then only current members will match.
- MembershipCategories (optional): list of names of myClubhouse membership categories that can be matched. The user must have an active membership subscription in at least one of these categories for the rule to match. The names must exactly match the ones specified in myClubhouse.
- RoleIDs (optional): list of IDs (integers) of myClubhouse roles that can be matched. The user must be assigned to one of these roles for the rule to match.
Tokens (optional): Defines how Net2 access token IDs are stored in myClubhouse and the types of tokens to create. Each token definition defines the following:
- TokenType: the Net2 token type to create.
- TokenValueAttribute: the name of the attribute in myClubhouse that contains the token ID. This must exactly match the caption of the attribute in myClubhouse.

NorpassOptions

These settings configure the integration with Norpass3 access control.

IPAddress: The IP address or host name of the Norpass server.
IPPort: The port number to access the Norpass server.
Username: The username used to login to the Norpass server.
Password: The password used to login to the Norpass server.
ChipCardNumberAttribute: the name of the attribute in myClubhouse that contains the electronic chip number (RFID) of the access card. This must exactly match the caption of the attribute in myClubhouse.
PrintCardNumberAttribute: the name of the attribute in myClubhouse that contains the number printed onto the access card. This must exactly match the caption of the attribute in myClubhouse.
PurgeDelayDays: the number of days after a user’s membership has expired that the matching user record in Norpass should be deleted. When a user’s membership lapses, the Norpass record is not immediately deleted. Instead, the access level of the user is set to “no access”.
AccessLevels: A list of rules mapping from myClubhouse users to particular access levels in Norpass. The ordering of these is important as only the first one that matches a given user will be applied. Note that the user must match all of the matching rules specified; for example, if CurrentMember and RoleIDs are defined, then the user must be both a current member and in one of the roles specified. Each mapping can define the following:
- ID: the numeric ID of the access level in Norpass that should be assigned.
- CurrentMember (optional): boolean to match against the current member status of the user in myClubhouse. If this is set to true, then only current members will match.
- MembershipCategories (optional): list of names of myClubhouse membership categories that can be matched. The user must have an active membership subscription in at least one of these categories for the rule to match. The names must exactly match the ones specified in myClubhouse.
- RoleIDs (optional): list of IDs (integers) of myClubhouse roles that can be matched. The user must be assigned to one of these roles for the rule to match.

VidexOptions

These settings configure the integration with Videx access control.

AccessLevel: The ID of the access level in Videx that the users will be assigned by default.
AccessKeyType: The ID of the access key type in Videx.
SiteCodeAttribute: The name of the attribute in myClubhouse which holds the Site Code part of the Videx key fob ID. This must exactly match the caption of the attribute in myClubhouse.
UserCodeAttribute: The name of the attribute in myClubhouse which holds the User Code part of the Videx key fob ID. This must exactly match the caption of the attribute in myClubhouse.
UnrestrictedRoleID (optional): The ID of the myClubhouse role whose incumbents receive unrestricted access through Videx.
Department: The ID of the Videx department.
ControllerName: The name of the Videx controller.

In addition to the above, a connection string to access the Videx database must be supplied:

AviosysOptions

These settings configure the integration with Aviosys IP Power boxes for lighting control. A single process can control multiple IP Power boxes. Note that if there are consecutive bookings on a single asset, then the power will be maintained across the entire time - it will not be switched off and on again at each booking boundary.

PowerUnits: List of the definitions of the IP Power boxes to connect to. Each one has the following:
- IPAddress: The IP address of the box.
- IPPort: The port on which to communicate with the box.
- Username: The username to login to the box.
- Password: The password to login to the box.
- Assets: The IDs of the bookable assets in myClubhouse and how they map to the power outputs of the box. For an IPPower 9258 with four outputs, the names of the outputs are p61, p62, p63 and p64.
PowerOnBeforeOffsetMinutes (optional): the number of minutes before a booking that the power should be switched on.
PowerOffAfterOffsetMinutes (optional): the number of minutes after a booking has ended that the power should stay on.
PowerUnpaidBookings (optional): boolean flag controlling whether unpaid bookings should still trigger the power being applied or not.
PowerUnattendedBookings V1.3 (optional - default: true): boolean flag controlling whether unattended bookings should still trigger the power being applied or not. If false, then members must check-in to bookings using the myClubhouse mobile app, in order to switch the lights on.

ModbusOptions V1.3

These settings configure the integration with Schneider M221 Controller boxes for lighting control. A single process can control multiple controller boxes. Note that if there are consecutive bookings on a single asset, then the power will be maintained across the entire time - it will not be switched off and on again at each booking boundary.

PowerUnits: List of the definitions of the IP Power boxes to connect to. Each one has the following:
- IPAddress: The IP address of the box.
- IPPort (optional - default: 502): The port on which to communicate with the box.
- Assets: The IDs of the bookable assets in myClubhouse and how they map to the outputs of the controller. The key (e.g. “0”) is the 0-based index of the output on the controller (as a string). The value (e.g. 1) is the ID of the bookable asset in myClubhouse.
PowerOnBeforeOffsetMinutes (optional): the number of minutes before a booking that the power should be switched on.
PowerOffAfterOffsetMinutes (optional): the number of minutes after a booking has ended that the power should stay on.
PowerUnpaidBookings (optional): boolean flag controlling whether unpaid bookings should still trigger the power being applied or not.
PowerUnattendedBookings (optional - default: true): boolean flag controlling whether unattended bookings should still trigger the power being applied or not. If false, then members must check-in to bookings using the myClubhouse mobile app, in order to switch the lights on.

Modicon OTB Options V1.3

The format of the options is exactly the same as the Modbus options, except that the name of the field is “ModiconOTBOptions” rather than “ModbusOptions”. So, as an example: