An ICIMS onboarding portal not working is rarely a platform problem. In the instances we audit, it is a handoff problem: the candidate was advanced to Hired, the recruiter assumed the rest happened automatically, and one field, one click, or one email address was off. The new hire sees a login page that rejects them. The recruiter sees a status that never moves. Nobody sees the cause.
This guide walks through the seven causes we check, in the order we check them. Each one has a symptom, a place to look, and a fix. If you are still building your onboarding configuration rather than repairing it, start with our ICIMS onboarding setup guide and come back here when something misbehaves.
How the ATS to onboarding handoff actually works
Every one of the seven causes lives somewhere in this sequence, so it helps to have it in your head before you start clicking.
A recruiter opens the job, finds the candidate on the People tab, clicks Advance, and picks the Hired status. That opens the New Hire window. Inside it there is a Notifications section, an Actions section, an Employee Fields section (this is where Start Date lives), an option to move the job to the Closed (Filled) folder, and a picker for the Onboarding Workflow filtered by New Hire Category. The suggested onboarding workflow tasks are pre-selected. When the recruiter clicks Send, ICIMS emails the Onboard Welcome Letter, and that letter is what grants portal access.
From there the onboarding workflow has its own status track: Ready to Onboard, Onboard in Progress, Onboard Complete, plus No Show and Closed. Statuses move automatically as tasks complete. Anyone can add more tasks later from the person profile’s Onboard Status tab, and each task notification is sent by the user who assigned that task.
Cause 1: The Onboard Welcome Letter never went out
Symptom: the new hire says they never got anything. The recruiter is certain they hired the candidate. The job is closed and filled.
Why it happens: the welcome letter only goes out when someone clicks Send in the New Hire window. We see three ways that step gets skipped. The recruiter advanced the candidate to Hired through a bulk action or a list view, which does not open the New Hire window. The window opened but was closed before Send. Or the notification checkbox in the Notifications section was cleared, often by a recruiter who did not want to email a candidate “yet” and never came back.
Where to look: open the person profile and check the Onboard Status tab. If there are no tasks assigned at all, the workflow was never launched. If tasks are there, check the email history on the profile for the welcome letter. No letter in the history means it was not sent, not that it bounced.
Fix: resend the welcome letter from the profile, or if no workflow was assigned, go to the Workflows tab, find the Onboarding section, and use Take Action to launch the onboarding workflow properly. Then confirm the letter appears in the email history before you tell the new hire to check again.
Cause 2: The login email does not match the hired profile
Symptom: the new hire got the welcome letter, clicked the link, and the portal rejects their password or says the account does not exist. Password resets go nowhere.
Why it happens: the new hire’s portal account is tied to the email on the person profile that was advanced to Hired. Candidates often have more than one profile in an instance: one from a job board apply two years ago with an old address, one from an employee referral, one they created themselves last month. If the recruiter hired the older profile, the welcome letter went to the old email (or a forwarding address), and the new hire is now trying to log in with the new one.
The second version of this is simpler: the new hire is going to the career portal login instead of the onboarding portal link in the letter. The credentials are the same person, but the portals are different, and a candidate account that never applied through that specific career portal will not be recognized there.
Where to look: search the new hire by last name and by both email addresses. Compare the email on the hired profile to the one they are typing. Then ask them for the exact URL they are on.
Fix: correct the email on the hired profile (or merge the duplicate so the hired record carries the right address), resend the welcome letter, and send the new hire the onboarding portal link directly rather than telling them to “log in to ICIMS.” If duplicate profiles are a recurring theme in your instance, that is a data hygiene project worth doing once, properly, rather than one new hire at a time.
Cause 3: The wrong onboarding portal is assigned
Symptom: the new hire can log in, but the portal has the wrong logo, the wrong welcome page, forms in the wrong language, or tasks that belong to a different business unit. Or the portal is nearly empty.
Why it happens: instances with more than one onboarding portal (one per brand, country, or employee population) rely on the Assign Onboard Portal field to route each new hire. That field is a single-select dropdown on the onboarding workflow. When it is blank, defaults to the first portal, or is set by a recruiter who guessed, the new hire lands in the wrong experience. The tasks may still be correct, because tasks come from the workflow profile, but the pages, branding, and any portal-specific content will not be.
Where to look: the onboarding workflow on the person profile. Check the Associated Onboard Portal value against the new hire’s entity and location.
Fix: set the correct portal and resend the welcome letter so the link points to the right place. Longer term, stop relying on recruiters to pick it. Tie portal assignment to a job field such as company or location through the New Hire Category so the right portal is suggested by default. If you manage several portals and a lot of hiring volume, this is exactly the kind of maintenance our ICIMS managed services team keeps current every month so your recruiters never have to think about it.
Cause 4: The status is stuck in Ready to Onboard
Symptom: the HR team’s onboarding tracking panel shows a new hire in Ready to Onboard for a week. The start date is three days away. Nobody has called.
Why it happens: Ready to Onboard means tasks are assigned and nothing has been started. It moves to Onboard in Progress automatically once the new hire acts on a task. So a stuck status is not a status problem. It is a signal that one of the first three causes is in play and nobody noticed, because the recruiter’s job is closed and the HR coordinator only sees a list.
Where to look: the Onboard Status tab on the person profile shows each task with its due date and a color state: gray for not started, yellow for started but incomplete, green for complete. All gray with a start date this week is your alert.
Fix: run causes 1 through 3 on that record. Then build the alert you were missing: a saved search or dashboard panel for onboarding workflows in Ready to Onboard with a start date inside seven days, owned by a named coordinator. We would rather a coordinator see that list every morning than discover it on day one.
Cause 5: Tasks are blocked by dependencies or assigned to the wrong role
Symptom: the new hire is in the portal and sees two tasks when HR expects nine. Or the direct deposit form is “waiting” with no explanation. Or the hiring manager says they were never asked to do anything.
Why it happens: onboarding tasks are built in the workflow task library, and each has an assignee (the new hire, HR, the hiring manager, IT) and optional dependencies. A dependent task does not appear for its assignee until the task it depends on is complete. That is by design and it is a good design. The problem is when the prerequisite is assigned to someone who does not know they own it: an HR admin task sitting in a departed coordinator’s queue, or a hiring manager task assigned to a manager who never logs in.
Our setup guide covers dependency chains in depth, so here we will stay on the diagnostic side. The question is not “why can’t the new hire see the form” but “what does that form depend on and who owns that.”
Where to look: the Onboard Status tab lists every task and its assignee. Trace the missing task back to its prerequisite. If the prerequisite belongs to a hiring manager, check whether that manager can actually log in: a manager who is not in the right login group, or who has never activated their account, will never clear the task. We wrote up the mechanics in our guide to ICIMS login groups setup.
Fix: reassign the stuck prerequisite to someone active using the Edit (pencil) icon on the task, or complete it on their behalf if policy allows. Then revisit the workflow profile so the same role is not a bottleneck for the next hire. If a task is an iForm that will not submit, confirm the form itself is published and attached correctly; our ICIMS iForms setup guide walks through the publishing steps.
Still have a new hire locked out?
Bring the record to a discovery call. We will look at the welcome letter history, the hired profile, and the portal assignment with you and tell you which of these seven causes applies to your instance. One client cut support tickets 90% in 90 days after we fixed the handoffs behind problems like this.
Book a discovery callCause 6: A partner task (I-9, E-Verify, WOTC) is rejecting the record
Symptom: everything works until the new hire clicks the I-9 task. Then they get an error page from the vendor, or the task bounces back to the portal incomplete with no explanation.
Why it happens: compliance tasks such as I-9, E-Verify, and Work Opportunity Tax Credit screening hand the new hire to a partner and expect the partner to send them back marked complete. ICIMS sends the partner the person and job data along with a completion URL and an incomplete URL. If the partner cannot accept the data, the new hire is returned through the incomplete path and the task stays open.
The rejections are almost always ICIMS data, not the vendor. The errors documented by one widely used I-9 partner are a good checklist: the I-9 Business Unit or I-9 Worksite on the profile does not match a valid employer and worksite pair on the vendor side; the worksite has no street address; the start date is missing; or the date of birth was keyed with the current year instead of the birth year, which trips the vendor’s age check.
Where to look: the Employee Fields on the hired profile, and the I-9 Business Unit and I-9 Worksite values specifically. Then the worksite record itself.
Fix: correct the field in ICIMS, then have the new hire reopen the task from the portal. Do not mark the task complete manually to make it go away; the vendor never received a valid record and the compliance gap is real. If you see the same error on every hire at one location, the worksite mapping is wrong at the source and a one-time fix in the integration settings will stop the tickets. Integration mappings like this are where a focused ICIMS system audit pays for itself quickly.
Cause 7: Reminders come from a user who no longer sends them
Symptom: new hires used to get task reminders. Now they do not, or the reminders arrive from a recruiter who left the company in June and land in spam or get ignored.
Why it happens: task notifications are sent by the user who assigned each task. When the assigning recruiter is deactivated, moved to a different login group, or has their email changed, the reminders for every task they assigned inherit that change. This is one of the quieter causes because nothing errors. The new hire simply stops hearing from you.
Where to look: the assignment history on the Onboard Status tab. Identify who assigned the tasks for the affected hires and check that user’s status.
Fix: for the affected hires, reassign the tasks from an active user so the next reminder comes from a real mailbox. For the future, assign onboarding tasks from a shared onboarding coordinator account or a role that survives turnover, and add “reassign onboarding tasks” to your offboarding checklist for recruiters. We cover this handoff in our guide to transitioning when an ICIMS admin leaves, and the same logic applies to any user who assigns tasks.
How to keep the ICIMS onboarding portal working after you fix it
Fixing one new hire is a support ticket. Fixing the pattern is the work. These are the five controls we put in place after a round of portal issues.
Make Send the only path to Hired. Train recruiters that Hired is reached through Advance on the profile, never through a bulk status change, and make the welcome letter checkbox a required step in the recruiter checklist.
Verify the email before the offer, not after. Add a step to the offer stage where the recruiter confirms the email on the profile is the one the candidate wants onboarding mail sent to. Merge duplicates at that moment.
Drive portal assignment from the job, not the recruiter. Map New Hire Categories to portals so the right one is suggested automatically. Recruiters should confirm, not choose.
Watch Ready to Onboard daily. One saved search: onboarding workflows in Ready to Onboard with a start date within seven days. One owner. Five minutes a morning.
Assign tasks from a role that outlives people. A shared onboarding user for task assignment means reminders never depend on one recruiter’s employment status.
None of this is heavy. Most of it is a checklist and a saved search. But it is the difference between an onboarding portal that quietly works for every hire and one that becomes a weekly ticket. If your team wants help getting hiring managers and coordinators to actually follow the process, that is what our ICIMS training sessions are built for, and the measured outcomes on our ICIMS ROI page show what happens to ticket volume when the handoffs are fixed.
Frequently asked questions
Turn onboarding portal tickets into a process that runs itself
On a discovery call we will review your Hired handoff, portal assignments, and task ownership, and show you which of the five controls above would remove the most tickets first.
Book a discovery call
