Session Management

With Blueriq's Angular framework, starting a Blueriq shortcut or flow to create a new Blueriq session is initiated by the frontend.

Starting a shortcut/project

Within an Angular components' template, you may easily include a Blueriq session by using bq-project component in one of the following manners.

The bq-project component is exported from BlueriqCommonModule. This module is re-exported through BlueriqModule.forRoot() so if the component you use bq-project in is declared in AppModule there is no need to add a new import. If the component is declared in a feature module, ensure that the module imports BlueriqCommonModule.

Default Shortcut

When including the component without any inputs, the default shortcut will be started. If no default shortcut has been configured, starting the project will fail.

<bq-project></bq-project>

Shortcut name

Specify the name of the shortcut to start using the shortcut input attribute.

<bq-project shortcut="Main"></bq-project>

Full project/flow reference

To start a project/flow, its details may be specified by a the project and flow inputs. If either one is missing or empty, the component will start a shortcut instead.

<bq-project project="export-Kinderbijslag" flow="start"></bq-project>

Additionally, you may provide the inputs version, languageCode and channel to further specify the project details.

Starting by full project/flow reference may be disabled in production environments.

Existing session id

In some situations, you may already have a raw session id for an already started session. For this use-case, the component accepts the sessionId input attribute.

<bq-project sessionId="aae5b53b-8a59-4cf1-a551-64aefbf9070c"></bq-project>

When the specified session is no longer available (for example it could have expired) this approach provides insufficient data to start a new session, so in that case the request will fail instead.

Sending query parameters

The Runtime accepts additional query parameters when starting a session, which can be used by the AQ_GetRequestParameters service from the Studio model. Therefore, bq-project accepts an optional input attribute parameters with a plain key-value object that will be sent along as query parameters when starting the session.

Session Names

Each session is given a name for easier debugging of session interactions. The root session is named Main by default but that can be configured through bq-projects sessionName input attribute. If multiple root sessions are to be hosted in a single page, you have to use different session names for all of them.

Session Resuming

Under normal circumstances, it is desirable for users to resume their current session when reloading the page. For this reason, bq-project will first attempt to resume an earlier session that has been started with the same data, based on information stored in the browser's session storage. In the situation where the session to resume fails to load, a new session is started instead.

By default, the project details are simply joined together to obtain a string key. If the additional parameters you provide may contain sensitive data that should not be stored as plain text key in the browser's storage, consider providing a custom ProjectKeyGenerator that uses some hashing algorithm on the project details.

Alternatively to session storage, which is not shared across tabs and expires as soon as the tab closes, you may choose to use local storage instead. This storage area is in fact shared across tabs and the data in it survives browser restarts. Redefine Blueriq's STORAGE provider with the local storage factory function provided by the framework in AppModule:

import { NgModule } from '@angular/core';
import { STORAGE, provideLocalStorage } from '@blueriq/angular';

@NgModule({
  // ...
  providers: [
    // ...
    { provide: STORAGE, useFactory: provideLocalStorage },
    // ...
  ],
  // ...
})
export class AppModule {}

When storing the session information in local storage, different tabs will share sessions. Since the name of a session is taken into account by the default ProjectKeyGenerator implementation, you may use distinct session names across tabs (for example using a query parameter to uniquely identify a tab) to allow multiple sessions of the same Blueriq project to exist.

To have even more control over storage semantics, provide a custom implementation of ResumeSessionStrategy instead. For completely turning off this feature, use the NoopSessionResumeStrategy as provided by the framework:

import { NgModule } from '@angular/core';
import { ResumeSessionStrategy, NoopResumeSessionStrategy } from '@blueriq/angular';

@NgModule({
  // ...
  providers: [
    // ...
    { provide: ResumeSessionStrategy, useClass: NoopResumeSessionStrategy },
    // ...
  ],
  // ...
})
export class AppModule {}

Session Heartbeat

Each session has a heartbeat signal that pings the Blueriq Runtime to signal that the session is still being used, to prevent it from expiring. By default, the heartbeat signal goes out after one minute of inactivity, however this interval may be adapted by overriding the SessionHeartbeat token with a custom implementation:

import { Injectable, NgModule } from '@angular/core';
import { Session, SessionHeartbeat, PeriodicSessionHeartbeat } from '@blueriq/angular';
import { Observable, interval } from 'rxjs';

@NgModule({
  // ...
  providers: [
    // ...
    { provide: SessionHeartbeat, useClass: CustomSessionHeartbeat },
    // ...
  ],
  // ...
})
export class AppModule {}

@Injectable()
export class CustomSessionHeartbeat extends PeriodicSessionHeartbeat {
  protected triggerMoments(session: Session): Observable<any> {
    return interval(120_000);
  }
}

In the example above, a subclass of PeriodicSessionHeartbeat is created such that the heartbeat moments can easily be modified.

In Blueriq, a session may host other child sessions, often referred to as widget sessions. These widget sessions are not started manually but they are always created by the Runtime. Therefore the bq-project component is not appropriate to use. Instead, the bq-session component can be used. This component acts as a session host, only accepting the name of the session to display.

In fact, all bq-project does is cause the session to be resumed/started, then simply displays bq-session that takes care of the rest.

A simple flow widget component looks as follows:

import { Component, Self } from '@angular/core';
import { BlueriqComponent, FlowWidget } from '@blueriq/angular';
import { Container } from '@blueriq/core';

@Component({
  template: `<bq-session [sessionName]="flowWidget.sessionName"></bq-session>`,
  providers: [FlowWidget],
})
@BlueriqComponent({
  type: Container,
  selector: 'dashboard_flowwidget',
})
export class FlowWidgetComponent {

  constructor(@Self() public flowWidget: FlowWidget) {
  }

}

The components provides its own instance of FlowWidget that takes care of actually loading the widget's session data. The bq-session component in the template will take care of showing the widget's page as soon as the session data has been loaded.

Opening sessions in new tabs

When AQ_StartProject is used to start a new session, the option to open the new session in a tab is available. When the event to open a session in a new tab is handled, the frontend application decides the exact URL that should be opened in a new tab. The path depends on the routing setup of the application, so this may need custom configuration depending on your setup. By default, the route is assumed to be /session/:sessionId, where :sessionId is replaced with the actual session id to load. For a different route path, the framework provides two configuration options.

The simplest approach would be to provide the sessionRoute option to the BlueriqModule.forRoot import:

import { NgModule } from '@angular/core';
import { BlueriqModule } from '@blueriq/angular';

@NgModule({
  // ...
  imports: [
    // ...
    BlueriqModule.forRoot({
      sessionRoute: '/blueriq-session/:sessionId',
    }),
    // ...
  ],
  // ...
})
export class AppModule {}

This provides a quick way to change the route path, but it may be too limited in situations where the route path should include dynamic data. For example, some query parameters from the original session may need to be passed along into the new tab. In that case, a custom session route provider can be registered using the SessionRouteProvider token:

import { NgModule, Injectable } from '@angular/core';
import { SessionRouteProvider } from '@blueriq/angular';
import { SessionId } from '@blueriq/core';

@Injectable()
export class MySessionRouteProvider implements SessionRouteProvider {
  provideRoutePath(sessionId: SessionId): string {
    return `/blueriq-session/${sessionId}`;
  }
}

@NgModule({
  // ...
  providers: [
    // ...
    { provide: SessionRouteProvider, useClass: MySessionRouteProvider },
  ],
  // ...
})
export class AppModule {}

If this provider occurs in a separate NgModule, please be aware that the NgModule must then be imported after BlueriqModule.forRoot to override the default implementation.

Development tools

When the default SessionRouteProvider is overridden by a custom implementation, and you wish to have to same effects as this SessionRouteProvider, then the SessionRouteProvider.provideRoutePath should return a path containing the query parameter devtools.

import { Injectable } from '@angular/core';
import { SessionRouteProvider } from '@blueriq/angular';
import { SessionId } from '@blueriq/core';
@Injectable()
export class MySessionRouteProvider implements SessionRouteProvider {
  provideRoutePath(sessionId: SessionId): string {
    return `/session/${sessionId}?devtools`;
  }
}

This will ensure that when a new session is started in the context of the devtools, that the new session window stays in that devtools context.

Session Data

Once a Blueriq session has completed loading, a Session instance is created and registered globally in the application in the SessionRegistry service. In order for Blueriq components to access the session they are part of, the bq-session component provides a BlueriqSession service that may be injected by all components and directives contained within the bq-session.

Because of this approach, we take advantage of Angular's hierarchical dependency injection (DI) system, as Blueriq's hierarchical sessions are simply encoded within Angular's component tree. Hence, BlueriqSession has hierarchical context of parent sessions, whereas Session has not.