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 members and their segmentation. This solution is particularly helpful when mapping complex organizational structures.

 

Important Notices

  • This integration is not available without a Premium Officevibe subscription.
  • Before running the Custom Integration, please contact support@officevibe.com.
  • If you are looking for a way to pull information from Officevibe, please visit api.officevibe.com.

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

Note: This integration requires some 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 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. Once you've copied the API key, click the Save & Activate button to launch the Custom Integration Tool.

Note: By default, attempts to synchronize members 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:

  • 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

 

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 working 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 will need to 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 one 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 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. This should be used with caution, 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

If you open the three sample files provided in the Data folder (samples attached at the bottom of this article), 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, but need to be unique.  

The files contain the following information:

  • users.csv: This file contains basic member information. The key identifier for Officevibe is the email address. This is also where you can 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:
    • English
    • Français
    • Español
    • Português
    • Deutsche

Note: If you configured members' properties in Officevibe, you can populate the property values for every member by adding columns to the CSV file, one for every property. The column header will need to contain the property name, and each line will specify the value for each member. You will need to configure the properties in Officevibe before assigning values through the Custom Integration tool and will need to ensure that the properties' names are a perfect match. 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. This allows for a team to be renamed without consequence as the ID is preserved. 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 multiple 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. 

Note: A team manager will automatically have access to the sub-teams. 

mceclip2.png

Example

  • John's Team includes 3 members. John is the team manager. 
  • Steph's Team includes 5 members.
  • Customer Service Department includes Steph's Team, John's Team, Steve's Team, Charles' Team, Peter's Team, 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're ready to push them to Officevibe. To try the process manually, you can simply open a Powershell window and execute the following. 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, 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 weekdays 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 click 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 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. 
Share

Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request