Custom Integration

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.

 

Important Notices

Before running the Custom Integration, fill out this request form to get in touch with our Support team.

If you are looking for a way to pull information from Officevibe, please visit api.officevibe.com. Additionally, if you want to write a GET request, please visit the following link

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.

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

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

 

How To

Step #1: Enabling the Custom Integration

You must go to the Admin - Integrations section and click 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. Extract one of the zip files below to a folder of your choice. We will assume C:\OV_Sync.

Contents of the package:

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

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

{
"Configuration": {
"ApiUrl": "https://sandbox.officevibe.com",
"ApiKey": "",
"UsersCsv": "./Data/users.csv",
"GroupsCsv": "./Data/groups.csv",
"MappingCsv": "./Data/groups-mapping.csv",
"SyncManagerEmail": "",
"InviteNewUsers": false
}
}

{
"Configuration": {
"ApiUrl": "https://app.officevibe.com",
"ApiKey": "",
"UsersCsv": "./Data/users.csv",
"GroupsCsv": "./Data/groups.csv",
"MappingCsv": "./Data/groups-mapping.csv",
"SyncManagerEmail": "",
"InviteNewUsers": false
}
}

 

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, change it to sandbox.officevibe.com. 

b. "ApiKey": This is the API key you generated in the previous step. You must modify the script with the new value if you generate a new API key. 

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)

"UsersCsv": "./Data/users.csv",

"GroupsCsv": "./Data/groups.csv",

"MappingCsv": "./Data/groups-mapping.csv"

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.

All the IDs specified below can be alphanumeric but need to be unique.  We do not recommend using a manager's name as a GroupID and suggest that it is something generic if a manager changes. 

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 first name, and last name; this will now be available in the Custom Integration 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:
    • English
    • Français
    • Español
    • Português
    • Deutsche
If you configured members' properties in Officevibe, you could populate the property values for every member by adding columns to the CSV file, one for every property. The column header must contain the property name, and each line will specify the value for each member. You must configure the properties in Officevibe before assigning values through the Custom Integration tool, ensuring that the properties' names match perfectly. Here's a guide on how to create properties: Create Properties.
  • 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 the following:
  1. Manager's Direct Reports (small teams with members)
  2. 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. 
A team manager will automatically have access to the sub-teams.  
Custom_Integration_Structure.jpg

Example

  • John's Team includes 3 members. John is the team manager. 
  • Steph's Team includes 5 members.
  • The Customer Service Department includes Steph's Team, John's Team, Steve's Team, Charles' Team, Peter's Team, and Angie's Team. Steph is the Team manager. 

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. 

 

Sandbox: 

./sync.ps1 -ConfigPath ./sandbox-config.json -Verbose -DumpFormattedRequest

 

Production: 

./sync.ps1 -ConfigPath ./config.json -Verbose -DumpFormattedRequest

 

As per the command above, adding -Verbose and -DumpFormattedRequest to the command for debugging purposes is possible. 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 on weekends.

The script will not remove employees with Administrator permissions. You'll need to manage those manually.

 

Step #6: Viewing Sync History

After running a sync, you can 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: team already exists, duplicates exist, etc. We recommend you double-check your file to see what might have caused this status.
  3. 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 support@officevibe.com if you get this message so we can follow up internally. 

Have more questions? Refer to our Custom Integration: FAQs article.

Share