COMS Micro-Frontend for self-care/ecare customer self-service (tef-coms4p) 1.1.3

Purpose

The COMS micro-frontend for ecare 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 or e2e2.

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

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

...
<head>
  <!-- load web component, make sure to use type="module"; This is an example, choose the base url above! -->
  <script type="module" src="https://micro-frontend-coms.telefonica.de/tef-coms4p/v1/tef-coms4p.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-coms4p
    sp-id="SP301"
    lc-id="12345678"
    theme="occl"
    theme-base-url="https://..."
    api-url="https://..."
  ></tef-coms4p>
  ...
</body>
...

Add handling of events triggered by <tef-coms4p>. 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-coms4p>.

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-coms4p> 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 customers (selfcare), i.e., the user is a customer.

There are several authentication scenarios:

The user is authenticated by legacy stack deprecated
- Provide a legacy stack access token in attribute access-token
The user is authenticated by new stack raitt
- Do not provide any access-token attribute. Instead, the 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>. Please see the image below:

flow

Attributes

Attributes initialize the web component.

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

Attribute names are lower-case or kebab-case (e.g., foobar or foo-bar).

The following attributes are supported.

`access-token`

deprecated

Optional.

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

`sp-id`

Required if user is authenticated by new stack.

Will override the default sp-id taken from the token of the active user.

The service provider id (eg. SP301)

`lc-id`

Required if user is authenticated by new stack.

Will override the default lc-id taken from the token of the active user.

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

`theme`

Required.

Design library: Currently supporting occl and tefOne.

`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-coms4p> is simply rendering this when using "https://library.telefonica.de/1" as the theme-base-url:

<tef-coms4p 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-coms4p fetch="altfetch" api-url="https://..." ... ></tef-coms4p>

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-coms4p> element provides a version class property:

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

Events

<tef-coms4p> issues CustomEvents to communicate changes. The event’s target is the <tef-coms4p> 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-coms4p> 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-coms4p>.

`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/SAVE`	`info`	The user clicked the “Speichern” button indicating he wants to save the changes. This doesn’t reflect if the change was successfully saved.
`action/CANCEL_MICROFRONTEND`	`info`	The user clicked the “Zurück” button indicating he wants to cancel the micro-frontend. The integrating portal should react appropriately and close the micro-frontend wrapper without further action.

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

<script>
   document.addEventListener('tef-coms4p', (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-coms4p",
  detail: {
    name: "consents/LOAD",
    level: "info",
    message: "consents loaded successfully"
  }
}
CustomEvent {
  type: "tef-coms4p",
  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-coms4p",
  detail: {
    name: "consents/SAVE",
    level: "info"
  }
}

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-coms4p> supports Semantic Versioning.

Global Resources

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

Console logging is prefixed tef-coms4p.