Events Service

The Events Service (CloudAppEventsService) provides hooks which allow your app to interact with Alma. The following methods are available:

• onPageLoad
• getPageMetadata
• refreshPage
• getInitData
• getAuthToken
• home
• back
• entities$

onPageLoad

This event is fired whenever a new page is loaded in Alma. The event is exposed as an Angular subscription which your app can subscribe to.

Important: As with all Angular subscriptions, be sure to unsubscribe when your page goes out of scope.

Interface

onPageLoad(handler: (pageInfo: PageInfo) => void): Subscription

Parameters:

• Function which accepts a PageInfo object and returns void.

Returns: Subscription

Example

import { CloudAppEventsService } from '@exlibris/exl-cloudapp-angular-lib';

export class MainComponent implements OnInit, OnDestroy {
  private pageLoad$: Subscription;

  constructor(
    private eventsService: CloudAppEventsService
  ) { }

  ngOnInit() {
    this.pageLoad$ = this.eventsService.onPageLoad(this.onPageLoad);
  }

  ngOnDestroy(): void {
    this.pageLoad$.unsubscribe();
  }

  onPageLoad = (pageInfo: PageInfo) => {
    console.log("Retrieved onPageLoad event", pageInfo.entities);
  }
}

getPageMetaData

This method is used to retrieve metadata about the open page.

Interface

getPageMetadata(): Observable<PageInfo>

Returns: Observable<PageInfo>.

Example

import { CloudAppEventsService } from '@exlibris/exl-cloudapp-angular-lib';

export class MainComponent implements OnInit {

  constructor(
    private eventsService: CloudAppEventsService
  ) { }

  ngOnInit() {
    this.eventsService.getPageMetadata().subscribe(
      pageInfo=>console.log('entities', pageInfo.entities)
    );
  }
}

refreshPage

This method is used to refresh the current page in Alma.

Interface

refreshPage(): Observable<RefreshPageResponse>

Example

import { CloudAppEventsService } from '@exlibris/exl-cloudapp-angular-lib';

export class MainComponent implements OnInit {

  constructor(
    private eventsService: CloudAppEventsService
  ) { }

  ngOnInit() {
    this.refresh();
  }

  refresh() {
    this.eventsService.refreshPage().subscribe(
      () => console.log('Page refreshed')
    );
  }
}

getInitData

This method is used to retrieve initializing information that Alma provides when an app is opened.

Interface

getInitData(): Observable<InitData>

Returns: Observable<InitData>.

Example

import { CloudAppEventsService } from '@exlibris/exl-cloudapp-angular-lib';

export class MainComponent implements OnInit {

  constructor(
    private eventsService: CloudAppEventsService
  ) { }

  ngOnInit() {
    this.eventsService.getInitData().subscribe(
      data => console.log('Page called by', data.user.firstName, data.user.lastName)
    );
  }
}

getAuthToken

This method is used to retrieve an authentication token that can be used to authenticate with external systems.

Interface

getAuthToken(): Observable<string>

Returns: Observable<string>.

The authentication token is a JSON Web Token (JWT). See this documentation for information on how to validate the token. The token is valid for 4 hours and contains the following details:

• iss (issuer): https://apps01.ext.exlibrisgroup.com/auth, supports OpenID configuration
• aud (audience): ExlCloudApp: followed by the application ID, which is the Github user and repository name
• sub (subject): The primary ID of the Alma user
• inst_code: The Alma institution code

{
  "iss": "https://apps01.ext.exlibrisgroup.com/auth",
  "aud": "ExlCloudApp:{APP_ID}",
  "sub": "{USER_PRIMARY_ID}",
  "inst_code": "{INST_CODE}"
}

Example

import { CloudAppEventsService } from '@exlibris/exl-cloudapp-angular-lib';

export class MainComponent implements OnInit {

  constructor(
    private eventsService: CloudAppEventsService
  ) { }

  ngOnInit() {
    this.eventsService.getAuthToken()
      .subscribe(authToken => this.authToken = authToken);
  }
}

home

This method is used to load the home page in Alma. (From the Alma January 2021 release and SDK version 0.4.0)

Interface

home(): Observable<RefreshPageResponse>

Example

import { CloudAppEventsService } from '@exlibris/exl-cloudapp-angular-lib';

export class MainComponent implements OnInit {

  constructor(
    private eventsService: CloudAppEventsService
  ) { }

  ngOnInit() {
  }

  home() {
    this.eventsService.home().subscribe(
      () => console.log('Redirected to home page')
    );
  }
}

back

This method is used to ask Alma to go back home page. (From the Alma January 2021 release and SDK version 0.4.0)

Interface

back(): Observable<RefreshPageResponse>

Example

import { CloudAppEventsService } from '@exlibris/exl-cloudapp-angular-lib';

export class MainComponent implements OnInit {

  constructor(
    private eventsService: CloudAppEventsService
  ) { }

  ngOnInit() {
  }

  back() {
    this.eventsService.back().subscribe();
  }
}

entities$

Observable of entities on the current Alma page. Can be used as an alternative to the onPageLoad . (From the SDK version 0.5.0).

Interface

entities$: Observable<Entity[]>

Example

Basic usage:

export class MainComponent implements OnInit {

  entities$: Observable<Entity[]> = this.eventsService.entities$;

  constructor(
    private eventsService: CloudAppEventsService,
  ) { }

  ngOnInit() { }
}

<div *ngIf="entities$ | async as entities">
  <ul>
    <li *ngFor="let entity of entities">
  </ul>
  <p *ngFor="let entity of entities">{{entity.description}}</p>
</div>

Retrieve full entities before displaying them:

export class MainComponent implements OnInit, OnDestroy {

  items$: Observable<Item[]> = this.eventsService.entities$
  .pipe(
    switchMap(entities => {
      const items = entities.filter(e=>e.type==EntityType.ITEM);
      return iif(
        ()=>items.length>0,
        forkJoin(items.map(e=>this.restService.call<Item>(e.link))),
        of(null)
      )
    })
  );

  constructor(
    private eventsService: CloudAppEventsService,
  ) { }

  ngOnInit() { }

  ngOnDestroy(): void { }
}

<div *ngIf="items$ | async as items">
  <ul>
    <li *ngFor="let item of items">Barcode-{{item.item_data.barcode}}</li>
  </ul>
</div>

Interfaces

PageInfo

Properties:

• entities: Entity[]
  • id: string, ID of the entity
  • code?: string, code of the entity, if exists
  • type: EntityType, entity type enum
  • link?: string, link to the corresponding REST API for the entity
  • description?: string, description of the entity suitable for display

InitData

Properties:

• user:
  • firstName: string, first name of the logged in user
  • lastName: string, last name of the logged in user
  • isAdmin: boolean, whether the logged in user has the General Administrator role
  • primaryId: string, primary ID of the logged in user
  • currentlyAtLibCode: string, the code of the library the user is logged in to
• lang: string, language of the user’s session, used to select language for localization
• instCode: string, current institution code (i.e. 01MYUNI_INST)
• color: string, color of the selected theme for the institution
• urls: An object which contains URLs for the Alma instance. The URL can be used to call other services (such as SRU)