notecuts

NoteCuts

NoteCuts continually monitors shared notes on Apple Notes, Dropbox, and Evernote, enabling automatically running of shortcuts, even when the iOS device is locked and sleeping.

NotesCuts: Trigger Shortcuts to Run via Shared Notes

With NoteCuts, you can:

NotesCuts offers features such as the ability to:

Automating Shortcuts

A common request from Shortcuts users is whether shortcuts can be automatically triggered. And, the most common, albeit uninformed, response is that they cannot. While true this is not a built-in part of iOS, solutions do exist today. I have developed a suite of apps enabling automatic triggering of shortcuts across a variety of use cases:

Of course, it would be great if these features are built into iOS and Shortcuts, but we could be waiting a long time for those features to come. In the meantime, you can take advantage of these automation shortcuts today.

System Requirements

NoteCuts has the following system requirements:

Getting Started

When you run NoteCuts for the first time, you’ll be presented with a short tutorial describes the major features of NoteCuts. Afterwards, you will have the option to create your first NoteCut, read the documentation, or go to the NoteCuts Home screen.

Let’s make a NoteCut. You must first choose if you want to create a local NoteCut or remote NoteCut.

Local NoteCuts

A local NoteCut is attached to a file/note in Dropbox, Evernote, or Apple Notes that allows you to run shortcuts on the same iOS device where the NoteCut resides. As you add shortcut commands to this note and evaluate them with NoteCuts — either manually or automatically — the shortcuts will run on your device.

You normally would have one local NoteCut on each of your iOS devices reserved for your own personal use.

Should you ever share this note with other people, they can remotely execute shortcuts on your device by associating the same note as a remote NoteCut.

In this case, you may want to provide others with a note that offers a subset of shortcuts that you want to make available for remote usage.

Remote NoteCuts

Remote NoteCuts are notes that are associated with local NoteCuts on other iOS devices. You can create these notes yourself or receive them as shared notes from other people. A shortcut command added to a remote NoteCut will run on a different iOS device.

Naming Your NoteCuts

It is recommended to name your NoteCuts by device. This way it will be easy to identify on which device the shortcuts will be running. For instance;

If you have an iPad and an iPhone, you would have a minimum of two notes (stored on either Dropbox, Evernote, or Apple Notes) and four NoteCuts (two on each device):

iPad

iPhone

A Local and Remote NoteCut

The setup above will allow your iPad to trigger shortcuts on itself and the iPhone. And, the iPhone will be able to trigger its own shortcuts as well as the shortcuts on the iPad.

Your First NoteCut

Let’s first create a local NoteCut. Give it a name using the scheme described above.

The name you choose will be used as part of the title of the note in Apple Notes or Evernote and the filename for the text file on Dropbox. The format for the note or filename will be:

`NoteCuts (XYZ)`

Where XYZ is the name you enter.

For NoteCuts using Dropbox, do not add .txt to the name. The file extension will automatically be appended to the end of the name you choose.

New NoteCut #1

NoteCut Location

Next, you’ll choose where you want the associated note will live. Select from:

For your first NoteCut, tap Apple Notes.

Description

Add a description for your NoteCut or tap OK to leave it blank.

Adding Shortcuts

When you create a local NoteCut, you can define which shortcuts can be run from the NoteCut. By default, you can run any shortcut installed on the device.

If you don’t specify anything, any shortcut on your iOS device will be available to run from this NoteCut.

To restrict this, separate keywords by new lines. Any shortcut that contains the keyword can run when this NoteCut is evaluated. For instance:

Speak
Toggle
Remote

Specifying these keywords means any shortcut that contains Speak, Toggle, or Remote can run with this local NoteCut. A shortcut named Photos will not run. Keywords are case-sensitive so Toggle is not the same as toggle.

Define shortcut keywords when sharing your local NoteCuts with other people. Otherwise, they will be able to run every shortcut on your device!

New NoteCut #2

Testing Your First NoteCut

After creating the NoteCut, you will be presented by the Edit NoteCut Screen. Tap either Add Text to Note to bring up a text input dialog.

If you have an iPad, you can display Notes in Split View or Slideover and choose View in Notes to see Shortcuts and Notes side-by-side.

Adding a Shortcut Command

In the text input dialog, add a command to run a shortcut by prefixing the shortcut name with the ▶️ character. For instance:

▶️ Speak Random Number

Choose a shortcut where it will be obvious to you that it has run. A simple one could be one that speaks a random number or flashes the flashlight on your device.

Adding a Shortcut Command to a Note

Evaluating Your First NoteCut

Return to the Shortcuts app and tap Evaluate This NoteCut from the NoteCut Edit menu. After a few seconds, the shortcut will run.

Congratulations, you just created and evaluated your first NoteCut!

To force Apple Notes to sync everytime you evaluate when Notes is not an active application, the Update Apple Notes Automatically preference must be enabled. Note that this will add about 5 seconds to the beginning of the evaluation time to let iCloud Notes to sync.

Next Steps

Running NoteCuts in the Background

NoteCuts can run continually in the background, constantly checking for new additions to your Apple Notes, Evernote notes, and Dropbox text files. You can configure from one to sixty seconds how often NoteCuts will check for changes. NoteCuts can even run these shortcuts when your device is locked and asleep.

Now, go into Apple Notes, Dropbox, or Evernote and start entering text at the end of the note, following the last appearance of ⚡️📅 🗒⚡️, where is the last evaluation date.

If you are using Apple Notes, you will see a ⚡️⚡️ appended after every NoteCuts evaluation. This is how NoteCuts can always make sure it sees the latest version of your notes during evaluation. If you turn off the Update Apple Notes Automatically setting, the ⚡️⚡️ will no longer appear, but Apple Notes will need to be active in order for new changes to appear.

Any shortcut command you add will be run during the next evaluation period by NoteCuts.

Make sure the shortcut you want to run automatically works when launched in the background. Any error may cause the Shortcuts app to display an modal dialog with will stop the shortcut and any future monitoring by NoteCuts until it has been removed from the Shortcut Quarantine.

Polling Interval

You can configure NoteCuts to check for new changes to your NoteCuts on Dropbox, Evernote, and Apple Notes every 1-60 seconds. For polling intervals longer than one minute, you’ll want to use Cronios and NoteCuts together.

Setting an aggressive polling interval may lead to timeouts when using Dropbox and Evernote as the notes storage system.

Adjusting NoteCut's Polling Interval

Quarantine

When NoteCuts runs a shortcut, it temporarily places the shortcut in a quarantine. If no errors occurred during execution, the shortcut is removed from the quarantine. However, if there was an error, it’s likely one that terminated the entire Shortcut application.

When this happens, NoteCuts will prevent that shortcut from running again until you remove it from the Quarantine.

  1. Open NoteCuts
  2. If shortcuts are in quarantine, a menu option called Shortcut Quarantine will appear below the evaluation menu items.
  3. Tap and select the shortcuts that should remain in quarantine.
  4. Tap Done.

Shortcuts Quarantine

When a shortcut is removed from the quarantine, it can run again from NoteCuts. If another error occurs, you’ll want to review the shortcut to see why it’s crashing. It could be one of several reasons, including:

Integration with Cronios

Cronios, the shortcuts scheduler for iOS, lets you can run shortcuts in the background. NoteCuts can run alongside other Cronios-compatible shortcuts by adding NoteCuts as a cron job to Cronios.

Here’s how to configure NoteCuts to work with Cronios:

  1. Enable Cronios Integration on the NoteCuts Settings page. Configure NoteCuts to run at an interval of your choosing in Cronios. NoteCuts gives you options to create a cron job in Cronios that checks every 1, 2, 5, 10, 15, 30, or 60 minutes. You can further customize this within the NoteCuts cron job details page in Cronios.
  2. Run Cronios in Run Continuously Mode.
  3. For best results, have some kind of background audio playing, be it a song, podcast, or a silent audio file.

Integrating NoteCuts with Third-Party Triggering Services

Combine a third-party triggering service like IFTTT or Zapier to append shortcut commands to your notes and files on Evernote or Dropbox. For Apple Notes, use shortcuts to append commands to local and remote NoteCuts notes.

IFTTT Applet Example

If NoteCuts is running continuously in the background, shortcut commands will run automatically. The screenshot below shows an IFTTT Do button widget running a shortcut on the iPad, triggered from either an iPhone or an Apple Watch.

Running a shortcut on the iPad from the iPhone and Apple Watch

Sharing NoteCuts

Invite friends, family, or colleagues to run shortcuts on your device. Have them do the same for you, so you can run shortcuts on their devices. As both of you edit notes that are associated with Local and Remote NoteCuts, the changes will stay in sync via iCloud, Evernote, or Dropbox.

If you have no interest in sharing shortcuts with others, you may still want to be able to trigger shortcuts on all the iOS devices that you do own. Simply share the NoteCuts notes to yourself using the same instructions below.

Sharing in Apple Notes

Learn more about sharing notes in this Apple Support web page.

  1. In NotesCuts, open the NoteCut that you want to share.
  2. Tap View in Notes to open the note in Notes.
  3. Tap the collaborate icon (the person with the plus sign).
  4. Choose how you’d like to send your invitation.
  5. Enter the recipients and tap Send.

Once a note has been shared, you can adjust its sharing settings by tapping on the collaborate icon again. You can:

Sharing in Dropbox

To share your text file in Dropbox, follow these steps:

  1. On the Dropbox website or app, navigate to the folder containing the note.
  2. Tap or click the Share Folder button.
  3. Enter the name or emails of the people you want to invite to edit the file.
  4. Make sure Can Edit is selected from the access permissions drop-down menu.
  5. Tap the gear icon.
  6. Under Manage Access, select Only You from the drop-down menu so only you can add more people to the shared folder.

NOTE: With Dropbox, in order for people to be able to edit the file, you have to share the parent folder, not the file.

Sharing in Evernote

To share your note in Evernote, follow these steps:

  1. Go to the Evernote NoteBook that holds the note you want to associated with the NoteCut.
  2. Tap the Share button.
  3. Enter the names or emails of the people to whom you want to share the notebook.
  4. Tap the pencil icon to allow them to edit the note. Best to not allow them to invite others to edit the note.

On iOS, the Share Note button looks similar to the one in Apple Notes. It’s a person with a plus button. On Evernote on the web, the button is green and says Share.

Once people have accepted the share invitation and gained access to the notebook, they will be able to associate notes in the notebook with NoteCuts to run shortcuts.

NoteCuts Syntax

NoteCuts looks for specially formatted lines to indicate shortcuts to run and the last evaluation dates.

Run Delimiter

NoteCuts will evaluate any text following the last occurrence of the following string:

⚡️📅 🗒⚡️

Where is an evaluation date. This string is called the NoteCuts Run Delimiter.

Note: Anything you place above the last run delimiter will be ignored.

You do not have to add the run delimiter yourself. NoteCuts automatically adds it when it evaluates your local NoteCuts. If you want to force an evaluation of new shortcuts, you can manually add the run delimiter, followed by a list of shortcuts.

Note: If your device is sleeping, the run delimiter will be added for NoteCuts using Evernote and Dropbox. Apple Notes syncing can only occur while the device is on and unlocked.

Shortcut Syntax

To run a shortcut, you must prefix the shortcut name with the ▶️ character. This instructs NoteCuts to run a shortcut. For instance:

▶️ Speak Random Number
▶️ Backup My Shortcuts
Toggle Flashlight

In the example above, only two shortcuts will run, Speak Random Number and Backup My Shortcuts. Toggle Flashlight will not run, even though it is a valid shortcut name, because the ▶️ character is not present at the beginning of the line.

Shortcut Options

You can specify the following emoji characters to provide options after the name of the shortcut:

🔒

Lock Detection: If this emoji is present, the shortcut will not run when the device is locked. While it is currently impossible to know if the device is locked, NoteCuts can guess that it is locked whenever the device screen brightness is 0. Note: if your shortcut natively handles lock detection (i.e. it alerts the user to unlock the device before continuing), you do not need to specify this option.

✋

Requires Interaction: This option will cause NoteCuts to open the Shortcuts app prior to running the shortcut. This is useful if you need to present dialogs and menus to the user. This requires the device to be on to work.

☁️

Requires Network Access: If this option is present, your shortcut will not run if the device is offline.

📗

Notify Shortcut: A Cronios-style dictionary will be sent to the shortcut as input. You can use this dictionary to determine whether or not you are running the shortcut in the background.

{
	"Cronios": 1,
	"online": 1
}

💬

Custom Input: Any text that follows this line will be sent to the shortcut as input. If the Notify Shortcut option is present, input will be placed under the input key of the dictionary sent to the shortcut.

Here are some examples:

▶️ The Dark Dungeon (PKS) ✋🔒
▶️ How Do You Feel? ✋🔒☁️
▶️ Retrieve Web API ☁️
▶️ Remote Notification 💬 How are you doing? Are you free for dinner tonight?
  1. The Dark Dungeon, a PromptKit Story shortcut, will not run when the device is locked. NoteCuts will Open the Shortcuts app prior to running the shortcut.
  2. How Do You Feel requires network access for dictation and user interaction (Shortcuts needs to be in the foreground for dictation to operate). It needs to run when the device is unlocked.
  3. Retrieve Web API only requires network access as it pings an API on the open web for information.
  4. Remote Notification has custom input which will be displayed on the iOS device in a notification banner.

Silent Audio

Use these audio files with Cronios to let run for long periods of time when you’re using your iOS device or when it’s locked.

Here are instructions on how to create a shortcut that plays the silent audio and runs NoteCuts in continuous monitoring mode.

  1. Add the audio files to iTunes.
  2. Sync them to your iOS device.
  3. Play the song to create a Siri Shortcut (optional).
  4. Create a shortcut that has the following actions:

24 Hours of Silence

Now, whenever you want to run NoteCuts or Cronios for long periods of uninterrupted time, run this shortcut. After seeing the notification from NoteCuts or Cronios as to when it will start evaluation, you can lock your screen or switch to using other apps.

Whether you use Cronios or NoteCuts, install and enable the NoteCuts Watcher or the Cronios Watcher to be notified if NoteCuts/Cronios were to stop, either by iOS or by an error in the Shortcuts app.

NoteCuts Watcher

To be notified in the event that NoteCuts does stop running, we get some help from Scriptable, is a JavaScript development enviroment for iOS from Simon B. Støvring. Scriptable allows you to create JavaScript scripts that can be run from Shortcuts and Siri. It also has the ability to schedule notifications, which we use to notify us when NoteCuts has stopped running.

NoteCuts Watcher is a script for use with Scriptable and Cronios that does two things:

  1. Creates reminder notifications in the future for you to restart NoteCuts in “Evaluate Continuously” Mode.
  2. Clears out any previously set reminders.

With the Enable NoteCuts Watcher preference is set and Scriptable and the NoteCuts Watcher Script installed, you’ll be notified when NoteCuts has stopped running within minutes. Tapping on the notification banner will relaunch NoteCuts in Evaluate Continuously mode via the NoteCuts Daemon shortcut.

NoteCuts Watcher Setup

Here’s how you install and configure Scriptable and NoteCuts Watcher:

Scriptable Instructions

  1. Download and install Scriptable.
  2. Open Scriptable.
  3. Tap the + icon to create a new script.
  4. Tap the Script Settings button.
  5. Tap and edit the name. Call it NoteCuts Watcher. Create Scriptable script for NoteCuts Watcher
  6. Change the icon and color if desired.
  7. Tap Done.
  8. In the main script area, copy and paste the contents of the following file on GitHub.
  9. If desired, change the values in the kNotificationInterval array according to the reminder schedule you want to have for NoteCuts Watcher. The default reminds you to restart the NoteCuts Daemon shortcut after 5, 7, 10, 15, 30, and 60 minutes of no detectable NoteCuts activity.
  10. Tap the Play button to run the script. This will create a shortcut in the Siri Suggestions actions section in Shortcuts.
  11. Tap Done.

In Shortcuts

  1. Make sure you have the NoteCuts Daemon shortcut installed.

In NoteCuts

  1. Open NoteCuts.
  2. Tap Settings.
  3. Tap Enable NoteCuts Watcher.
  4. Confirm that NoteCuts Daemon, Scriptable app, and the NoteCuts Watcher Scriptable script are all installed.

To test this, run NoteCuts in “Evaluate Continuously” mode. After one evaluation period, stop it. Wait for five minutes and you will see a banner notification to relaunch NoteCuts.

NoteCuts Watcher in Action

Make sure that Do Not Disturb is disabled and that Shortcuts can send you notifications, or you will not see the notification.

Tapping the notification banner will cause the NoteCuts Daemon shortcut to relaunch NoteCuts back in “Evaluate Continuously” mode. Every time NoteCuts successfully processes your NoteCuts, it will call NoteCuts Watcher to reset the relaunch reminders.

NoteCuts Daemon

The NoteCuts Daemon shortcut launches NoteCuts in Evaluate Continuously mode. Use it instead of running NoteCuts from the Edit Shortcut Screen for speed. Running through five actions is a lot faster than running through 2400!

NoteCuts Daemon

Exploring the NotesCuts Interface

The NoteCuts Home screen has the following elements:

Settings

You can configure the following options in NoteCuts from the Settings page:

Background-Aware Shortcuts

When writing background aware shortcuts, you have to consider what you can and cannot do in your shortcut.

Your shortcut can be executing from many places when run from NoteCuts:

Some actions do not work when the device is locked and some do not work when Shortcuts is not the frontmost application.

Requires Unlocked Device

The following actions (not an exhaustive list) require the device to be unlocked.

Requires Shortcuts be the Frontmost Application

Here are some actions that require Shortcuts to be the frontmost application:

If you use any of these actions above when not in the Shortcuts app, an error will occur and stop NoteCuts.

The following actions will not raise an error, but you must return to the Shortcuts app in order to continue running the shortcut. If you wait too long, the Shortcuts app may time out and quit.

You can force a switch to the Shortcuts app either in your shortcut or by specifying the ✋ option in the shortcut command to the NoteCut. For instance:

▶️ Check The Weather ✋
▶️ Dictate Some Text ✋ ☁️
▶️ Text My Location ✋

Right before any of these shortcuts run, NoteCuts will call the Open App action and open Shortcuts.

Always test your shortcuts so that they run without errors in the background. If an error does occur, the shortcut may be added to the Shortcut Quarantine in NoteCuts.

Frequently Asked Questions and Troubleshooting

I added items to run, but they are not running.

Did the device go to sleep before you added the items to the shared Note? iCloud Sync does not happen when the device is sleeping or off. NoteCuts will remember the last set of shortcuts that were run so it doesn’t run them again when the device wakes up.

Do you have Shortcuts Cache enabled? If so, have you added new shortcuts after the last time you updated the cache?

Did you provide keywords for your NoteCut, restricting the shortcuts that can run from the NoteCut? If so, make sure the shortcut you are trying to run is on the list of available shortcuts. You can view what shortcuts will run by selecting View Triggerable Shortcuts from the Edit NoteCut menu.

I’m getting an error, “The action could not be run in the current user interface.”

With Apple Notes, NoteCuts makes use of the Append Note action when evaluating Local NoteCuts. By appending a new line to the end of the note, iCloud sync is triggered for the note, causing all updates to be fetched. The Append Note action currently requires the device to be unlocked. If NoteCuts tries to do this when the device is locked, this error will be thrown and NoteCuts and Shortcuts will stop execution. The shortcut will be placed into quarantine, however, so it will not disrupt NoteCuts again unless your release it from quarantine.

Let’s hope Apple and the Shortcuts team allow shortcut developers better ability to handle errors without terminating the entire shortcut execution in the future.

This is not a concern with Evernote and Dropbox. Retrieving data from those two services always seems to fetch the latest data from the cloud.

I can’t run other shortcuts from the Shortcuts app while NoteCuts or Cronios is running in continuous mode.

Because NotesCuts and Cronios are shortcuts themselves, they have to be running continually in order to evaluate your shortcuts.

Notification Widget and Share Sheet

You can, within limits, use shortcuts from the Notification Widget or shortcuts from the Share Sheet. If one of these shortcuts needs to open the Shortcut app, it will not work, since NoteCuts is running. Stop NoteCuts to be able to run your shortcut.

Siri

If you use Siri to run one of your shortcuts and NoteCuts is running, NoteCuts will terminate and iOS will run your shortcut. Remember to relaunch NoteCuts afterwards.

From the iOS Home Screen

Tapping on a shortcut that you’ve added to the Home screen will terminate NoteCuts if it is running and run your shortcut.

If you have the NoteCuts Watcher enabled, you’ll be notified within minutes that NoteCuts needs to be relaunched.

Refer to the section on running other shortcuts in the Cronios documentation for additional information on this subject.

NoteCuts is making this beep noise every minute

That is the Keep-Alive beep feature of NoteCuts. It’s proven to be the most reliable method for keeping NoteCuts running in the background, even when the device is locked and asleep. Turn down the sound so that the noise reaches an acceptable level for you, but note that this volume setting is the same for the Speak Text action of Shortcuts.

I’m seeing a the Request Time Out error when I leave NoteCuts running for long periods of time

Error handling is not the best in Shortcuts. Because the time out error is displayed in a modal dialog, it terminates whatever shortcut is running. Let’s hope that Apple allows better error handling in future versions of Shortcuts so that apps like NoteCuts and Cronios can continue running even after experiencing an error.

How it works

When NoteCuts evaluates your notes, it does the following things:

  1. Checks to see if the device is locked by inspecting the device brightness value.
  2. Checks online status.
  3. Retrieves a list of shortcuts on the device. If you have a lot of shortcuts, this process can take several seconds. You can speed it up by enabling the Shortcuts Cache in Settings.
  4. Retrieves all local NoteCuts or a single local NoteCut (if NoteCuts was supplied at launch with name of a NoteCut). Retrieved information from Apple Notes, Evernote, or Dropbox.
  5. If the screen is on, assume that the device is unlocked. Update each note to force an iCloud sync of the note.
  6. Wait a few seconds for iCloud sync to complete.
  7. Evaluate the NoteCut for new shortcuts to run.
  8. Run the shortcuts if evaluation is successful. Don’t run if certain conditions are not met (i.e. online status, lock detection, etc.).
  9. Exit the shortcut.

This workflow can be visualized in the following flow diagram:

NoteCuts Flow Diagram

Will running Cronios and NoteCuts impact my battery life?

If the shortcuts that are being run employ battery-draining activities like Get Current Location, battery life will be affected. However, if Cronios and NoteCuts are just polling and not running shortcuts, battery drain can be minimal.

When running while the device is locked, the lack of battery drain is even more pronounced. A test shown that over a nearly 8 hour period, only 10% of a locked and sleeping iPad Pro battery was drained, despite Cronios, NoteCuts, and WatchCuts checking for new shortcuts to run every minute.

Localization

NoteCuts is available in English, but is ready to be localized into other languages.

You can use the Localization Helper shortcut to assist with localizing NoteCuts into your language.

Download Localization Helper from RoutineHub »

Help make NoteCuts more accurate and more universal for all iOS users!

App Framework

NoteCuts was developed using the Shortcut App Framework approach to developing application-like shortcuts. This framework was also used to develop:

Learn more how you can create your own shortcut applications with App Framework here.

License

Copyright © 2019 Adam Tow • tow.com • @atow

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

This site is open source. Improve this page.