Ask Alexa - Schedules

Schedules is an extension to Ask Alexa, the popular SmartThings Add in. You must be running Ask Alexa to use Schedules. More information about Ask Alexa can be found here: Ask Alexa

As the name implies, the Schedules extension allows you to use Ask Alexa as a 'scheduling agent' for all sorts of things. This can be simple one-time reminders like doctor's appointments, setting up a schedule to remind the children to take out the trash, to annual events like birthdays and anniversaries. While the main purpose of Schedules is to remind you of events, the extension can also be used to perform regular activities within Ask Alexa that would normally require a voice command. For example, you can set up to run a macro on a regular basis, report on the house status (sending the output to a message queue), and event alert you (in real time) to adverse weather conditions.

While Ask Alexa is fundamentally a voice application, Schedules requires you to set up your schedules using the SmartApp. This is much easier than inputting all of the parameters of a required schedule using voice. However, once a schedule is created you can always query, delete or pause the schedule via Ask Alexa.

Summary

Category: Ask Alexa Extension - Requires Ask Alexa

Author:Michael Struck --MichaelStruck (talk) 00:01, 1 January 2016 (EST)

ST Community Handle: https://community.smartthings.com/users/michaels/activity

Latest Version

The latest version this extension (as of 5/6/18)

Ask Alexa Extensions	Area Used	Version	Location
Schedules	SmartThings IDE	1.0.4a	https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa-schedule.src/ask-alexa-schedule.groovy

Ask Alexa Extension Code Installation

To install the extension use the code located here:

   https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa-schedule.src/ask-alexa-schedule.groovy

The steps for installation of the extensions are almost exactly the same as Ask_Alexa#Ask_Alexa_Code_Installation:

• Copy the raw code from the GitHub link above
• Go to the SmartThings IDE page and log in
• Click the My SmartApps link
• Click the +New SmartApp link
• Click the From Code tab
• Paste the GitHub code in the open area
• Click Create from the bottom left corner
• Save the code using the button in the upper right-hand corner of the page
• There is no need to do any OAuth settings on extension code.

   Please Note:
   You DO NOT need to publish the extension code; however, there is no harm in doing so. 
   Simply be aware that if you publish it the extension will show up in the 
   SmartThings Marketplace. However, you should NOT install it from there...
   Ask Alexa will utilize this child code from the main (parent) application.

Schedules Parameters

With regard to "parameters" that were mentioned above, there are some naming conventions that you should become familiar with when using Schedules:

• Schedule Types-This is the type of schedule you set up ranging from easy, one-time events, up to Cron expressions.
• Schedule Actions-This is what happens when the schedule timer is triggered. This could be simply sending you a message to running a macro to clearing the message queue
• Reminders-These are 'schedules within schedules'. A reminder can be triggered before an action occurs, and there can even be an interval of reminders that happen (hourly, daily) before an action occurs.

Voice Commands

As mentioned at the top of this section, the setup of the schedules is done within the SmartApp as it is actually quicker to set them up manually than to go through all of the options via a voice command. However, once the schedule is set up you have various voice commands you can use within Ask Alexa to control and manage your schedules.

It is VERY important, however, that just like Macros and other extensions, you MUST add the names of the schedules to the Amazon Developer slots (see: Ask_Alexa#Setup_Variables) if you want to address them verbal. However, please note something important about that statement "if you want to address them verbal". There is NO requirement for the actual operation of the schedule or reminders to have the slots populated with the schedule names. It is ONLY if you want to query or control the schedules that this becomes important. This is different than every other aspect of Ask Alexa.

If you DO choose the address your schedules verbally (and you have the names properly entered into the Amazon Developer Slots), you have the following options:

• Turning a schedule on or off- This allows you to keep the schedule, but temporarily turn it off (and back on) if necessary. The commands for this are:

   <"Alexa, tell SmartThings to turn off {schedule name}"> 
   <"Alexa, tell SmartThings to turn on {schedule name}"> 

• Querying a schedule - This allows you to get a detailed description of the schedule.

   <"Alexa, ask SmartThings about {schedule name}">

• Deleting a schedule - Sometimes you may want to simply delete a schedule. This is non-recoverable; once you delete it you can not get it back. However, you have a certain amount of time (as outlined in Ask_Alexa_-_Schedules#Schedule_Global_Options ) to override the delete command up to 10 minutes after you tell it to delete.

   <"Alexa, tell SmartThings to delete {schedule name}">

Schedule Global Options

When schedules are created, you will see the global options appear on the main Schedules page. These options allow you to see an active summary of the schedules created, along with allowing you to set up the number of minutes after the expiration (or the delete command) that you can override the deletion.

Schedule Types/Recurrence

There are currently 5 types of schedules available to you to give you as much control over your schedule creation as possible. These are:

• One-Time Events-As the name implies, you create this schedule to trigger an action that happens once in the future. For example, let's say you have a one-time appointment you want to ensure you are reminded of. Please note that you can designate the date and time of the event. Best practice for a one time event is to actually schedule the 'action' to happen before the event occurs to give yourself a reminder of what you are attempting to remember. The other option, of course, is to schedule the exact time of the event, and then use the reminders function to give you a 'notice' of the upcoming event. Remember, all of this information goes into the message queue so plan accordingly with reminders as the items that go into the queue are retained until you delete them. Real-time alerting, however, may require multiple reminders. Ask Alexa is very flexible in giving you the information you need!

• Simple Recurring - If something in your life recurs on a regular basis, you can put this into Schedules and even remind you of the event. A great example of this is a birthday or anniversary. While having this information the day of is important, it is actually MORE important to remind you of the event BEFORE it happens. Schedules can do this for you as well.

   Two notes about scheduling simple recurrences:
   
   First, any recurrence less than 12 hours will randomly start between the time you press 
   <<Done>> and the recurrence interval. This is based on a SmartThings' recommendation 
   to reduce the workloads on the back-end SmartThings servers. This is typically not a 
   problem as once the first action occurs, they will continue to recur on the interval 
   schedule. If timing of when the first event is critical, it is recommended you use a cron
   schedule. 
   
   Second, as mentioned in this paragraph, the scheduling for simple recurrences is based 
   on when you tap <<Done>> to save the schedule. Again, for a short recurrence this might 
   not be a problem. However, if you are alerting or notifying based on a specific time frame, 
   complex or cron scheduling might suit you better for those use cases. Please note that you 
   can limit the number of times the schedule recurs, and also delete the schedule when the 
   number of recurrences reaches the threshold.

• Annual Birthday/Anniversary - This is a targeted schedule specifically for keeping track of birthdays or anniversaries. While complex recurring schedules can also be used to arrange this, you get the added ability to see add the ORIGINAL date of the event and allow Schedules to give you the 'age' of that event as of this year. All other options with regard to message queues and reminders are the same as the other schedules. What is NOT included are any restrictions, limits of number of time this schedules runs or the auto-delete function. If those are needed you should utilize the complex recurring schedules option.

• Complex Recurring - Complex Recurring has exactly the same options and intervals as the simple recurring schedules with two major differences. First, you can have a specific start and end time that the schedule will recur. For example, let's say you have piano training starting June 1st and ending August 1st and it is currently May 2nd. You won't have to wait until June 1st to set the schedule; instead you can set the schedule to ONLY run during those times. In addition, like simple recurrences, you can have the schedule also run a set number of times or even delete when the schedule expires. The other major difference in complex recurring schedules is the ability to have it run with restrictions. For example, if you schedule a macro to run every two days it will eventually fall on a weekend. By setting up restrictions, you can 'fine tune' when the scheduled actions happen and when they don't.

• Custom Cron Schedule - Cron is a Unix originating command structure for setting up complex schedules. For example, the following cron schedule set up a recurring interval for 12:00:00 pm on Wednesdays and Saturdays.

0 0 0 12 ? * WED,SAT *

The intention of this document is not to train you in cron syntax. Instead, it is recommended you read the following documentation from SmartThings: http://docs.smartthings.com/en/latest/smartapp-developers-guide/scheduling.html?highlight=scheduling#schedule-using-cron

It should be noted that cron scheduling is a difficult concept to grasp and it is sometimes trial and error to get it right. However, once you master it you will really wield the power of complex scheduling using this extension.

Actions

Actions are basically what happens when the schedule time arrives. There are currently 5 options available:

Action Name	Description
Send Free-Text To Message Queue(s)	This simply allows a message to be sent to the message queue. This can be a reminder (i.e. Bob's birthday is November 20th) or any text that you type into the app. Be sure to end with proper punctuation for the speech engine to process it properly with other text.
Run Macro	This will NOT give output to the message queue, but it does allow your automatons to run based on the schedule you set up. While Ask Alexa is mostly voice driven, this is a convience feature that allows your macros to run without the need to switch to another SmartApp. Please note that while macros will not give output, you CAN set up a reminder to the message queue to let you know this macro will be running.
Send/Play Voice Report	This will run one of your voice reports and place the message in the message queue(s) you choose. This might be handy, depending on how you have your message queue set up, to play real-time conditions of your house.
Send/Play Weather Report/Advisory	Like the voice report above, this action will run one of your weather reports or advisories and place the message in the message queue(s) you choose. This could be VERY convenient for setting up weather advisories alerts (see the use case Ask_Alexa_-_Schedules#Inclement_Weather_Advisories below).
Purge Message Queue(s)	As the name says, this will simply purge the message queues you choose. Many users have their message queues just accumulate messages on a daily basis. This allows you to set up a regular schedule to have this clean up occur. Please use this action with care; once a message is deleted it can not be recovered.

Options

There are only (at most) three options available for your scheduled actions. Two of these include appending text to the beginning or ending of any output to the message queues. These are 'variable aware' which means you can use some of the global variables (%time%, %date%, etc) that are listed here: Ask_Alexa#Text_Field_Variables. Please note that these fields will only be visible and active when you choose an option that outputs to the message queue(s). In other words, voice reports and free text will have this option available, while "Run Macro" will not.

The other option is to be reminded prior to the action. You can set these up to remind you of an action/event that will take place. A good example of how reminders work is listed in the use cases below (Ask_Alexa_-_Schedules#Birthdays.2FAnniversaries.2FAnnual_Events). You have multiple options to set up reminders. For example, you can set up a primary reminder simply 2 days before an action is scheduled to occur. However, if it is an important date, you can also set up additional reminders after the initial reminder. For example, if you have an important phone call you can set up a reminder to happen 1 day before an scheduled action and then hourly after that. Be sure to utilize the message queue restrictions as this could mean getting hourly reminders at night while you are trying to sleep (depending on your output options).

Please note that reminders are available for ALL actions. If you choose any that have output to a message queues (every action except "Run Macros"), you have the ability to simply use the same message queue as the action will use. However, for "Run Macros" you will be required to designated a message queue to send the reminder to.

Notes about reminders

There are certain circumstances you may run into with actions and reminders that may confuse you at first as they may not function as you intended. Here are a few examples:

Situation: You schedule a complex schedule that runs monthly, but starts in 1 week. You want Ask Alexa Schedules to remind you 2 weeks prior to the monthly event. You forget you set this schedule, and then the action of the scheduled instance happens without warning. Subsequent reminders seem to be working correctly.

Answer: This is expected. Using real dates, if today is July 1, and you set the monthly schedule to recur starting July 7th, but you want a 2 week reminder, you are running into an issue where the first reminder was to happen in June...BEFORE you set the schedule. The system simply starts reminding you on July 16th, which would be the subsequent reminder in for the action that will happen August 7th. The action for July 7th WILL occur without a reminder in this case.

Situation: You set up a cron expression and the action actually happens before the reminder.

Answer: This is a common occurrence, but unfortunately, is the nature of cron expressions; they are difficult to master. In the situation listed above, the cron reminder was simply entered with incorrect parameters. There are many detailed instruction online for creating cron expressions, including cron 'builders' that you can use to build you schedules. However, be warned....SmartThings implementation of cron does NOT translate to all cron makers. Be sure the builder applications are able to utilize the 'seconds' field at the beginning of the expression, and use the same wildcards as what SmartThings uses. As mentioned above, the best place to start is the SmartThings documentation for their format of cron (http://docs.smartthings.com/en/latest/smartapp-developers-guide/scheduling.html?highlight=cron#schedule-using-cron), then explore the internet for a good cron builder app

Use Cases

Below are some common use cases for schedules and how to set them up.

Birthdays/Anniversaries/Annual Events

The most common use case for the Ask Alexa Schedules is to give a voice notification to birthdays and anniversaries. Setting these up is rather straight forward, but just like any other schedule, you will need to plan ahead with regard to the primary alert (the day OF the event) and the reminders.

While simple or complex recurring schedules can be used, it is recommended you utilize the "Annual Birthday/Anniversary" schedule option. Simply choose this option, the start date (and time) as for your annual event. It is recommended that you include the beginning year of the event so that Ask Alexa Schedules can utilize the year to calculate the 'age' of the schedule. For example, if the person was married in 1997, you could put in that date and (in future versions of Ask Alexa) you could call out this age as part of the reminders or notification.

To alert yourself (either through audio, visual, or mobile means) to this event, simple go to the reminder section to choose the number of days before the event that you would like to be alerted to the primary event. In addition, you can set up the interval of reminders after the primary alert to continue to send reminders until the event. For example, you could send a reminder 7 days before a birthday, and continue to send daily reminders until the actual birthday date.

If you do not choose a message queue for the reminder, the one (or multiple ones) that you chose for the primary alerting will be used. Finally, if you choose audio alerting for the reminder (or the primary event) be sure to be cognizant of the time you set; you could be awoke early in the morning to a birthday event if you are not careful!

One-time Events

While annual events are important to remember, so are more immediate, and even one time events. For example, let’s say you have a doctor’s appointment at 4:00 pm on 6/21. This is the only appointment you have with this doctor, but you want to be reminded the day before and then every hour until the appointment. In this case, you will be home all of the time, but don’t want to have the alerting wake you up, but you still want it to remind you every hour of the appointment. Finally, you don’t want to store the 24 messages to remind you in your message queue. In fact, you don’t even want the messages in the queue...you just want to be reminded through your Sonos speaker to the appointment.

All of this is possible with a little bit of planning. First, you should set up your message queue with some restrictions for when you are sleeping. Let’s say you are awake from 8am to 10pm and only want messages during those times. Also, be sure to set up the proper speaker (or speakers) you want the messages to go to.

Next, you will create a one-time event for 6/21 at 4pm. Since this is a one-time appointment and you won’t be repeating it, you can also turn on the <<Delete schedule when expired>> option. This will delete the schedule from Ask Alexa when 6/21 after 4pm.

You will then set up a reminder for 1 day before the appointment, and then a reminder interval of hourly to the message queue you designated at the beginning. Since you don’t want to store this message in your message queue, you will set it up for ‘Notify Only’. At 4pm on 6/20 the first reminder will go off, and then each subsequent hour the reminder will go off, except when the time restrictions you set up in the message queue are in effect. The day of the appointment (after 8am) the reminders will continue and when you are safely at your appointment, the schedule will self-delete.

Inclement Weather Advisories

With the integration of Ask Alexa Weather Reports, you have the ability to create weather advisories for your area. Unfortunately, voice reports are typically ‘on demand’...which means you need to ask for them. However, you can have Ask Alexa Schedules to create a process where it checks the weather report on a regular basis and then alerts you ONLY when a weather advisory has been issued.

Since these types of alerts are important, we will assume you want them to not be limited by the time of day...even if you are sleeping you want to be alerted. Therefore, you want to set up a message queue with no restrictions on it. Depending on your needs, you may want to set up some notifications that don’t just put messages into the queue, but that notify you verbally, visually, or with a mobile alert. Once those are set up you can set up the schedule.

First, you want to choose a simple recurring schedule. While you could do every minute, depending on your area this may be too much. In addition, over polling may force SmartThings to disable this feature. Set the recurrence reasonably! In this example, we will set it for every three hours.

The “Action” in this case will be to <<Play Weather Report/Advisory>>. You will choose a report you set up previously that is just an advisory and doesn’t have any additional parameters of weather in it.

Next, turn on the <<Turn on Weather Advisory Notification Feature>>. This will look at the output of the weather report every time it is run and determine if it has content. If so, it will play on the message queue you set up. If there is no advisory, no alert is sent.

Finally, choose the message queue that you set up at the beginning. No reminders should be set if the goal is ONLY to alert when there is bad weather reported. However, depending on your use case, you may want to put an expiration time, overwrite or turn on the “Notify Only” switch as you don’t need the messages to accumulate in your queue as they are time sensitive. You can also set up a schedule to purge the message queues on a regular schedule/ basis.

Tap "Done" and the system will continue to check the weather, alerting you when there is an advisory published by Weather Underground.

Reminder About Amazon Developer Slots

Please remember ANY changes or additions you make to your Ask Alexa environment should immediately be followed up with running <<Settings>> <<Setup Variables>> in the main Ask Alexa SmartApp. This will allow newly created schedules to be reflected in the Amazon developer site. See Ask_Alexa#Setup_Variables for more information.