Skip to content

Base Service Functions

Following functions are provided in the WidgetBaseService that can be used for widget development. Actual implementation of these functions are injected from the client framework. These are exposed through CloudHomeWidgetBaseDirective which is extended by each widget entry component. Several base framework utility services are provided to support various widget functional requirements.

widgetFrameworkUtilsService

Consists of a set of methods that can be used to access a generic set of framework functions for various purposes.

Enable the navigation action from a widget to redirect users to a different page.

Parameters:

  • url [string] - URL of the page to navigate
  • context [any] - any contextual information to be passed when navigating to the page

Example:

this.widgetFrameworkUtilsService.navigate('page/ViewDocuments/DocumentActivities', {});

this.widgetFrameworkUtilsService.navigate('page/ViewDocuments/DocumentActivities?$filter=DocId eq 10', {});

translate$

Get the translated value for a translatable label

Parameters:

  • key [string] - Property name of the translatable (In Marble client file or default translations JSON file)

Returns:

  • Observable<string> - translation value

Example:

translatedReportedHoursLabel$: Observable<string> = this.widgetFrameworkUtilsService.translate$('ReportedHours').pipe(take(1));

translationsLoadingState$

Get the loading state of the translations

Returns:

  • Observable<TranslationsLoadingState | null> - loading state ('initial' | 'loading' | 'loaded' | 'error')

Example:

translationsLoadingState$: Observable<TranslationsLoadingState | null> = this.widgetFrameworkUtilsService.translationsLoadingState$();

setCopilotPrompt

Used to pass a prompt from a widget to the copilot.

Parameters:

  • widgetId [string] - ID of the widget
  • prompt [string] - prompt to be shown in the copilot chat
  • description [string] - prompt description
  • openPanel [boolean] - (deprecated) whether to open the copilot panel or not (true by default)
  • context [Array<CopilotPromptParam>] - (optional) context params to be passed to the copilot, CopilotPromptParam is an id/value pair

Example:

this.widgetFrameworkUtilsService.setCopilotPrompt(fwWidget2Metadata.id, `Please show me guidelines to ${type} an Order`, `Guidelines to ${type} an Order`, true, [{id: 'isDemo', value: true}]);

copilotAvailable

Used to enable widgets to check whether the copilot is available or not

Returns:

  • Observable<boolean> - copilot availability status

Example:

// TS
showCopilotButtons$: Observable<boolean> = this.widgetFrameworkUtilsService.copilotAvailable();

// HTML
<button *ngIf="showCopilotButtons$ | async" graniteButton (click)="getAIHelp()">
     <granite-icon>help-ai</granite-icon>
</button>

getTeamsAudioCall

Start a Teams audio call with a contact person

Parameters:

  • email [string] - Email address of the contact

Example:

this.widgetFrameworkUtilsService.getTeamsAudioCall('alain.prost@mmail.com');

getTeamsVideoCall

Start a Teams video call with a contact person

Parameters:

  • email [string] - Email address of the contact

Example:

this.widgetFrameworkUtilsService.getTeamsVideoCall('alain.prost@mmail.com');

startTeamsChat

Start a Teams chat with a contact person

Parameters:

  • email [string] - Email address of the contact

Example:

this.widgetFrameworkUtilsService.startTeamsChat('alain.prost@mmail.com');

showToastMessage

Show a toast message in IFS Cloud

Parameters:

  • type [MessageType] - Type of toast message (Error | Warning | Info | Success)
  • message [string] - Message to be shown in the toast
  • title [string] - (optional) Title of the toast message
  • details [string] - (optional) Additional details for the toast message

Example:

this.widgetFrameworkUtilsService.showToastMessage(MessageType.Error, 'Error occured while loading Widget data!', 'Failed Loading Widget Data');

showMessageBox

Show a message box in IFS Cloud

Parameters:

  • message [string] - Message to be shown in the message box
  • type [MessageBoxType] - (optional) Type of the message box (Error | Warning | Information | Question | Generic | Server),
  • title [string] - (optional) Title of the message box
  • standardActions [MessageBoxActions] - (optional) Standard message box actions (Ok | OkCancel | YesNo | YesNoCancel)
  • customActions [Array<string>] - (optional) Set of custom action button names
  • customIcon [string] - (optional) Custom icon
  • preselected [any] - (optional) Pre-selected action button
  • wide [boolean] - (optional) Is a wide message box

Returns:

  • Observable<string> - User Response for the message box action

Example:

this.widgetFrameworkUtilsService.showMessageBox('Error occured while loading Widget data!', MessageBoxType.Error, 'Failed Loading Widget Data', MessageBoxActions.Ok);

Data Provider Service (WidgetDataProviderService)

These functions can be used to send a request to an Odata Function, Action or an Entityset in the connected Projection in metadata. Optional parameters should be left as undefined unless a specific option is required for the query.

odataFunction

Execute Odata function and returns the response

Parameters:

  • fn [string] - Function name
  • options [any] - (optional) Function parameters
  • warningsSupported [boolean] - (optional) If warnings are supported
  • addTzHeader [boolean] - (optional) If time zone header should be added
  • addIgnoreSiteTzFilter [boolean] - (optional) If ignore site time zone filter header should be added

Returns :

  • Observable<any> - Http response for the request

Example :

this.widgetDataProviderService.odataFunction(`GetOrderDetails(Context='Test')`)
   .subscribe((data: any) => {});

odataAction

Execute odata action and returns the response

Parameters :

  • fn [string] - Action name
  • params [{ [key: string]: any }] - Function parameters. Keep {} in no parameters
  • etag [string] - (optional) Etag of the record
  • warningsSupported [boolean] - (optional) If warnings are supported
  • addTzHeader [boolean] - (optional) If time zone header should be added
  • addIgnoreSiteTzFilter [boolean] - (optional) If ignore site time zone filter header should be added

Returns :

  • Observable<any> - Http response for the request

Example :

this.widgetDataProviderService.odataAction(`SetOrderComplete` { OrderNo: '007'})
   .subscribe((response: any) => {});

getRequest

Executes http get request to the connected projection endpoint. Can be used to fetch entityset data or execute Functions.

Parameters :

  • url [string] - Endpoint url
  • metadatafull [boolean] - (optional) If metadata full (keep undefined)
  • addTzHeader [boolean] - (optional) If time zone header should be added
  • addIgnoreSiteTzFilter [boolean] - (optional) If ignore site time zone filter header should be added

Returns :

  • Observable<HttpResponse<any> | null - Http response for the request

Example:

this.widgetDataProviderService.getRequest('OrderDetailsSet')
  .pipe(map(res => res?.body?.value))
  .subscribe(() => {});

postRequest

Executes http post request to the connected projection endpoint. Can be used to execute a post request on an Entityset or execute Actions.

Parameters :

  • url [string] - Endpoint url
  • data [any] - Parameters data object
  • etag [string] - (optional) Etag of the record
  • addTzHeader [boolean] - (optional) If time zone header should be added
  • addIgnoreSiteTzFilter [boolean] - (optional) If ignore site time zone filter header should be added

Returns :

  • Observable<HttpResponse<any> | null - Http response for the request

Example:

this.widgetDataProviderService.postRequest('UpdateOrderLine', {Line: '505'})
  .pipe(map(res => res?.body))
  .subscribe(() => {});

patchRequest

Executes http patch request to the connected entityset.

Parameters:

  • url [string] - Endpoint url
  • data [any] - Parameters data object
  • etag [string] - Etag of the record
  • addTzHeader [boolean] - (optional) If time zone header should be added
  • addIgnoreSiteTzFilter [boolean] - (optional) If ignore site time zone filter header should be added

Returns:

  • Observable<HttpResponse<any> | null- Http response for the request

Example:

this.widgetDataProviderService.patchRequest(`OrderLinesSet(Line='2077')`, {Quantity: '505'}, #etag)  .subscribe();

deleteRequest

Executes http delete request to the connected entityset.

Parameters :

  • url [string] - Endpoint url
  • data [any] - Parameters data object
  • etag [string] - Etag of the record

Returns :

  • Observable<HttpResponse<any> | null- Http response for the request

Example :

this.widgetDataProviderService.deleteRequest(`OrderLinesSet(Line='2077')`, {}, #etag)  .subscribe();

download

Download file.

Parameters :

  • url [string] - Endpoint url
  • context[any] - (optional) Context object

Example :

this.widgetDataProviderService.download(`DocSet(DocNo='D00036')/FileData`)  .subscribe();

upload

Upload file.

Parameters :

  • url [string] - Endpoint url
  • data [File | string] - File or string
  • etag [string] - Record Etag
  • id [number] - (optional) Custom Id

Example:

this.widgetDataProviderService.upload(`DocSet(DocNo='D00036')/FileData`, File, #etag)
  .subscribe();

frameworkServicesRequest

Framework services get request through FrameworkServices.svc

Parameters :

url [string] - Endpoint url

Returns:

  • Observable<HttpResponse<any> | null - Http response for the request

Example : 

this.widgetDataProviderService.frameworkServicesRequest('GetApplicationName()')  .subscribe();

Converter Utilis Service (WidgetConverterUtilsService)

Functions for converting and formatting date, time, time zones, numbers, and currency.

iSOToDate

Converts an ISO formatted string to a Date object. When applyTimezone is set the internal representation is adjusted for the current user time zone so that when formatted it will show the date and time as it came in the string.

Parameters :

  • value [string] - Endpoint url
  • applyTimeZone [boolean] - (Optional) If time zone offset should be removed. Default is true

Returns :

  • Date - native date object

Example :

this.widgetConverterUtilsService.iSOToDate('2014-12-23T00:00:00Z')

toISODatetime

Converts legacy date to ISO format to be used when sending with odata

Parameters :

  • date [Date] - Datetime in legacy format
  • addUtcOffset [boolean] - (Optional) To add UTC offset to the date. Default is true

Returns :

  • string - ISO date string

Example :

this.widgetConverterUtilsService.toISODatetime(new Date(2022, 0, 1, 13, 14, 15)) // expected output 2022-01-01T13:14:15Z

toISOTime

Converts legacy date to ISO time format to be used when sending with odata

Parameters :

  • date [Date] - Datetime in legacy format
  • delimiter [string] - (Optional) To addCustom delimiter to use. Default is ':'

Returns :

  • string - ISO time string

Example :

this.widgetConverterUtilsService.toISODatetime(new Date('2023-10-01T00:00:00Z')) // expected output 00:00:00.000Z

getWorkingTimeZone

Returns user’s working time zone

Returns :

  • string - ISO time string

Example :

this.widgetConverterUtilsService.getWorkingTimeZone() // expected output sample: America/Chicago

formatDateTime

Converts legacy date to ISO time format to be used when sending with odata

Parameters :

  • isoDate [string] - Date to format in ISO format
  • applyTimeZone [boolean] - (Optional) If time zone offset should be removed. Default is true
  • options [string] - (Optional) Options to format the date: showOnlyDate | longtime | short

Returns :

  • string - Formatted date string

Example:

this.widgetConverterUtilsService.formatDateTime('2014-12-23T11:30:15Z', true, 'longtime') // expected output 12/23/2014, 11:30:15 AM

parseDateTime

Converts legacy date to ISO time format to be used when sending with odata

Parameters :

  • date [string] - Formatted date to be parsed

Returns :

  • Date | null- Native date object or null

Example :

this.widgetConverterUtilsService.parseDateTime('Nov 6, 2018, 4:30:00 PM') // expected output: Parsed Date()

formatNumber

Formats a number to a display string.

Parameters :

  • value [string] - Number to format

Returns :

  • string

Example :

this.widgetConverterUtilsService.formatNumber('Nov 10044.55444') // expected output: 10044,55444

parseNumber

Parses a display number string to a native number.

Parameters :

  • value [string] - Number in string format

Returns:

  • string

Example:

this.widgetConverterUtilsService.parseNumber('−44,33555') // expected output: -44.33555

getTimezoneForTzElement

Get the time zone for a Tz element. Tz element could be server or site. If it is site, the actual site should be provided.

Parameters :

  • tzElement [TzElement] - Tz element to get the time zone for. 
TzElement { type: 'server' | 'site'; siteValue?: string; }

Returns :

  • string | null

Example :

this.widgetConverterUtilsService.getTimezoneForTzElement({ type: 'site', siteValue: rec.site }) // expected output sample: America/Chicago

convertToCustomTimezone

Convert a date to a custom time zone.

Parameters :

  • date [Date] - Date to convert
  • currentTimezone [string] - Current time zone for the date
  • targetTimezone [string] - Designated time zone for conversion

Returns :

  • Date | null - Date object with the time zone applied.

Example :

this.widgetConverterUtilsService.convertToCustomTimezone(Date, 'UTC', 'Europe/Stockholm') // expected output: Timezone converted Date.

UTCToCustomTimezone

A wrapper for convertToCustomTimezone() where sourceTimeZone is UTC. Converts a UTC date to a custom timezone. Can be used to convert ISO date times received through odata provider.

Parameters :

  • date [Date] - Date to convert
  • targetTimezone [string] - Target timezone

Returns :

  • Date | null - Date object with Target time zone applied.

Example :

this.widgetConverterUtilsService.UTCToCustomTimezone(Date,'Europe/Stockholm')

Writing your own injectable services

If the above base services are not sufficient for your implementation, you can write your own abstract service and inject the actual implementation from the client application. Refer fnd-sample-widget-1-context-provider.service in fnd-sample-widget-1 sample library.

Working With Time Zones

Receiving Timestamps from server.

//Convert receivedDateISO to Date object. iSOToDate() will remove the timezone offset.
const receivedDate: Date = this.widgetConverterUtilsService.iSOToDate(receivedDateISO); 

//Get the timezone. When endpoint timestamptzref = "server";
this.timezone = this.widgetConverterUtilsService.getTimezoneForTzElement({ type: 'server' });

//Convert receivedDate from UTC to timezone. This is the date that you should pass into components.
this.convertedDate = this.widgetConverterUtilsService.UTCToCustomTimezone(receivedDate, this.timezone ?? '');

// If this date needs to be formatted into user locale format, you can use the formatDateTime() method.
 this.widgetConverterUtilsService.formatDateTime(this.widgetConverterUtilsService.toISODatetime(<Date>this.convertedDate));

Sending Timestamps to the Server

// Sending Timestamp fields back to the server. The server expects the timestamp in UTC format.

let UTCDate = this.widgetConverterUtilsService.customTimezoneToUTC(<Date>this.convertedDate, this.timezone ?? '');
let isoDateToSend = this.widgetConverterUtilsService.toISODatetime(<Date>UTCDate);