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 {}

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.

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.