This process is highly technical and will require someone to create one or more automated scripts (using whatever programming language you prefer).
Step 1 - Create your files
The first step is to create an employee file and positions file (where appropriate) that includes every Active employee. For more information about the file formats, see:
- For employee file format - see XML File Format (Employees)
- For position file format - see XML File Format (Positions)
Step 2 - Verify your files
BEFORE you post your files, you should always verify that they are correctly structured and contain valid data (e.g. a valid email address format) for every Active employee. This will avoid your files being rejected. To do this:
- Call our REST API to retrieve the appropriate XSD schema file (see below)
- Use an appropriate function (in your preferred programming language) to check it validates against the schema
To download the appropriate schema, see the following endpoints in the REST API article:
- For employee schema, refer to "GET /admin/api/v2/hrdatasync/employees.xsd"
- For position schema, refer to "GET /admin/api/v2/hrdatasync/positions.xsd"
If you are providing a positions file (hierarchy) you should also check the hierarchy is valid otherwise your file will be rejected. In a valid hierarchy, employees report all the way up to the MD/CEO.
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 files to our REST API
For more information, see the following endpoints in the REST API article:
- For employee files, refer to "POST /admin/api/v2/hrdatasync/employee"
- For position files, refer to "POST /admin/api/v2/hrdatasync/position"
Step 4 - System Validation (Schema)
Once the file has been successfully received it will 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, NO CHANGES will be made to the data we store
- If the file validates against the schema, it will be queued for processing
Step 5 - Processing & Data Checks
Employee files will always be processed ahead of position files. This ensures the employee exists when they are assigned to a position.
- The data processor runs every 5-15 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 added, employees removed, hierarchy changes applied, etc.)
- Every sync cycle must sync your entire HRIS roster of Active employees; Any employee excluded from the employee file will be automatically deleted from the recognition platform
A non-critical notification will 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.
Please see the following articles: