wakeup Message

Oracle Field Service destroys a plug-in's iframe window after the close message is successfully run, regardless of whether the device is online or offline. So, no JavaScript code runs after the plug-in is closed. However, the plug-in may have data, which must be synchronized with its server side, Oracle Field Service REST API, or third-party services. Hence, the wakeup parameter is available with the close message.

wakeupNeeded with close

The optional parameter wakeupNeeded is added to the close message to let the plug-in synchronize its data as mentioned earlier. If wakeupNeeded is set to true, the Oracle Field Service Core Application opens the plug-in's hidden iframe in the background, as soon as Oracle Field Service Core Application is online, but no earlier than 10 seconds after the plug-in is closed. After the plug-in iframe is opened, Oracle Field Service Core Application sends the wakeup message to the plug-in, in response to the ready message. The plug-in then sends the sleep message back to Oracle Field Service Core Application, when it finishes synchronization. This lets Oracle Field Service Core Application destroy the iframe.

If the plug-in tries to synchronize, but still has data to be sent, it sends the sleep message with the wakeupNeeded param set to true. In this case, Oracle Field Service Core Application opens the plug-in's iframe in the background again, as soon as Oracle Field Service Core Application is online, but no earlier than five minutes after the plug-in is closed. If the plug-in doesn't send the sleep message in two minutes (120 s) after the wakeup message is sent, Oracle Field Service Core Application destroys its iframe and reopens it again, as if the plug-in sent the sleep message with the wakeupNeeded param set to true.

Example of close with wakeupNeeded

{
    "apiVersion": 1,
    "method": "close",
    "activity": {
        cname: "John"
    },
    "wakeupNeeded": true,
    "wakeOnEvents": {
        "online": { wakeupDelay: 120 },
        "timer": { wakeupDelay: 10, sleepTimeout: 1800 }
    }
}

wakeupNeeded with initEnd

The optional parameter wakeupNeeded is added to the initEnd message, to let the plug-in synchronize even after refreshing Oracle Field Service Core Application or closing the browser. If the plug-in doesn't synchronize within two minutes that is allowed for initialization, it sends the initEnd message with the wakeupNeeded parameter set to true. In this case, Oracle Field Service Core Application opens the plug-in's iframe in the background, as soon as Oracle Field Service Core Application is online, but no earlier than five minutes after it receives the initEnd message.

The plug-in opens in five minutes after it's closed, if the wakeupNeeded parameter of close, sleep, or initEnd messages is set to true. This happens even if Oracle Field Service Core Application doesn't detect the offline mode, when the plug-in is opened or closed. If the user opens the plug-in by clicking its button, the background iframe is destroyed without sending any messages to the plug-in. If the plug-in still has data to be synchronized, it sends the close message with the wakeupNeeded parameter set to true.

Example of wakeup Message for the online event

{
    "apiVersion": 1,
    "method": "wakeup",
    "event": online
}

Example of wakeup Message for the timer event

{
    "apiVersion": 1,
    "method": "wakeup",
    "event": timer
}

Configure the Frequency and Duration of a Background Operation

Apart from the wakeupNeeded field, you can also use the optional field wakeOnEvents to control the frequency and duration of a plug-in's background operation. This field is applicable only for close, initEnd, and sleep methods. If the wakeupNeeded field is absent, empty, or is set to false, then the wakeOnEvents field is ignored.

The value of wakeOnEvents is an object with two possible keys, which define the event for which the plug-in must be opened for background operation:

online: If this field is set and is not null, the plug-in is opened in the background only when Oracle Field Service is online, as if wakeOnEvents field was not sent.
timer: If this field is set and is not null, the plug-in is opened in the background regardless of the connection status.

The value of these fields has the same format - it's an object with two optional fields:

Field	Type	Min Value	Max Value	Default Value	Description
wakeupDelay	Number (integer)	10	-	300	Delay (in seconds), after which Oracle Field Service opens the plug-in in the background and sends a wakeup message. Oracle Field Service wakes a plug-in as close as possible to the requested time, but not earlier than that. The actual time may be longer because of the browser's limitations.
sleepTimeout	Number (integer)	10	3600	120	Duration in seconds, after which Oracle Field Service forcibly closes a background frame of the plug-in if it hasn't sent a sleep message explicitly. This period starts when Oracle Field Service sends the wakeup message to the plug-in.

Field

Type

Min Value

Max Value

Default Value

Description

wakeupDelay

Number (integer)

300

Delay (in seconds), after which Oracle Field Service opens the plug-in in the background and sends a wakeup message.

Oracle Field Service wakes a plug-in as close as possible to the requested time, but not earlier than that. The actual time may be longer because of the browser's limitations.

sleepTimeout

Number

(integer)

3600

120

Duration in seconds, after which Oracle Field Service forcibly closes a background frame of the plug-in if it hasn't sent a sleep message explicitly. This period starts when Oracle Field Service sends the wakeup message to the plug-in.

If both online and timer are set, the plug-in is opened on the first event for which all conditions are met (wakeupDelay period has passed, Oracle Field Service is online (for the online event)).

If both fields have the same value for wakeupDelay and Oracle Field Service is online, then there's no guaranteed order of wakeup events.

The default value for wakeOnEvents is { online: {} }. That is, the plug-in is woken only on an online event with a default delay to maintain backward compatibility.

If wakeOnEvents is set and is empty, or all its fields equal to null, it's equivalent to wakeupNeeded: false.

Background synchronization schedule is discarded as soon as the plug-in sends the close, initEnd, or sleep message. So if a plug-in has to be opened in the background again after that, it must send the new (or the same) value of wakeupNeeded and wakeOnEvents in the close, initEnd, or sleep message.

Note: Constant working of plug-ins in the background is not advised, as it may negatively affect a device's performance (hence the user experience) and its battery life. However, if it is necessary for your business, then the best practice is to set a higher value for sleepTimeout (up to 3600 s (1 hour)). This helps to avoid repeated reopening and closing of the plug-in's frame in high-frequency series (which will be the case if the values of wakeupDelay and sleepTimeout both set to low values and waking up is requested by each sleep message).

Available Message Fields for wakeup:

eventName: Name of the wakeup event which caused the error (if applicable).
paramName: Name of the event field which caused error (if applicable).