Differences

This shows you the differences between two versions of the page.

--- trigger:Remote [2017/09/05 02:39] – peternlewis
+++ trigger:Remote [2019/09/22 19:26] (current) – ADD section on How to Invoke JMichaelTX
@@ Line 1: / Line 1: @@
-The *Remote trigger* (v8+) lets you execute a trigger remotely without authentication via a Stairways Software web server.
+====== Remote Trigger ======
-(!) Anyone who knows the trigger code can trigger this macro from anywhere on the Internet so it should generally only be used with a safe macro such as restarting a service that is always supposed to be running, or launching iTunes or some other fairly innocuous activity.
+The *Remote trigger* (v8+) lets you trigger selected macros from any device on the Internet, without authentication, via a Stairways Software web server.  Of course, you have to have set this [[:Triggers|trigger]] on the [[manual:Macros|Macro]] first.
-(!) Because this trigger relies on a Stairways Software web server, and Keyboard Maestro is not sold as a service, this part of Keyboard Maestro is not guaranteed indefinitely - at some point the server will no longer be maintained and the trigger will stop working.
+For a good discussion, see:
+  * [Tip:  How & When to Use the Remote Trigger](https://forum.keyboardmaestro.com/t/triggering-keyboard-maestro-macros-remotely/8277?u=jmichaeltx), 2017-10-13, peternlewis
+  * [Macro Triggers that Use a URL](https://forum.keyboardmaestro.com/t/request-for-a-working-example-of-remote-trigger/10844/10?u=jmichaeltx), 2018-07-15, peternlewis
-(!) Because this trigger operates over the Internet, through a Stairways Software web server, as well as over the Internet between Keyboard Maestro on your Mac and the Stairways Software web server, the trigger will not be 100% reliable, so it should not be used in cases where it is essential that the trigger gets through.
+---
-(!) Note that this trigger has nothing to do with the in-built Keyboard Maestro web server, this trigger works entirely independently of that and turning the in-built web server on or off will not affect this trigger.
+===== Read Before Your Use the Remote Trigger =====
+**Clearly there are some serious security issues with this, so you should use a lot of caution when you allow any macro to be executed with a Remote trigger.**
-The trigger works defining a URL in the form of:
+{{:trigger:caution-small.png?nolink |}}
-`https://trigger.keyboardmaestro.com/t/<UniqueID1>/<UniqueID2>?TriggerValue`
+  * **A macro with the _Remote Trigger_ may be used by anyone who knows the trigger code from anywhere on the Internet.**
+* **It should only be used with a very safe macro**, such as:\\     • Restarting a service that is always supposed to be running, or\\     • Launching iTunes or\\     • Some other fairly innocuous activity.
+  * **This feature of Keyboard Maestro is not guaranteed indefinitely**, and may be removed at any time without notice.
+  * **The trigger will not be 100% reliable**
+    * It is dependent on many devices on the Internet, some outside the control of Stairways Software, between the device which invokes the trigger and Keyboard Maestro on your Mac.
+    * **So it should not be used in cases where it is essential that the target Macro be executed.**
+  * **Your macro _could_ be triggered by anyone who just happens to use the same pair of Remote Trigger UniqueIDs.**
+  * The _Remote Trigger_ does not use, and is not dependent on the local built-in Keyboard Maestro [[trigger:Web_Server|Web Server]].
-UniqueID1 can either be specified by you, or can be a unique ID for your Mac (so that each Mac you sync macros to has a different trigger value).
+---
+===== How To Use =====
+==== Macro Setup ====
+Create a New Macro, and follow these steps:
+  - Click on the ➕ to add a trigger, and select "Remote Trigger".
+  - That will add the trigger and generate UniqueID1 and UniqueID2 for you to use in the Remote Trigger URL:
+    * {{:trigger:remote-trigger-example.png?nolink|}}
+  - Paste the URL on the Clipboard somewhere for safe-keeping.
+    * Probably best to store in a password manager like 1Password.
+    * Remember:  Anyone with this URL can trigger your macro.
+==== URL for Remote Trigger ====
+The trigger uses a URL in the form of:
+```html
+https://trigger.keyboardmaestro.com/t/<UniqueID1>/<UniqueID2>?TriggerValue
+```
+where:
+  * //UniqueID1// can either be specified by you, or can be a unique ID for your Mac (so that each Mac you sync macros to has a different trigger value).
+  * //UniqueID2// can be defined by you, and defaults to a Globally Unique ID.
+  * **It is best to not change these IDs to ensure that no one else is using the same ID as you are.**
+==== How To Invoke Remote Trigger ====
+  - In the Remote trigger section of the Macro, click the _Copy_ button (as shown in the above screen shot), and it will copy the URL required.
+  - Paste it into any app or tool that will open a URL, like:
+      - The Address bar of any web browser
+      - The `/bin/open` command in Terminal, or a [[action:Execute_a_Shell_Script|Execute a Shell Script]]
+      - [[action:Open_a_URL|Open a URL action]]
+==== More Information ====
-UniqueID2 can be defined by you, and defaults to a Globally Unique ID.
 If more than one macro (on any Mac, anywhere in the world, yours, or anyone else's) has the same pair of UniqueIDs, then all those macros will trigger when the URL is accessed.
@@ Line 21: / Line 67: @@
 Generally, you should use the default values unless there is some reason to change them (such as explicitly wishing to trigger multiple macros in multiple locations).
-The [[token:TriggerValue|%TriggerValue%]] token will hold the TriggerValue from the accessed URL.
+When the macro executes, its [[token:TriggerValue|%TriggerValue%]] token will hold the //TriggerValue// used in the Remote Trigger URL.
 As with all triggers, macros are only available if they are currently active, that is if they are enabled and in a Macro Group that is enabled and active.
 For example, if you are running some sort of process on your Mac that occasionally fails, you could write a script to restart it and make it available as a Remote triggered Macro, which you (or anyone else) could then execute to restart the process.
+===== Using with Web Services =====
 You can also connect up web services (eg [[https://healthchecks.io|HealthChecks.io]]) to trigger a macro based on whatever conditions they operate on.
-Clearly there are some serious security issues with this, so you should use a lot of caution when you allow any macro to be executed with a Remote trigger.
 ===== See Also =====