VSN Module Switcher

The VSN Module Switcher (Module Navigator) is a Web Component designed for Visma Nordic applications to provide a consistent navigation experience across different services. It allows users to easily switch between various applications while maintaining a cohesive user experience.

Table of Contents

1. Package Installation
2. Configuration
- Basic Implementation
- Component Attributes
- CSS Variables
3. Authentication Integration
- Authentication with Local Token
- Authentication with API
4. Static Application Data
5. Dynamic Application Data
6. CI/CD Integration
- AWS CodeBuild Setup

Package Installation

Install the module navigator component in your project:

``bash
npm install @visma-swno/module-navigator --save
`

Configuration

$3

First, include the script reference in your HTML file:

`html

`

Then, add the component in your HTML, typically in a header or navigation section:

`html
application-name="YourAppName"
locale="en-US">

`

If using an Angular application, add the script reference in your angular.json:

`json
"scripts": [
"@visma-swno/module-navigator/dist/assets/index.js"
],
`

For Angular components, you'll also need to add CUSTOM_ELEMENTS_SCHEMA to your component or module:

`typescript
@Component({
selector: 'app-navbar',
templateUrl: './navbar.component.html',
styleUrls: ['./navbar.component.scss'],
schemas: [CUSTOM_ELEMENTS_SCHEMA] // Required for custom elements
})
`

$3

The component supports the following attributes:

| Attribute | Type | Default | Description |
|------------------------|----------|---------|--------------------------------------------------------------|
| application-name | String | "" | Name of the current application |
| application-name-alt | String | "" | Secondary/alternative name of the current application (e.g., Admin - Business Unit) |
| locale | String | "en-US" | Locale for the component UI (supported: en-US, en-GB, nb-NO, sv-SE, fi-FI, da-DK) |
| applications | Array/JSON String | [] | List of application modules to display in the menu. Note: This attribute is for testing and transitional integration purposes only. It will be deprecated in future versions as the component is designed to retrieve consistent module data across all applications via its API endpoints using provided access token. |

$3

You can customize the appearance of the component using CSS variables:

`css
vsn-module-navigator {
/ Font styling /
--vsn-module-menu-font-family: Inter, ui-sans-serif, system-ui, sans-serif;
--vsn-module-menu-font-feature-settings: "liga" 1, "calt" 1;

/ Scrollbar styling - works in both webkit browsers and Firefox /
--vsn-module-menu-scrollbar-width: 4px;
--vsn-module-menu-scrollbar-thumb-color: #b9b9b9;
--vsn-module-menu-scrollbar-track-color: transparent;
}
`

For Angular applications that have global scrollbar styling, you might need to add higher-specificity rules:

`css
/ In your global Angular styles /
vsn-module-navigator::part(modules-menu) {
scrollbar-width: thin !important;
scrollbar-color: #b9b9b9 transparent !important;
}
`

Authentication Integration

The component requires an access token to fetch available applications. It emits a request-token event that your application must handle.

$3

If you store your authentication token in sessionStorage or localStorage:

`javascript
document.querySelector('vsn-module-navigator')?.addEventListener('request-token', (event) => {
const token = sessionStorage.getItem('accessToken');
if (event.detail && typeof event.detail.callback === 'function') {
event.detail.callback(token);
}
});
`

In an Angular component:

`typescript
ngOnInit() {
this.elementRef.nativeElement.addEventListener('request-token', this.handleTokenRequest.bind(this));
}

private handleTokenRequest(event: Event) {
// Access the callback function passed via the event detail
const customEvent = event as CustomEvent;
const { callback } = customEvent.detail;

const tokenStr = sessionStorage.getItem('tokenResponse');
if (tokenStr) {
const token = JSON.parse(tokenStr);
const accessToken = token.access_token;
callback(accessToken);
}
}
`

$3

If you need to fetch the token from an API:

`javascript
document.addEventListener('request-token', async (event) => {
try {
const response = await fetch('your-token-endpoint');
if (!response.ok) {
throw new Error(HTTP error! Status: ${response.status});
}
const data = await response.json();
const token = data.accessToken;

if (event.detail && typeof event.detail.callback === 'function') {
event.detail.callback(token);
}
} catch (error) {
console.error('Token fetch error:', error);
}
});
`

Static Application Data

> Important: Static application data through the applications attribute is intended for transitional integration and testing purposes only. In production environments, the component should fetch application data through its API endpoints using an access token to ensure consistency across all Visma applications.

During the integration phase, you can provide a static list of applications directly through the applications attribute:

`javascript
const appModules = [
{
"id": "home-app",
"name": "Home",
"url": "https://example.com/home",
},
{
"id": "admin-app",
"name": "Admin",
"url": "https://example.com/admin",
}
];

// JSON stringify for attribute setting
document.querySelector('vsn-module-navigator')
.setAttribute('applications', JSON.stringify(appModules));

// Or direct object assignment if using framework bindings
// component.applications = appModules;
`

Each application object should have the following properties:
- id: Unique identifier for the application
- name: Display name of the application
- url: URL to navigate to when clicking the application

Dynamic Application Data

The recommended approach for production environments is to provide an access token to the component, which will then fetch a consistent set of applications from the API endpoints. This ensures all Visma applications display the same navigation menu.

When an access token is provided (via the request-token event handler), the component will automatically fetch applications from the API endpoint:

`
GET: {api-base-url}/v1/me/applications
``

The API base URL is determined automatically based on your hostname:
- localhost: "http://localhost:3000"
- .int.: "https://gw.access-management.api.aws.int.test.visma.net"
- .stag.: "https://gw.access-management.api.odp.aws.stag.visma.net"
- production: "https://gw.access-management.api.odp.aws.visma.net"

The API should return an array of application objects with the same format described in the Static Application Data section. This eliminates the need to manually maintain the application list in each individual application, ensuring a consistent user experience across the Visma application ecosystem.