I-9HQ Custom Roles and User Management

The migration to I-9HQ will help clients use the User Management option to manage their company users. The actions that users can take in I-9HQ will depend on the type of roles that users are assigned. In this article, we dive into the roles available and adding users to the I-9HQ portal.

In this article:
I-9HQ Roles Overview
I-9HQ User Roles
Custom User Roles
Creating a New Custom Role
User Management
       Adding a User
       Editing a User
       Bulk Adding Users
F.A.Q.
Additional Resources

I-9HQ Roles Overview

User roles are broken into three main categories:

• Standard: These permissions will be applied to all solutions within PeopleHQ.
• I9: Roles specific to I-9 HQ or I-9 Inspect.
• Custom: Custom roles created by you (or another company admin).

Note:

Clients with multiple solutions enabled in PeopleHQ may have additional categories visible in this section. Those categories will house roles specific to that product.

I-9HQ User Roles

There are currently five I-9 specific user roles to choose from when adding a new user. These are preset roles that the majority of customers use within I-9 HQ. Please review the roles and features below.

Role Name	Functionality
I-9 HR Admin	This is the highest-level role, giving the user the ability to manage organization settings, user maintenance, and I-9 business processes*.
I-9 HR Agent	This user can manage all I-9 business processes, but cannot manage organization settings or user maintenance.
I-9 Completer Only	This user can complete I-9 tasks such as Section 2 or Supplement B, but cannot access E-Verify or other business processes*.
I-9 HR Agent - No E-Verify	This user has essential functionality to complete I-9 processes, without access to manage E-Verify tasks.
View Only User	This user has the ability to view employee profiles, Forms I-9s, and reporting options, but cannot complete any I-9 business processes*.
*Business Processes refers to the ability to send I-9 requests to a new hire, leverage reporting, and data management options.

Custom User Roles

Note

Custom roles are available only for iFrame clients. This feature is not supported for SSO clients.

If one of the preconfigured I-9 user roles will not work, then authorized company users will have the ability to create and manage custom roles. To begin:

1. Click Settings, then User Management. (click image to enlarge.)

    

2. Click Manage Custom Roles.

    

3. In Manage Custom Roles, you have the ability to create a Custom Role, edit Existing Custom Roles (if one has been created), or view the Default roles and permissions that already exist in the service.

    

Note:

Existing default permissions cannot be adjusted or edited within your service, but you are able to view which permissions are associated with each role if you are trying to determine what your users will or will not have access to.

---

Creating a New Custom Role

Custom Role Requirements

When creating a custom user role name, ensure it meets the following requirements:

1. Each custom role name must be unique.
2. Role names cannot include leading or trailing spaces.
3. Approved special characters are: hyphen (-), underscore (_), comma (,), and period (.).
4. Role names may include multiple words, separated by a space or an approved special character.
5. Role names may contain alphanumeric characters.
6. Upper and lowercase letters are allowed.
7. Maximum role name length: 40 characters (including spaces and special characters).
8. Maximum role description length: 500 words.

Creating a New Custom Role

1. From Manage Custom Roles, click Create Custom Role.

    

2. Add a Role Name and Role Description. The role description is required. Click Continue.

    

3. Select the permission that this role should have. Our best practice recommendation is to assign product-specific permissions, as opposed to using the Standard user roles. Some examples of the permissions:
   • Access I-9HQ: This permission allows access to the I-9HQ product.
   • Complete E-Verify Scan and Upload Tasks: This permission allows the user to view and take action on E-Verify Scan and Upload Tasks.
   • Complete Form I-9 Section 2: This allows users to complete Form I-9 Section 2 and to view and take action on Pending I-9 tasks.
   • Complete New Hire Packet Tasks: This allows users to view and manage New Hire Packet Tasks.

4. Permissions fall into the following categories:

    

   • I-9 HQ Entitlements: The I-9 HQ section will include options that pertain specifically to I-9 Actions, such as Section 1/2/ or Supplement B completion, E-Verify, reporting, configurations, etc. You will want to read through the options carefully to determine whether or not you want this role to have a specific entitlement.

     TIP: Don’t forget to assign the Access I-9 HQ entitlement. This permission is required for any I-9 HQ user to view and access I-9 HQ.

   • General Permissions: The General Permissions section will include functionality that is aligned with the overall PeopleHQ™ portal. This would include things like the ability to view tasks, access their profile, set up notifications, access/run reports, configure their dashboard, etc. You may notice that some permissions can go hand-in-hand with options you selected in I-9 HQ. For example, if you allow a user role to run certain reports in the I-9 HQ category, you should also select the ‘View Reports’ option under the General Permissions category.
   • User Management: The User Management section allows you to determine if the custom role you are creating should have the ability to Assign Data Access Groups, Manage Employer Roles, Manage Users, and/or Reset Passwords.
5. Once you have selected all of the desired permissions for a role, click Save Custom Role. Please note that it can take up to 10 minutes for a newly created role to be ready for user assignment.

Edit A Custom Role

Note:

Users are unable to edit permissions on their own profile. This must be done by another administrator or your Workforce Solutions Support team. Once a custom role has been added, authorized users will have the ability to edit or delete a role.

Edit a Custom Role

1. Navigate to Manage Custom Roles. (Click Settings, then User Management.)

2. Click on the menu icon for the role you wish to take action on and choose Edit Role.

    

3. You will be brought back to the permissions screen. From here, you can either make changes to the selected permissions. To make changes to the role name or descriptions, click the Actions dropdown and select which change you would like to make.

    

4. After you make changes, select Save Custom Role to apply your changes.

    

5. Saved changes will be applied to all existing users with this role within 10 minutes.

Deleting a Custom Role

Custom roles may only be deleted if there are no user(s) assigned to the role. From the Manage Custom Role, click the menu icon and select Delete Role. You will be presented with a warning message alerting you that a deleted role cannot be recovered. If a user is associated with the role, and if you confirm this screen, you will receive an error message.

• Please note that you may only delete a role from a user’s profile after another has been added. To remove a user’s access completely, you should deactivate their account instead of editing it.

---

User Management

Adding A User

Once a new user is added, they will immediately receive an email inviting them to create an account and log in.

Note:

If your organization is utilizing Single Sign-On (SSO), users should not be added directly in I-9HQ. Instead, they must be granted access through the ClearCompany World of Work App. For more information, refer to: I-9HQ and E-Verify Integration - Setup Guide.

Add User

To add a user:

1. Click Settings, then User Management.

    

2. Click Add a User.

    

3. Complete the fields: First Name, Last Name, Email, Phone, Job Title.

   

4. Select the Roles that the user should have. Please note that you may only delete a role from a user’s profile after another has been added. To remove a user’s access completely, you should deactivate their account instead of editing it.

   

5. Select the Locations this user will have access to.

   

6. Click Save.

---

Editing A User

Edit A User

To edit a user:

1. Click Settings, then User Management.

    

2. Click the pencil icon next to the user you would like to edit.

    

3. To remove a user’s access completely, you should deactivate their account instead of editing it. If the user is currently listed as Active, deactivate the user by clicking Deactivate User on the right-hand side.

    

4. Use the Reset Password option to send a password link to the user. The link will be sent to the email address on file. This is only applicable if your organization is not using SSO through ClearCompany.

5. In the Profile tab, you can click Edit Information to edit: First Name, Last Name, and Job Title.

    

6. Phone number and email address cannot be edited because the email is used to log into the application.

7. The Roles tab allows you to update the roles assigned to a user. For SSO users, roles can be updated in bulk to assign them to a custom role.

    

8. The Locations tab allows you to update which locations a user can access.

    

---

Bulk Adding Users

The Data Management tool is a great option for adding bulk users to your account. This feature can only be used for adding new users (or adding additional roles and location access to existing users) at this time. 

---

Important

Users should only be added if they are currently directly logging into the system. If you are using SSO, users should originate from ClearCompany. This process requires that you first update the relevant data in an Excel file and upload it.

---

Bulk Adding Users: Considerations & Requirements

When preparing your file using the provided template, the following rules apply to all file types:

1. Only one file upload is allowed at a time. Maximum file size: 10 MB.
2. Add new locations (or reactivate inactive locations) before adding users to those locations or sending new hires an I-9 packet assigned to them. Uploading out of order will cause errors.
3. Line items may not process sequentially. If you need specific actions to occur in a certain order, consider splitting the actions into two separate files. Example: You cannot deactivate a primary location until another primary location is assigned. This may require two uploads or a manual update.
4. No special characters are allowed in any file (exceptions: @ in email addresses and - in user roles).
5. Delete all instructional rows from the template, but keep the header row. Do not change the order of the headers.
6. After modifying or formatting the file, use File > Save As and save as CSV (Comma Delimited) (*.csv). If you reopen the file before uploading to PeopleHQ, repeat the Save As process.
7. You may name the file anything you choose. No specific naming convention is required.

Bulk User Fields

The following fields are necessary in your upload template:

Header/Field	Required	Notes
FirstName	Yes	First Name of the user you are adding.
LastName	Yes	Last Name of the user you are adding.
Email	Yes	Email address of the user you are adding.
Phone	Yes	10-digit phone number of the user you are adding with no hyphens. The user could have the ability to receive SMS messages, if desired, to this phone number.
JobTitle	Yes	Job Title of the user you are adding.
Role	Yes	Value should be the user role name (EX: I-9 HR Admin). Roles are case and spacing-sensitive, so please copy exactly. Multiple roles should be separated with a pipe (|).
Locations	Yes	This is the location(s) the user should have access to. You must enter the exact location code that is in PeopleHQ to assign. Multiple location codes should be separated with a pipe (|). If the user should have access to all locations, you can simply enter ALL here. **Users cannot be added to inactive locations from a file upload. This task can only be completed manually by your I-9 HR Admin.
HrUserId	No	This field is not required and will not be read using the Data Management upload feature. Please leave blank.
EmployerCode	No	This field is not required and will not be read using the Data Management upload feature. Please leave blank.

Uploading File

After you complete the spreadsheet with your desired information, you are ready to upload the file.

1. From the dashboard, click Data Management.

    

2. Click Download Template to download the file. Select the New User Template.

    

3. Edit the template with the new users that will be added.

    

4. When ready, click Upload File.

5. Select File Type - User. Then drag and drop or search for the file.

    

6. Click Import.

---

 Notes

• Files containing one or more failed line items will show a Failed status. A failed status does not mean the entire file failed—only the line items identified in the error report.
  Example: If you upload 10 line items and 2 fail, the file status will be “Failed,” total records will show 10, and failed records will show 2. The remaining 8 items processed successfully.
• Most files process within 10–15 minutes; however, files with potential errors may remain In Progress for up to 24 hours until errors are detected and reported.
• Once processing is complete, the file status will update from In Progress to either Success or Failed.

File Notifications

Authorized users can request email notifications when a file has been processed, failed to process, or processed with errors. To set up your notifications:

1. Click My Account, then My Profile.

    

2. Click Settings, and a user can determine how they prefer to receive notifications from PeopleHQ.

    

3. In App will always be selected and appear under the notifications clipboard, pictured on the top navigation bar.

    

4. Opting for email or SMS messages will allow the user flexibility to receive particular notifications to one or more destinations.
5. SMS messages will be sent to the phone number listed on the Profile tab, and standard messaging rates apply.

Additional Resources

I-9HQ Migration & Best Practices
I-9HQ New Hire Experience
I-9HQ Preferences & Settings