ready Method

A message that includes the ready method indicates that all the resources needed for the plug-in's functioning are loaded; the plug-in has started listening to the messages from Oracle Field Service Core Application and is ready to process them.

The plug-in sends the ready message every time it's loaded. When Oracle Field Service Core Application is being loaded or a page is being refreshed, the message, 'Preparing data for offline' is shown to the user. The message is displayed until every plug-in sends the ready message. If a plug-in doesn’t send the ready message within 120 seconds, Oracle Field Service Core Application marks the plug-in as ‘Failed to init’ and shows the corresponding message to the user ("This plugin has not been loaded: ..."). If a plug-in is marked as ‘Failed to init’, Oracle Field Service Core Application tries to re-initialize it when the user opens the plug-in by clicking a button. When a user opens the plug-in through a button, the message, 'Screen is loading. Please wait.' is shown. This message is shown until the plug-in sends the ready message. If a plug-in doesn’t send the ready message within 120 seconds, Oracle Field Service Core Application displays the message, 'The plug-in has not loaded.'.

Message Format

Messages of this method have this format:

{
    "apiVersion": 1,
    "method": "ready",
    "sendInitData": true,
    "showHeader": true,
    "enableBackButton": true
}

Initialization

If you have set the field 'sendInitData' to true, and Oracle Field Service Core Application has loaded the plug-in while initializing (not when the user opens the plug-in), Oracle Field Service Core Application sends an additional init message with initialization data to the plug-in such as attribute description. It destroys the plug-in's iframe only when the plug-in sends the initEnd message. If you have not set the field 'sendInitData' or set it as not equal to true, and Oracle Field Service Core Application loads the plug-in while initializing Oracle Field Service Core Application (not when the user opens the plug-in), Oracle Field Service Core Application destroys the plug-in's iframe immediately after the 'ready' message received. If the user opens the plug-in, the field 'sendInitData' is ignored.

Amount of Data Sent to Plug-In

Oracle Field Service Core Application sends the open message with all data available for entity collections, according to the context layout, where the plug-in's button is placed and depending on how the Available Properties section is configured. For example, if a plug-in is opened from the Activity List page, the data of all the activities for the selected day's queue is sent with the data of all non-scheduled activities of the selected resource. Oracle Field Service Core Application collects and serializes the data, and the plug-in un-serializes it, thereby increasing the loading time for the plug-in. To reduce the amount of this data, the optional parameter, "dataItems" is supported for the ready message. The value of this parameter defines the items that are present in the entity collections. Using this parameter, a plug-in can prevent Oracle Field Service Core Application from sending certain items in the available entity collections, but it can't broaden the set of entity collections that is sent to the plug-in. This set is predefined and depends on the page from which the plug-in is opened.

Format of dataItems

dataItems is an array, where each item is a label of a certain data subset. If the item with the label of some subset is absent in this array, Oracle Field Service Core Application does not send the corresponding items in the entity collections of the open message. If dataItems is not set in the ready message, no filtering is applied and the full data set is sent to the plug-in. Here is the list of available keys and data subsets:

Key	Affected Collections	Description
team	team	Information about assistants and resources who the current resource is assisting to
resource	resource	Properties of the current selected resource
scheduledActivities	activityList	Activities, scheduled (belongs to the queue) for the selected date
nonScheduledActivities	activityList	Non-scheduled activities that don't belong to any date's queue
resourceInventories	inventoryList	Inventories in the "provider" pool
installedInventories	inventoryList	Inventories in the "install" pool
deinstalledInventories	inventoryList	Inventories in the "deinstall" pool
customerInventories	inventoryList	Inventories in the "customer" pool

Example of a Message with "dataItems"

{
    "apiVersion": 1,
    "method": "ready",
    "sendInitData": true,
    "dataItems": ["team",
        "resource",
        "scheduledActivites",
        "nonScheduledActivites",
        "resourceInventories",
        "installedInventories",
        "deinstalledInventories",
        "customerInventories"
    ]
}

Restriction of Navigation with the ready Method

Users can click Back on the header of the page or the browser to exit the plug-in page. Some business flows require mobile users to stay on the required action page until the action is finished. Further, users may be required to go to a specific page after leaving the current page. For example, during the completion flow, a mobile user is required to fill a custom checklist and only after filling it that the regular completion page is displayed. To support such business flows, the parameters "showHeader" and "enableBackButton" are available for the ready method. Here are the details of the “showHeader” and “enableBackButton” parameters:

Param Name	Mandatory	Default Value	Type	Description
enableBackButton	No	true	boolean	If the flag value is set to true, then the Oracle Field Service Core Application "< Back" button is shown and its navigation is not locked. If the flag value is set to false, then the Oracle Field Service Core Application "< Back" button is hidden and the navigation is locked. (The browser's native Back and Forward buttons are blocked, notification is shown if the user uses the native Back button).
showHeader	No	true	boolean	If the flag value is set to true, then the Oracle Field Service Core Application header is shown. If the flag value is set to false, then the header is hidden.

Users can be redirected to a specific page after the plug-in is closed. See the close method for details. This table shows the behavior of the plug-in for different values of the showHeader param.

enableBackButton Value	showHeader = True	showHeader = False
enableBackButton = True	In this scenario: Navigation is possible Global header is visible Page header is visible	In this scenario: Navigation is possible Global header is not visible Page header is not visible
enableBackButton = False	In this scenario: Navigation is not possible Global header is not visible Page header is visible	In this scenario: Navigation is not possible Global header is not visible Page header is not visible

This screenshot shows the scenario when enableBackButton is True and showHeader is True.

This screenshot shows the scenario when enableBackButton is True and showHeader is False.

This screenshot shows the scenario when enableBackButton is False and showHeader is True.

This screenshot shows the scenario when enableBackButton is False and showHeader is False.

Examples of the "ready" Message

// the header is shown but the "back" button is hidden:
{
    "apiVersion": 1,
    "method": "ready",
    "showHeader": true,
    "enableBackButton": false
}

// the header is hidden but the user can go back using browser's back button:
{
    "apiVersion": 1,
    "method": "ready",
    "showHeader": false,
    "enableBackButton": true
}

// the header is hidden and the user can leave the plugin only when the plugin sends the "close" message via Plugin API (the browser's back button does not work):
{
    "apiVersion": 1,
    "method": "ready",
    "showHeader": false,
    "enableBackButton": false
}

sendMessageAsJsObject - use JSON or JS object in transfer

PostMessage technology on early stage had some limitations in some browsers to type of data that is transferred. So on very beginning of Plugin API was decided to use JSON string as simple type of data to communication between Plugin and OFS. During some time OFS start to support receiving of JS object instead of JSON string, but responses still were sent as JSON string.

"TakePhoto" procedure which requires to send photo as a file from OFS to plugin as a result of procedure calling. So in 23.5 was added functionality to send data as JS object from OFS to Plugin. In order to keep backward compatibility it was added "sendMessageAsJsObject" flag that by default is equal to true.

Benefits that brings using of JS object:

ability to send files from OFS to Plugin
faster transfer, because it is absent parsing and validation of JSON format

It is highly recommended to use "sendMessageAsJsObject": true in all modern plugins

OFS keep information about choosen variant of transfer in browser's memory. So if "sendMessageAsJsObject":true flag was sent, OFS will transfer data as a JS object until the "sendMessageAsJsObject": false will be sent or while the browser tab will be opened.

Examples of the "ready" message

{
    "apiVersion": 1,
    "method": "ready",
    "sendMessageAsJsObject": true
}