NeonOne Integration

Decatur Makers stores membership and training records in our Neon One CRM account. We store machine access rights (really, trainings / safety checks) as custom fields on members’ Accounts.

Support for this is provided by the neongetter entrypoint (dm_mac.neongetter), which will use the Neon One API to generate users.json.

Configuration

First, export the name of your Neon organization as the NEON_ORG environment variable and your Neon API key as the NEON_KEY environment variable.

You will then need to generate a neon.config.json configuration file. An example configuration file can be dumped to STDOUT by running neongetter --dump-example-config and a description of the fields can be seen in the below JSON Schema. In some cases you will need to know the names of fields and custom fields set up for Accounts in your Neon instance. This information can be obtained by running neongetter --dump-fields.

You can either save your configuration file to neon.config.json in the directory that you run neongetter from, or specify the full path to the file in the NEONGETTER_CONFIG environment variable.

In order to activate the newly-updated users config immediately (i.e. without restarting the machine-access-control server), set the MAC_USER_RELOAD_URL environment variable to the full URL to the /api/reload-users endpoint. If you are running MAC in a Docker container and neongetter in the same container (i.e. via docker exec), you could set MAC_USER_RELOAD_URL=http://localhost:5000/api/reload-users on the container itself.

Configuration Schema

type	object
properties
full_name_field	Neon field name containing member full name.
	type	string
first_name_field	Neon field name containing member first name.
	type	string
preferred_name_field	Neon field name containing member preferred name.
	type	string
email_field	Neon field name containing member email address.
	type	string
expiration_field	Neon field name containing membership expiration date.
	type	string
account_id_field	Neon field name containing account ID.
	type	string
fob_fields	List of Neon field names containing RFID fob codes. The value of these fields can be either a single string fob code, or a CSV list of multiple fob codes.
	type	array
	items	type	string
	minItems	1
authorized_field_value	Value for name of option indicating that member is authorized / training complete.
	type	string
static_fobs	Optional list of static user entries to be added directly to users.json without querying NeonOne API.
	type	array
	items	type	object
		properties
		fob_codes	List of RFID fob codes for this user.
			type	array
			items	type	string
			minItems	1
		account_id	Account ID for this user.
			type	string
		email	Email address for this user.
			type	string
		full_name	Full name of this user.
			type	string
		first_name	First name of this user.
			type	string
		preferred_name	Preferred name of this user.
			type	string
		expiration_ymd	Membership expiration date in YYYY-MM-DD format.
			type	string
		authorizations	List of authorizations for this user.
			type	array
			items	type	string
		additionalProperties	False
additionalProperties	False

Static User Entries

The configuration file supports an optional static_fobs field that allows you to specify user entries that will be added directly to the generated users.json file without querying the NeonOne API. This is useful for:

Administrative/emergency access fobs to be used if there are problems with NeonOne
Fobs for group events where multiple people may share access
Temporary fobs for users who do not already have their own fob

The static_fobs field is an array of user objects with the following required fields:

fob_codes: Array of RFID fob codes for this user
account_id: Unique account identifier
email: Email address
full_name: Full name of the user
first_name: First name
preferred_name: Preferred name
expiration_ymd: Membership expiration date in YYYY-MM-DD format
authorizations: Array of authorization/training field names

Example:

{
  "full_name_field": "Full Name (F)",
  "first_name_field": "First Name",
  "preferred_name_field": "Preferred Name",
  "email_field": "Email 1",
  "expiration_field": "Membership Expiration Date",
  "account_id_field": "Account ID",
  "fob_fields": ["Fob10Digit"],
  "authorized_field_value": "Training Complete",
  "static_fobs": [
    {
      "fob_codes": ["9999999999"],
      "account_id": "admin-1",
      "email": "admin@example.com",
      "full_name": "Admin User",
      "first_name": "Admin",
      "preferred_name": "Admin",
      "expiration_ymd": "2099-12-31",
      "authorizations": ["Woodshop 101", "CNC Router"]
    }
  ]
}

Important Notes:

Static users are merged with NeonOne users in the final users.json file
Duplicate fob codes between static users and NeonOne users will cause an error
Duplicate fob codes within static users themselves will also cause an error
Static users follow the same validation rules as NeonOne users

Authorization and Custom Fields

This script uses custom fields on users’ Neon Accounts to store whether or not they’ve received the training required for specific machines. The custom fields must be “checkbox” type and must use the same option name to indicate that an account has completed the training; the examples in this project use “Training Complete” as the option name, but that is configurable using the “authorized_field_value” configuration file option.

For each user, their list of authorizations will be made up of the custom field names, which on their account have a value matching the “authorized_field_value”.

Usage

Set up your configuration file and environment variables as described above, then run neongetter. If all goes well, it will write a users.json file in the current directory; a different output path can be specified with the -o option.

Development

Testing of neongetter is slightly different, as it makes external API calls to an API that presumably returns sensitive personal information. The process for testing API calls to neon uses the responses library for testing HTTP requests, and specifically uses the (as of v0.25.3) beta feature of recording actual HTTP responses to a file.

In neongetter add an from responses import _recorder import.
Decorate the method in question (generally run()) with @_recorder.record(file_path="tests/fixtures/test_neongetter/run-raw.yaml") (or a similar decorator for other methods).
Run neongetter with your actual real credentials. DO NOT commit anything to git until instructed!.
Assuming that it finished successfully and created/updated the responses YAML file, remove the import and decorator added in steps 1 and 2.
IMPORTANT Currently, only data in the fields enumerated in neon.config.json are sanitized in the following step!
Run NEONGETTER_CONFIG=tests/fixtures/neon.config.json tests/fixtures/test_neongetter/sanitizer.py tests/fixtures/test_neongetter/run-raw.yaml tests/fixtures/test_neongetter/run.yaml
Examine the generated tests/fixtures/test_neongetter/run.yaml file and ensure it appears sanitized.
IMPORTANT Delete the original tests/fixtures/test_neongetter/run-raw.yaml file.
Add and commit to git.