OneCX angular-integration-interface Library

Overview

@onecx/angular-integration-interface library is a set of tools aiming to ease the development of Angular applications integrated with OneCX by utilizing and extending functionalities of @onecx/integration-interface. This library offers Injectable services exposing a set of functionalities useful for integrating Microfrontends with OneCX without directly utilizing Topics.

Services

App Config Service

Usage

Initialize and access configuration variables for a specific Microfrontend.

It is similar to ConfigurationService, however App Config Service should be used for a Microfrontend configuration management. If sharing the configuration variable with multiple Microfrontends is desired, please use ConfigurationService and provide variables via Shell Application.

Topics used

None

Dependencies

HttpClient

API

App Config Service properties enable access to the config data directly:

Table 1. App Config Service properties
Property name	Type	Description
`config$`	`BehaviorSubject<{ [key: string]: string }>`	BehaviorSubject for Application configuration data.

App Config Service methods can be used for Microfrontend configuration variable management:

Table 2. App Config Service methods
Method signature	Return type	Description
`init(baseUrl: string)`	`Promise<void>`	Initializes App Config Service by loading configuration variables. The configuration will be loaded from the `{baseUrl}/assets/env.json` file.
`getProperty(key: string)`	`string \| undefined`	Gets the value for a key from config$.
`async setProperty(key: string, val:string)`	`void`	Updates the value for a key in config$.
`getConfig()`	`{ [key: string]: string }`	Gets all configuration variables defined for the Microfrontend.

App State Service

Usage

Access information about the platform state.

This service creates new instances of several Topics that contain information about the current state of the platform and makes sure they are cleaned up correctly on destruction.

Topics used

Dependencies

None

API

App State Service properties enable access to topic instances:

Table 3. App State Service properties
Property name	Type	Description
`globalError$`	`GlobalErrorTopic`	GlobalErrorTopic instance.
`globalLoading$`	`GlobalLoadingTopic`	GlobalLoadingTopic instance.
`currentMfe$`	`CurrentMfeTopic`	CurrentMfeTopic instance.
`currentPage$`	`CurrentPageTopic`	CurrentPageTopic instance.
`currentWorkspace$`	`CurrentWorkspaceTopic`	CurrentWorkspaceTopic instance.
`isAuthenticated$`	`IsAuthenticatedTopic`	IsAuthenticatedTopic instance.
`currentPortal$`	`CurrentWorkspaceTopic`	Deprecated. Use currentWorkspace$ instead.

Configuration Service

Usage

Initialize and access configuration variables for a platform.

This service is initialized by, and contains configuration variables, for the Shell Application that could be used in any place on the platform.

ConfigurationService should not be initialized by Microfrontends. They can utilize specific functionality of this service to access and update configuration data.

Topics used

ConfigurationTopic

Dependencies

HttpClient

API

Configuration Service properties:

Table 4. Configuration Service properties
Property name	Type	Description
`config$`	`ConfigurationTopic`	ConfigurationTopic instance.
`isInitialized`	`Promise<void>`	Promise resolved when Configuration Service is initialized.

Configuration Service methods can be used for platform configuration variable management:

Table 5. Configuration Service methods
Method signature	Return type	Description
`init()`	`Promise<boolean>`	Initializes Configuration Service by loading Shell configuration variables and publishes them via ConfigurationTopic. Should not be used in Microfrontends.
`getProperty(key: CONFIG_KEY)`	`string`	Gets value set for a key from topic.
`async setProperty(key: string, val:string)`	`void`	Updates the value for a key in the configuration. Publishes new message via ConfigurationTopic.
`getConfig()`	`Config`	Gets all configuration variables defined for the app from the topic.

Portal Message Service

Usage

Display messages for a short period in an overlay on the top of the page.

This service is a wrapper for MessageTopic that should be used to display messages using translation keys.

Topics used

MessageTopic

Dependencies

TranslateService

API

Portal Message Service properties enable access to the topic instances:

Table 6. Portal Message Service properties
Property name	Type	Description
`message$`	MessageTopic	MessageTopic instance.

Portal Message Service methods can be used for displaying various messages:

Table 7. Portal Message Service methods
Method signature	Return type	Description
`success(msg: Message)`	void	Display message with 'success' severity. Publishes new message via MessageTopic.
`info(msg: Message)`	void	Display message with 'info' severity. Publishes new message via MessageTopic.
`error(msg: Message)`	void	Display message with 'error' severity. Publishes new message via MessageTopic.
`warning(msg: Message)`	void	Display message with 'warning' severity. Publishes new message via MessageTopic.

Message object accepted by the Portal Message Service methods extends the Message object used by the MessageTopic with the following properties:

Table 8. Message object extensions
Property name	Type	Description
summaryKey?	`string`	Translation key of the Message summary text.
summaryParameters?	`object`	Translation parameters of the Message summary text.
detailKey?	`string`	Translation key of the Message detail text.
detailParameters?	`object`	Translation parameters of the Message detail text.

Remote Components Service

Usage

Access Remote Components' information.

This service creates a new instance of RemoteComponentsTopic which contains information about the Remote Components and makes sure it is cleaned up correctly on destroy.

Topics used

RemoteComponentsTopic

API

Remote Components Service properties enable access to topic instances:

Table 9. Remote Components Service properties
Property name	Type	Description
`remoteComponents$`	`RemoteComponentsTopic`	RemoteComponentsTopic instance.

Theme Service

Usage

Change the page display style by applying Themes.

This service allows changing the currently used Theme by applying it to the document and informs about it via a new message in the CurrentThemeTopic.

Topics used

CurrentThemeTopic

Dependencies

HttpClient
ConfigurationService

API

Theme Service properties enable access to topic instances:

Table 10. Theme Service properties
Property name	Type	Description
`currentTheme$`	`CurrentThemeTopic`	CurrentThemeTopic instance.
`baseUrlV1`	`string`	Deprecated.

Theme Service methods:

Table 11. Theme Service methods
Method signature	Return type	Description
`apply(theme: Theme)`	`Promise<void>`	Applies Theme via document style manipulation (styles will be lost on page exit). Publishes a new message via CurrentThemeTopic.
`getThemeHref(themeId: string)`	`string`	Deprecated.
`loadAndApplyTheme(themeName: string)`	`void`	Deprecated.

User Service

Usage

Access the user’s data, settings and permissions.

This service contains user-related information and allows checking user permissions by utilizing Topics.

Topics used

API

User Service properties enable access to the user’s information:

Table 12. User Service properties
Property name	Type	Description
`profile$`	`UserProfileTopic`	UserProfileTopic instance.
`lang$`	`BehaviorSubject<string>`	User’s language. For every new message in the UserProfileTopic, the language will be updated based on the user’s locale information.
`isInitialized`	`Promise<void>`	Promise resolved when User Service is initialized.
`getPermissions()`	`Observable<string[]>`	Observable with list of permissions for the current user.
`permissions$`	`BehaviorSubject<string[]>`	Deprecated.

User Service methods:

Table 13. User Service methods
Method signature	Return type	Description
`hasPermission(permissionKey: string	string[])`	`boolean`

Workspace Service

Usage

Manage Workspace resources.

This service offers set of methods useful when developing Microfrontends referencing other Applications via routing.

Topics used

None.

Dependencies

HttpClient
AppStateService

API

Workspace Service methods can be used for constructing routes to Applications:

Table 14. Workspace Service methods
Method signature	Return type	Description
`getUrl(productName: string, appId: string, endpointName?: string, endpointParameters?:Record<string, unknown>)`	`Observable<string>`	Constructs a valid url for a desired Application in context of the current Workspace. It is possible to use Route endpoints to further customize an accessed resource.
`doesUrlExistFor(productName: string, appId: string, endpointName?: string)`	`Observable<boolean>`	Checks if a valid url exists for a desired Application in context of the current Workspace. It is possible to use Route endpoints to further customize an accessed resource.