A script can be run between your company's HRMS system and Officevibe in order to synchronize users and manage group information. This script will include a set of three CSV files and push them to Officevibe through a secure HTTP connection and authenticated through an Officevibe API token. The process can be run manually, but is engineered to enable automation of the user synchronization process.
Here's a guide to set up the API integration with Officevibe:
1. Creating and configuring the environment
In order to run the script, there will need to be an instance of Windows that can execute a Powershell script and can reach the app.officevibe.com domain on the secure HTTP (443) port. You can extract OV_EnterpriseSyncTool.zip to a folder of your choosing. We will assume C:\OV_Sync.
2. Configuring the Enterprise Sync tool
The configuration of the synchronization process is done through the config.json file at the root folder of the tool (C:\OV_Sync\config.json). The important parameters within the file are the following:
- "ApiKey": This field is used to authenticate the request. If you don't have an API key, you can check with the Officevibe Support team (firstname.lastname@example.org) and they will send the appropriate link.
- "SyncManagerEmail": When the synchronization process is executed, it is associated with an admin account. As such, you need to provide the user email of a user with admin rights.
- "InviteNewUsers": When set to true, this flag will automate the process of sending out the user invites to use Officevibe, instead of having to manually invite employees within the app. This is useful for incremental operations where new employees or changes should be automated, but should be used with caution, as setting it to true can potentially send hundreds or thousands of invites on initial imports.
In addition, if you wish to put the three files mentioned in step 3 in a different location, or set them with a different name, you can also set the appropriate values within this section.
3. Exporting data from the HRMS system to the three CSV files
If you open the three sample files provided in the Data folder (samples attached below), you will see CSV files. These files use a CSV format, separated by comma, escaped with double quotes, with a header line, encoded in UTF-8. You will need to generate these three files from your HRMS and drop the resulting files in the location you configured in config.json. The files contain the following information:
- users.csv: This file contains basic user information. The key identifier for Officevibe is the email address. This is also where you can set fields like first name, last name, job title and language. Creating new users is done by adding a line, and removing a user is done by removing a line.
- groups.csv: This file contains basic group definitions, with an ID and an employee name. This allows for a group to be renamed without consequence as the ID is preserved.
- groups-mapping.csv: This file will assign users to groups, and control additional group settings such as assigned a manager to that group. It is also possible to map sub-groups to groups within this file.
4. Running the script through a scheduled task
Once your files are complete, then you are ready to push them to Officevibe. To try the process manually, simply open a Powershell window and execute the following:
./sync.ps1 -ConfigPath ./config.json [-Verbose] [-DumpFormattedRequest]
As per the command above, it is possible to add -Verbose and -DumpFormattedRequest to the command for debugging purposes. Verbose will display additionnal information while executing the command and DumpFormattedRequest will generate a dump.json file at the script location containing the json request that will be sent to the API.
**To ensure that the sync runs, an Admin within the Officevibe account will want to make sure that they go to Admin - Integrations - click on the blue Configure button next to API and toggle the Daily Sync slider to the right. Please note that this will not automatically activate the sync every day - this is a manual process which must be done by your company, however if this is not turned on, the information in your HRMS system will not sync in Officevibe.**