Scheduling

SmartApps may schedule future executions using the Schedules API.

Two types of scheduled executions are supported:

Once schedules are created to be executed exactly once at the specified day and time.
Cron schedules are created according to a Cron expression. These expressions may define recurring schedules (e.g., execute every fifteen minutes).

Creating Scheduled Executions#

SmartApps do not require any OAuth2 scopes to create schedules.

note

When using a personal access token to read/write schedules, you must include the w:schedules scope.

An example response to the INITIALIZE phase of the CONFIGURE lifecycle:

{
  "name": "my app name",
  "description": "my app description",
  "id": "my-app",
  "permissions":[],
  "firstPageId": "1"
}

Once Schedules#

Once schedules are defined in the number of milliseconds from 1 January 1970 UTC (Unix Time).

The request body for Once schedules looks like this:

{
  "name": "<SCHEDULE-NAME>",
  "once": 1587409157
}

Here is an example request to create a Once schedule:

CuRL
Node

curl -X POST -H "Authorization: Bearer <TOKEN>" \
    ST_API_URL/installedapps/<INSTALLED_APP_ID>/schedules
    -d "{'name': 'schedule-name', 'once': 1587409157}"

Cron Schedules#

Cron schedules use the Quartz Scheduler format, with an important difference: The seconds field is not supported, and is omitted from the cron expression.

All Cron schedules will be assigned a random seconds field by the SmartThings Platform.

The request body for Cron schedules looks like this:

{
  "name": "<SCHEDULE-NAME>",
  "'cron'": {
    "expression": "0/5 * * * ? *",
    "timezone": "CST"
  }
}

An example request to create a Cron schedule:

CuRL
Node

curl -X POST -H "Authorization: Bearer <TOKEN>" \
    ST_API_URL/installedapps/<INSTALLED_APP_ID>/schedules
    -d "{'name': '<SCHEDULE-NAME>', 'cron': {'expression': '0/5 * * * ? *', 'timezone': 'GMT'}}"

Cron Expression Examples#

Expression	Description
`"0/5 * * * ? *"`	Fire every five minutes, every day.
`"30 10 * * ? *"`	Fire every day at 10:30 a.m.
`"0/10 9 * * ?"`	Fire every ten minutes starting at 9 a.m and ending at 9:50 a.m., every day.

Timezones#

When creating schedules, consider in what time zone the schedule should be executed in. Usually, this will be the time zone of the installed app. You can get the time zone for the Location that the installed app belongs to by using the Locations API.

Scheduled execution events#

When a scheduled execution is triggered by SmartThings, your app is called with an EVENT lifecycle phase payload. It will contain information about the schedule that triggered the execution:

{
  "lifecycle": "EVENT",
  "executionId": "b328f242-c602-4204-8d73-33c48ae180af",
  "locale": "en",
  "version": "1.0.0",
  "eventData": {
    "authToken": "string",
    "installedApp": {
      "installedAppId": "d692699d-e7a6-400d-a0b7-d5be96e7a564",
      "locationId": "e675a3d9-2499-406c-86dc-8a492a886494",
      "config": {
        "contactSensor": [
          {
            "valueType": "DEVICE",
            "deviceConfig": {
              "deviceId": "e457978e-5e37-43e6-979d-18112e12c961",
              "componentId": "main"
            }
          }
        ],
        "lightSwitch":[
          {
            "valueType": "DEVICE",
            "deviceConfig": {
              "deviceId": "74aac3bb-91f2-4a88-8c49-ae5e0a234d76",
              "componentId": "main"
            }
          }
        ],
        "minutes":[
          {
            "valueType": "STRING",
            "stringConfig": {
              "value": "5"
            }
          }
        ],
      },
      "permissions": [
        "r:devices:e457978e-5e37-43e6-979d-18112e12c961",
        "r:devices:74aac3bb-91f2-4a88-8c49-ae5e0a234d76",
        "x:devices:74aac3bb-91f2-4a88-8c49-ae5e0a234d76"
      ]
    },
    "events": [
      {
        "eventType": "TIMER_EVENT",
        "timerEvent": {
          "eventId": "string",
          "name": "lights_off_timeout",
          "type": "CRON",
          "time": "2017-09-13T04:18:12.469Z",
          "expression": "string"
        }
      }
    ]
  },
  "settings": {
    "property1": "string",
    "property2": "string"
  }
}

Getting Schedules#

SmartApps do not require any OAuth2 scopes to get schedules.

note

When using a personal access token to read/write schedules, you must include the w:schedules scope.

A sample response to the INITIALIZE phase of the CONFIGURE lifecycle:

{
  "name": "my app name",
  "description": "my app description",
  "id": "my-app",
  "permissions":[],
  "firstPageId": "1"
}

Get a Schedule#

A specific schedule for an installed app can be retrieved by issuing a GET request to /installedapps/{installedAppId}/schedules/{scheduleName}

CuRL
Node

curl -X GET https://api.smartthings.com/installedapps/<INSTALLED_APP_ID>/schedules/<SCHEDULE_NAME> \
     -H "Authorization: Bearer {TOKEN}"

A schedule will be returned:

{
  "scheduledExecutions": [
    1505752823000
  ],
  "name": "weather-check-schedule",
  "cron": {
    "expression": "0/10 * * * ? *",
    "timezone": "America/Chicago"
  },
  "installedAppId": "937e11d5-317d-445f-bec7-3055fdb827a3",
  "locationId": "8418eebd-8d5f-48dd-h028-03474bd1aecb"
}

Get All Schedules#

All schedules for an installed app can be retrieved by issuing a GET request to /installedapps/{installedAppId}/schedules:

CuRL
Node

curl -X GET https://api.smartthings.com/installedapps/<INSTALLED_APP_ID>/schedules \
     -H "Authorization: Bearer <TOKEN>"

A paged result of schedules will be returned:

{
  "items": [
    {
      "scheduledExecutions": [
        1505752823000
      ],
      "name": "weather-check-schedule",
      "cron": {
        "expression": "0/10 * * * ? *",
        "timezone": "America/Chicago"
      },
      "installedAppId": "937e11d5-317d-445f-bec7-3055fdb827a3",
      "locationId": "844rgebd-8d5f-48dd-a028-05474bd1aecb"
    }
  ],
  "_links": {
    "next": null,
    "previous": null
  }
}

Deleting schedules#

note

All schedules and subscriptions for an installed app are automatically deleted when a user uninstalls an app.

SmartApps do not require any OAuth2 scopes to delete schedules.

note

When using a personal access token to read/write schedules, you must include the w:schedules scope.

A sample response to the INITIALIZE phase of the CONFIGURE lifecycle:

{
  "name": "my app name",
  "description": "my app description",
  "id": "my-app",
  "permissions":[],
  "firstPageId": "1"
}

Delete a schedule#

Individual schedules can be deleted for an installed app by issuing a DELETE request to /installedapps/{installedAppId}/schedules/{scheduleName}:

CuRL
Node

curl -X DELETE https://api.smartthings.com/installedapps/<INSTALLED_APP_ID>/schedules/<SCHEDULE_NAME> \
     -H "Authorization: Bearer {TOKEN}"

Delete All Schedules#

All schedules for an installed app can be deleted by issuing a DELETE request to /installedapps/{installedAppId}/schedules:

CuRL
Node

curl -X DELETE https://api.smartthings.com/installedapps/<INSTALLED_APP_ID>/schedules \
     -H "Authorization: Bearer {TOKEN}"

Scheduling Limits#

Each installed app is limited to having ten pending scheduled executions at any time. Requests to create any additional pending scheduled executions will result in a 422 Unprocessable Entity response.