In 2016, Viessmann—one of the world’s leading manufacturers of efficient, reliable, and affordable heating and solar products—took a giant step toward digitizing their internal communications with their Vi2Go employee app.

The app has since attracted more than 11,000 users, thus enabling each one of them to stay connected at all times, which has been especially beneficial to the company's many non-desk workers. The app features company news, local factory news, access to the employee’s SAP timesheets, internal job offerings, meal plans, documents, and more.

An important requirement for Viessmann was having the ability to automatically offboard employees who leave the company. To do so, the team around Viessmann's Christoff Thalheim have facilitated the Staffbase REST API, thus ensuring that all user information is updated daily.

Teaser Techstudy Useroffboardingrestapi.jpg

The Goal: Automatic User Sync

Viessmann uses SSO via the OpenID authentication protocol as one way to provide their personnel with an ideal user experience. SSO allows users to access their applications with a single set of login credentials and thus provides an easy way to onboard users. SSO, however, does not end active sessions. Therefore, the company needed a way to remove exited employees in real time.

Staffbase provides a set of methods to help keep users in sync, including CSV active directory integration and APIs. Viessmann chose the REST API, as it provides the greatest flexibility when it comes to integration with their existing offboarding process.

Solution, Steps, and Delivery

In using the  REST API, Viessmann made sure that when a user is deleted the REST API will be automatically triggered to delete the user from the app, too. Viessmann does this by performing a daily cron job. The cron job fetches all users deleted from Viessmann’s identity provider during the previous twenty-four hours and removes them from Staffbase as well.

Infograph_Techstudy-100.jpg

Key in this task is to have shared user IDs between the company’s user directory and Staffbase. To support existing IDs you can set an externalID for a Staffbase user which will then serve to identify them when compared to their Staffbase ID. The externalID could for example be the employee’s ID number or their first name. (An email address is a bad choice for an externalID, as it is often subject to change.)  

In our case, the Single-Sign On flow provided by Viessmann’s Identity Provider automatically sets the user’s externalID during the SSO flow. This externalID is also known to the customer’s HR systems and to the workflow that handles offboarding. Using this externalID, the cron job only fetches the externalID of the user who needs to be deleted from Viessmann’s identity provider and then triggers the deletion for each user facilitating the Staffbase API.

This flow is simple and robust. To be failure tolerant in execution, the cron job will not break if a user does not exist in Staffbase, and all remaining users will be deleted nonetheless.

The following code examples illustrate how to use our REST API for achieving this task.

Advisory and Sample Code

HTTP API call to delete a user:

DELETE /api/users/{USER_ID} HTTP/1.1

Host: backend.staffbase.com

Authorization: Basic {API_TOKEN}

Snippet for deleting a user in C#:

var API_TOKEN = "";

var USER_ID = "";

var client = new HttpClient();

client.BaseAddress = new Uri("https://backend.staffbase.com/");

client.DefaultRequestHeaders.Authorization =

new System.Net.Http.Headers.AuthenticationHeaderValue("Basic", API_TOKEN);

var response = await client.DeleteAsync($"/api/users/" + USER_ID);

var statusCode = response.StatusCode;

Snippet for deleting a user in Java:

final String API_TOKEN = "";

final String USER_ID = "";

final URL url = new URL("https://backend.staffbase.com/api/users/" + USER_ID);

final HttpURLConnection httpCon = (HttpURLConnection) url.openConnection();

httpCon.setRequestMethod("DELETE");

httpCon.setRequestProperty("Authorization", "Basic " + API_TOKEN);

final int statusCode  = httpCon.getResponseCode();

Conclusion

By using SSO with OpenID and the Staffbase REST API, Viessmann is able to keep their users up-to-date daily—whether they're onboarding or offboarding—while still ensuring the best possible user experience.

Kudos to the team! We’re looking forward to the next project!

IT-Whitepaper, Internal-Communications-App, Employee-App, Employee-IT

Read more about employee communication apps: