Overview
Auto-assignment is Housing.Cloud's powerful automated matching engine that uses YOUR rulesets to automatically generate optimal room assignments for approved applicants. Instead of manually reviewing hundreds of applications and finding compatible matches, auto-assignment analyzes tags, preferences, and compatibility rules to propose assignments in minutes.
Who this is for: Housing directors, assignment managers, and staff responsible for assigning large numbers of students to housing.
What you'll learn: How auto-assignment works, algorithm options, building priority strategies, how to review and accept proposals, understanding assignment confidence scores, handling failed assignments, and finalizing the workflow.
Duration: 25 minutes
Major Time Saver: Auto-assignment can process hundreds of applications in minutes—a task that would take days manually. The algorithm respects YOUR rulesets (from PLS-4), ensuring compatible roommate matches and appropriate room placements while saving significant staff time.
How Auto-Assignment Works
Think of auto-assignment as a multi-stage workflow where you maintain control at every step. First, you select which approved applications to assign. Then you configure how the algorithm should work—choosing between optimization strategies, setting building priorities, and deciding whether to respect roommate groups.
The system processes your selections and generates assignment proposals using YOUR ruleset (created in PLS-4). Every proposal comes with a confidence score explaining how well it matches the student's preferences and your compatibility rules. You review each proposal, accepting those that work and rejecting those that don't. Finally, you finalize the workflow to convert accepted proposals into actual residency assignments.
Throughout this process, YOUR ruleset determines compatibility. Tags from student applications (applied via YOUR form in PLS-5) drive the matching logic. The algorithm never assigns students in ways that violate your hard rules (requirements that must be met)—it only proposes valid matches, though some proposals may not meet all soft rules (preferences that contribute to scoring).
Prerequisites for Auto-Assignment
Before running auto-assignment, verify:
✓ Applications are in "Approved" status (reviewed in PLS-8B)
✓ Your housing cycle has a ruleset assigned (configured in PLS-6)
✓ Students have tags applied from form responses (from YOUR application form)
✓ Inventory has available beds for the cycle dates
✓ You have assignAuto permission
Ruleset Required: Auto-assignment cannot run without a ruleset assigned to your cycle. If you see an error "Assignment workflow scheduled with non-resident cycle," verify your cycle has a ruleset in Setup → Cycles → [Your Cycle] → Application tab.
Step 1: Select Applications for Auto-Assignment
Navigate to Applications
Filter by Cycle and Status: "Approved"
Review the list of eligible students
-
Select applications using checkboxes:
Individual checkboxes for specific students
Header checkbox to select all visible on current page
Click the ellipsis menu (⋮) that appears
Select Auto-Assign Based on Ruleset
Same Cycle Required: All selected applications must be from the same housing cycle. If you select applications from different cycles, the auto-assign option will be disabled with a message: "Cannot auto-assign applications from different cycles."
Step 2: Configure Assignment Parameters
After initiating auto-assignment, you're taken to the Auto-Assignment Setup page where you'll make several strategic decisions about how assignments should be generated.
Review Assignment Overview
The top section shows summary information about your assignment run: the total number of applicants selected, which housing cycle they're applying to (like "Fall 2025 Housing"), and the cycle's date range. This confirmation helps ensure you've selected the right batch of students before configuring algorithm settings.
Select Assignment Algorithm
You'll choose between two different matching strategies that determine how the system pairs students with rooms.
Standard Algorithm (Default)
The Standard algorithm prioritizes finding the absolute best fit for every single applicant. It evaluates every possible room assignment for each student and selects the option with the highest compatibility score based on YOUR ruleset. This means each student gets their individually optimal match.
Use this algorithm when maximizing student satisfaction and roommate compatibility matters most. It works best when you have ample inventory across multiple buildings and care more about individual fit than which buildings fill first. The trade-off: while you'll see higher average assignment confidence scores, some buildings may fill unevenly as students are placed in their best matches regardless of building location.
Experimental Algorithm
The Experimental algorithm takes a different approach by prioritizing complete building fill over individual optimization. It fills rooms in the priority order you specify, accepting lower individual compatibility scores to ensure rooms are completely filled before moving to the next building.
Choose this option when you have strategic building priorities—like filling freshman halls completely before opening upperclass buildings, or when operational efficiency requires predictable building occupancy for staffing purposes. The result: buildings fill more completely and in the order you specify, though some students may receive lower compatibility scores than they would with the Standard algorithm.
Algorithm Selection Strategy: Most institutions use the Standard algorithm for general assignment periods. Use Experimental when you have strategic building priorities (e.g., fill freshman halls first, keep upperclass buildings closed until needed) or when operational efficiency requires predictable building occupancy.
Configure Building Priority (Optional)
Check "Specify Building Priority for Assignment" to control which buildings fill first. When you enable this option, a table appears showing all buildings with available beds for your cycle.
Select buildings in the order you want them filled: the first building you select gets priority, followed by the second, and so on. Each building shows its available bed count to help you make decisions. Buildings you don't select are still considered for assignment but have lower priority.
Example scenario: You manage two residence halls—East Hall and West Hall. For operational efficiency, you want East Hall completely full before opening any beds in West Hall. Select East Hall first, then West Hall second. The algorithm will prioritize placing students in East Hall, only moving to West Hall after East fills up or when students can't be matched there due to ruleset requirements.
Building Priority Requirement: If you check this option, you must select at least one building before proceeding. The "Proceed" button will be disabled until you make a selection.
Configure Roommate Group Preferences (Optional)
Check "Respect Preferred Roommate Groups" to keep student-formed groups together during assignment.
When this option is enabled, the algorithm attempts to assign roommate group members together in the same suite or room. This keeps requested roommates together but may result in sub-optimal individual compatibility matches and more failed assignments if groups can't be physically accommodated in available inventory.
When this option is disabled, the algorithm prioritizes individual best-fit matches based on tags and ruleset compatibility. Roommate groups may be split up if separating them creates better overall compatibility scores. You'll see a higher assignment success rate, but students may not end up with their requested roommates.
Trade-off Warning: The system displays: "Selecting this option might result in sub-optimal pairings and more failed assignments." Check this box only if keeping roommate groups together is more important than individual compatibility scores.
Proceed to Processing
After configuring all parameters, click Proceed to begin processing. You'll see a processing screen showing "Processing Placements... We are generating placements for [N] applicants" with an animated progress bar while the algorithm runs. Processing typically takes 30 seconds to 2 minutes depending on the number of applicants and complexity of rulesets.
Step 3: Review Auto-Assignment Proposals
After processing completes, you're taken to the Auto-Assignment Proposal page with four tabs organizing the results.
Understanding the Tabs
Proposed (TODO): Assignments awaiting your review and decision
Accepted: Proposals you've approved
Rejected: Proposals you've declined
Assignment Failed: Applicants for whom no valid assignment could be generated (only visible if failures exist)
Each tab shows a count (e.g., "Proposed (45)", "Accepted (12)", "Rejected (3)") helping you track progress through the review process.
Reviewing Proposals in Table View
The Proposed tab shows a table with columns:
Name: Applicant name with checkbox for multi-select
Proposed Assignment: Bed location (e.g., "East Hall - Suite 2 - Room 201 - Bed A")
Submission Date: When they applied
Profile Tags: Tags on their profile
Application Tags: Tags specific to this application
Roommate Group Size: Number in their group (0 if none)
Assignment Confidence: Score from 0-100% with visual progress bar
Action: Accept, Reject, or View Details buttons
You can sort by any column (e.g., sort by Assignment Confidence to see lowest scores first) and filter using the filter button.
Understanding Assignment Confidence Scores
The Assignment Confidence score indicates how well the proposed assignment matches the student's preferences and YOUR ruleset requirements. This score helps you quickly identify excellent matches versus assignments that technically work but don't align perfectly with preferences.
Score Ranges
90-100%: Excellent match. All or most rules satisfied, preferences met.
75-89%: Good match. Most rules satisfied, some preferences met.
50-74%: Acceptable match. All hard rules met, but many soft rules or preferences not matched.
Below 50%: Poor match. All hard rules met (required for proposal to exist), but most soft rules and preferences violated.
All Proposals Are Valid: Any proposal that appears in the Proposed tab has met all hard rules from YOUR ruleset. A low confidence score means soft rules and preferences weren't matched, but the assignment is still technically valid and can be accepted.
What Affects the Score
Assignment confidence is calculated from several factors. Hard rules from YOUR ruleset must always pass—these are requirements like "Student with tag X must have room with tag Y." Green checkmarks indicate these passed. Soft rules are preferences that add or subtract percentage points, like "Student with tag A prefers roommate with tag B."
The score also considers whether the student got their preferred building, whether they got their preferred room type (single, double, suite, etc.), and whether they were assigned with their requested roommates.
Example score breakdown:
Base: 100%
+ Matched building preference: +5%
+ All hard rules passed: ✓ (required)
- Soft rule not matched (sleep schedule): -10%
- Room type not matched: -15%
+ Assigned with requested roommate: +10%
Total: 90%
Viewing Assignment Details
Click View Details on any proposal to open a detailed review modal showing everything about the proposed assignment.
Assignment View (Default)
The modal opens with the applicant's name and avatar at the top, along with any roommate group membership tags. A large Assignment Confidence percentage (like "87%") displays prominently, with a status badge if you've already accepted or rejected this proposal. A toggle button labeled "To Explanation" lets you switch to the scoring breakdown view.
The Proposed Assignment section shows the building (with a green checkmark if it matches building preference), suite name, room name, room type (with a checkmark if it matches room type preference), bed name, and a list of bed features and tags.
Below that, the Inventory Preferences section shows whether building and room type preferences were matched and their score contributions. If the student is in a roommate group, the Matching Group section shows whether they were assigned with their wanted roommates and the score impact.
The Proposed Roommates/Suitemates table lets you toggle between viewing roommates and suitemates, showing their names, profile tags, application tags, and answers from the application form. A red exclamation icon (!) indicates a roommate was NOT in this auto-assignment batch—they were assigned separately.
Explanation View (Score Breakdown)
Click "To Explanation" to switch to the scoring breakdown view, which shows exactly how the confidence score was calculated.
The Inventory Rules section lists all inventory rules (Hard and Soft) from YOUR ruleset. Green percentages show matched rules with explanations like "+10%: Student with 'First-Year' matches room with 'First-Year Hall'." Red percentages show non-matched rules like "-15%: Student prefers 'Single' but assigned to 'Double'." Green checkmarks appear next to Hard Rules that cannot be broken.
The Roommate Rules section lists roommate compatibility rules from YOUR ruleset and shows which rules matched with assigned roommates and their score contributions. The Total Score at the bottom shows the overall Assignment Confidence with a complete breakdown of positive and negative contributions.
Use Explanation View for Low Scores: When you see a proposal with 60% or lower confidence, switch to Explanation view to understand exactly which rules weren't matched. This helps you decide whether to accept the sub-optimal match or reject and manually assign later.
Making Decisions on Proposals
Once you understand a proposal, you'll accept or reject it based on whether it meets your assignment standards.
Individual Accept/Reject
From the table view or detail modal, click Accept to approve the proposal or Reject to decline it. The item moves from the "Proposed" tab to either "Accepted" or "Rejected." You can change your decision later by visiting those tabs and using "Un-Accept" or "Un-Reject" options to move proposals back to Proposed for reconsideration.
Bulk Accept/Reject
To make decisions on multiple proposals at once, select multiple items in the Proposed tab using checkboxes. A selection menu appears showing the count (like "15 items selected"). Click the dropdown menu and select either "Accept selected" or "Reject selected" to move all selected items to the appropriate tab.
Efficient workflow tip: Sort by Assignment Confidence in descending order. Select all proposals with 85%+ scores and bulk accept them. Then individually review proposals with lower scores to make case-by-case decisions.
Handling Failed Assignments
If the algorithm couldn't generate valid assignments for some students, the Assignment Failed tab appears with a count of failures.
Why assignments fail:
No available inventory matches all hard rules
Roommate group size exceeds available suite capacity
Conflicting hard rules cannot all be satisfied simultaneously
Student has tags that exclude them from all available inventory
What the tab shows:
Applicant name
Profile and application tags
Roommate group information
Most Likely Reason: Explanation of why assignment failed
Example reason: "Person tagged [Vegetarian] must have [Shared Kitchen]" — but all shared kitchen rooms are full.
Failed Items Cannot Be Accepted: You cannot accept or assign failed items through auto-assignment. You'll need to either manually assign them later (PLS-8C), adjust YOUR ruleset to be less restrictive, or add more compatible inventory.
Resolving Failed Assignments
Option 1: Relax Rules
Review YOUR ruleset in Setup → Rules
Convert hard rules to soft rules for more flexibility
Re-run auto-assignment with adjusted ruleset
Option 2: Manual Assignment
Note which students failed
After finalizing auto-assignment, manually assign failed students using override methods (PLS-8C)
Option 3: Add Compatible Inventory
Add tags to more rooms to match student requirements
Open additional buildings with compatible features
Re-run auto-assignment
Viewing the Ruleset
At any time during review, click View Ruleset to see YOUR ruleset in a read-only modal.
This shows:
Hard Rules: Requirements that must be met (cannot be violated)
Soft Rules: Preferences that contribute to scoring (can be unmet)
Rule descriptions with involved tags
This helps you understand why certain assignments were proposed and why others failed.
Step 4: Finalize Auto-Assignment
Once all proposals in the Proposed tab are reviewed (the count shows 0), the page displays "All Done" with a summary showing suggestions accepted, suggestions rejected, and failed to suggest counts.
Click Finish Auto-Assignment to finalize.
What happens:
All accepted proposals become actual residency records
Application statuses change from "Approved" to "Resident"
Residency statuses are set to "Assigned"
Bed statuses update to "Occupied"
Housing charges are posted based on YOUR charge codes
Students receive assignment notifications (if enabled)
You're redirected back to the Applications page
Finalization is Permanent: Once you click "Finish Auto-Assignment," accepted proposals become real assignments. Rejected proposals return to "Approved" status and can be included in future auto-assignment runs or manually assigned.
Viewing Historical Workflows
After completing an auto-assignment workflow, you can view it later by navigating to Workflows from the admin portal. The table shows all completed workflows with ID, who created it (the staff member who ran it), total items reviewed, items accepted, and items rejected. Click any row to review the workflow results for reporting or auditing purposes.
Real-World Auto-Assignment Example
Scenario: You have 150 approved applications for Fall 2025. You want to fill East Hall first, then West Hall, keeping roommate groups together where possible.
Your workflow: Filter applications to Fall 2025 with Status "Approved" and select all 150 applications. Click the ellipsis menu and choose Auto-Assign Based on Ruleset. On the Setup page, select the Experimental algorithm for building fill priority, check "Specify Building Priority" and select East Hall first followed by West Hall, then check "Respect Preferred Roommate Groups." Click Proceed and wait 60-90 seconds for processing.
The system generates 135 proposed assignments and 15 failed assignments. Sort by Assignment Confidence, select all proposals with 80%+ scores (110 students), and bulk accept them. Individually review the remaining 25 proposals with lower scores, accepting 20 and rejecting 5 that you'll manually assign later. Review the Failed tab to understand why 15 students couldn't be assigned. Finally, click Finish Auto-Assignment.
Result: 130 students assigned automatically in under 15 minutes. 20 students (5 rejected + 15 failed) will be manually assigned using special considerations.
Common Auto-Assignment Issues
Issue: High Number of Failed Assignments
Cause: Too many hard rules, or hard rules conflict with available inventory.
Solution: Review YOUR ruleset. Convert some hard rules to soft rules. Add more inventory with compatible tags. Consider whether all hard rules are truly required.
Issue: Low Confidence Scores Across All Proposals
Cause: Soft rules and preferences are not being met, or available inventory doesn't match student preferences.
Solution: Review if this is acceptable (hard rules are still met). Consider adjusting soft rules. Add more diverse inventory options. Students may not get ideal preferences but assignments are still valid.
Issue: Roommate Groups Are Split Up
Cause: "Respect Preferred Roommate Groups" was unchecked, or group members had conflicting tags making them incompatible.
Solution: If groups must stay together, reject these proposals and re-run auto-assignment with "Respect Preferred Roommate Groups" checked. Or manually assign the group using Method 1 (PLS-8C).
Issue: "Cannot Auto-Assign Applications from Different Cycles" Error
Cause: You selected applications from multiple cycles (e.g., some Fall 2025, some Spring 2026).
Solution: Filter to show only one cycle. Deselect all. Select applications from a single cycle only.
Issue: Proposed Roommate Shows Red Exclamation (!) Icon
Cause: The proposed roommate was not included in this auto-assignment batch. They were assigned separately (different workflow or manual assignment).
Meaning: If you accept this proposal, the applicant will be assigned, but their assigned roommate may not be from the current batch—creating potential mismatch.
Solution: Verify the roommate's assignment status before accepting. Consider whether this pairing is still valid given the roommate was assigned elsewhere.
Auto-Assignment Best Practices
Run Multiple Passes: Don't try to assign everyone in one workflow. Run auto-assignment for first-years first, then transfers, then graduate students. This allows you to use different building priorities and settings for each population.
Review Failed Items First: Before accepting proposals, check the Assignment Failed tab. Understanding why assignments failed helps you identify ruleset issues or inventory gaps that might affect future assignments.
Don't Bulk Accept Everything: While tempting, bulk accepting all proposals without review can miss important issues. At minimum, review proposals with confidence scores below 70% before accepting.
Combine Auto and Manual: The most efficient workflow is to auto-assign the bulk of students (those with straightforward requirements), then manually assign special cases, failed assignments, and students with unique circumstances. This combines speed with precision.
What's Next
Continue your Product Learning Session 8 journey:
PLS-8E: Managing Residency Changes - Learn how to cancel, transfer, and swap residencies after initial assignment
Complete PLS-8: PLS-8: Managing Applications & Assignments
Auto-Assignment Mastery: You now understand how to use Housing.Cloud's powerful auto-assignment engine to efficiently assign large batches of students while respecting YOUR rulesets and preferences. Combined with manual assignment skills from PLS-8C, you can handle any assignment scenario efficiently.