OneCX react-integration-interface Library

Overview

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

Contexts

App State Provider

Usage

Access information about the platform state.

This context 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

GlobalErrorTopic
GlobalLoadingTopic
CurrentMfeTopic
CurrentPageTopic
CurrentWorkspaceTopic
IsAuthenticatedTopic

Dependencies

None

API

App State Provider properties enable access to topic instances:

Table 1. App State Provider 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 Provider

Usage

Initialize and access configuration variables for a platform.

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

Topics used

ConfigurationTopic

Dependencies

HttpClient

API

Configuration Provider properties:

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

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

Table 3. Configuration Provider 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.

Theme Provider

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
ConfigurationProvider

API

Theme Provider properties enable access to topic instances:

Table 4. Theme Provider properties
Property name	Type	Description
`currentTheme$`	`CurrentThemeTopic`	CurrentThemeTopic instance.

Theme Provider methods:

Table 5. Theme Provider 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`	Get theme href
`loadAndApplyTheme(themeName: string)`	`void`	Load and apply theme

User Provider

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

UserProfileTopic
PermissionsTopic

API

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

Table 6. User Provider 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.
`permissions$`	`BehaviorSubject<string[]>`	Permission.

User Provider methods:

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

Workspace Hook

Usage

Manage Workspace resources.

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

Topics used

None.

Dependencies

HttpClient
AppStateProvider

API

Workspace Hook - useWorkspace can be used for constructing routes to Applications:

Table 8. Workspace Hook 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.