Activity Manager

Service URI - luna://com.palm.activitymanager

Monitors various parts of the system, and launches services when the corresponding events happen. Activities can also be used to schedule work, periodically, or at particular times.

 

The Activity Manager is responsible for coordinating work in the system. This includes work currently being done, and work that is scheduled to be done at some point in the future. The primary unit of control is the Activity, which represents some specific item of work in the system - such as syncing an email account, or a game that is being played. The Activity Manager will track what Apps, Services, and other system resources are associated with particular Activities. The Activity Manager will dynamically alter operating system priorities on those resources. This is to give preference to Activities the user is currently directly interacting with, while lowering the priority of resources associated with background Activities. This is to improve the perceived performance of the system as a whole.

 

Method

Description

Supported in Emulator

adopt Registers an app's or service's willingness to take over as the Activity's parent. Yes
cancel Terminates the specified Activity and sends a "cancel" event to all subscribers. Yes
complete An Activity's parent can use this method to end the Activity and optionally restart it with new attributes Yes
create Creates a new Activity and returns its ID. Yes
release Allows a parent to free an Activity and notify other subscribers. Yes
start Attempts to start the specified Activity Yes
stop Stops an Activity and sends a "stop" event to all Activity subscribers. Yes

 

Open All


adopt

Description

Registers an app's or service's willingness to take over as the Activity's parent.

If your app can wait for an unavailable, not released Activity to become available, then set the "wait" flag to true. If it is, and the Activity is valid, which means Activity exists and is not exiting, the call should succeed. If it cannot wait, and the Activity is valid but cannot be adopted, then the call fails. The adopted return flag indicates a successful or failed adoption.

If not immediately adopted and waiting is requested, the "orphan" event informs the adopter that they are the new Activity parent.

An example where adoption makes sense is an app that allocates a separate Activity for a sync, and passes that Activity to a service to use. The service should adopt the Activity and be ready to take over in the event the app exits before the service is done syncing. Otherwise, it receives a "cancel" event and should exit immediately. The service should wait until the adopt() call returns successfully before beginning Activity work. If adoption fails, it indicates the caller has quit or closed the Activity and the request should not be processed. The Service should continue to process incoming events on their subscription to the Activity.

If the service did not call adopt() to indicate to the Activity Manager its willingness to take over as the parent, it should be prepared to stop work for the Activity and unsubscribe if it receives a "cancel" event. Otherwise, if it receives the "orphan" event indicating the parent has unsubscribed and the service is now the parent, then it should use complete() when finished to inform the Activity Manager before unsubscribing.

Syntax

adopt(Number activityId, String activityName, Boolean wait, Boolean subscribe[, Boolean detailedEvents])

Parameters

Name

Required

Type

Description

activityId Required Number Activity ID. Either this, or "activityName" is required.
activityName Required String Activity name. Either this, or "activityId" is required.
wait Required Boolean Flag to wait for Activity to be released.
subscribe Required Boolean

Flag that decides whether to subscribe or not.

  • true: Subscribe.
  • false: Do not subscribe. Call the method only once. (Default)
detailedEvents Optional Boolean Flag to have the Activity Manager generate "update" events when the state of an Activity's requirement changes.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean  Flag that indicates success/failure of the request.
  • true: Success
  • false: Failure
errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.
See the Error Codes Reference of this method for more details.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.
adopted Optional Boolean True if the Activity was adopted.

Error Reference

Error Code

Error Message

2 No such file or directory
11 Operation blocked
12 Out of memory
13 Permission denied
17 File already exists
22 Invalid argument
38 Function not implemented
-1000 Internal error

Subscription Returns

Name

Required

Type

Description

returnValue Required Boolean  Flag that indicates success/failure of the request.
  • true: Success
  • false: Failure
activityId Required Number Created Activity ID. You could get a subscription when there's status updates.
event Required String

What this activity did. The Activity Manager will generate either an "start" event if the requirements are met, and than return this result to subscriber. It is same when the activity is canceled or stopped as "cancel" or "stop".

Example:​

{
​   "activityId": 10813,
    "event": "start",
    "returnValue": true
}
$activity Required Object Acitivity object.

Example

// Adopt an activity
var request = webOS.service.request("luna://com.palm.activitymanager", {
    method: "adopt",
    parameters: {
        "activityId": 90,
        "wait": true,
        "subscribe": true,
        "detailedEvents": false 
    },
    onSuccess: function (inResponse) {
		if (inResponse.event == "orphan") {
			console.log("The activity has been adopted to current app or service");				
			// To-Do something
		} else if (inResponse.adopted) {
			console.log("The activity has been transfered from current app or service to another adopter");
			// To-Do something
		} else if (!inResponse.adopted) {
			console.log("The succeeded to request a activity adoption and start subscription");
		}
    },
	onFailure: function (inError){
		console.log("Failed to request a activity adoption");
		console.log("[" + inError.errorCode + "]: " + inError.errorText);
		// To-Do something
        return;
	}
});

Return Example

// Subscription return: If parent of the activity did not release the activity. Mostly your app or service will receive this result at first time return.
{
    "adopted": false,
    "returnValue": true
}

// Subscription return: When the activity is released and current app or service adopts the activity. 
// Only one adopter receives this result and it becomes the parent of the activity.
// Other adopter candidates remain as adopter continuously. (First in, First out)
{
    "event": "orphan",
    "activityId": 90,
    "returnValue": true
}

// Subscription return: When the activity is transfered to another adopter.
{
    "adopted": true,
    "returnValue": true
}

// Error return
{
    "errorCode": 2,
    "returnValue": false,
    "errorText": "activityId not found"
}

See Also


cancel

DESCRIPTION

Terminates the specified Activity and sends a "cancel" event to all subscribers. This call should succeed if the Activity exists and is not already exiting.

This is different from the stop() in that the Activity should take little or no time to clean up. On a "cancel", it should immediately abort the processing task, clean up, and exit, On a "stop", it should finish processing task in some reasonable amount of time (10-15 seconds).

SYNTAX

cancel (Number activityId, String activityName)

PARAMETERS

Name

Required

Type

Description

activityId Required Number Activity ID. Either this, or "activityName" is required.
activityName Required String Activity name. Either this, or "activityId" is required.

CALL RETURNS

Name

Required

Type

Description

returnValue Required Boolean Flag that indicates success/failure of the request.
  • true: Success
  • false: Failure
errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.
See the Error Codes Reference of this method for more details.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.
See the Error Codes Reference of this method for more details.

ERROR REFERENCE

Error Code

Error Message

2 No such file or directory
11 Operation blocked
12 Out of memory
13 Permission denied
17 File already exists
22 Invalid argument
38 Function not implemented
-1000 Internal error

EXAMPLE

var request = webOS.service.request("luna://com.palm.activitymanager", {
        method: "cancel",
        parameters: {
        "activityId": 93
    },
    onSuccess: function (inResponse) {
        console.log("The Activity is canceled");
        // To-Do something
    },
    onFailure: function (inError) {
        console.log("Failed to cancel the Activity");
        console.log("[" + inError.errorCode + "]: " + inError.errorText);
        // To-Do something
        return;
    }
});

RETURN EXAMPLE

// Success return
{
    "returnValue": true
}
 
// Error return
{
    "errorCode": 2,
    "returnValue": false,
    "errorText": "activityId not found"
}

SEE ALSO


complete

Description

An Activity's parent can use this method to end the Activity and optionally restart it with new attributes. If there are other subscribers, they receive a "complete" event.

If restart is requested, the Activity is optionally updated with any new Callback, Schedule, or Trigger data and returned to the queued state. Specifying false for any of those properties removes the property completely. For any properties not specified, current properties are used.

If the Activity is persistent (specified with the persist flag in the Type object), the db8 database is updated before the call returns.

Syntax

complete(Number activityId, String activityName[, Boolean restart][, Object callback][, Object schedule][, Object trigger][, Object metadata])

Parameters

Name

Required

Type

Description

activityId Required Number Activity ID. Either this, or "activityName" is required.
activityName Required String Activity name. Either this, or "activityId" is required.
restart Optional Boolean Restart Activity flag. Default is false.
callback Optional Object Callback to use if Activity is restarted.
schedule Optional Object To use if Activity is restarted or just set as false.
trigger Optional Object Trigger to use if Activity is restarted.
metadata Optional Object If Meta data is provided or just set as false.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean  Flag that indicates success/failure of the request.
  • true: Success
  • false: Failure
errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.
See the Error Codes Reference of this method for more details.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.
See the Error Codes Reference of this method for more details.

Error Reference

Error Code

Error Message

2 No such file or directory
11 Operation blocked
12 Out of memory
13 Permission denied
17 File already exists
22 Invalid argument
38 Function not implemented
-1000 Internal error

Subscription Returns

Name

Required

Type

Description

returnValue Required Boolean  Flag that indicates success/failure of the request.
  • true: Success
  • false: Failure
activityId Required Number Created Activity ID. You could get a subscription when there's status updates.
event Required String

What this activity did. The Activity Manager will generate either an "start" event if the requirements are met, and than return this result to subscriber. It is same when the activity is canceled or stopped as "cancel" or "stop".

Example:​

{
​   "activityId": 10813,
    "event": "start",
    "returnValue": true
}
activity Required Object Acitivity object.

Example

var request = webOS.service.request("luna://com.palm.activitymanager", {
	method: "complete",
	parameters: {
		"activityId": 94
	},
	onSuccess: function (inResponse) {
		console.log("The Activity is completed");
		// To-Do something
	},
	onFailure: function (inError) {
		console.log("Failed to complete the Activity");
		console.log("[" + inError.errorCode + "]: " + inError.errorText);
		// To-Do something
		return;
	}
});

Return Example

// Success return 
{
    "returnValue": true
}

// Error return
{
    "errorCode": 2,
    "returnValue": false,
    "errorText": "activityId not found"
}

See Also


create

Description

Creates a new Activity and returns its ID.
You can create either a foreground or background Activity. A foreground Activity is run as soon as its specified prerequisites are met. After a background Activity's prerequisites are met, it is moved into a ready queue, and a limited number are allowed to run depending on system resources. Foreground is the default.

Activities can be scheduled to run at a specific time or when certain conditions are met or events occur.

Each of your created and owned Activities must have a unique name. To replace one of your existing Activities, set the "replace" flag to true. This cancels the original Activity and replaces it with the new Activity.

To keep an Activity alive and receive status updates, the parent (and adopters, if any) must set the "subscribe" flag to true. Activities with a callback and "subscribe=false", the Activity must be adopted immediately after the callback is invoked for the Activity to continue.

To indicate the Activity is fully-initialized and ready to launch, set the flag to. Activities with a callback should be started when created - the callback is invoked when the prerequisites have been met and, in the case of a background, non-immediate Activity, it has been cleared to run.

When requirements are not initially met

​If the creator of the Activity also specifies "subscribe":true, and detailed events are enabled for that subscription, then the Activity Manager will generate either an immediate "start" event if the requirements are met, or an "update" event if the Activity is not yet ready to start due to missing requirements, schedule, or trigger objects. This allows the creating Service to determine if it should continue executing while waiting for the callback, or exit to free memory if it may be awhile before the Activity is ready to run.

Syntax

create(Object activity[, Boolean subscribe][, Boolean detailedEvents][, Boolean start][, Boolean replace])

Parameters

Name

Required

Type

Description

activity Required Object Activity object
subscribe Optional Boolean

Flag that enables whether to subscribe or not.

  • true: Enable the subscription
  • false: Do not enable the subscription (Default).
detailedEvents Optional Boolean Flag to have the Activity Manager generate "update" events when the state of one of this Activity's requirements changes.
start Optional Boolean Start Activity immediately flag. This flag should be set true when subscribe is false.
replace Optional Boolean Cancel Activity and replace with Activity of same name flag.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean  Flag that indicates success/failure of the request.
  • true: Success
  • false: Failure
errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.
See the Error Codes Reference of this method for more details.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.
See the Error Codes Reference of this method for more details.

activityId Optional Number Activity ID

Error Reference

Error Code

Error Message

2 No such file or directory
11 Operation blocked
12 Out of memory
13 Permission denied
17 File already exists
22 Invalid argument
38 Function not implemented
-1000 Internal error

Subscription Returns

Name

Required

Type

Description

returnValue Required Boolean  Flag that indicates success/failure of the request.
  • true: Success
  • false: Failure
activityId Required Number Created Activity ID. You could get a subscription when there's status updates.
event Required String

What this activity did. The Activity Manager will generate either an "start" event if the requirements are met, and than return this result to subscriber. It is same when the activity is canceled or stopped as "cencel" or "stop".

Example:​

{
​   "activityId": 10813,
    "event": "start",
    "returnValue": true
}
$activity Required Object Acitivity object

Example

// Create a basic activity
var request = webOS.service.request("luna://com.palm.activitymanager", {
	method: "create",
	parameters: {
		"activity": {
			"name": "basicactivity",
			"description": "Test create",
			"type": {
				"foreground": true
			},
		},
		"start": true,
		"subscribe": true
	},
	onSuccess: function (inResponse) {
		if (!inResponse.event) {
		    console.log("The Activity is created");
			// To-Do something
		} else {
			console.log("Received event: " + inResponse.event);
			// To-Do something
		}
	},
	onFailure: function (inError) {
		console.log("Failed to create the Activity");
		console.log("[" + inError.errorCode + "]: " + inError.errorText);
		// To-Do something
		return;
	}
});

// Create a scheduled activity
var request = webOS.service.request("luna://com.palm.activitymanager", {
	method: "create",
	parameters: {
		"activity": {
			"name": "ScheduledActivity",
			"description": "Test create of scheduled activity",
			"type": {
				"foreground": true
			},
                    "schedule": {
                        "start": "2015-02-15 13:22:00"
                    }
		},
		"start": true,
		"subscribe": true
	},
	onSuccess: function (inResponse) {
		if (!inResponse.event) {
		    console.log("The scheduled Activity is created");
			// To-Do something
		} else {
			console.log("Received event: " + inResponse.event);
			// To-Do something
		}
	},
	onFailure: function (inError) {
		console.log("Failed to create the Activity");
		console.log("[" + inError.errorCode + "]: " + inError.errorText);
		// To-Do something
		return;
	}
});

// Create a scheduled activity with callback
var request = webOS.service.request("luna://com.palm.activitymanager", {
	method: "create",
	parameters: {
		"activity": {
			"name": "ScheduledActivityWithCallback",
			"description": "Test create of scheduled activity with callback",
			"type": {
				"foreground": true
			},
                        "schedule": {
                                "start": "2015-02-15 00:05:00"
                        },
                        "callback": {
                                "method": "luna://com.webos.audio/setMuted",
                                "params": {
                                    "muted": "true"
                                }
                        }
		},
		"start": true,
		"subscribe": true
	},
	onSuccess: function (inResponse) {
		if (!inResponse.event) {
		    console.log("The scheduled Activity is created");
			// To-Do something
		} else {
			console.log("Received event: " + inResponse.event);
			console.log("Audio will be muted");
			// To-Do something
		}
	},
	onFailure: function (inError) {
		console.log("Failed to create the Activity");
		console.log("[" + inError.errorCode + "]: " + inError.errorText);
		// To-Do something
		return;
	}
});

// Create a triggered activity with callback
var request = webOS.service.request("luna://com.palm.activitymanager", {
	method: "create",
	parameters: {
		"activity": {
			"name": "triggeredActivity",
			"description": "Test create Activity with Trigger",
			"type": {
				"background": true
			},
                        "trigger": {
                                "method": "luna://com.palm.connectionmanager/getStatus",
                                "params": { "subscribe": true }
                        },
                        "callback": {
                                "method": "luna://com.webos.applicationManager/launch",
                                "params": {
                                        "id": "com.yourdomain.app.downloader"
                                }
                        }
		},
		"start": true,
		"subscribe": true
	},
	onSuccess: function (inResponse) {
		if (!inResponse.event) {
			console.log("The scheduled Activity is created");
			// To-Do something
		} else {
			console.log("Received event: " + inResponse.event);
							console.log("Audio will be muted");
			// To-Do something
		}
	},
	onFailure: function (inError) {
		console.log("Failed to create the Activity");
		console.log("[" + inError.errorCode + "]: " + inError.errorText);
		// To-Do something
		return;
	}
});

Return Example

// Success return - First return (When activity is created)
{
    "activityId": 83,
    "returnValue": true
}

// Success return - When activity starts
{
    "event": "start",
    "activityId": 83,
    "returnValue": true
}

// Error return
{
    "errorCode": 22,
    "returnValue": false,
    "errorText": "invalid parameters: caller='' error='required property not found - 'activity''"
}

See Also


release

Description

Allows a parent to free an Activity and notify other subscribers. The Activity is cancelled unless one of its non-parent subscribers adopts it and becomes the new parent. The Activity is cancelled immediately. For a completely safe transfer, a subscribing app or service, prior to the release, should already have called adopt(), indicating its willingness to take over as the parent.

Syntax

release(Number activityId, String activityName)

Parameters

Name

Required

Type

Description

activityId Required Number Activity ID. Either this, or "activityName" is required.
activityName Required String Activity name. Either this, or "activityId" is required.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean  Flag that indicates success/failure of the request.
  • true: Success
  • false: Failure
errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.
See the Error Codes Reference of this method for more details.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.
See the Error Codes Reference of this method for more details.

Error Reference

Error Code

Error Message

2 No such file or directory
11 Operation blocked
12 Out of memory
13 Permission denied
17 File already exists
22 Invalid argument
38 Function not implemented
-1000 Internal error

Example

var request = webOS.service.request("luna://com.palm.activitymanager", {
	method: "release",
	parameters: {
		"activityId": 98
	},
	onSuccess: function (inResponse) {
		console.log("The Activity is released");
		// To-Do something
	},
	onFailure: function (inError) {
		console.log("Failed to release the Activity");
		console.log("[" + inError.errorCode + "]: " + inError.errorText);
		// To-Do something
		return;
	}
});

Return Example

// Success return 
{
    "returnValue": true
}

// Error return
{
    "errorCode": 2,
    "returnValue": false,
    "errorText": "activityId not found"
}

See Also


start

Description

Attempts to start the specified Activity, either moving it from the "init" state to be eligible to run, or resuming it if it is currently paused. This sends "start" events to any subscribed listeners once the Activity is cleared to begin. If the "force" parameter is present (and true), other Activities could be cancelled to free resources the Activity needs to run.

Syntax

start(Number activityId, String activityName)

Parameters

Name

Required

Type

Description

activityId Required Number Activity ID. Either this, or "activityName" is required.
activityName Required String Activity name. Either this, or "activityId" is required.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean  Flag that indicates success/failure of the request.
  • true: Success
  • false: Failure
errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.
See the Error Codes Reference of this method for more details.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.
See the Error Codes Reference of this method for more details.

Error Reference

Error Code

Error Message

2 No such file or directory
11 Operation blocked
12 Out of memory
13 Permission denied
17 File already exists
22 Invalid argument
38 Function not implemented
-1000 Internal error

Example

var request = webOS.service.request("luna://com.palm.activitymanager", {
	method: "start",
	parameters: {
		"activityId": 93
	},
	onSuccess: function (inResponse) {
		console.log("The Activity is started");
		// To-Do something
	},
	onFailure: function (inError) {
		console.log("Failed to start the Activity");
		console.log("[" + inError.errorCode + "]: " + inError.errorText);
		// To-Do something
		return;
	}
});

Return Example

// Success return
{
    "returnValue": true
}

// Error return
{
    "errorCode": 2,
    "returnValue": false,
    "errorText": "activityId not found"
}

See Also


stop

DESCRIPTION

Stops an Activity and sends a "stop" event to all Activity subscribers. This succeeds unless the Activity is already cancelled.

This is different from the cancel() in that more time is allowed for the Activity to clean up. On a "cancel", it should immediately abort the processing task, clean up, and exit. On a "stop", it should finish processing task in some reasonable amount of time (10-15 seconds).

SYNTAX

stop(Number activityId, String activityName)

PARAMETERS

Name

Required

Type

Description

activityId Required Number Activity ID. Either this, or "activityName" is required.
activityName Required String Activity name. Either this, or "activityId" is required.

CALL RETURNS

Name

Required

Type

Description

returnValue Required Boolean Flag that indicates success/failure of the request.
  • true: Success
  • false: Failure
errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.
See the Error Codes Reference of this method for more details.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.
See the Error Codes Reference of this method for more details.

ERROR REFERENCE

Error Code

Error Message

2 No such file or directory
11 Operation blocked
12 Out of memory
13 Permission denied
17 File already exists
22 Invalid argument
38 Function not implemented
-1000 Internal error

EXAMPLE

var request = webOS.service.request("luna://com.palm.activitymanager", {
        method: "stop",
        parameters: {
            "activityId": 93
    },
    onSuccess: function (inResponse) {
        console.log("The Activity is stopped");
        // To-Do something
    },
    onFailure: function (inError) {
        console.log("Failed to stop the Activity");
        console.log("[" + inError.errorCode + "]: " + inError.errorText);
        // To-Do something
        return;
    }
});

RETURN EXAMPLE

// Success return
{
    "returnValue": true
}
 
// Error return
{
    "errorCode": 2,
    "returnValue": false,
    "errorText": "activityId not found"
}

SEE ALSO


Object

Activity Object

Represents everything about an Activity-name, type, state, requirements, schedule, trigger, callback, id,creator, adopters, processes, flows, and associations.

{
    //**The following are Activity creator specified attributes
    "name" : string,
    "description" : string,
    "type" : Type object,
    "schedule" : Schedule object,
    "trigger" : Trigger object,
    "callback" : Callback object,

    //**The following are AM maintained read-only attributes.
    "metadata" : any object,
    "activityId" : int,
    "creator" : Parent object,
    "parent" : Parent object,
    "adopters" : Parent object array,
    "state" : State object,
    "focused" : boolean
}

Name

Required

Type

Description

name

Required String Activity name. Must be unique for creator. Applies to both persistent and non-persistent Activities. The create call will fail if this field is not unique unless the "replace" field is true.
description Required String Activity description.
type Required Object Indicates how the Activity is handled. Principally, it is used to denote the Activity as either foreground or background, and whether it can be paused or cancelled.
schedule Optional Object Time-based requirements for Activity.
trigger Optional Object Event that must occur for Activity to run.
callback Optional Object Call to invoke when Activity runs. This object should be defined when activity is needed to start immediately.
metadata Optional Object Opaque object the Activity Manager stores and returns in the callback parameters.
activityId Optional Number Activity ID
creator Optional Object Activity creator (parent object)
parent Optional Object Activity parent
adopters Optional Object array Activity adopters (parent object array)
state Optional String

Activity state. Property that represents current activity state with following strings:

  • init : Activity has been created and is waiting for Activity's associations and initial app and service subscriptions to be in place.
  • waiting: Activity is waiting for a trigger to fire or its scheduled time to begin running.
  • blocked: Activity is waiting for its specified Requirements to be met.
  • queued: The Activity is queued and ready to run.
  • running: The Activity is running.
  • pause: The Activity is paused.
  • cancelling: The Activity has been cancelled and waiting for potential adopters to take over as the parent.
  • cancelled: The Activity is cancelled.
  • stopping: The Activity is in the process of stopping.
  • stopped: The Activity has been stopped.
  • complete: The Activity is complete and has stopped.
focused Optional Boolean Flag that indicates whether Activity has focus or not.

Callback Object

Callbacks allow a service to stop running and consuming resources while it waits for an Activity to start at a set time or for a trigger to fire. When the Activity begins, the callback is invoked and the service can resume. A callback specification consists of a method and arguments. Activities with a callback should be started immediately. The Activity Manager invokes the callback when the prerequisites are met and, in the case of a background/non-immediate Activity, it is cleared to run.

{
    "method" : string,
    "params" : any
}

Name

Required

Type

Description

method

Required String Callback URI.
params Optional Any Any parameters to pass to the callback.

Schedule Object

The Schedule object defines an Activity's time-based requirements. The time an Activity is scheduled to run can be either absolute or local. If a local time is specified, the Activity Manager watches for time zone changes and automatically adjusts the UTC time.

Smart Intervals, specified with the interval field, allow tasks to be scheduled in evenly aligned batches, optimizing battery power and efficiency. Smart intervals are specified with the interval string field as "##d##h##m##s". Days (d), hours (h), minutes (m) and seconds (s) must be specified in order, but any can be left out. The 24h Activity slot is aligned at a random point between midnight and 2am local time (determined each time the device boots) to avoid excessive server access at midnight. It is recommended you use this if a precise interval is not required. Smart intervals must be specified as an even multiple of days, 1, 3, 6, or 12 hour intervals and 5, 10, or 15 minute intervals. All tasks on the interval are aligned at approximately the same time.

Starting can be delayed if additional Requirements are specified, or if a Trigger has yet to fire.

​Most scheduled Activities should be background Activities.

All fields are optional through you must specify either "start" or "interval". UTC time strings not ending in Z are interpreted as local time.
{
    "precise" : boolean,
    "start" : string,
    "interval" : string,
    "skip" : boolean,
    "local" : boolean,
    "end" : string,
    "relative" : boolean,
    "lastFinished" : string
}

Name

Required

Type

Description

precise

Required Boolean Indicates the interval occurs at the precisely specified start time, and every given interval thereafter. 
start Required String Launch time. Time format is a subset of ISO 8601 "YYYY-MM-DD HH:MM:SS"(for local) or "YYYY-MM-DD HH:MM:SSZ" for UTC. This field is required for basic scheduled items, and optional for intervals.
interval Optional String Specifies the number of days, hours, minutes, and seconds-"##d##h##m##s"-between Activity execution. If set, then after an Activity is marked Complete, it is re-queued with a new start time. Days, hours, minutes and seconds must be specified in order, but any can be left out.
skip Optional Boolean If an interval Activity is not able to run, i.e., the device was off when scheduled to start, it runs(by default) at the first opportunity. However, if skip is true, it waits for the next scheduled interval time to occur before running.
local Optional Boolean Indicates that a date/time NOT ending in 'Z' is local. This will become unnecessary once times not ending in 'Z' are interpreted as local by default.
end Optional String End date/time for the interval.
relative Optional Boolean Indicates the interval occurs at the finished time of last activity. Finished time of last activity is set as base time for interval. Start time is needed for initialization. Therefore this property is available when precise property is true.
lastFinished Optional Boolean Last finished time. Time format is a subset of ISO 8601 "YYYY-MM-DD HH:MM:SS"(for local) or "YYYY-MM-DD HH:MM:SSZ" for UTC.

Trigger Object

Activities with Triggers do not become runnable until an event occurs on a subscribed method. In addition, other requirements or scheduling constraints may also need to be met before the Activity is runnable. When the Activity starts, the specified method is called with "subscribe=true", and any additional arguments the Activity creator provides. If another Activity has previously been created and started with an identical Trigger, with the same method and arguments, then the Activity Manager may utilize its existing subscription to monitor the Triggering event, unless "unique" is true in the Trigger specification.

If the Trigger specification includes a "key" property, the Activity Manager looks for responses to the Trigger method call that include the named "key" property. The Trigger fires when a response with that property is seen (including the initial response). The Trigger also fires if the Trigger method returns an error result-either the initial call result or any subsequent results. If a "key" property is not specified the Trigger fires on the first response after the initial successful response.

An example of a "key" property would be the "fired" property that db8 returns in a notification that watchedquery results have changed.

Triggers are not "persistent subscriptions". The Trigger is unsubscribed after the response which causes it to fire is seen.

The Trigger fires on any error return result. Once it fires, the Trigger is unsubscribed. If a new Trigger is desired, your app should create a new Activity.

Do NOT ignore the trigger information returned in a callback. If an error is returned to the method specified for a Trigger, then the Trigger fires immediately. This could happen if, for example, the parameters passed to the method were invalid or wrong. If the Trigger callback re-starts the Activity, i.e., in the case of a db8 watch, then the potential exists for an infinite loop. Check for errors.

Keep the mutual exclusion among the "key", "compare", and "where" properties. They are incompatible with each other.
{
    "method" : string,
    "key" : string,
    "params" : object,
    "where" : string or array of strings,
    "compare" : {
        "key": string,
        "value": number or string
    }
}

Name

Required

Type

Description

method  Required String Name of callback method.
params Optional Object Parameters for subscription or watch.
where Optional Object Single db8 where clause or array of db8 where clauses.
compare Optional Object Object that holds key and value properties. Trigger will query with the key and compare old value with specified value.
key Optional String Key property name. Activity Manager looks for this field in callback response, i.e., "fired" from db8 watch where query results have changed.

Type Object

Indicates how the Activity is handled. Principally, it is used to denote the Activity as either foreground or background, and whether it can be paused or cancelled.

Forground or Background

​Default attributes are associated with background and foreground Activities:

  • Foreground Activities are high priority and immediate- They cannot be queued and begin running when their prerequisites are met.
  • Background Activities are low priority and not immediate- They are runnable, but queued until necessary resources become available.


Whether an activity is foreground or background should only be set once. The default is foreground. If your app specifies foreground or background, do NOT set the advanced attributes like "immediate" and "priority". If you set them, the Activity Manager will NOT create the Activity. If you do not set either foreground or background, then you MUST set "immediate" and "priority".

Priority

Use "high" or "highest" priority if your Activity's performance is critical, for example: 3D games, where failing to keep up with the desired frame rate is dramatically noticeable. Normal interactive UI Activities should use "normal". If immediate display is not critical to your app, say, for example, an email sync, "low" priority is appropriate since the user does not necessarily expect email to show up immediately when they hit the 'sync' button, so a little extra time is not a problem. In addition, the delay only happens if the device has other things to do; if your Activity is the only thing running, it gets all the CPU it needs.

Probe Activity

As indicated with the "probe" flag, a probe Activity is one that does not impact resources, allowing many to run in parallel, rather than serially. You can use this in cases where more complex logic is required to determine if an Activity can proceed. Schedule the probe Activity with the Activity Manager and conclude the probe. For example, an email syncing app or service may first want to see if there is email to sync. Let's say there are 10 email accounts. The setup, login negotiation, and waiting for the server to respond might take 15-30 seconds. If done in sequence, it would take 5 minutes to discover if there was email to sync on all the accounts. Most of this involves waiting, so there is minimal CPU involved. It is also likely to be implemented in the same few services, so, in terms of memory use, doing five is probably as expensive as doing one. In this case, it is better to run them in parallel, find out which accounts had mail to sync, and then create new background Activities specifically to sync each account with mail.

Persistent Activity

If "persist" is true, the Activity continues across device reboots. These Activities are atomically updated and re-scheduled across version updates and device or services crashes. However, note that the Activity Manager does not have any visibility into what your activity is actually doing, so if your app is in the middle of doing something in response to a fired activity, the Activity Manager has no awareness of that. In other words, the state of an activity, such as "paused", is not saved; instead, what happens is that activity specifications are reloaded as if you had just called "create" for it.

Explicit Activity

If "explicit" is true, the Activity can only be terminated with a stop, cancel, or complete call. If the parent of an explicit Activity unsubscribes, and no other adopter is available, then, instead of being cancelled (the default) the Activity is moved back to the ready state and its callback is invoked.

Schema

All fields are optional, but if you do not set "foreground" or "background", then you must set "immediate" and "priority".
{
    "foreground" : boolean | "background": boolean,
    "immediate" : boolean,
    "priority" : string,
    "userInitiated" : boolean,
    "persist" : boolean,
    "explicit" : boolean,
    "continutous" : boolean,
    "power" : boolean,
    "powerDebounce" : boolean
}

Name

Required

Type

Description

foreground

Optional Boolean Activity runs in the foreground and starts running when its prerequisites are met. Set either this or background, or immediate and priority.
background Optional Boolean Activity runs in the background. When its prerequisites are met it's placed into a ready queue and runs as system resources allow. Set either this or foreground, or immediate and priority.
immediate Optional Boolean Activity should run immediately. Set either this and priority, or background or foreground.
priority Optional String Indicates Activity's priority. Must be one of the following: "highest", "high", "normal", "low", or "lowest". Set either this and immediate, or background or foreground.
userInitiated Optional Boolean Not currently used.
persist Optional Boolean Stores Activity state in db so it can span reboots, loss of service, or updates.
explicit Optional Boolean Activity is restarted unless terminated with complete, stop, or cancel.
continuous Optional Boolean Activity does not have a well defined ending point and could run indefinitely.
power Optional Boolean Activity requires device remain powered while it is running.
powerDebounce Optional Boolean Events associated with this Activity are due to complete shortly. Set this flag to keep the device from having to suspend/restart in the meantime.

Schedule Object

The Schedule object defines an Activity's time-based requirements. The time an Activity is scheduled to run can be either absolute or local. If a local time is specified, the Activity Manager watches for time zone changes and automatically adjusts the UTC time.

Smart Intervals, specified with the interval field, allow tasks to be scheduled in evenly aligned batches, optimizing battery power and efficiency. Smart intervals are specified with the interval string field as "##d##h##m##s". Days (d), hours (h), minutes (m) and seconds (s) must be specified in order, but any can be left out. The 24h Activity slot is aligned at a random point between midnight and 2am local time (determined each time the device boots) to avoid excessive server access at midnight. It is recommended you use this if a precise interval is not required. Smart intervals must be specified as an even multiple of days, 1, 3, 6, or 12 hour intervals and 5, 10, or 15 minute intervals. All tasks on the interval are aligned at approximately the same time.

Starting can be delayed if additional Requirements are specified, or if a Trigger has yet to fire.

​Most scheduled Activities should be background Activities.

All fields are optional though you must specify either "start" or "interval".
UTC time strings not ending in Z are interpreted as local time.
{
    "precise" : boolean,
    "start" : string,
    "interval" : string,
    "skip" : boolean,
    "local" : boolean,
    "end" : string,
    "relative" : boolean,
    "lastFinished" : string
}

Name

Required

Type

Description

precise

Required Boolean Indicates the interval occurs at the precisely specified start time, and every given interval thereafter. 
start Required String Launch time. Time format is a subset of ISO 8601 "YYYY-MM-DD HH:MM:SS"(for local) or "YYYY-MM-DD HH:MM:SSZ" for UTC. This field is required for basic scheduled items, and optional for intervals.
interval Optional String Specifies the number of days, hours, minutes, and seconds-"##d##h##m##s"-between Activity execution. If set, then after an Activity is marked Complete, it is re-queued with a new start time. Days, hours, minutes and seconds must be specified in order, but any can be left out.
skip Optional Boolean If an interval Activity is not able to run, i.e., the device was off when scheduled to start, it runs(by default) at the first opportunity. However, if skip is true, it waits for the next scheduled interval time to occur before running.
local Optional Boolean Indicates that a date/time NOT ending in 'Z' is local. This will become unnecessary once times not ending in 'Z' are interpreted as local by default.
end Optional String End date/time for the interval.
relative Optional Boolean Indicates the interval occurs at the finished time of last activity. Finished time of last activity is set as base time for interval. Start time is needed for initialization. Therefore this property is available when precise property is true.
lastFinished Optional Boolean Last finished time. Time format is a subset of ISO 8601 "YYYY-MM-DD HH:MM:SS"(for local) or "YYYY-MM-DD HH:MM:SSZ" for UTC.

Parent Object

The Parent (or potential parent) of an Activity specified as an app ID or service ID. The Activity Manager automatically obtains this value when the app or service invokes the create() or adopt().

{
    "appId" : string | "serviceId" : string
}

Name

Required

Type

Description

appId  Optional String Application ID. Either this or serviceId must be specified.
serviceId Optional String Service ID. Either this or appId must be specified.

 



Navigation