Note: This document details the setup of HR Integration, including helpful tips to ensure a smooth and successful implementation.
What is HR Integration?
HR Integration enables the transfer of employee personal data between a payroll vendor (HRIS software) to the Manager website. The benefit of HR Integration is to keep employees (called “users”) accurate. This can include adding new hires, updating job titles, changing badge numbers, and archiving (deactivating) terminated users. This information is exported from your payroll vendor and imported into the Manager on a nightly, weekly or monthly basis (depending on preference).
HR Integration Process
As diagrammed below, HR Integration involves an export of user information, then a SFTP upload, followed by an import of that data into the Manager. The process can involve several departments in your organization.
Data Transfer Options
Options for retrieving HRIS Data
There are two (2) options for retrieving data from the payroll vendor. We recommend the Automated process, as this ensures that the data will be exported into the exact column structure originally set in place. This helps reduce the risk of corrupt data. See Helpful Tips below for more information.
- Manual Option: A person from your organization manually exports user data directly from payroll vendor in to the proper format
- Automated Option: The HR Payroll vendor creates an automated script that retrieves user data and exports into the properly formatted file structure
Options for uploading file to SFTP server
There are two options for posting the HR Import file to the SFTP server. We recommend the Automated process, as this ensures the HR Import file will consistently be placed on the SFTP server on schedule.
- Manual Option: A person from your organization moves the file onto the SFTP server
- Automated Option: The HR Payroll vendor creates an automated script to move the file onto the SFTP server automatically
Key Points
Logistics and Naming
The Alchemy server is a very particular about the form and formatting. The file name must start with lowercase “hr”. What comes after the “hr” is the client’s decision, but we highly recommend the date (e.g. “hrYYYY-MM-DD.csv” or “hrYYYYMMDD”).
The default file extension is .CSV, but Manager can be configured to accept .TXT instead.
The default is comma delimited (,) but we can also use tab- ( ) or pipe- (|) delimited. If mailing addresses use commas in the import file, consider using a tab- or pipe- delimited style. For more information on commas, see Avoiding Special Characters.
Structure of file contents
Column Structure in hard-coded. There are six required fields that must be included in the import file (see Column Order Description for more details). The remaining fields are optional and can be left empty if the information is not needed for Manager records.
The key identifier is User ID (Employee ID). When the file is processed, the Manager scans for the User ID. If the User ID is a match (between the import file and Manager), the user (employee) is updated with the data associated in the import file.
If the User ID is not found, a new entry will be created within Manager.
Column Order Description
|
Column |
Name |
Description |
Character Limitation |
|
A |
Last Name |
This is the surname of the user (employee) |
50 |
|
B |
First Name |
This is the given name of the user |
50 |
|
C |
User Name |
As internet login. This must be unique for each users (for the entire company). This column is used for: 1.An Administrator Username with which supervisors can run reports and check user transcripts. 2.An eLearning username with which students can lo into the Manager Site. 3.A security foolproof that prevents importing duplicate User ID records. This can be alphanumeric. Example Usernames: “12345”, “jsmith”, “jsmith123” |
50 |
|
D |
Password |
This column is for the Password (administrator and eLearning student login). |
50 |
|
E |
|
This column is for user email addresses. This is highly recommended for eLearning setup (so that users can use the Forgot Password tool). |
50 |
|
F |
User ID (Employee ID) |
This is the key identifier. This must be unique for each users (across your company’s entire Manager). This can be alphanumeric. Example Usernames: “12345”, “jsmith”, “jsmith123” |
50 |
|
G |
Supervised Groups |
This column is rarely used. This column will make the employee a supervisors/developer in Manger. It will also make them a supervisor of the Group Stated in the column. NOTE: if a Group name is placed in this column for a Group that does not exist, the Group will be created and the employee will supervise that new Group |
100 |
|
H |
Worksite |
This column is used to place a user into their “home group”. The Worksite is normally set to the facility location – typically the city name (e.g., Austin). Sometime Worksites are called Cost Centers. |
80 |
|
I |
Address 1 |
This is the mailing address for the user |
50 |
|
J |
Address 2 |
This is the continuation of Address 1 |
50 |
|
K |
City |
This is the City that the user resides in |
50 |
|
L |
State |
This is the U.S. Stat (or Canadian Province) where the user resides. Currently, supports only two (2) characters |
2 |
|
M |
Zip (Postal Code) |
This is the postal code where the user resides. Currently supports only 5-digit codes. |
5 |
|
N |
Phone 1 |
This is the primary telephone number for the user. |
None |
|
O |
Phone 2 |
The is the secondary phone number for the user |
None |
|
P |
Corporate Groups |
This column is used for reporting. Examples of information placed into this column would include: •Department •Shift •Supervisor •Position Title These will be made into Groups (and the user is placed into the Group). Administrators who supervise the group will be able to see the user in the group (and run reports on the Group itself). In the import file, groups are colon-separated (e.g. “Group A:Group B:Group C”). |
Recommended limit: 80 per group name NOTE: This field has a total limit of 10,000 characters, the equivalent of 125 Corporate Groups with 80 characters each |
|
Q |
Classes |
This column is ignored by default |
None |
|
R |
SSN |
This column must be left blank |
None |
|
S |
Prefix |
This is the prefix for the user (e.g. Mr., Ms., Mrs.) |
None |
|
T |
DOH |
This is the Date of Hire for the user. We recommend the YYYY-MM-DD or MM/DD/YYYY Format |
None |
|
U |
DOT |
This is the Date of Termination for the user. This column is also used to determine whether Manager will Archive the user. We recommend the YYYY-MM-DD or MM/DD/YYYY formats |
None |
|
V |
Position Title |
This is the job title for the user |
50 |
|
W |
Base Rate |
This is the base pay rate for the user. NOT recommended due to visibility |
None |
|
X |
DOB |
This is the Date of Birth for the user. We recommend the YYYY-MM-DD or MM/DD/YYYY format. |
None |
|
Y |
Barcode 1 |
This is the barcode/badge ID number for the user. This is only used when the barcode functionality has been turned on within the Player. |
50 |
|
Z |
Barcode 2 |
This is a secondary barcode number for the user. This is only used when the barcode functionality has been turned on within the Player. |
50 |
|
AA |
Barcode 3 |
This is another barcode number for the user. This is only used when the barcode functionality has been turned on with in the Player. |
50 |
|
BB |
Barcode 4 |
This is another barcode number for the user. This is only used when the barcode functionality has been turned on with in the Player. |
50 |
|
CC |
Barcode 5 |
This is another barcode number for the user. This is only used when the barcode functionality has been turned on with in the Player. Extra information (Such as Notes about the employee) can be stored here. |
50 |
*All fields overwritten by default
Bold= a required field
Helpful Tips
Existing information is overwritten
All user data imported will overwrite any existing user data within the Manager. There are options to not overwrite certain user data fields, if preferred. Contact Alchemy for more information about “ignoring” fields. You have the choice of whether to import only new users, or all existing employees. We recommend importing all users at the same time (as it provides redundancy), but the decision ultimately rests with your organization.
System Groups and Corporate Groups
If System Groups are imported, any Groups that are created by other locations ad hoc will be overwritten by the import. We can prevent this by activating “Corporate Groups”. Contact your Account Manager or Alchemy Customer Support for more information on Corporate Groups.
Avoid Leading Zeroes and Special Characters
One of the biggest challenges is “leading zeroes” (on User IDs, Worksites, Groups, and Barcode IDs). A leading zero would be any sequence of zeroes at the beginning of a number. For instance, an User ID of “00012345” has three leading zeroes.
If not exported properly, Microsoft Excel will strip any leading zeroes. It is your responsibility to make sure that the file comes across with the leading zeros intact.
If HR Integration originally imports the file with the leading zeroes and later imports another file without the leading zeroes, duplicate records will be created (because the User ID does not perfectly match).
The same precaution goes for special characters, such as hyphens (-), dashes (—), commas (,), and semi colons (;). We recommend using alphanumeric characters. For example: a Worksite suggestion would be Austin TX or Austin and a System Group would be Austin Maintenance Dept or Austin Maint Dept.
Options for Worksite Aliases
An Alias can be used if your HR payroll vendor software does not have a means to convert and match what exists in Manager.
If Worksite names are not set up correctly (beforehand), duplicate Worksites will be created (because the Worksite does not perfectly match what exists on Manager). It is the client’s responsibility to supply Alchemy Support with Worksite Aliases as they are managed on the back-end of the Manager and are only accessible by Alchemy.
Errors and Error Corrections
Should erroneous data come through the HR Import, compromising user data, Alchemy will perform services which may result in additional costs. Clean-up efforts can be very time consuming and costly for all parties involved. It is ultimately the client’s responsibility to maintain the user database.
Other import options include Encryption and Reverse Batch Interface (transfer information from Manager to your HRIS