Custom Integration

Officevibe offers you the possibility 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 users and their segmentation. This solution is particularly helpful when mapping complex organizational structures.

Built as a script that runs from your infrastructure, it will require a set of three CSV files to be pushed them through a secure HTTP connection to Officevibe, allowing you to fully configure all users,  groups and permissions all in one go! The process can be run manually, but is engineered to enable automation of the user synchronization process.

Note: This integration requires some advanced technical knowledge that includes programming and software coding capabilities. Th person in charge will need to be assigned as an administrator of the Officevibe account. 

Below is a guide to set up the API integration with Officevibe.

How To:

Step #1: Enabling the Custom Integration

You will need to 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'll be able to generate an API key to use with the Enterprise Sync Tool (see image below).

Once you've copied the API key, click the Save & Activate button to launch the Custom Integration Tool.

Note: By default, attempts to synchronize users via the script will fail, even with a valid API key, unless the Custom Integration provisioning is activated.

Step #2: 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: 

• json
• sandbox-config.json
• ps1
• Data
  • users.csv
  • groups-mapping.csv
  • groups.csv
• Modules
  • PS.SyncSDK.psd1
  • PS.SyncSDK.psm1

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:

a. "ApiKey": This is the API key you generated in the previous step. If you generate a new API key, you will need to modify the script with the new value. 

b. "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 one linked to Officevibe.

c. The files you want to sync (more info in Step #4 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 invitations to employees to join Officevibe, instead of having to manually invite employees within the App. This is useful for incremental operations where new employees or other changes should be automated.

Note: This 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.

Step #4: Exporting Data from your HRMS to the 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 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.

Note: All the IDs specified below can be alphanumeric. 

The files contain the following information:

1. 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. Acceptable values for language are:
   • English
   • Français
   • Español
   • Português

Note: If you configured user Attributes in Officevibe, you can populate the Attribute values for every user by adding columns to the CSV file, one for every Attribute. The column header will need to contain the Attribute name, and each line will specify the value for each user. You will need to configure the Attributes in Officevibe before assigning values through the Custom Integration tool and will need to ensure that the Attributes names are a perfect match.

2. groups.csv: This file contains basic group definitions, with an ID and a name. This allows for a group to be renamed without consequence as the ID is preserved. If sub-groups are required, these should also be created within this file.
3. groups-mapping.csv: This file will assign users to groups, and control additional group settings such as assigning a manager to a group. It's also possible to create a sub-group structure in this file, essentially mapping sub-groups to a group.

Step #5: Running the Script Through a Scheduled Task

When your files are complete, you're ready to push them to Officevibe. To try the process manually, you can simply open a Powershell window and execute the following:

./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.

Note: 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 week days between 12:00 AM EST and 5:00 AM EST, or on 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:

1. Success- The sync ran successfully.
2. Warning- The sync ran, however some information didn't transfer over - ex: group already exists, duplicates exist, etc. We recommend you double check your file to see what might have caused this status to appear.
3. 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 support@officevibe.com if you get this message so we can follow up internally.