Viessmann Global Header

The global header is available as web component and as an angular library. The web component can be used in any web application. The angular library is intended for apps using angular 15 or higher. Angular apps below angular 15 should either upgrade to angular 15 or use the web component. Note however that the web component causes material menus (<mat-menu>) to not work properly in angular apps.

Project stages

There are 3 project stages

Preparation

Angular Library

Install the library with npm/yarn (or download it from here): 

yarn add @vi/global-header
add the following to your NgModule 
import { GlobalHeaderModule } from '@vi/global-header';
@NgModule({
  declarations: [...],
  imports: [
    ...
    GlobalHeaderModule.forRoot({
      // (environment.ts)
      baseUrl: 'https://api-integration.viessmann.com',
      accountAppUrl: 'https://account-integration.viessmann.com'
    })
  ],
  providers: [...]
})
export class MyModule

Web Component

Add following code to your index.html header:

<head>
...

    <script defer src="https://global-header-integration.viessmann.com/elements.js"></script>
    <link rel="stylesheet" type="text/css" href="https://global-header-integration.viessmann.com/styles.css">

...
</head>

In Angular apps using the web component you need to add following code to the regarding module (this is NOT required if you use the angular library): 

schemas: [CUSTOM_ELEMENTS_SCHEMA]

Example implementation:

@NgModule({
      declarations: [],
      imports: [],
      schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class SomeModule {}

Component usage

Regardless of whether you are using the web component or the angular library, you can now just add the components into your html template:

Support Link Component

<vih-support-link></vih-support-link>

App-Switcher Component

<vih-app-switcher></vih-app-switcher>

Login Component

Set the attributes "login-redirect-url" and / or "logout-redirect-url" to redirect the user to given URL after login / logout. 

<vih-login login-redirect-url="https://allowed.redirect.url/dashboard" logout-redirect-url="https://allowed.redirect.url/public" ></vih-login>

This component fires an event on logout named logoutEvent.
You can use it for custom coding on your side (e.g. clearing Local Storage).

By default, after successful login, users are redirected to the origin URL they came from. You can change this by specifying a different loginRedirectUrl. For example if the (publicly available) landing page of your application is http://my-app.com/ and your app has a dashboard you can configure this URL to redirect users to that page after login. 

GlobalHeaderModule.forRoot({
        ...
        loginRedirectUrl: 'http://my-app.com/dashboard'
})

After logout the user is redirected to the exact URL where the logout button was pressed. So if your app is divided into public and protected sections (e.g. some pages require login and some not) you may want to always redirect to a public page. Otherwise, if the user clicks logout from a page that is protected by e.g. an angular route guard that automatically redirects to IAM, a login would be triggered right after logout. To set the redirect URL after logout to a different url, add logoutRedirectUrl to global header configuration. It can be either set to true or to the target URL. 

GlobalHeaderModule.forRoot({
      ...
      logoutRedirectUrl: 'http://my-app.com/public'
})

End Customer support

Set the attribute "type" to "endcustomer" to apply some EK-specific adjustments (default: "customer"). In endcustomer mode, a different registration link is used and the "forgot username" link, which is only available for customers, is hidden. 

<vih-login type="endcustomer"></vih-login>
GlobalHeaderModule.forRoot({
                ...
                type: 'endcustomer'
})

Bell Component

<vih-bell></vih-bell>

Customization

Depending on your application's overall style, the global header might not look like on this sample page. For example, the icons or texts in the menus might have different color. The global header components intentionally do not enforce them, to allow customization for app-specific style. You can easily override the styles (classes app-switcher and app-login) to adapt them to your app's look-and-feel: 

#my-header .app-switcher .mat-icon {
  color: white;
}

#my-header .app-login .mat-icon {
  color: white;
}

For angular apps: If your application has its own "logged in" state, e.g. if your app detects the session has timed out, you can set appManagesAuthentication and use the Observable input param authenticated of login component. It will subscribe to the Observable and update the loggedIn state when the value is changed, without making calls to the platform. 

<vih-login [appManagesAuthentication]="true" [authenticated]="my.loggedInState$"></vih-login>

i18n

The components display all texts in the user's browser language (Accept-Language header) by default, supporting the following languages:

Language-only string is coerced to the best matching language+country string (e.g. 'de' -> 'de-DE'). If your app has a language selector, you can use the parameter lang for each component, e.g. 

<vih-login lang='fr-FR'></vih-login>
<vih-app-switcher lang='fr-FR'></vih-app-switcher>

App Switcher without authentication

For apps like avendoo which can't authenticate against everest, you can still use the app switcher by setting the user-id param: 

<vih-app-switcher user-id="userId"></vih-app-switcher>

3rd Party Cookies

Some users disable third party cookies and some browsers even started blocking them by default which produces problems for our cookie-based SAML authentication. To get around this, apps should use CSRF token approach as described here. You can set the appId of your application in Global Header either via configuration (angular apps only) 

GlobalHeaderModule.forRoot({
    ...
    appId: 'myAppId'
})
or via component input 
<vih-login app-id="myAppId"></vih-login>
(works for both angular and non-angular apps).

After successful login, the redirect URL will contain the CSRF token as described on the wiki page mentioned above.

If your application performs login itself, you can also pass it via parameter `csrfToken` to both components. The parameter can be either the token itself or the name of the local storage key that holds the token: 

<vih-login csrf-token="token or key"></vih-login>
<vih-app-switcher csrf-token="token or key"></vih-app-switcher>

IAM login page background image

By default the IAM login page has a login form on the left side and an empty entire right side. By adding an optional global header configuration parameter `iamBackgroundImage` you can specify a background image which fills that empty space on the right. 


GlobalHeaderModule.forRoot({
    ...
    iamBackgroundImage: 'iam_lpi_000001.png' // or other image file which is supported by IAM
})

Troubleshooting

If you see a neverending spinning circle (loading) animation where the login / app switcher components should be, this can have multiple reasons: