COMS Micro-Frontend for self-care/ecare customer self-service 1.0.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:
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
- ICT:
-
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-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
orsp-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 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-coms4p>
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 thefetch
attribute. new raitt
- The user is a customer who has logged via legacy piranha (eg. https://login.o2online.de). These customers will get their
spId
andlcId
via the userinfo fetched for these types of tokens. This is the only case wherespId
andlcId
are optional (see below).
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.
The following attributes are supported.
access-token
deprecated
Optional.
The agent token is sent to the COMS backend for authentication & authorization.
sp-id
Optional if using piranha token, otherwise required.
Will override the default sp-id
taken from the token of the active user.
The service provider id (eg. SP301)
lc-id
Optional if using piranha token, otherwise required.
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 CustomEvent
s 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
.