Web SDK documentation
  1. Injectables
  2. OptionsService

File

core/common/options.service.ts

Description

A service that allows to set or get application options which configure the default behavior of the UI.

Extends

ApplicationOptions

Index

Properties
Methods

Constructor

constructor(options, systemOptionsService: SystemOptionsService, tenantOptionService: TenantOptionsService)
Parameters :
Name Type Optional
options No
systemOptionsService SystemOptionsService No
tenantOptionService TenantOptionsService No

Methods

delete
delete(key: T)
Type parameters :
  • T

Deletes an application option.

Parameters :
Name Type Optional Description
key T No

The key to remove.
Returns : void
get
get(optionKey: T, defaultValue?, attemptParse?: boolean)
Type parameters :
  • T

Returns an application option used to configure the UI.

Parameters :
Name Type Optional Description
optionKey T No

The application options key.
defaultValue Yes

A value to return if non is set.
attemptParse boolean Yes

Indicates whether the value should be parsed with JSON.parse.
get$
get$(optionKey: T, defaultValue?, attemptParse?: boolean)
Type parameters :
  • T

Returns an observable of an application option used to configure the UI.

Parameters :
Name Type Optional Description
optionKey T No

The application options key.
defaultValue Yes

A value to return if non is set.
attemptParse boolean Yes

Indicates whether the value should be parsed with JSON.parse.
Returns : Observable<>
Async getActivateSupportUser
getActivateSupportUser()

Returns if the tenant allows to show the activate-support user menu entry. Note: Only if system-level support-user/enabled is false we can activate it at tenant level.

Returns : unknown
Async getCurrentTenantOption
getCurrentTenantOption(category: string, key: string, defaultValue?: T)
Type parameters :
  • T

Gets current tenant option value from the tenant service omitting the inheritance supported based on given parameters.

Parameters :
Name Type Optional Description
category string No

The category for this option.
key string No

The key for that option.
defaultValue T Yes

The default if the option was not found.
Returns : Promise<T | string>
Async getInheritedTenantOption
getInheritedTenantOption(category: string, key: string, defaultValue?: T)
Type parameters :
  • T

Gets an inherited from parent value from the tenant service if inheritance supported based on given parameters.

Parameters :
Name Type Optional Description
category string No

The category for this option.
key string No

The key for that option.
defaultValue T Yes

The default if the option was not found.
Returns : Promise<T | string>
Async getSupportUrl
getSupportUrl()

Gets support URL from:

  • application option supportUrl,
  • or current tenant's option configuration / system.support.url,
  • or current tenant's inherited option configuration / system.support.url,
  • or system option configuration / system.support.url,
  • otherwise defaults to false.
Returns : unknown

Returns support url or false.
Async getSystemOption
getSystemOption(category: string, key: string, defaultValue?: T)
Type parameters :
  • T

Gets a value from the system service and parses it.

Parameters :
Name Type Optional Description
category string No

The category for this option.
key string No

The key for that option.
defaultValue T Yes

The default if the option was not found.
Returns : Promise<T | string>
Async getTenantOption
getTenantOption(category: string, key: string, defaultValue?: T)
Type parameters :
  • T

Gets a value from the tenant service and parses it.

Parameters :
Name Type Optional Description
category string No

The category for this option.
key string No

The key for that option.
defaultValue T Yes

The default if the option was not found.
Returns : Promise<T | string>
set
set(key: T, value)
Type parameters :
  • T

Sets an application option.

Parameters :
Name Type Optional Description
key T No

The key to set.
value No

The value to set.
Returns : void

Properties

optionsUpdated$
Type : Observable<void>
Optional alarmsRefreshType
Type : "interval" | "realtime"

Defines the type of refresh mechanism used for alarms in the application.

  • 'realtime': Utilizes a realtime mechanism for updating alarms.
  • 'interval': Utilizes HTTP polling at regular intervals to refresh the alarms.

This setting allows to switch between realtime and interval-based refresh methods.
Optional brandingCssVars
Type : BrandingCssVars

Object with properties that will be converted to CSS custom variables.
Optional brandingEntry
Type : string | boolean

Path to the branding entry file. (Set it to false to disable any styling. You can handle the styling then on your own e.g. in an angular.json file using ng-cli)
Optional brandingPreview
Type : boolean

Enables the branding preview mode. If set to true, the dynamicOptionsUrl will be polled regularly for changes. In case the lastUpdated field of the dynamic options changes, the page is reloaded in order to apply the new branding.
Optional brandingUrl
Type : string

URL to *.css file which will replace default branding.
Optional breadcrumbs
Type : boolean

Enable or disable breadcrumbs in the header for groups and devices (default: false).
Optional companyName
Type : string

Name of company handling support requests from app users (displayed in notification message).
Optional contentSecurityPolicy
Type : string

CSP string to be applied to index.html by replacing default values.
Optional contextHelp
Type : boolean | string

Allows to enable or disable context help, or to override the default base URL used to load its contents. By default, the context help uses the same base URL as defined in the docsBaseUrl option (if this option is undefined, then the following value will be used: https://www.cumulocity.com/guides/{{version}}). Alternatively, if a string is provided here, it'll be used as the base URL and any {{ version }} placeholder will be replaced with the relevant docs version.
contextPath
Type : string
Optional cookieBanner
Type : CookieBannerConfiguration

Cookie Banner configuration
Optional cookiePreferences
Type : CookiePreferencesConfiguration

Cookie preferences configuration. Here you can enable or disable cookie categories
Optional copy
Type : []

Additional assets to copy to the build output. See https://github.com/webpack-contrib/copy-webpack-plugin for more information about the patterns to add here.
Optional disableOnlyRootsQuery
Type : boolean

By default, cockpit and devicemanagement use the onlyRoots query to resolve root nodes. This could lead to performance issues, if a customer has a lot of root nodes. Therefore you can disable the use of this query with this flag.
Optional disableTracking
Type : boolean

Disable user tracking
Optional docs
Type : Docs

Documentation links settings.
Optional docsBaseUrl
Type : string

Base URL for documentation links (include {{ version }} placeholder, if you want versioned links).
Optional dynamicOptionsUrl
Type : string | boolean

URL to dynamically fetched options. If set to true or left undefined, an URL will be used based on the applications contextPath. If set to false, no dynamic options will be fetched.
Optional entryModule
Type : string

Entry module for Angular compiler (only used with lazy loaded routes), e.g. 'app.module.ts#AppModule'.
Optional exports
Type : PluginsExports[]

NgModule export for plugins.
Optional extraCss
Type : string

Stylesheet (CSS) that will be added at runtime. The string should actually contain the CSS not a path or URL to it.
Optional extraCssUrls
Type : string[]

Array of URLs to additional *.css files to be loaded at runtime.
Optional faviconUrl
Type : string

URL to favicon.
Optional forceSetup
Type : boolean

Allows to force showing the setup wizard.
Optional forceUrlRemotes
Type : boolean

If set to true, only remotes defined in the remotes query parameter will be loaded.
Optional gainsightKey
Type : string

A key for the product experience software Gainsight.
Optional globalTitle
Type : string

HTML page title.
Optional guideHrefTemplate
Type : string

URL template for documentation links (default: '${docsBaseUrl}${partialUrl}').
Optional hideNavigator
Type : boolean

Collapse navigator on initial load.
Optional hidePlatformInformation
Type : boolean

Hides the "Platform information" in the right drawer, will overrule the "hidePowered" option
Optional hidePowered
Type : boolean

Hide "powered by" and version info at the bottom of the navigator and in the right drawer.
Optional hideTypeDashboardForAssets
Type : boolean

Hides possibility to create typed dashboards for assets (and groups). If true, typed dashboards can be created only for devices. It is true by default.
Optional i18nExtra
Type : I18nExtra

Allows to add custom translations. It is an optional property.

Its keys are language codes (https://cumulocity.com/guides/users-guide/getting-started/#a-name-languages-a-available-languages) and its values are objects with key-value pairs, where the key is the original string in English and the value - its translation.

  • Home: "Startseite"

For example you can add the translation of your custom cookie banner configured in the branding settings:

Example :
"i18nExtra": {
  "de": {
    "About cookies on Cumulocity IoT": "Informationen zu Cookies in Cumulocity IoT",
    "Click Agree and Proceed to accept cookies and go directly to the platform or click on Privacy Policy to see detailed descriptions of the used cookies.": "Klicken Sie auf Zustimmen und fortfahren, um Cookies zu akzeptieren und direkt zur Plattform zu gelangen, oder klicken Sie auf Datenschutzrichtlinie, um detaillierte Beschreibungen der verwendeten Cookies anzuzeigen."
  }
}
Optional icon
Type : Icon

Application icon to be displayed in app switcher and header bar.
Optional indexTemplate
Type : string

Path to custom index.html (otherwise default one will be used).
Optional isSetup
Type : boolean

Indicates if the application needs to show the setup wizard.
key
Type : string
Optional label
Type : string

Is used for plugins to indicate their owner. Software AG plugins are marked with OFFICIAL label.
Optional languages
Type : Languages

Allows for adding or overriding languages available in the application.

Its keys are language codes and its values are objects with the following properties:

  • name: English name of the language,
  • nativeName: native name of the language,
  • url: full URL to JSON file with compiled translations; if not defined, translations will be loaded from ${localePath}/${langCode}.json.

Example:

Example :
"languages": {
  "de": {
    "name": "German",
    "nativeName": "Deutsch",
    "url": "/apps/public/ui-assets/de.json"
  }
}
Optional localePath
Type : string

Path to the folder from which *.po files will be loaded.
Optional loginExtraLink
Type : LoginExtraLink | LoginExtraLink[]

Additional link(s) to display on login screen.
Optional mapConfig
Type : MapDefaultConfig

Allows to set default configurations on the maps.
Optional mapLayers
Type : MapTileLayer[]

Allows to set the map layers. If not set, defaults to open street map layer.
Optional mapNominatimUrl
Type : string

The URL used to lookup geo coordinates for a user provided address via nominatim API. Can be set to empty to disable the find address feature on the location tab. Uses: https://nominatim.openstreetmap.org/search?format=json&q={searchTerm} if not set.
Optional mapWidgetHideMaxDeviceOnMapHint
Type : boolean

Allows to hide the hint that there are more devices with geo coordinates then displayed on the map widget and maps in general.
Optional mapWidgetPageSize
Type : number

Allows to adjust the default pagesize of 100 items of the map widget and maps in general.
Optional mapWidgetRealtimeDisabled
Type : boolean

Disables realtime updates on the map widget and maps in general.
name
Type : string
Optional newsletter
Type : boolean

Show or hide a newsletter subscription checkbox in edit user modal.
Optional noAppSwitcher
Type : boolean

Hide application in app switcher (saved to the server).
Optional noLogin
Type : boolean

By default a WebSDK app requires the user to be logged in. In case you would like to develop just a static application, that does not require any kind of access to the backend, you can use this flag to disable the login screen. NOTE: not all WebSDK components support this, some might require the user to be logged in and won't work.
Optional noPlugins
Type : boolean

Allows to opt out of supporting/loading plugins for this application.
Optional noVersionWarning
Type : boolean

Allows to opt out of the version warning which is shown in the dev tools.
Optional remotes
Type : RemotePlugins

List of imported remote plugins.
Optional rightDrawer
Type : boolean

Enable or disable the right drawer.
Optional rootNodeModulesPath
Type : string

Path to the root node_modules dir (useful when working in monorepo setup, e.g. yarn workspaces).
Optional rootTagName
Type : string

The name of the root element. By default c8y-bootstrap.
Optional sensorPhone
Type : boolean

Enables cloud sensor wizard
Optional source
Type : string | number | IApplication

The package source a application origins from as IApplication or simply the id of the source
Optional storageLimitationFeatureEnabled
Type : boolean

Enable or disable storage limitation feature.
Optional supportUrl
Type : boolean | string

URL to support page (set to false to hide the link).
Optional supportUserString
Type : string

Replacement string for user field in audit logs for actions performed by a support user (available placeholders: {{support_user}}, {{supported_user}}).
Optional tabsHorizontal
Type : boolean

Show tabs horizontally or vertically.
Optional tsConfigPath
Type : string

Path to tsccnfig.json file if TypeScript is used (default: ./tsconfig.json).
Optional upgrade
Type : boolean

Set to true if the application is hybrid and uses Angular and AngularJS simultaneously.
version
Type : string
Optional versioningMatrix
Type : VersioningMatrix

A matrix of versions indicating which versions of the application (key) are dependent on which version of a cumulocity component (API version and Web SDK version of the shell application currently supported, indicated by the value). The versions of the dependent components can be indicated by a semver range.

Example :
```json
{
 "1.0.0": {
   "sdk": ">=1016.0.0 <1017.0.0",
   "api": ">=1016.0.0 <1017.0.0"
 },
 "2.0.0": {
   "sdk": "~1017.0.0",
   "api": "~1017.0.0"
 },
 "3.0.0": {
   "sdk": ">=1018.0.0",
   "api": ">=1018.0.0"
 },
}
Example :
Optional webSdkVersion
Type : string

results matching ""

    No results matching ""