Updating FUYL Classic users from Active Directory

Overview

FUYL Classic AD Export is a free PowerShell script that builds your FUYL Classic user import files from Active Directory, saving a lot of manual spreadsheet editing.

FUYL Classic doesn't connect to your directory automatically, so users are added and updated by uploading CSV files (see Creating and Updating Locker Users). The script reads your users from AD and compares them with your FUYL Classic export. It then writes the files to upload (new users and changed users), plus a list of users who may need removing.

It's read-only in AD and doesn't connect to FUYL Classic at all; you export your current users and upload the results yourself, so you can review every change first.

Before you start

You'll need a domain-joined Windows machine and an account that can read AD.

• Windows: Windows Server 2016 or later, or Windows 10/11, joined to your domain. A domain controller is ideal, but any domain-joined machine works.
• PowerShell: Windows PowerShell 5.1, built into those versions of Windows (RSAT isn't required).
• Permissions: any account that can read users and groups in AD, which standard domain users can by default.
• FUYL Classic access: an admin login to the LocknCharge Cloud that can export and import users.

Download: FUYL Classic AD Export (zip)

Download and unpack

Windows may block scripts downloaded from the internet. If it does, unblock the zip before you extract it.

1. Download the zip Download it to the machine you'll run it on.
2. Unblock it (if needed) Right-click the zip and choose Properties. If there's an Unblock checkbox, tick it, then click OK.
3. Extract it Extract it to a folder, for example C:\FuylExport.

You can also unblock it from PowerShell:

Unblock-File .\FuylClassicAdExport-*.zip

The folder contains the script, a README, an example config and an empty export folder where your files will be written.

Run setup

Setup asks a few questions (showing real values from your directory as examples) and saves your answers to config.json. It only needs running once.

Open PowerShell in the folder you extracted to and run:

powershell -ExecutionPolicy Bypass -File .\FuylClassicAdExport.ps1 -Setup

Setup walks you through these choices:

1. Base OU The OU to read users from. Everything below it is included. Pick one from the list, type a word to filter the list, or paste a DN (for example CN=Users,DC=contoso,DC=local).
2. Groups Which users to include, and which groups to give them in FUYL Classic.
   • All: every user under the base OU. Groups found under the base OU are added to their members.
   • None: every user under the base OU, with no groups.
   • Specific: only members of the groups you pick who are also under the base OU. You can give each group a friendlier name for FUYL Classic, for example GS-Year7-Students becomes Year 7.
3. Sample user A user whose details are shown as examples in the next steps. Press Enter to accept the suggestion, or type a name to pick someone else.
4. Name What FUYL Classic shows as the user's name. The default is the AD display name.
5. PIN The AD attribute that holds each user's PIN (for example employeeID), or have the script generate random PINs, or leave PINs alone.
6. RFID The AD attribute that holds each user's card number. Setup shows the card number as-is and with its byte order reversed, so you can pick whichever matches what your readers produce.
7. Tags (optional) Fill tags from an AD attribute (such as department), the user's OU name, or a fixed tag for everyone (such as AD-Sync). You can combine these.
8. Disabled accounts Whether to include disabled AD users. By default they're left out, so they show up in the removal list.
9. Classic export Where you'll save your FUYL Classic user export. Leave it blank for your very first import.
10. Revoke access for removed users See Upload to FUYL Classic.

Setup finishes by showing how many users and groups would be exported, then asks before saving. Run setup again any time to change something; your current answers are shown as the defaults.

Export your users from FUYL Classic

Export a fresh copy of your FUYL Classic users before every run, so the script can tell who's new and who's changed. Skip this step on your very first import if you have no users in FUYL Classic yet.

1. Export your users In the LocknCharge Cloud, select Users in the left-hand menu, then Bulk Actions followed by Export Users, and download the CSV.
2. Save it Save it to the path you gave in setup, for example C:\FuylExport\classic_users.csv.
3. Leave it unchanged Don't open and re-save the file in Excel first. Excel can strip leading zeros from PINs and change long card numbers.

Run the export

Run the script with no options. It writes up to three files to the export folder, named with the date and time, and prints a summary of what it found.

powershell -ExecutionPolicy Bypass -File .\FuylClassicAdExport.ps1

If there's nothing to add, update or remove, that file isn't created.

FUYL Classic accepts up to 5,000 rows per upload, so large files are split into parts ending _1, _2 and so on. Upload each part.

Read any warnings in the summary before uploading. For example, the script warns when two users share a PIN or card number, because FUYL Classic will reject one of them.

Upload to FUYL Classic

Upload new users first, then updates, then deal with removals by hand.

1. Upload new users Upload each new_import file as a user import. In the LocknCharge Cloud, select Users, then Bulk Actions followed by Import Users.
2. Upload updates Upload each update_import file as a user update. In the LocknCharge Cloud, select Users, then Bulk Actions followed by Update Users.
3. Review removals Open delete_manually.csv, check each user, and delete the ones who should go.

Revoke access for removed users (optional): if you turned this on in setup, users who came from AD but are no longer found are also added to the update file, with their PIN cleared, a new random card number and the tag Deleted. Uploading the update removes their access straight away but keeps their account and history, so you can delete them later. Users added to FUYL Classic by hand aren't affected.

How users are matched

Each user is matched by their AD account's permanent ID, so renaming someone or moving them to another OU updates their existing FUYL Classic user instead of creating a new one.

• The ID: the script stores each user's AD objectGUID in FUYL Classic's externalRefId field. It stays the same for the life of the account.
• First run with existing users: FUYL Classic users with no externalRefId are matched by name instead. The update file then adds their ID, and from the next run they match by ID.
• Same names: if more than one person has the same name, the script doesn't link them, and lists those names in a warning so you can put the right ID on each FUYL Classic user, or make the names unique, then export and run again.
• Users with an older ID: if a new AD user has the same name as a FUYL Classic user who already has a different externalRefId (for example from an older import), the script warns you. If they're the same person, clear externalRefId on that user in FUYL Classic, export again and re-run.
• Fields you didn't set up: if you didn't choose a PIN attribute, card attribute, tags or groups, the script leaves those values in FUYL Classic as they are.

Settings reference

Setup writes config.json for you, but you can also edit it in Notepad. Keep it valid JSON: write every backslash in a path twice (C:\\FuylExport\\users.csv) or use forward slashes (C:/FuylExport/users.csv), and write true and false without quotes. Relative paths are relative to the folder config.json is in.

Running on a schedule

You can run the export from Task Scheduler, but you still need to export from FUYL Classic before each run and upload the files afterwards.

Use the same command as in Run the export, with the full path to the script, for example:

powershell -ExecutionPolicy Bypass -File C:\FuylExport\FuylClassicAdExport.ps1

If the FUYL Classic export file is missing when the script runs, it warns and treats every user as new. Check the summary before uploading, so you don't add everyone a second time.

Troubleshooting

The most common messages, and how to fix them:

If you need a hand, contact support with the version number shown when the script starts, your config.json and the full message.