How to sync your HR data¶
To sync your data from your HR/IS system to our recognition platform you post files via one of the following options:
- XML files directly to our REST API (see REST API v2)
- CSV files via our Console App (see Console App)
- We use the employee file to add new employees, replace existing employee information and remove employees who have left.
- We use the position file to syncronise your hierarchy. We add new positions, change existing positions, assign employees to positions and remove old positions.
- At a minimum we recommend that you upload your file(s) on a monthly basis but you can upload them weekly or even daily if you choose.
- We also suggest that you upload files during your office hours to ensure any validation errors can be picked up and fixed by your HR/Technical team.
When using HR Data Sync, all data changes must be made in your system and cannot be overridden manually.
XML File Process¶
This process is highly technical and will require someone to create one or more automated scripts (using whatever programming language you prefer).
We highly recommend you create a Technical administrator account to allow easy access to API keys, error files and to recieve notification emails (see Notifications).
Step 1 - Create your file¶
The first step is to create an employee file and positions file (where appropriate). For more information about the file format, see:
Step 2 - Verify your file¶
Before you post your file you should always verify that it is correctly structured and contains valid data (e.g. a valid email address format). To do this you should call our REST API to retrieve our XSD schema and then use an appropriate validation function (in your preferred programming language ) to check it complies. The schema file you download is the same file we will use to validate your file when you post it.
To download the appropriate schema, see:
- For employee schema, see API > Download Employee Schema (XSD)
- For position schema, see API > Download Position Schema (XSD)
For position files you should also check the hierarchy is valid otherwise your file will be rejected.
How to validate an XML file against a schema is outside the scope of this document as it differs depending on which programming language you use. However, XML is a widely used file format and the internet contains many examples of how to validate them against a schema.
Step 3 - Post your file to our REST API¶
For more information about which API endpoint to use, see:
Step 4 - System Validation (Schema)¶
- Once the file has been successfully received it be validated against the same schema file you used in step 2.
- If the files doesn’t validate against the schema, the ENTIRE FILE will be rejected and NO CHANGES will be made to the data we store.
- If the file validates against the schema, it will be queued for processing.
Employee files will always be processed ahead of position files. This ensures the employee exists when they are assigned to a position.
Step 4 - Processing & Data Checks¶
- The data processor runs every 5 minutes and automatically collects any queued files.
- The file is processed record by record and if an issue is detected ONLY THAT RECORD will be skipped and file processing will continue.
- If there are any errors/warnings an exception file will be generated to help you resolve any issues.
- The employee data and positions will be updated appropriately and any actions taken (e.g. employees addded, employees removed, hierarchy changes applied, etc.)
A non critical notification will be be added to the administration portal for the Primary Administrator and any Technical administrators at the validation and processing steps. An email will also be sent when a notification is added.
However, if any serious errors are found it will generate a critical notification which must be confirmed as read. Please ensure administrators are aware to check and confirm them as they indicate there is a problem with your data which WILL affect your program.
How to manage uploaded files¶
To access the HR Data Sync interface login to your administrator account then click on the Employees menu and select HR Data Sync
Here you can:
- view your uploaded files and status
- download previously processed files
- view error reports
- cancel queued files
- download schema files
- manually upload files (this is only available for testing prior to launch)
The following statuses are used:
|Scheduled||The file has passed validation and has been scheduled (the scheduled date and time will be displayed)|
|Queued||The file has passed validation and has been queued for processing|
|Processing||The file is processing (you can view the % as it processes)|
|Skipped||The file was rejected as it was the same as the last successful file.|
|Blocked||The file was blocked to prevent data issues e.g. the file would have removed more than 75 of your employees (click the link for more information)|
|Error||The file failed validation and was rejected (download the error file to view why)|
|Complete||The file has completed successfully|
|Complete With Errors||The file was processed but 1 or more lines generated a warning (download the error file to view why)|
Welcome Email Process¶
You can import your users pre-launch and an invite will not be sent. Once you are ready you can use the Launch process to send invitations to everyone.
Once your program is live every user added will be automatically sent an email invitation. This contains a link to register, which prompts them to select a password and then sign in to your program.
Do I have to post a position file?
If you are running a program that requires hierarchy you must post an employee file AND a position file. If you are not using hierarchy you only need to post an employee file.
The file says it has been blocked, what does that mean?
To protect your data history the processor will block files that try to make significant changes. For example, if you try to remove more than 75% of your employees or positions. This is not normal and is usually caused by either a data problem (e.g. leading zeros removed from EmployeeID by mistake) or a change in HR systems (e.g. new positonsID’s are different than old positonsID’s).
My position file says it cant find an employee
This happens when you try to assign an employee to a position but the employee does not exist in our system. This usually happens if you try and post a position file without first updating your employees. We suggest that if you are using hierarchy that you post an employee file followed by a position file.
I dont understand the validation errors
Please see the appropriate file specification document for help troubleshooting errors.