Custom Integration: FAQs

Officevibe allows you to create a customized integration between your HRIS (or any other consistent source) 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. 

For the API to work, the account needs to have a Pro or Business Subscription. 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.

We have compiled the frequently asked questions below:

What data can I export from the API?

You can use the API to export your; Engagement Scores, Feedback Report, Team list, and Members. You cannot export the; Question results, Custom Survey Data, Goals, 1-on-1s, or Good Vibes — refer to our API Documentation for how to do this!

How do I ensure members are Invited when I sync?

You must ensure that "InviteNewUsers" is set to true in your Enterprise Sync Tool.

Can I test my custom integration without inviting any Members?

Yes — you must ensure that "InviteNewUsers" is set to false in your Enterprise Sync Tool. Members will be under the Created status and will not be invited until you invite them manually in the platform.

If I decide to set "InviteNewUsers" to FALSE, how do I invite my Members after?

Should I re-upload the file with "InviteNewUsers" set to true? You can invite your members via the platform! Re-uploading with "InviteNewUsers" to true will not work.

Once you are in your Members' settings, you first need to click on More filters (next to the dropdown) > select the Created status > click on the blue Apply button, and you will then be able to select Members.

If not, the option to choose Members will be greyed out.

Are Administrators/Executive Managers affected by the API Integration?

No — the API does not alter the status of Admins/Executive Managers. Their access must be managed directly in the platform.

Do Administrators need to be on the file?

No — Administrators do not need to be included in the file. If an Administrator is listed on your account but not in your files, they will not be deactivated.

Who inputs the information in the CSV files?

The designated Administrator will have to systematically export data from their HR system to ensure that the Integration is continually updated.

They can potentially run a script on their side which will regularly update the CSV/JSon files they are syncing with Officevibe. Otherwise, they will have to manually export from their HR system to update the files they are integrating with us.

Can we use special characters in the API files?

Special characters found in users' names will sync properly with Officevibe, i.e., including "ñ" and "í".

How does Officevibe help prevent accidental data deletion?

If the request body for a /sync call is missing users, groups, or mappings, or if any of those parameters is empty, the call will fail. This is a safety measure to prevent accidental deletion of data associated with these parameters.

Can Officevibe help restore all the data we mistakenly wiped while concluding tests with the custom API?

Rest assured that we can work on a solution that will bring back most of the data that is no longer accessible.

To begin with, please note that we cannot proceed with a backup of deleted Team structures when they have been deleted via the API files.

A workaround we suggest is to recreate your organization's Team structures in your API files as they were before this event (recreate your Teams, Sub-Teams, add appropriate Members and Managers, etc.). Once this has been done, we may do a recompute on our side, which will recalculate/bring back the data associated with each member currently removed from the account.

Note, however, that while this operation can import current Members' data, it cannot account for any historical team mobility, so your recomputed reports may differ slightly from their original versions.

Unfortunately, if any members were permanently deleted, it will not be possible to restore their data - they will need to be re-invited and begin the process as new users. To prevent such losses, the Integration can only deactivate members, and deletions must be made manually in-app.

How do I change my Team names without losing data?

Not manually, as we understand it would be time-consuming. If you're setting up your custom integration, there is a workaround to change the team names in Officevibe via the API, which will require uploading a file with the current names. Hence, why each Team has a unique ID created for them, and then upload another file that would change the team names as desired without creating new Teams and losing your data.

To ensure that you keep the data, here is the best course of action:

1. Sync with the API the first time but keep the previous team names. This sync would then add the correct external IDs to Teams. External IDs do not need to match pre-existing IDs at this step — we encourage you to use IDs from your own lists but avoid using the Team's name as the team ID. 
2. Sync a second time with the new team names. The app would then find the teams using their external IDs and update their name.

E.g., let’s say “Team A” becomes “Team 1," and its ID in your account is “0001”. In Officevibe's database, we would have team A as its name and no external ID (since there has not yet been an API sync in the account). The first API file would have the mapping { “ID: “0001”, “name”: “Team A” }.

By syncing with the old name first, the application would find the correct Team in the database by name and add its external ID.

Then, we could sync again, but the file would look like { “ID: “0001”, “name”: “team 1” }.

During the second sync, the app would find the team by its external ID and update it, changing its name to Team 1.

I have an existing account with data and want to start using the Custom API for provisioning. Will I lose my data?

No. You must ensure that the team names in your API files match what you currently have in the platform when activating your Integration. If you want to change names, you can do so after the first sync because your Teams will have associated IDs.

Can I keep Teams in the platform but not include them in the API files?

The API will overwrite all Members and Teams, not in the files — that said, all Teams will be managed by the Integration.

Rule-Based Teams that are managed by segments will not be overridden.

Can I create properties and segments via Custom Integration?

The API can assign property values that have already been created in the platform, but it can’t create properties or segments for you. 

Find out how to create your properties and segments via this article: Officevibe Member's Properties.

Once you have created your properties in the platform, you can use the API sync to assign your members with the values you created in Officevibe.

You can do this by adding a column for each property you created into the user.csv file and filling in the respective values for each user. 

When you sync, it will add the property values you created in Officevibe to their profiles, and then you can create Segments for your account. 

Can I test my Integration before running it in my production account?

You can contact our Support Team to request a sandbox environment for testing at no additional charge. 

What do the Error messages mean?

What happens when a member changes roles within the organization, I.e., they move from one team to another? Is there anything to be done on the client’s IT side manually?

If the changes are made in your HRIS, and you have an automatic feed to your API files, the members will be moved automatically at the next sync. Most clients have a script that pulls the info from their HRIS and imports the data into the files; therefore, nothing is manual.

Is a member automatically added to the correct team after they've been added to my HRIS?

Yes. If you have the person in the correct team via your HRIS, the script will place them in the correct team on the file, and they will be added when the sync occurs. The sync can be scheduled to happen as frequently as you prefer, but most clients schedule it once a week.

How to prevent manual work and ensure my custom integration functions?

Scripting will do the heavy lifting and prevent manual changes from being done. Setting up a script means that the data from the HRIS will populate into the files and the sync will take care of the changes in Officevibe.

What IDs are needed in the three API files to set up custom API?

These are the different IDs needed if you ever need to set up your own custom API: 

1. User File ID: Unique ID belonging to the user (not group ID). This ID would be used to identify users in the Group Mapping File.
   
   
2. Group File ID: Unique Id that belongs to the group (a Team). This ID is for internal use only and won't be reflected anywhere. It can be the same as the ID you have in your system.
   
   
3. Name: This name would be visible on the Officevibe Screen. It can be a manager's name or department name.

Data can be lost if you use a manager's name as the ID and you want to change the ID due to a personnel change. In that case, a new group will be created, and the historical data will be lost.

Group Mapping File 

Three things can be mapped to a group:

1. A subgroup: In this case, you input the Group Id (From the Group File) and a Subgroup Id (Also from the Group File). It is used to define the hierarchy of the teams.
2. A Manager: In this case, you input the Group Id (From the Group File) and the UserId (From the User File). IsManager Field would be True and isMember field would be False.
3. A Member: In this case, you input the Group Id (From the Group File) and the UserId (From the User File). IsManager Field would be False and isMember field would be True.