Officevibe allows you to create a customized integration between your HRMS and your Officevibe account. This is an ideal solution if your organizational context requires you to have additional control and flexibility when managing your members and their segmentation. This solution is beneficial when mapping complex organizational structures.
- Before running the Custom Integration, please get in touch with email@example.com.
Built as a script that runs from your infrastructure, it will require three CSV files to be pushed through a secure HTTP connection to Officevibe, allowing you to fully configure all members, teams, and permissions in one go! The process can be run manually but is engineered to enable the member synchronization process automation.
Below is a guide to setting up the API integration with Officevibe.
Step #1: Enabling the Custom Integration
You must go to the Admin - Integrations section and click on Configure next to the Custom Integration (API) option.
This will lead you to a screen where you can generate an API key to use with the Enterprise Sync Tool, enabling the API's endpoint for the sync and simultaneously disabling the other active provisioning methods.
By default, attempts to synchronize members via the script will fail, even with a valid API key, unless the Custom Integration provisioning is activated.
It’s also important to know that API keys do not expire once the integration is active.
Step #2: Creating and Configuring the Environment
To run the script, there will need to be an instance of Windows that can execute a Powershell script and 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:
To use Officevibe, all members of an organization must be included in the "users document" and not just the Team Members. In addition to Team Members, this includes Administrators and Executive Managers.
Step #3: 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:
|Sandbox Environment||Production Environment|
a. "ApiUrl": This is the Officevibe URL. If you are working in Production, you can set it to app.officevibe.com. If you are in our Sandbox environment, you can change it to sandbox.officevibe.com.
b. "ApiKey": This is the API key you generated in the previous step. If you generate a new API key, you must modify the script with the new value.
c. "SyncManagerEmail": This optional field allows you to specify an email address where a notification will be sent should there be an error while processing the synchronization.
Any email address can be used for this field. It does not need to be linked to Officevibe.
d. The files you want to sync (more info in Step #4 below)
e. "InviteNewUsers": When set to true, this flag automatically sends out invitations to employees to join Officevibe instead of manually inviting employees within the App. This is useful for incremental operations where new employees or changes should be automated. This should be used cautiously, as setting it to TRUE can potentially send hundreds or thousands of invites on initial imports.
Step #4: Exporting Data from your HRMS to the CSV files
You will see CSV files if you open the three sample files provided in the Data folder (samples attached at the bottom of this article). These files use a CSV format, separated by commas, 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 member information. The key identifier for Officevibe is the email address. You can also set fields like the first name, last name, job title, and language. Creating new members is done by adding a line, and removing a member is done by removing a line. Acceptable values for language are:
- groups.csv: This file contains basic team definitions, with an ID* and a name. As the ID is preserved, a team can be renamed without consequence. If sub-teams are required, these should also be created within this file.
If you have multiple business units or brands under one account, you will also need to identify them here to represent your various levels of segmentation.
For example, Parent Company, Business Unit 1, Business Unit 2, Etc.
Ensure that you create both levels of segmentation for your managers since they'll want to see data based on:
- Manager's Direct Reports (small teams with members)
- All Manager's hierarchy (a bigger team made of sub-teams)
- groups-mapping.csv: This file will assign members to teams and control additional team settings, such as assigning a manager to a team. It's also possible to create a sub-team structure in this file, essentially mapping sub-teams to a team (ex: department ABC is made of Director's Direct report + Team A + Team B + Team C).
For multiple business units, this is also where you will identify them as Sub-teams of the main account to ensure you can reflect the levels of segmentation needed.
We recommend starting by the button of the organizational structure to work your way up using parent teams and sub-teams. All managers should have access to their team's results. If they are also managers of managers, they'll want visibility on their entire hierarchy.
Steph will automatically have access to the sub-teams.
The Customer Service Department does not have any members, only sub-teams.
Step #5: Running the Script Through a Scheduled Task
Each sync will overwrite the previous one. You need to push all the information every time. If a user is not in the file, they will be removed. If a team is not in the file, they will be deleted.
When your files are complete, you can push them to Officevibe. You can simply open a Powershell window and execute the following to try the process manually. Make sure that you are in the same folder that sync.ps1.
./sync.ps1 -ConfigPath ./sandbox-config.json -Verbose -DumpFormattedRequest
./sync.ps1 -ConfigPath ./config.json -Verbose -DumpFormattedRequest
As per the command above, it's possible to add -Verbose and -DumpFormattedRequest to the command for debugging purposes. Verbose will display additional 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.
Once you've validated the process manually, you can automate the execution of the Enterprise Sync Tool through a standard Windows scheduled task.
You have complete control over the execution of the script. This means you can execute it daily, weekly, monthly, or even ad-hoc based on your business needs. We strongly recommend scheduling the execution on weekdays between 12:00 AM EST and 5:00 AM EST or weekends.
Step #6: Viewing Sync History
After running a sync, you'll be able to view the history/success of the sync by going to the Admin - Integrations section and clicking on View History in the top right-hand corner of the page. There are three possible statuses:
- Success- The sync ran successfully.
- Warning- The sync ran; however, some information didn't transfer over - ex: team already exists, duplicates exist, etc. We recommend you double-check your file to see what might have caused this status.
- Error- The sync did not run due to an internal error. This typically happens if the integration expires or something goes 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.