cron'able command line utility to manage the access control lists of a set of UHPPOTE UTO311-L0x access access controllers from a Wild Apricot organisational account.
Supported operating systems:
- Linux
- MacOS
- Windows
- ARM7
v0.8.8 - 2024-03-27
- Bumped Go version to 1.22
- Reworked member initialisation to resolve group names against system group names using group ID because Wild Apricot does not keep the member groups fields consistent.
- Fixed bug that ignored '0' when normalising strings.
Executables for all the supported operating systems are packaged in the releases. The provided archives contain the executables for all the operating systems - operating system specific tarballs can be found in the uhppoted releases.
Installation is straightforward - download the archive and extract it to a folder of your choice and then place the executable in a filder in your PATH. The uhppoted-app-wild-apricot utility requires the following additional information:
uhppoted.confconfiguration file- a Wild Apricot account ID
- a Wild Apricot API key with read permission for contact lists and member groups
- a Grule rules file that defines the member access permissions
uhppoted.conf is the communal configuration file shared by all the uhppoted project modules and is (or will eventually be) documented in uhppoted. uhppoted-app-wild-apricot requires the
devices section to resolve non-local controller IP addresses and door to controller door identities.
It also uses the following additional configuration items:
| Key | Default value | Description |
|---|---|---|
wild-apricot.http.client-timeout |
10s | Wild Apricot API request timeout |
wild-apricot.http.retries |
3 | Number of times retry a failed API request |
wild-apricot.http.retry-delay |
5s | Interval between retries of a failed API request |
wild-apricot.facility-code |
Facility code | Facility code prepended to card numbers that are 5 digits or less |
wild-apricot.fields.card-number |
Card Number | Contact field name to use for card number |
wild-apricot.display-order.groups |
(alphabetic) | Optional output ordering for the member list groups |
wild-apricot.display-order.doors |
(alphabetic) | Optional output ordering for the ACL doors |
A sample uhppoted.conf file is included in the uhppoted distribution.
A credentials file should be a valid JSON file that contains the Wild Apricot account ID and API key e.g.:
{
"account-id": 615252,
"api-key": "8dhuwyeb7262jdufhde87bhbdehdes"
}
The rules file is a text file containing the Grule rules that define the member access e.g.:
// *** GRULES ***
rule Teacher "Grants a teacher access to common areas and Hogsmeade" {
when
member.HasGroup("Teacher")
then
record.Grant("Great Hall");
record.Grant("Gryffindor");
record.Grant("Hufflepuff");
record.Grant("Ravenclaw");
record.Grant("Slytherin");
record.Grant("Hogsmeade");
Retract("Teacher");
}
rule Staff "Grants ordinary staff access to common areas, Hogsmeade and kitchen" {
when
member.HasGroup(601422)
then
record.Grant("Great Hall");
record.Grant("Gryffindor");
record.Grant("Hufflepuff");
record.Grant("Ravenclaw");
record.Grant("Slytherin");
record.Grant("Hogsmeade");
record.Grant("Kitchen");
Retract("Staff");
}
rule Gryffindor "Grants a Gryffindor student access to common areas and Gryffindor" {
when
member.HasGroup("Student") && member.HasGroup("Gryffindor")
then
record.Grant("Great Hall");
record.Grant("Gryffindor");
Retract("Gryffindor");
}
rule Pets "Grants a Pet access to the Kitchen at mealtimes" {
when
member.HasGroup("Pet")
then
record.Grant("Kitchen:100");
Retract("Pets");
}
rule DeathEaters "Denies Hogwarts access to any known members of the Death Eaters" {
when
member.HasGroup("Death Eaters)
then
record.Revoke"Great Hall");
record.Revoke("Gryffindor");
record.Revoke("Hufflepuff");
record.Revoke("Ravenclaw");
record.Revoke("Slytherin");
record.Revoke("Dungeon);
record.Revoke("Kitchen");
Retract("DeathEaters");
}
// *** GRULES ***
Notes:
-
The card associated with a member has access to a door if access has been
grantedand NOTrevoked. If a card's door access has been both granted and revoked then it will not have access e.g. a Slytherin student could have access to the Great Hall, unless of course he/she is a known associate of Voldemort. -
To grant time based access to a door:
record.Grant("Kitchen:100"); -
The grules file must have markers at the start and end of the file as a basic validity check for downloaded files e.g. Google Drive shares occasionally download as empty files without error (ref. #2)
- The first non-blank line should be
// *** GRULES ***- The last non-blank line should be:
// *** END GRULES *** -
member.HasGroupresolves against the group name in the Wild Apricot groups list and not the group names in the member record. If a member is assigned to a group and the name of that group is subsequently changed, the Wild Apricot member record is not updated and still reflects the original group name. Since a group name could be changed several times in the lifetime of an organisation theHasGroupfunction resolves against the actual group name.
Assuming you have Go and make installed:
git clone https://github.com/uhppoted/uhppoted-app-wild-apricot.git
cd uhppoted-app-wild-apricot
make build
If you prefer not to use make:
git clone https://github.com/uhppoted/uhppoted-app-wild-apricot.git
cd uhppoted-app-wild-apricot
mkdir bin
go build -trimpath -o bin ./...
The above commands build the uhppoted-app-wild-apricot executable to the bin directory.
| Dependency | Description |
|---|---|
| com.github/uhppoted/uhppote-core | Device level API implementation |
| com.github/uhppoted/uhppoted-lib | Shared application library |
| github.com/hyperjumptech/grule-rule-engine | Grule rule engine for processing ACL rules |
| github.com/sirupsen/logrus | Indirect dependency from grule-rule-engine |
| golang.org/x/sys | Library for Windows system calls |
Usage: uhppoted-app-wild-apricot [--debug] [--config <configuration file>] <command> [options]
Supported commands:
helpversionget-membersget-groupsget-doorsget-aclcompare-aclload-acl
Displays a summary of the command usage and options.
Command line:
uhppoted-app-wild-apricot help
uhppoted-app-wild-apricot help <command>
Displays the current version of the command.
Command line:
uhppoted-app-wild-apricot version
Combines the contacts list and membership groups from a Wild Apricot membership database to create the table of members that is used to generate an access control list. The resulting member summary list can be optionally stored to a file. Intended for use in a cron task that routinely retrieves information from the Wild Apricot database for use by scripts on the local host.
Command line:
uhppoted-app-wild-apricot get-members --credentials <file>
uhppoted-app-wild-apricot [--debug] [--config <file>] get-members [--credentials <file>] [--with-pin] [--workdir <dir>] [--file <file>]
--credentials <file> File path for the credentials file with the Wild Apricot account ID and API key.
Defaults to <config dir>/.wild-apricot/credentials.json
--with-pin Optionally includes the card keypad PIN field in the retrieved member information. Defaults
to false.
--workdir Directory for working files, in particular the tokens, revisions, etc. Defaults to:
- /var/uhppoted on Linux
- /usr/local/var/com.github.uhppoted on MacOS
- ./uhppoted on Microsoft Windows
--file <file> Optional file path for the destination TSV file. Displays a formatted member list on console if not provided. If the file has a .tsv extension, the output is formatted as a TSV file.
--config File path to the uhppoted.conf file containing the access
controller configuration information. Defaults to:
- /etc/uhppoted/uhppoted.conf (Linux)
- /usr/local/etc/com.github.uhppoted/uhppoted.conf (MacOS)
- ./uhppoted.conf (Windows)
--debug Displays verbose debugging information, in particular the communications
with the UHPPOTE controllers
Retrieves the membership groups from a Wild Apricot membership database to displays as a table (or optionally stores it to a file). Intended as a convenience to assist when creating the rules that convert a member list into an access control list.
Command line:
uhppoted-app-wild-apricot get-groups --credentials <file>
uhppoted-app-wild-apricot [--debug] [--config <file>] get-groups [--credentials <file>] [--workdir <dir>] [--file <file>]
--credentials <file> File path for the credentials file with the Wild Apricot account ID and API key.
Defaults to <config dir>/.wild-apricot/credentials.json
--workdir Directory for working files, in particular the tokens, revisions, etc. Defaults to:
- /var/uhppoted on Linux
- /usr/local/var/com.github.uhppoted on MacOS
- ./uhppoted on Microsoft Windows
--file <file> Optional file path to which to write the output. Displays a formatted groups list on console if not provided. If the file has a .tsv extension, the output is formatted as a TSV file.
--config File path to the uhppoted.conf file containing the access
controller configuration information. Defaults to:
- /etc/uhppoted/uhppoted.conf (Linux)
- /usr/local/etc/com.github.uhppoted/uhppoted.conf (MacOS)
- ./uhppoted.conf (Windows)
--debug Displays verbose debugging information, in particular the communications
with the UHPPOTE controllers
Extracts the list of doors from the uhppoted.conf configuration file. Intended as a convenience to assist when creating the rules that convert a member list into an access control list.
Command line:
uhppoted-app-wild-apricot get-doors
uhppoted-app-wild-apricot [--debug] [--config <file>] get-doors [--workdir <dir>] [--file <file>]
--workdir Directory for working files, in particular the tokens, revisions, etc. Defaults to:
- /var/uhppoted on Linux
- /usr/local/var/com.github.uhppoted on MacOS
- ./uhppoted on Microsoft Windows
--file <file> Optional file path to which to write the output. Displays a formatted door list on console if not provided. If the file has a .tsv extension, the output is formatted as a TSV file.
--config File path to the uhppoted.conf file containing the access
controller configuration information. Defaults to:
- /etc/uhppoted/uhppoted.conf (Linux)
- /usr/local/etc/com.github.uhppoted/uhppoted.conf (MacOS)
- ./uhppoted.conf (Windows)
--debug Displays verbose debugging information, in particular the communications
with the UHPPOTE controllers
Retrieves the contacts list and membership groups from a Wild Apricot membership database and applies the access rules to create an access control list for the configured set of access controllers. The ACL can optionally be stored to a file for use by other scripts.
Command line:
uhppoted-app-wild-apricot get-acl --credentials <file> --rules <uri>
uhppoted-app-wild-apricot [--debug] [--config <file>] get-acl --credentials <file> --rules <uri> [--with-pin] [--workdir <dir>] [--lockfile <file>] [--file <TSV>]
--credentials <file> File path for the credentials file with the Wild Apricot account ID and API key.
--rules <uri> URI for the Grule file that defines the rules used to grant or
revoke access (assumes a local file if the URI does not start with
http://, https:// or file://).
Note that for rules files stored on Google Drive, the URI should be
of the form:
https://drive.google.com/uc?export=download&id=<file ID>
--with-pin Optionally includes the card keypad PIN field in the retrieved ACL. Defaults
to false.
--lockfile Optionally specifies the path to the lockfile used to serialize ACL requests. Defaults
to <workdir>/.wild-apricot/uhppoted-uhppoted-app-wild-apricot.lock.
--workdir Directory for working files, in particular the tokens, revisions, etc. Defaults to:
- /var/uhppoted on Linux
- /usr/local/var/com.github.uhppoted on MacOS
- ./uhppoted on Microsoft Windows
--file <file> File path for the optional output file. Displays the ACL on the console
if not provided. Formats the output as TSV if the provided file has a
.tsv extension.
--config File path to the uhppoted.conf file containing the access
controller configuration information. Defaults to:
- /etc/uhppoted/uhppoted.conf (Linux)
- /usr/local/etc/com.github.uhppoted/uhppoted.conf (MacOS)
- ./uhppoted.conf (Windows)
--debug Displays verbose debugging information, in particular the communications
with the UHPPOTE controllers
Retrieves the contacts list and membership groups from a Wild Apricot membership database and applies the access rules to create an access control list for the configured set of access controllers and compares the resulting ACL with the access control lists stored on the configured controllers. Intended for use in a cron task that routinely audits the controllers against an authoritative source.
Command line:
uhppoted-app-wild-apricot compare-acl --credentials <file> --rules <uri>
uhppoted-app-wild-apricot [--debug] [--config <file>] compare-acl [--credentials <file>] [--rules <uri>] [--with-pin] [--strict] [--summary] [--workdir <dir>] [--lockfile <file>] [--report <file>]
--credentials <file> File path for the credentials file with the Wild Apricot account ID and API key.
--rules <uri> URI for the Grule file that defines the rules used to grant or
revoke access (assumes a local file if the URI does not start with
http://, https:// or file://).
Note that for rules files stored on Google Drive, the URI should be
of the form:
https://drive.google.com/uc?export=download&id=<file ID>
--with-pin Optionally includes the card keypad PIN field when comparing the ACLs. Defaults to false.
--strict Fails with an error if the contacts and/or membership groups contains
errors e.g. duplicate card numbers
--summary Reports only a summary of the comparison. Defaults to false.
--workdir Directory for working files, in particular the tokens, revisions, etc. Defaults to:
- /var/uhppoted on Linux
- /usr/local/var/com.github.uhppoted on MacOS
- ./uhppoted on Microsoft Windows
--report <file> File path for the optional output file. Displays the compare report on
the console if not provided. Formats the output as TSV if the provided
file has a .tsv extension.
--lockfile Optionally specifies the path to the lockfile used to serialize ACL requests. Defaults
to <workdir>/.wild-apricot/uhppoted-uhppoted-app-wild-apricot.lock.
--config File path to the uhppoted.conf file containing the access
controller configuration information. Defaults to:
- /etc/uhppoted/uhppoted.conf (Linux)
- /usr/local/etc/com.github.uhppoted/uhppoted.conf (MacOS)
- ./uhppoted.conf (Windows)
--debug Displays verbose debugging information, in particular the communications
with the UHPPOTE controllers
Retrieves the contacts list and membership groups from a Wild Apricot membership database and applies the access rules to create an access control list that is downloaded to the configured set of access controllers.. Intended for use in a cron task that routinely updates the controllers from an authoritative source.
The command writes an operation summary to a log file and a summary of changes to a report .
Unless the --force option is specified, the command will only download and update changes since the last update.
Command line:
uhppoted-app-wild-apricot load-acl
uhppoted-app-wild-apricot [--debug] [--config <file>] load-acl [--credentials <file>] [--rules <uri>] [--with-pin] [--force] [--strict] [--dry-run] [--workdir <dir>] [--lockfile <file>] [--log <file>]
--credentials <file> File path for the credentials file with the Wild Apricot account ID and API key.
--rules <uri> URI for the Grule file that defines the rules used to grant or
revoke access (assumes a local file if the URI does not start with
http://, https:// or file://).
Note that for rules files stored on Google Drive, the URI should be
of the form:
https://drive.google.com/uc?export=download&id=<file ID>
--with-pin Optionally updates the card keypad PIN on the access controllers. Defaults to false.
--force Retrieves and updates the access control lists unconditionally.
--strict Fails with an error if the contacts and/or membership groups contains
errors e.g. duplicate card numbers
--dry-run Executes the load-acl command but does not update the access
control lists on the controllers. Used primarily for testing
scripts, crontab entries and debugging.
--workdir Directory for working files (in particular the version information
for the last update). Defaults to:
- /var/uhppoted on Linux
- /usr/local/var/com.github.uhppoted on MacOS
- ./uhppoted on Microsoft Windows
--lockfile Optionally specifies the path to the lockfile used to serialize ACL requests. Defaults
to <workdir>/.wild-apricot/uhppoted-uhppoted-app-wild-apricot.lock.
--log <file> Optional output file for a summary of the load operation. Formatted as
headerless TSV if the file has a .tsv extension. worksheet
--report <file> Optional output file for a detailed report of the load operation.
Formatted as headerless TSV if the file has a .tsv extension.
--config File path to the uhppoted.conf file containing the access
controller configuration information. Defaults to:
- /etc/uhppoted/uhppoted.conf (Linux)
- /usr/local/etc/com.github.uhppoted/uhppoted.conf (MacOS)
- ./uhppoted.conf (Windows)
--debug Displays verbose debugging information, in particular the
communications with the UHPPOTE controllers