Skip to main content

Set Up Bulk Room Access Mapping

Quick Setup

Most hotels can test a small room range in 5 to 10 minutes. Run a dry run first.

Use these scripts when you need to map many rooms at once for keycard encoders or smart locks.

Quick reference​

ScriptWhat it doesBest for
scripts/bulk-keycard-room-mapping.mjsCreates or updates keycard encoder room mappingsEncoder room names follow a clear pattern
scripts/bulk-smart-lock-room-mapping.mjsCreates or updates smart lock room mappingsLocks are named or assigned in bulk

Before you start​

Confirm these items first:

  • You can log in with merchant credentials
  • You know the target merchant ID
  • Your env file includes TEST_MERCHANT_ID, TEST_USERNAME, and TEST_PASSWORD
  • You are running the command from the repository root
Load your environment

Set your env file before running the scripts:

set -a
source packages/e2e-tests/.env.production-cloudbeds
set +a

If your env file has a different name, change the path.

Step 1: Test a small range​

  1. Run a dry run for a small room range.
  2. Review the output carefully.
  3. Confirm the room names match the rooms you expect.

Keycard encoder example​

node scripts/bulk-keycard-room-mapping.mjs \
  --merchant-id "$TEST_MERCHANT_ID" \
  --username "$TEST_USERNAME" \
  --password "$TEST_PASSWORD" \
  --room-name-pattern 'TES({n})' \
  --start 10 \
  --end 20 \
  --dry-run

Smart lock example​

node scripts/bulk-smart-lock-room-mapping.mjs \
  --merchant-id "$TEST_MERCHANT_ID" \
  --username "$TEST_USERNAME" \
  --password "$TEST_PASSWORD" \
  --vendor igloohome \
  --room-name-pattern 'TES({n})' \
  --lock-id 'IGB40903c5f5' \
  --start 1 \
  --end 5 \
  --allow-assigned-elsewhere \
  --dry-run

Step 2: Run the real mapping​

  1. Remove --dry-run.
  2. Keep the same room range.
  3. Run the command again.

Use --update-existing if you need to correct existing mappings.

Keycard encoders​

Use scripts/bulk-keycard-room-mapping.mjs when encoder room names follow a predictable pattern.

What it does​

  • Resolves PMS rooms from /api/rooms
  • Creates or updates /api/keycard-encoder-room-mapping
  • Generates encoderRoomName from the room number

Example​

node scripts/bulk-keycard-room-mapping.mjs \
  --merchant-id "$TEST_MERCHANT_ID" \
  --username "$TEST_USERNAME" \
  --password "$TEST_PASSWORD" \
  --room-name-pattern 'TES({n})' \
  --start 10 \
  --end 300

Smart locks​

Use scripts/bulk-smart-lock-room-mapping.mjs when you need to map many rooms to smart locks.

What it does​

  • Resolves PMS rooms from /api/rooms
  • Loads devices from /api/integrations/devices?vendor=...
  • Checks existing mappings from /api/mappings/room-lock
  • Sends bridge metadata when the selected lock provides it

Common modes​

  1. Use one fixed lock across many rooms.
  2. Match locks by device name.
  3. Match locks by lock ID pattern.

Example​

node scripts/bulk-smart-lock-room-mapping.mjs \
  --merchant-id "$TEST_MERCHANT_ID" \
  --username "$TEST_USERNAME" \
  --password "$TEST_PASSWORD" \
  --vendor igloohome \
  --room-name-pattern 'TES({n})' \
  --device-name-pattern 'TES({n})' \
  --start 1 \
  --end 20 \
  --dry-run

Troubleshooting​

What you see: The dry run shows the wrong rooms​

Fix:

  1. Check your --room-name-pattern.
  2. Confirm your --start and --end values.
  3. Run the dry run again.

What you see: A room already has a different mapping​

Fix:

  1. Confirm the new mapping is correct.
  2. Rerun with --update-existing.
  3. Verify the room in the UI.

What you see: A lock is already assigned elsewhere​

Fix:

  1. Confirm reuse is intentional.
  2. Add --allow-assigned-elsewhere only for shared locks.
  3. Rerun the script.

What you see: No rooms appear​

Fix:

  1. Confirm PMS rooms load in AVA.
  2. Refresh the page.
  3. Check the merchant ID and credentials.

Still Stuck?​

Contact success@vouch-technologies.com if:

  • ❌ The script keeps failing after a dry run
  • ❌ Mappings save but do not appear in AVA
  • ❌ You are unsure which mapping mode fits your property

Helpful to include:

  • Screenshot of the command output
  • Merchant ID
  • Vendor name and lock model
  • Time the issue started