You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@openwhisk.apache.org by GitBox <gi...@apache.org> on 2018/02/01 19:17:49 UTC
[GitHub] csantanapr closed pull request #125: alarm readme updates
csantanapr closed pull request #125: alarm readme updates
URL: https://github.com/apache/incubator-openwhisk-package-alarms/pull/125
This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:
As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):
diff --git a/README.md b/README.md
index 2b0d0d5..53c88aa 100644
--- a/README.md
+++ b/README.md
@@ -3,89 +3,43 @@
[](http://www.apache.org/licenses/LICENSE-2.0)
[](https://travis-ci.org/apache/incubator-openwhisk-package-alarms)
-The `/whisk.system/alarms` package can be used to fire a trigger at a specified frequency. This is useful for setting up recurring jobs or tasks, such as invoking a system backup action every hour.
+The `/whisk.system/alarms` package can be used to fire a trigger at a specified frequency. Alarms are useful for setting up recurring jobs or tasks, such as invoking a system backup action every hour.
The package includes the following feeds.
| Entity | Type | Parameters | Description |
| --- | --- | --- | --- |
-| `/whisk.system/alarms` | package | - | Alarms and periodic utility |
-| `/whisk.system/alarms/alarm` | feed | cron, trigger_payload, maxTriggers, startDate, stopDate | Fire trigger event periodically |
-| `/whisk.system/alarms/once` | feed | date, trigger_payload | Fire trigger event once on a specific date |
-| `/whisk.system/alarms/interval` | feed | minutes, trigger_payload, startDate, stopDate | Fire trigger event on an interval based schedule |
-
-
-## Firing a trigger event periodically on a time based schedule
-
-The `/whisk.system/alarms/alarm` feed configures the Alarm service to fire a trigger event at a specified frequency. The parameters are as follows:
-
-- `cron`: A string, based on the UNIX crontab syntax, that indicates when to fire the trigger in Coordinated Universal Time (UTC). The string is a sequence of five fields that are separated by spaces: `X X X X X`.
-For more details about using cron syntax, see: http://crontab.org. Following are some examples of the frequency that is indicated by the string:
-
- - `* * * * *`: top of every minute.
- - `0 * * * *`: top of every hour.
- - `0 */2 * * *`: every 2 hours (i.e. 02:00:00, 04:00:00, ...)
- - `0 9 8 * *`: at 9:00:00AM (UTC) on the eighth day of every month
-
- **Note**: The parameter `cron` also supports a custom syntax of six fields, where the first field represents seconds.
- For more details about using this custom cron syntax, see: https://github.com/ncb000gt/node-cron.
- Here is an example using six fields notation:
- - `*/30 * * * * *`: every thirty seconds.
-
-- `trigger_payload`: The value of this parameter becomes the content of the trigger every time the trigger is fired.
-
-- `maxTriggers`: Stop firing triggers when this limit is reached. Defaults to infinite (-1).
-
-- `startDate`: The date when the trigger will start running. The trigger will fire based on the schedule specified by the `cron` parameter.
-
-- `stopDate`: The date when the trigger will stop running. Triggers will no longer be fired once this date has been reached.
-
- **Note**: The `startDate` and `stopDate` parameters support an integer or string value. The integer value represents the number of milliseconds
- since 1 January 1970 00:00:00 UTC and the string value should be in the ISO 8601 format (http://www.ecma-international.org/ecma-262/5.1/#sec-15.9.1.15).
-
-
-The following is an example of creating a trigger that will be fired once every 2 minutes with `name` and `place` values in the trigger event. The trigger will not start firing until
-January 1, 2019, 00:00:00 UTC and will stop firing January 31, 2019, 23:59:00 UTC.
-
- ```
- wsk trigger create periodic \
- --feed /whisk.system/alarms/alarm \
- --param cron "*/2 * * * *" \
- --param trigger_payload "{\"name\":\"Odin\",\"place\":\"Asgard\"}" \
- --param startDate "2019-01-01T00:00:00.000Z" \
- --param stopDate "2019-01-31T23:59:00.000Z"
- ```
-
-Each generated event will include as parameters the properties specified in the `trigger_payload` value. In this case, each trigger event will have parameters `name=Odin` and `place=Asgard`.
+| `/whisk.system/alarms` | package | - | Alarms and periodic utility. |
+| `/whisk.system/alarms/interval` | feed | minutes, trigger_payload, startDate, stopDate | Fire Trigger event on an interval based schedule. |
+| `/whisk.system/alarms/once` | feed | date, trigger_payload | Fire Trigger event once on a specific date. |
+| `/whisk.system/alarms/alarm` | feed | cron, trigger_payload, startDate, stopDate | Fire Trigger event on a time-based schedule using cron. |
## Firing a trigger event periodically on an interval based schedule
-The `/whisk.system/alarms/interval` feed configures the Alarm service to fire a trigger event on an interval based schedule. The parameters are as follows:
+The `/whisk.system/alarms/interval` feed configures the Alarm service to fire a Trigger event on an interval based schedule. The parameters are as follows:
- `minutes`: An integer representing the length of the interval (in minutes) between trigger fires.
-- `trigger_payload`: The value of this parameter becomes the content of the trigger every time the trigger is fired.
+- `trigger_payload`: The value of this parameter becomes the content of the Trigger every time the Trigger is fired.
- `startDate`: The date when the first trigger will be fired. Subsequent fires will occur based on the interval length specified by the `minutes` parameter.
- `stopDate`: The date when the trigger will stop running. Triggers will no longer be fired once this date has been reached.
- **Note**: The `startDate` and `stopDate` parameters support an integer or string value. The integer value represents the number of milliseconds
- since 1 January 1970 00:00:00 UTC and the string value should be in the ISO 8601 format (http://www.ecma-international.org/ecma-262/5.1/#sec-15.9.1.15).
-
+ **Note**: The `startDate` and `stopDate` parameters support an integer or string value. The integer value represents the number of milliseconds since 1 January 1970 00:00:00 UTC and the string value should be in the ISO 8601 format (http://www.ecma-international.org/ecma-262/5.1/#sec-15.9.1.15).
-The following is an example of creating a trigger that will be fired once every 90 minutes. The trigger will not start firing until
-January 1, 2019, 00:00:00 UTC and will stop firing January 31, 2019, 23:59:00 UTC.
+The following example creates a trigger that is fired once every 2 minutes. The trigger fires as soon as possible, and will stop firing January 31, 2019, 23:59:00 UTC.
```
wsk trigger create interval \
--feed /whisk.system/alarms/interval \
- --param minutes 90 \
+ --param minutes 2 \
--param trigger_payload "{\"name\":\"Odin\",\"place\":\"Asgard\"}" \
- --param startDate "2019-01-01T00:00:00.000Z" \
--param stopDate "2019-01-31T23:59:00.000Z"
```
+
+Each generated event includes parameters, which are the properties that are specified by the `trigger_payload` value. In this case, each Trigger event has the parameters `name=Odin` and `place=Asgard`.
## Firing a trigger event once
@@ -96,7 +50,7 @@ The `/whisk.system/alarms/once` feed configures the Alarm service to fire a trig
**Note**: The `date` parameter supports an integer or string value. The integer value represents the number of milliseconds
since 1 January 1970 00:00:00 UTC and the string value should be in the ISO 8601 format (http://www.ecma-international.org/ecma-262/5.1/#sec-15.9.1.15).
-- `trigger_payload`: The value of this parameter becomes the content of the trigger when the trigger is fired.
+- `trigger_payload`: The value of this parameter becomes the content of the Trigger when the Trigger is fired.
The following is an example of creating a trigger that will be fired once on December 25, 2017, 12:30:00 UTC.
@@ -106,3 +60,42 @@ The following is an example of creating a trigger that will be fired once on Dec
--param trigger_payload "{\"name\":\"Odin\",\"place\":\"Asgard\"}" \
--param date "2017-12-25T12:30:00.000Z"
```
+
+## Firing a Trigger on a time-based schedule using cron
+
+The `/whisk.system/alarms/alarm` feed configures the Alarm service to fire a Trigger event at a specified frequency. The parameters are as follows:
+
+- `cron`: A string, based on the UNIX crontab syntax that indicates when to fire the Trigger in Coordinated Universal Time (UTC). The string is a sequence of five fields that are separated by spaces: `X X X X X`.
+For more information, see: http://crontab.org. The following strings are examples that use varying duration's of frequency.
+
+ - `* * * * *`: The Trigger fires at the top of every minute.
+ - `0 * * * *`: The Trigger fires at the top of every hour.
+ - `0 */2 * * *`: The Trigger fires every 2 hours (that is, 02:00:00, 04:00:00, ...).
+ - `0 9 8 * *`: The Trigger fires at 9:00:00AM (UTC) on the eighth day of every month.
+
+ **Note**: The parameter `cron` supports five or six fields. Not all OpenWhisk vendors may support 6 fields so please check their documentation for support.
+ For more details about using this custom cron syntax, see: https://github.com/ncb000gt/node-cron.
+ Here is an example using six fields notation:
+ - `*/30 * * * * *`: every thirty seconds.
+
+- `trigger_payload`: The value of this parameter becomes the content of the Trigger every time the Trigger is fired.
+
+- `startDate`: The date when the Trigger will start running. The Trigger fires based on the schedule specified by the cron parameter.
+
+- `stopDate`: The date when the Trigger will stop running. Triggers are no longer fired once this date is reached.
+
+ **Note**: The `startDate` and `stopDate` parameters support an integer or string value. The integer value represents the number of milliseconds since 1 January 1970 00:00:00 UTC, and the string value should be in the ISO 8601 format (http://www.ecma-international.org/ecma-262/5.1/#sec-15.9.1.15).
+
+The following is an example of creating a trigger that fires once every 2 minutes with `name` and `place` values in the trigger event. The trigger will not start firing until
+January 1, 2019, 00:00:00 UTC and will stop firing January 31, 2019, 23:59:00 UTC.
+
+ ```
+ wsk trigger create periodic \
+ --feed /whisk.system/alarms/alarm \
+ --param cron "*/2 * * * *" \
+ --param trigger_payload "{\"name\":\"Odin\",\"place\":\"Asgard\"}" \
+ --param startDate "2019-01-01T00:00:00.000Z" \
+ --param stopDate "2019-01-31T23:59:00.000Z"
+ ```
+
+ **Note**: The parameter `maxTriggers` is deprecated and will be removed soon. To stop the Trigger, use the `stopDate` parameter.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services