com.webos.service.activitymanager

API Summary

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

Overview of the API

(click to expand)

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 H/W and S/W through Activity and notify when the specified events occur. If there is a dynamic service that needs to wake up when certain conditions are met, Activity Manager is the best choice.

Activity_State_Transition_Diagram.png

An Activity can have the state shown in the diagram above. What the Activity does for each state is as follows.

  • creating : The create method is called and the Activity is creating.
  • created : The Activity was created successfully. When calling create method with { 'start' true }, the Activity will move to unsatisfied state automatically.
  • starting : The start method is called and the Activity is starting. In this step, the Activity will subscribe Requirements, Triggers and Schedule.
  • unsatisfied : The Activity waits for all conditions are satisfied - Requirements, Triggers and Schedule. The Activity in unsatisfied can be paused by pause method.
  • pausing : The pause method is called and the Activity is pausing.
  • paused : The Activity is paused. In this state, the Activity does not move to the satisfied state, although all conditions are satisfied. The Activity can move to unsatisfied state by start method.
  • satisfying : All conditions of the Activity are satisfying. An activity in unsatisfied state automatically moves to this state without an API call.
  • satisfied : All conditions of the Activity are satisfied. And there is nothing to do special.
  • expiring : The Activity is expiring. The Activity will call Callback method and unsubscribe Triggers and cancel Schedule.
  • expired : The Activity is over. All callbacks are handled successfully. If the Activity is not set continuous property, the activity is in expired state forever. If its parent wants to start it again, the parent should call complete with { 'restart ': true }. If parent doesn't want to restart it, then need to call cancel.
  • restarting : The Activity is restarting. There are two ways to restart Activity. One is to call complete method with { 'restart' : true }. And the other is to give the continuous property to true when creating the Activity. If the Activity was created with continuous property, the Activity will move to unsatisfied state as soon as receive the Callback response.
  • failing : An error occurs during Activity job and the Activity is failing. Any Activity in any state can move to this state, if an error occurs. Make sure that Triggers or Callbacks do not fail for any reason. Their failure will move the Activity immediately to this state.
  • failed : The Activity is failed, and the Activity Manager cannot do anything anymore. The parent should call cancel method to destroy the Activity.
  • destroying : The cancel method is called and the Activity is destroying. The cancel method can be called in any Activity state,
  • destroyed : The Activity is destroyed. In this state, the Activity will be excluded from being managed by the Activity Manager.

 


Open All


create

Description

NOTE: The 'creator' in Activity object can be set only by configurator.

Create a new Activity and return its ID. Each of created Activities must have a unique name.

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

If the Activity specify start as true, because the Activity moves to unsatisfied state, you do not need to call start method.

If this method is failed with 'activitymanager doesn't have rights to call callback/trigger'.

Parameters

Name

Required

Type

Description

activity Required Object: Activity

Activity object.

subscribe Optional Boolean

Flag that enables whether to subscribe or not.

  • To enable subscribe, set subscribe to true. The caller becomes a parent of the Activity.
  • To disable subscribe, set subscribe to false. When the caller does not subscribe to the Activity, callback must be specified and start must set to true.
  • The default value of subscribe is false
detailedEvents Optional Boolean

Flag that enables to return detailed Activity information in a subscription response. It needs to be used when subscribe is set to true.

  • To enable detailedEvents, set detailedEvents to true.
  • To disable detailedEvents, set detailedEvents to false.
  • The default value of detailedEvents is false.
start Optional Boolean

Start Activity immediately flag.

  • To indicate the Activity is fully-initialized and ready to launch, set start to true. When subscribe is set to false, must set start to true
  • To disable start, set start to false. If start is set to false, you need to call the start method to make the Activity runnable.   
  • The default value of start is false.

NOTE: It is recommended to use start as true regardless of the default value of this. Then you do not need to call start method.

replace Optional Boolean
  • To create a new Activity with the same name with the existing Activity, set replace to true. This cancels the existing Activity and replaces it to new one.
  • Otherwise, set replace to false.
  • The default value of replace is false.

NOTE: If replace is true, the Activity created by configurator can overwrite the existing Activity.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed.
activityId Optional Number (uint64_t)

Activity ID.

subscribed Optional Boolean

If it is subscribed, subscribed will contain true.
If it is not subscribed, subscribed will contain false.

errorCode Optional Number (int64_t)

The error code for the failed operation.

errorText Optional String

Indicates the reason for the failure of the operation. 

Subscription Returns

Name

Required

Type

Description

activityId Required Number (uint64_t)

Created Activity ID. You could get a subscription when there's status updates.  

event Required String

NOTE: These events may be changed, as the activity state has been redefined.

Indicate what the created Activity just has been done. The Activity Manager will generate the following events when the corresponding requirements are met:

  • "start"
  • "cancel"
  • "stop"
  • “pause”
  • "complete”
  • “orphan”
  • “adopted”
  • "update" (available only when detailedEvents input parameter is set to true)

The following JSON object is a subscription example that shows the created activity just started:

{
    "activityId": 10813,
    "event": "start",
    "returnValue": true
}

$activity Optional Object: Activity

Acitivity object.

subscribed Required Boolean

If it is subscribed, subscribed will contain true.
If it is not subscribed, subscribed will contain false.

returnValue Optional Boolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed.

Example

1. Example code to create basic activity:

# luna-send -f -i luna://com.webos.service.activitymanager/create '{
  "activity": {
    "name": "basicactivity",
    "description": "Test create",
    "type": { "foreground": true }
  },
  "start": true,
  "subscribe": true
}'

Example return:
{
  "activityId": 83,
  "returnValue": true,
  "subscribed": true
}

Example subscription return:
{
  "event": "start",
  "activityId": 83,
  "returnValue": true,
  "subscribed": true
}

----------------------------------------------------------------------

2. Example code to create scheduled activity:

# luna-send -f -i luna://com.webos.service.activitymanager/create '{
  "activity": {
    "name": "ScheduledActivity",
    "description": "Test create of scheduled activity",
    "type": { "foreground": true },
    "schedule": { "start": "2015-02-15 13:22:00" }
  },
  "start": true,
  "subscribe": true
}'

Example return:
{
  "activityId": 102,
  "returnValue": true,
  "subscribed": true
}

Example subscription return:
{
  "event": "start",
  "activityId": 102,
  "returnValue": true,
  "subscribed": true
}

----------------------------------------------------------------------

3. Example code to create scheduled activity with callback:

# luna-send -f -i luna://com.webos.service.activitymanager/create '{
  "activity": {
    "name": "ScheduledActivityWithCallback",
    "description": "Test create of scheduled activity with callback",
    "type": { "foreground": true },
    "callback": {
      "method": "luna://com.webos.service.applicationmanager/launch",
      "params": { "id": "com.webos.app.browser" }
    },
    "schedule": { "start": "2015-02-15 00:05:00" }
  },
  "start": true,
  "subscribe": true
}'

Example return:
{
  "activityId": 84,
  "returnValue": true,
  "subscribed": true
}

Example subscription return:
{
  "event": "start",
  "activityId": 84,
  "returnValue": true,
  "subscribed": true
}

----------------------------------------------------------------------

4. Example code to create activity with multiple trigger:

# luna-send -i -f luna://com.webos.service.activitymanager/create '{
  "activity": {
    "name": "browser restart", "description":"",
    "type": { "foreground":true, "continuous": true },
    "callback": {
      "method": "luna://com.webos.service.applicationmanager/launch",
      "params": { "id": "com.webos.app.browser" }
    },
    "trigger": {
      "and": [
        {
          "method": "luna://com.webos.service.applicationmanager/getAppLifeStatus",
          "params": { "subscribe": true },
          "where": {
            "and": [
              { "op": "=", "prop": "appId", "val": "com.webos.app.browser" },
              { "op": "=", "prop": "status", "val": "stop"}
            ]
          }
        },
        {
          "method": "luna://com.webos.service.connectionmanager/getstatus",
          "params": { "subscribe": true },
          "where": { "prop": "isInternetConnectionAvailable", "op": "=", "val": true }
        }
      ]
    }
  },
  "start": true,
  "subscribe": true
}'

Example return:
{
  "activityId": 85,
  "returnValue": true,
  "subscribed": true
}

Example subscription return:
{
  "event": "start",
  "activityId": 85,
  "returnValue": true,
  "subscribed": true
}

----------------------------------------------------------------------

5. Example code to create continuous activity

# luna-send -n 1 -f luna://com.webos.service.activitymanager/create '{
  "activity": {
    "name": "continuous-schedule", "description":"",
    "type": {"foreground": true, "continuous": true},
    "callback": {"method": "luna://com.webos.notification/createToast", "params": {"message": "5m", "persistent": true}},
    "schedule": {"interval": "5m"}
  },
  "replace":true,
  "start":true
}'

Example return:
{
  "activityId": 60,
  "returnValue": true,
  "subscribed": false
}

Example subscription return:
{
  "event": "start",
  "activityId": 60,
  "returnValue": true,
  "subscribed": true
}


start

Description

Attempt to start the specified Activity, either moving its state from 'created' to 'starting', or from 'paused' to 'resuming'.

Parameters

Name

Required

Type

Description

activityId Required Number (uint64_t)

Activity ID. 

Note: Either activityId or activityName is a REQUIRED field.

activityName Required String

Activity name.Only the creator of the Activity can specify activityName.

Note: Either activityId or activityName is a REQUIRED field.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. 
errorCode Optional Number (int64_t)

The error code for the failed operation.

errorText Optional String

Indicates the reason for the failure of the operation. 

Example

# luna-send -n 1 -f luna://com.webos.service.activitymanager/start '{"activityId" : 93}'

Example response for a successful call:
{
  "returnValue": true
}

Example response for a failed call:
{
  "errorCode": 2,
  "returnValue": false,
  "errorText": "activityId not found"
}


complete

Description

Terminate the specified Activity and optionally restart it with(or without) new callback, schedule or trigger. Only the Activity's parent can call this method. Other subscribers to the Activity receive a "complete" event.

If the Activity is persistent (i.e., persist in the Type object is set to true), the db8 is updated before the call returns.

If this method is failed with 'activitymanager doesn't have rights to call callback/trigger', see Activity Manager ACG.

Parameters

Name

Required

Type

Description

activityId Required Number (uint64_t)

Activity ID.

Note: Either activityId or activityName is a REQUIRED field.

activityName Required String

Activity name.Only the creator of the Activity can specify activityName.

Note: Either activityId or activityName is a REQUIRED field.

restart Optional Boolean
  • To restart the Activity with any new callback, schedule or trigger, set restart to true. The restarted Activity goes into the Activity Manager queue.
  • To disable restart, set restart to false.
  • The default value of restart is false.

NOTE: If restart is false, this is equivalent to cancel. Therefore, it is recommended to always set restart to true to avoid confusion.

callback Optional Object: Callback

Callback to use when the specified Activity is restarted.

  • To use the current callback condition, do not specify callback parameter.
  • To remove the current callback condition, set callback to false.
schedule Optional Object: Schedule

Schedule to use when Activity is restarted.

  • To use the current callback condition, do not specify schedule parameter.
  • To remove the current callback condition, set schedule to false.
trigger Optional Object: Trigger

Trigger to use when the specified Activity is restarted.

  • To use the current callback condition, do not specify trigger parameter.
  • To remove the current callback condition, set trigger to false.
metadata Optional Object

Opaque object the Activity Manager stores and returns in the callback parameters.

  • To use the current metadata, do not specify metadata parameter.
  • To remove the current metadata, set metadata to false.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed.
errorCode Optional Number (int64_t)

The error code for the failed operation.

errorText Optional String

Indicates the reason for the failure of the operation. 

Example

# luna-send -n 1 -f -a myapp luna://com.webos.service.activitymanager/create '{
    "activity": {"name": "browser closed", "description": "", "type": {"foreground": true},
      "callback": {"method": "luna://com.webos.notification/createToast", "params": {"message": "browser closed", "persistent": true}},
      "trigger": {"method": "luna://com.webos.service.applicationmanager/getAppLifeStatus", "params": {"subscribe": true},
                  "where": {"prop": "status", "op": "=", "val": "stop"}}},
    "replace": true, "start": true}'
{
    "subscribed": false,
    "activityId": 62,
    "returnValue": true
}

# luna-send -n 1 -f luna://com.webos.service.applicationmanager/launch '{"id":"com.webos.app.browser"}'
{
    "returnValue": true
}

# luna-send -n 1 -f luna://com.webos.service.applicationmanager/closeByAppId '{"id":"com.webos.app.browser"}'
{
    "appId": "com.webos.app.browser",
    "returnValue": true
}

# luna-send -n 1 -f -a myapp luna://com.webos.service.activitymanager/complete '{"activityName": "browser closed", "restart": true}'

Example response for a successful call:
{
    "returnValue": true
}

Example response for a failed call:
{
    "errorCode": 2,
    "returnValue": false,
    "errorText": "Activity name/creator pair not found"
}


cancel

Description

Terminate the specified Activity and send a "cancel" event to all subscribers to this Activity. This method succeeds if the Activity exists.

Parameters

Name

Required

Type

Description

activityId Required Number (uint64_t)

Activity ID.

Note: Either activityId or activityName is a REQUIRED field.

activityName Required String

Activity name.Only the creator of the Activity can specify activityName.

Note: Either activityId or activityName is a REQUIRED field.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean

If the cancel method succeeds, returnValue will contain true.

If the cancel method fails, returnValue will contain false.

errorCode Optional Number (int64_t)

The error code for the failed operation.

errorText Optional String

Indicates the reason for the failure of the operation.

Example

# luna-send -n 1 -f luna://com.webos.service.activitymanager/cancel '{"activityId" : 93}'

Example response for a successful call:
{
  "returnValue": true
}

Example response for a failed call:
{
  "errorCode": 2,
  "returnValue": false,
  "errorText": "activityId not found"
}


stop

Description

Stop the specified Activity and send a "stop" event to subscribers to this Activity. This method succeeds if the Activity exists.

This method is exactly the same as cancel method. It is recommended to use cancel to avoid confusion.

Parameters

Name

Required

Type

Description

activityId Required Number (uint64_t)

Activity ID.

Note: Either activityId or activityName is a REQUIRED field.

activityName Required String

Activity name.Only the creator of the Activity can specify activityName.

Note: Either activityId or activityName is a REQUIRED field.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed.
errorCode Optional Number (int64_t)

The error code for the failed operation.

errorText Optional String

Indicates the reason for the failure of the operation.

Example

# luna-send -n 1 -f luna://com.webos.service.activitymanager/stop '{"activityId" : 95}'

Example response for a successful call:
{
  "returnValue": true
}

Example response for a failed call:
{
  "errorCode": 2,
  "returnValue": false,
  "errorText": "activityId not found"
}


adopt

Description

The Activity Manager considers the creator of the Activity as a parent.

Therefore, the creator of the activity does not need to adopt the Activity to be a parent.

An app or a service registers its willingness to become an Activity's parent, which means becoming an adopter.

  • If there are adopters, all subscribers to this Activity receives an "orphan" event and the Activity is adopted to the new parent, one of the adopters. 
  • If there are no waiting adopters, all subscribers to this Activity receives a "cancel" event and the Activity disappears immediately.

Parameters

Name

Required

Type

Description

activityId Required Number (uint64_t)

Activity ID.

Note: Either activityId or activityName is a REQUIRED field.

activityName Required String

Activity name. Only the creator of the Activity can specify activityName.

Note: Either activityId or activityName is a REQUIRED field.

wait Required Boolean

Flag that enables whether to wait until the Activity is available to be adopted or not.

  • If an app or a service wants to wait until the Activity is available to be adopted, set wait to true. If the Activity is not immediately adopted, returnValue will contain true and adopted will contain false. Once the Activity is disconnected with its parent, the caller is informed of an "orphan" event and becomes the new parent of the Activity.
  • Otherwise, set wait to false. Generally returnValue will contain false with an errorCode. If the Activity does not have a parent returnValue will contain true.
  • The default value of wait is false.
subscribe Required Boolean

Flag that enables whether to get informed when status of the created activity has been changed or not.

  • To enable subscribe, set subscribe to true.
  • To disable subscribe, set subscribe to false.
  • The default value of subscribe is false.
detailedEvents Optional Boolean

Flag that enables to return detailed Activity information in a subscription response. It needs to be used when subscribe is set to true.

  • To enable detailedEvents, set detailedEvents to true.
  • To disable detailedEvents, set detailedEvents to false.
  • The default value of detailedEvents is false.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed.
subscribed Required Boolean

If it is subscribed, subscribed will contain true.
If it is not subscribed, subscribed will contain false.

errorCode Optional Number (int64_t)

The error code for the failed operation.

errorText Optional String

Indicates the reason for the failure of the operation.

adopted Optional Boolean

adopted indicates a successful or failed adoption.

If the app or service adopts the Activity, adopted will contain true.
If the app or service does not adopt the Activity, adopted will contain false.

Subscription Returns

Name

Required

Type

Description

activityId Required Number (uint64_t)

Created Activity ID.

event Required String

NOTE: These events may be changed, as the activity state has been redefined.

Indicate what the created Activity just has been done. The Activity Manager will generate the following events when the corresponding requirements are met:

  • "start"
  • "cancel"
  • "stop"
  • “pause”
  • "complete”
  • “orphan”
  • “adopted”
  • "update" (available only when detailedEvents is set to true)

The following JSON object is a subscription example that shows the created activity just started:

{
    "activityId": 10813,
    "event": "start",
    "returnValue": true
}

$activity Optional Object: Activity

Acitivity object.

subscribed Required Boolean

If it is subscribed, subscribed will contain true.
If it is not subscribed, subscribed will contain false.

returnValue Optional Boolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed.

Example

# luna-send -i -f luna://com.webos.service.activitymanager/adopt '{
  "activityId": 90,
  "wait": true,
  "subscribe": true,
  "detailedEvents": false
}'

Example response for a successful call:

Subscription return: If parent of the activity did not release the activity
{
  "adopted": false,
  "returnValue": true,
  "subscribed": 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,
  "subscribed": true
}

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

Example response for a failed call:
{
  "errorCode": 2,
  "returnValue": false,
  "errorText": "activityId not found"
}


release

Description

Allow 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. For a completely safe transfer, a subscribing app or service, prior to the release, should already have called the adopt method.

Parameters

Name

Required

Type

Description

activityId Required Number (uint64_t)

Activity ID.

Note: Either activityId or activityName is a REQUIRED field.

activityName Required String

Activity name.Only the creator of the Activity can specify activityName.

Note: Either activityId or activityName is a REQUIRED field.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed.
errorCode Optional Number (int64_t)

The error code for the failed operation.

errorText Optional String

Indicates the reason for the failure of the operation.

Example

# luna-send -n 1 -a test -f luna://com.webos.service.activitymanager/release '{"activityId" : 98}'

Example response for a successful call:
{
  "returnValue": true
}

Example response for a failed call:
{
  "errorCode": 2,
  "returnValue": false,
  "errorText": "activityId not found"
}


pause

Description

Suspend the work on the specified Activity and place the Activity in pause state.

Parameters

Name

Required

Type

Description

activityId Optional Number (uint64_t)

Activity ID.

Note: Either activityId or activityName is a REQUIRED field.

activityName Optional String

Activity name. Only the creator of the Activity can specify activityName.

Note: Either activityId or activityName is a REQUIRED field.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean

If the pause method succeeds, returnValue will contain true. The method succeeds only if the Activity is in unsatisfied state.

If the pause method fails, returnValue will contain false. The method fails the Activity has ended (and is waiting for its subscribers to unsubscribe before cleaning up) or has been cancelled.

errorCode Optional Number (int64_t)

The error code for the failed operation.

errorText Optional String

Indicates the reason for the failure of the operation.

Example

Sample code with activityName:

# luna-send -n 1 -f luna://com.webos.service.activitymanager/create '{
  "activity":{
     "description":"",
     "name":"basic",
     "schedule":{"start":"2030-12-31 09:00:00"},
     "callback":{"method":"luna://com.webos.service.config/setConfigs",
     "params":{"configs":{"com.webos.service.activitymanager.basic":true}}}},
     "start":true}'

{
    "subscribed": false,
    "activityId": 58,
    "returnValue": true
}
 

Sample code with activityId:

# luna-send -n 1 -f luna://com.webos.service.activitymanager/pause '{"activityId":58}'

Example response for a successful call:
{
  "returnValue": true
}

Example response for a failed call:
{
  "errorCode": 2,
  "returnValue": false,
  "errorText": "activityId not found"
}


getActivityInfo

Description

Gets information of Activities.

If activityId or activityName is given, getActivityInfo only returns information about that activity.

Conversely, if activityId or activityName is not given, getActivityInfo returns all undestroyed activities.

Parameters

Name

Required

Type

Description

activityId Optional Number (uint64_t)

Activity ID

activityName Optional String

Activity name. Only the creator of the Activity can specify activityName.

subscribers Optional Boolean
  • To return the current parent, queued adopters, and subscribers for each Activity, set subscribers to true.
  • To not return the current parent, queued adopters, and subscribers for each Activity, set subscribers to false.
details Optional Boolean
  • To return detailed information for each Activity, set details to true.
  • To return brief information for each Activity, set details to false.
current Optional Boolean
  • To return the state of the Activity prerequisites (e.g., whether the Activity is scheduled or not, whether the trigger is invoked or not), set current to true.
  • Otherwise, set current to false.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed.
errorCode Optional Number (int64_t)

The error code for the failed operation.

errorText Optional String

Indicates the reason for the failure of the operation.

activity Optional Object: Activity

The Activity object.

If activityId or activityName is given, getActivityInfo will contain the property.

activities Optional Object array: Activity

Array with Activity objects.

If activityId or activityName is not given, getActivityInfo will contain this property.

Example

1. luna-send -n 1 -f luna://com.webos.service.activitymanager/getActivityInfo
'{
    "activityId":36
}'

 

1-1. Example response for a successful call:

{

    "activity": {

        "type": {

            "foreground": true

        },

        "name": "myactivity",

        "adopters": [],

        "callback": {

            "method": "luna://com.webos.service.test/callback"

        },

        "subscribers": [],

        "creator": {

            "serviceId": "com.webos.service.test"

        },

        "state": "expired",

        "schedule": {

            "interval": "1d",

            "local": true,

            "lastFinished": "2015-03-20 00:37:38"

        },

        "description": "my test activity",

        "activityId": 36

    },

    "returnValue": true

}

 

1-2. Example response for a failed call:

{

    "errorCode": 2,

    "returnValue": false,

    "errorText": "activityId not found"

}

 

2. luna-send -i -f -a "creator" luna://com.webos.service.activitymanager/create

'{

    "start": true,

    "activity": {

        "type": {

            "foreground": true

        },

        "name": "sdet",

        "description": "Test create"

    },

    "subscribe": true,

    "replace": true

}'

 

2-1. Example response for a successful call:

luna-send -n 1 -f -a "creator" luna://com.webos.service.activitymanager/getActivityInfo

'{

    "current": true,

    "activityName": "sdet"

}'

{

    "activity": {

        "type": {

            "foreground": true

        },

        "parent": {

            "appId": "creator"

        },

        "name": "sdet",

        "adopters": [

        ],

        "subscribers": [

            {

                "appId": "creator"

            }

        ],

        "state": "expired",

        "creator": {

            "appId": "creator"

        },

        "description": "Test create",

        "activityId": 82

    },

    "returnValue": true

}

 

2-2. Example response for a failed call:

luna-send -n 1 -f luna://com.webos.service.activitymanager/getActivityInfo

'{

    "current": true,

    "activityName": "sdet"

}'

{

    "errorCode": 2,

    "errorText": "Activity name/creator pair not found",

    "returnValue": false

}

 

3. luna-send -n 1 -f luna://com.webos.service.activitymanager/getActivityInfo

'{

}'

 

3-1. Example response for a successful call:

{

    "activities": [

        {

            "state": "expired",

            "description": "my test activity",

            "activityId": 2,

            "creator": { "serviceId": "com.webos.service.test" },

            "name": "test"

        }

    ],

    "returnValue": true

}

 

3-2. Example response for a failed call:

N/A


getManagerInfo

Description

Gets Activity Manager related information such as:

  • List of activities
  • Supported requirements

Parameters

None

Call Returns

Name

Required

Type

Description

returnValue Required Boolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details
queues Optional Object: InfoQueue

Queued Activity information.

requirements Optional Object array: InfoRequirement

Supported requirement

errorCode Optional Number (int64_t)

The error code for the failed operation.

errorText Optional String

Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Example

# luna-send -n 1 -f luna://com.webos.service.activitymanager/getManagerInfo '{}'

Example response:
{
  "queues": [
    {
      "activities": [
        { "activityId": 20, "name": "mojotempdbspace", "creator": { "serviceId": "com.webos.service.db" } },
        ...
      ]
    },
    ...
  ],
  "requirements": [
    { "name": "bootup", "type-schema": {"type": "boolean"} },
    { "name": "internet", "type-schema": {"type": "boolean"} },
    { "name": "wifi", "type-schema": {"type": "boolean"} }
  ]
}


Objects

Activity

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

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: Type

Indicates how the Activity is handled. Principally, it is used to denote the Activity as either foreground or background, and whether it is continuous or not.

schedule Optional Object:Schedule

Time-based requirements for Activity.

trigger Optional Object:Trigger Event that must occur for Activity to run.
requirements Optional Object: Requirement

Conditions that must satisfy for Activity to run.

callback Optional Object:Callback

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 (uint64_t)

Activity ID

creator Optional Object: Parent

NOTE: The 'creator' in Activity object can be set only by configurator.

parent Optional Object: Parent

Activity parent

adopters Optional Object array: Parent

Activity adopters (parent object array)

state Optional String

NOTE: These states are deprecated. These will be replaced with new states in the next version.

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.

Callback

The Callback object specifies a method to be called, and optionally arguments that should be passed to that method when the activity moves from 'satisfied' state to 'expiring'.

If the callback method fails::

  • For normal (non-continuous) activity: activity is moved to 'failed' state.
  • For continuous activity: activity moved to 'unsatisfied' state.

To change the behavior when callback fails, use the 'ignoreReturn' property.

Name

Required

Type

Description

method Required String Callback URI.
params Optional any

Parameters to be passed to the callback method.

ignoreReturn Optional Boolean

Keeps the activity alive when the activity callback fails. Possible values are:

  • true : Activity manager does not cancel the activity but moves it to the next step.
    • For normal (non-continuous) activity: waits for client to complete (or cancel)
    • For continuous activity: restarts activity
  • false :Activity manager moves the activity to failed state and ultimately cancels it.

Default values:

  • false : For non-continuous (normal) activity. (because backward compatibility should be maintained)
  • true : For continuous activity.

InfoActivity

Activity information

Name

Required

Type

Description

activityId Required Number (uint64_t)

Activity ID

creator Required Object: InfoCreator

Indicates creator

name Required String

Activity name

InfoCreator

Creator information

Name

Required

Type

Description

serviceId Required String

Service ID

InfoQueue

List of Activities for which power is currently locked.

Name

Required

Type

Description

activities Required Object array:InfoActivity

Activities array

name Required String

Queued status

InfoRequirement

Supported requirement information

Name

Required

Type

Description

name Optional String

requirement name

type-schema Optional Object

requirement type

Parent

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()

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.

Requirement

The Requirements are preconditions that the Activity Manager will ensure are met before an Activity will be run. Any number of requirements may be specified for a single Activity, and all must be met in order for the Activity to move to the satisfied state. Requirements can transition from the met state back to unmet if the condition the particular requirement is monitoring for no longer holds true.

The Requirements available on the system can be queried using getManagerInfo method.

Example :
luna-send -n 1 -f luna://com.webos.service.activitymanager/create '{
    "activity": {
        "requirements": {"bootup": true, "internet": true},
        "name": "browser-restart", "description": "", "type": {"foreground": true},
        "callback": {"method": "luna://com.webos.service.applicationmanager/launch", "params": {"id": "com.webos.app.browser"}},
        "trigger": {"method":"luna://com.webos.service.applicationmanager/getAppLifeStatus", "params": {"subscribe": true},
                      "where": {"and":[{"op": "=", "prop": "appId", "val": "com.webos.app.browser"}, {"op": "=", "prop": "status", "val":"stop"}]}}
    },
    "replace": true,
    "start": true
}'

 

Name

Required

Type

Description

bootup Optional Boolean

bootup

internet Optional Boolean

internet

wifi Optional Boolean

wifi

Schedule

The Schedule object will define the time-based requirements for an Activity. If Schedule is specified, the schedule must be met before the Activity move to satisfied state.

Note: Some properties of Schedule may be changed.

 

1. Basic schedule

"schedule": {
    // Start time. Time format is a subset of ISO 8601.
    // That is, "YYYY-MM-DD HH:MM:SS" for local, or "YYYY-MM-DD HH:MM:SSZ" for UTC.
    "start": "2017-03-01 21:00:00",
}

 

2. Smart interval

Smart intervals align all Activities operating with that period to the same start times, allowing them to batch up and avoid unnecessary device wakeups, potentially saving significant amounts of power.

"schedule": {
    // Time between events, in seconds.
    // For a smart interval, the interval must be an even multiple of days,
    // or one of the following: 12h, 6h, 3h, 1h, 30m, 15m, 10m, or 5m.
    "interval": "5m"
}

 

3. Precise interval

"schedule": {
    // Specifies that the Interval should occur at the precisely specified start time, and every given interval thereafter.
    "precise": true,

    // Start time. Time format is a subset of ISO 8601.
    // That is "YYYY-MM-DD HH:MM:SS" for local, and "YYYY-MM-DD HH:MM:SSZ" for UTC.
    "start": "2017-03-01 21:00:00",

    // End time for the interval (NOTE. This does not work currently.)
    [ "end": "2017-03-01 22:00:00", ]

    // Time between events, in seconds.
    // Specifies the number of days, hours, minutes, and seconds between executions of the Activity.
    // They must be specified in order, but any can be left out.  Any interval is valid.
    "interval": "1m",
}

 

Name

Required

Type

Description

start Optional String

start is required for basic schedue or precise interval.

end Optional String

end time

precise Optional Boolean

precise is required for precise interval

interval Optional String

interval is required for smart or precise interval

skip Optional Boolean

skip

local Optional Boolean

local

relative Optional Boolean

relative

lastFinished Optional String

lastFinished

Trigger

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.

Note: Key Trigger and Compare Trigger are deprecated.

 

1. Key Trigger is triggered when the specified key exists.

"trigger": {
    "method": "luna://com.webos.service.applicationmanager/getForegroundAppInfo",
    "params": { "subscribe": true, "extraInfo": true },
    "key": "foregroundAppInfo"
}

 

2. Compare Trigger is triggered when the specified key & value pair in compare are matched.

"trigger": {
    "method": "luna://com.webos.service.applicationmanager/getForegroundAppInfo",
    "params": { "subscribe": true },
    "compare": { "appId": "com.webos.app.browser" }
}

 

3. Where Trigger is triggered when the conditions of where clauses are satisfied.

3-1. Single Trigger

"trigger": {
    "method": "luna://com.webos.service.connectionmanager/getstatus",
    "params": { "subscribe": true },
    "where": { "prop": "isInternetConnectionAvailable", "op": "=", "val": true }
}

3-2. Multiple Trigger can be combined by 'and' or 'or'

"trigger": {
    "and": [
        {
            ....
        },
        {
            "method": "luna://com.webos.service.application,anager/getAppLifeStatus",
            "params": { "subscribe": true },
            "where": { "and": [
                { "op": "=", "prop": "appId", "val": "com.webos.app.browser" },
                { "op": "=", "prop": "status", "val": "close" }
            ]}
        },
        {
            ....
        },
    ]
}

 

The Activity Manager will unsubscribe all subscriptions of Triggers, if the Activity arrives 'satisfied' state, and re-subscribe Triggers when 'restarting'.

WARNING

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.

NOTE. As the 'failed' state is added, if an error is returned from the Trigger method, the Activity will move to 'failed' state without calling Callback in the next version.

Keep the mutual exclusion among the "key", "compare", and "where" properties. They are incompatible with each other.

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.

and Optional Object array: Trigger

The and field is used when combining multiple triggers to be combined with an 'and' condition.

or Optional Object array: Trigger

The or field is used when combining multiple triggers to be combined with an 'or' condition.


ERROR REFERENCES

Error Code

Error Text

Error Description

2 No such file or directory

No such file or directory

11 Operation blocked

Operation blocked

12 Out of memory

Out of memory

13 Permission denied

Permission denied

17 File already exists

File already exists

22 Invalid argument

Invalid argument

38 Function not implemented

Function not implemented

-1000 Internal error

Internal error


Except as noted, this content is licensed under Creative Commons Attribution 4.0 and sample code is licensed under Apache License 2.0.