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.
Note: This option is most helpful when mapping complex organizational structures.
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.
Contents of the package:
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:
a. "ApiKey": In order to generate your API key, click on the Configure button next to Custom Integration (API) and click on the Generate API Key button.
To ensure that the sync runs, an Admin within the Officevibe account will want to make sure that they go to Admin - Integrations to activate the Custom Integration. 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.
Note: if you request a new API key, you will need to modify the script.
b. "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 in Officevibe.
c. The files you want to sync (more info in Step 3 below)
- "UsersCsv": "./Data/users.csv",
- "GroupsCsv": "./Data/groups.csv",
- "MappingCsv": "./Data/groups-mapping.csv"
d. "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.
Note that IDs can be alphanumeric.
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.
5. Viewing sync history
After running a sync, you're able to view the history/success of the sync by going to Admin - Integrations - View History link at the top of the page. There are three statuses available.
a. Success - The sync ran successfully
b. Warning - The sync ran, however certain information did not transfer over - group already exists, duplicates exist, etc. We recommend you double check your file to see what might have caused this status to appear as well as to view the details.
c. Error - The sync did not run due to an internal error. This typically happens if the integration expires or if something went wrong in your company's internal system. We recommend contacting firstname.lastname@example.org if you get this message so we can follow up internally.