COMS Micro-Frontend for Customer Service (4P) 1.0.3

Purpose

The COMS micro-frontend for customer service for kernel consents (aka 4th-platform)

For development and test purposes, you can use this test page.

Changes are tracked in the changelog.

Integration Guide

The micro-frontend is provided as a standard web components (v1).

To integrate this micro-frontend follow these steps:

Choose a COMS environment you want to integrate that fits your own app environment, e.g.:
- ICT: https://ict-micro-frontend-proxy.high.coms-dev.aws.de.pri.o2.com
- E2E2: https://e2e2-micro-frontend-proxy.high.coms-dev.aws.de.pri.o2.com
- E2E1: https://e2e1-micro-frontend-proxy.high.coms-dev.aws.de.pri.o2.com
- PROD: https://micro-frontend-coms.telefonica.de

Load the corresponding javascript file into the <head> of your app using this setup:

<base URL>/tef-coms4cs4p/<version>/tef-coms4cs4p.js:

...
<head>
  <!-- load web component, make sure to use type="module" -->
  <script type="module" src="https://micro-frontend-coms.telefonica.de/tef-coms4cs4p/v1/tef-coms4cs4p.js">
  </script>
</head>
...

Collect the values for all required attributes inside your app and add the web-component tag into your page. Optional attributes can also be added.

...
<body>
  ...
  <tef-coms4p4cs
    sp-id="SP301"
    lc-id="12345678"
    theme-base-url="https://..."
    api-url="https://..."
  ></tef-coms4p4cs>
  ...
</body>
...

Add handling of events triggered by <tef-coms4p4cs>. Learn more under “Events”.

General Hints

If you are familiar with the other COMS micro-frontends <tef-coms> and <tef-coms4cs>, please note the following general differences of <tef-coms4cs4p>.

All html attributes (see section attributes below) are consistenty in lowercase with dash separator (aka “kebab-case”), e.g., access-token or sp-id. This is to be compliant with the html specification.
Some attributes were renamed although their purpose is identical, e.g., apiUri -> api-url, occlUri -> theme-base-url.
<tef-coms4cs4p> is rendering its own loading spinner. If that’s a problem, please let us know.
This web component has it’s own set of “save” and “cancel” buttons. All interaction with the user is handled by the micro-frontend. Please take care to handle events that are triggered by the component.

Authentication

This micro-frontend is for customer service agents, i.e., the user is an agent.

There are several authentication scenarios:

The user is authenticated using a ForgeRock EIAM access token. Make sure you pass it on as the access-token attribute on the <tef-coms4cs4p> tag. deprecated
The user is authenticated using a ForgeRock EIAM access token. But instead of passing the access token as html attribute to the micro-frontend, the new RAITT architecture requires the integrating portal to intercept all REST calls from the micro-frontend to the COMS backend (via API Gateway) in order to add the authorization header appropriately: authorization: Bearer <token>. If you need client-side interception, you may want to use the fetch attribute. new raitt

flow

Attributes

Attributes initialize the web component.

⚠️ Attributes must be set when <tef-coms4cs4p> is initially rendered into the page’s DOM. It is not supported to change any attribute values afterwards.

The following attributes are supported.

`access-token`

deprecated

Optional.

The agent token is sent to the COMS backend for authentication & authorization.

`lc-id`

Required.

The local customer id. The format depends on the according CRM system or IT stack.

`sp-id`

Required.

The service provider id (eg. SP301)

`theme`

Optional. Defaults to occl.

Design library: Currently only supporting occl.

`theme-base-url`

Required.

This parameter is provided for integration with the OCCL (Telefónica’s omni-channel component library).

The base URL to the OCCL including brand id. Something like https://$host/$brandid.

For example, <tef-coms4cs4p> is simply rendering this when using "https://library.telefonica.de/1" as the theme-base-url:

<tef-coms4cs4p theme-base-url="https://library.telefonica.de/1">
  #shadow-root
    <link rel="stylesheet" href="https://library.telefonica.de/1/v3/components/theme/bundle.css">
</tef-coms4cs>

In addition, all required OCCL scripts are loaded dynamically by the micro-frontend.

`api-url`

Required. The base URL of the COMS API. Something like https://$host.

The intended way to connect to the COMS API is via API gateway. Please subscribe to the gateway APIs “4p-extra-services-{env}” or “4p-extra-services” (the latter is a shortcut on the standard environments ict, e2e2, e2e1, and prod).

`fetch`

Optional. In some special cases, it is technically necessary to intercept the micro-frontend’s requests to its backend on the client-side. For this purpose, an alternative fetch can be provided to be used instead of the global fetch. If provided, the alternative fetch must be compliant with the Standard Fetch API (as needed). The integrating portal (frontend) is fully responsible for appropriately proxying all requests.

<tef-coms4cs4p fetch="altfetch" api-url="https://..." ... >
</tef-coms4cs4p>

The micro-frontend is then internally calling…

const response = await window.altfetch(...);

A small usage example:

window.altfetch = async (uri, options = {}) => {
  const { headers = {}, ...other } = options;
  return window.fetch(uri, {
    ...other,
    headers: {
      ...headers,
      Authorization: `Bearer ${token}`,
    },
  });
};

`traceid`

Optional. A trace ID to pass into all relevant requests to the COMS backend. If traceid is not set, it will be generated.

Methods and Properties

Web components can be referenced as objects and thus may provide “custom element methods”. Similarly, their classes may provide methods or properties.

`version`

The <tef-coms4cs4p> element provides a version class property:

const coms = window.customElements.get('tef-coms4cs4p');
console.log(coms.version); // eg. "1.0.0"

Events

<tef-coms4cs4p> issues CustomEvents to communicate changes. The event’s target is the <tef-coms4cs4p> DOM element (re-targeting all events that come from further down the hierarchy). All details are further specified in the event’s detail property.

<tef-coms4cs4p> does not provide any visual error feedback to the call center agent. This must be implemented by the integrating portal based on error-level events issued by <tef-coms4cs4p>.

detail.name	detail.level	Description
`consents/LOAD`	`info`	Loading consents was successful.
`consents/SAVE`	`info`	Saving consents was successful.
`consents/ERROR`	`error`	Loading or saving consents failed.
`consents/CHANGE`	`info`	The user changed a consent. This event does not provide any further details which consents where changed. It is issued at every change, i.e., multiple times. This event is indicating that consents were changed, e.g., in order to enable an external save button.
`consents/EMPTY`	`info`	There are no consents to be rendered. The micro-frontend will not visually render anything.
`load/READY`	`info`	The micro-frontend has successfully loaded all required resources (including OCCL). It is guaranteed that either `load/READY` or `load/ERROR` is issed – exactly once.
`load/ERROR`	`error`	The micro-frontend has failed. This might be due to a misconfiguration or it failed to load a required resource (including OCCL). It will not visually render anything and will stay in “loading” state. This is indicating that the microfrontend should be removed and an error displayed in the integrating portal. It is guaranteed that either `load/READY` or `load/ERROR` is issed – exactly once.
`action/CANCEL`	`info`	The user clicked the “Dialog schließen” button closing the micro-frontend. The integrating portal should close the micro-frontend wrapper without further action.

For listening to all events issued by <tef-coms4cs4p>, place something like this into your page:

<script>
   document.addEventListener('tef-coms4cs4p', (e) => { console.log(e); });
</script>

Below are a couple of sample events. Please note that all properties message and statusText are not formally specified, i.e., they will be subject to change and/or are platform-specific. ⚠️

CustomEvent {
  type: "tef-coms4cs4p",
  detail: {
    name: "consents/LOAD",
    level: "info",
    message: "consents loaded successfully"
  }
}
CustomEvent {
  type: "tef-coms4cs4p",
  detail: {
    name: "consents/ERROR",
    level: "error",
    message: "loading or saving consents failed",
    error: {
      name: "Error",
      statusCode: 400,
      statusText: "Bad Request",
      message: "Something went wrong"
    }
  }
}
CustomEvent {
  type: "tef-coms4cs4p",
  detail: {
    name: "auth/ERROR",
    level: "error",
    message: "token validation failed",
    error: {
      name: "Error",
      statusCode: 401,
      statusText: "Unauthorized",
      message: "user not found"
    }
  }
}
CustomEvent {
  type: "tef-coms4cs4p",
  detail: {
    name: "auth/ERROR",
    level: "error",
    message: "token validation failed",
    error: {
      name: "TypeError",
      // network error does not have status code
      message: "Failed to fetch"
    }
  }
}

Browser Support

The key technology used here is standard web components (v1). It is guaranteed to work in the latest two versions of all major browsers: Chrome, Firefox, Edge, Safari, Safari/iOS.

As a general rule, only browsers with native support for Web Components (custom elements and es6 modules) are supported. Consequently, it is no longer recommended nor required to load polyfills for Web Components.

Please make sure to load the micro-frontend as a module: type="module" ⚠️

Versioning

<tef-coms4cs4p> supports Semantic Versioning.

Global Resources

All global resources used by <tef-coms4cs4p> are pre-fixed. In particular:

Session storage key is tef-coms4cs4p-state.
Console logging is prefixed tef-coms4cs4p:.