diff --git a/CHANGELOG.md b/CHANGELOG.md index a67dd64317e..94c1ea84549 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -25,6 +25,7 @@ - console: add the ability to delete a role in permissions summary page (close #3353) (#4987) - console: fix styling of table row contents on tables on relationship page (#4974) - cli: handle missing files during metadata apply (close #5163) (#5170) +- docs: add page on scheduled triggers (close #4913) (#5141) - docs: add page on Relay schema (close #4912) (#5150) ## `v1.3.0-beta.2` diff --git a/docs/graphql/manual/index.rst b/docs/graphql/manual/index.rst index 3624a1d0667..cbc79f160da 100644 --- a/docs/graphql/manual/index.rst +++ b/docs/graphql/manual/index.rst @@ -27,6 +27,7 @@ The Hasura GraphQL engine lets you set up a GraphQL server and event triggers ov actions/index remote-schemas/index event-triggers/index + scheduled-triggers/index auth/index migrations/index Deploying diff --git a/docs/graphql/manual/scheduled-triggers/create-cron-trigger.rst b/docs/graphql/manual/scheduled-triggers/create-cron-trigger.rst new file mode 100644 index 00000000000..7112d56a6fc --- /dev/null +++ b/docs/graphql/manual/scheduled-triggers/create-cron-trigger.rst @@ -0,0 +1,175 @@ +.. meta:: + :description: Create a cron trigger with Hasura + :keywords: hasura, docs, cron trigger, scheduled trigger, create + +.. _create_cron_trigger: + +Creating a cron trigger +======================= + +.. contents:: Table of contents + :backlinks: none + :depth: 2 + :local: + +Introduction +------------ + +Cron triggers are used to reliably trigger HTTP endpoints to run custom business logic periodically based on a `cron schedule `__. For example, you can create a cron trigger to generate an end-of-day sales report every weekday at 10pm. + +To add a cron trigger, follow these steps: + +Step 1: Navigate to Cron Triggers +--------------------------------- + +- Go to the ``Events`` tab in your Hasura console. +- Click ``Cron Triggers``. +- Click ``Create``. + +.. thumbnail:: /img/graphql/manual/event-triggers/create-cron.png + :alt: Adding a cron trigger + :width: 1000px + +Step 2: Define the cron trigger +------------------------------- + +Let's define the cron trigger. + +.. rst-class:: api_tabs +.. tabs:: + + .. tab:: Console + + In the form opened by the above step, fill out the following fields: + + - **Name**: Create a name for the cron trigger. + - **Webhook**: Enter the HTTP endpoint that should be triggered. + - **Cron schedule**: Enter a schedule for the cron. You can use the link next to the field to help `build a cron expression `__, or use the ``Frequently used crons`` dropdown as a shortcut. Cron events are created based on the UTC timezone. + - **Payload**: The JSON payload which will be sent to the webhook. + + .. thumbnail:: /img/graphql/manual/event-triggers/define-cron-trigger.png + :alt: Defining a cron trigger + :width: 550px + + In this example, we're creating a cron trigger called ``eod_reports``, to trigger the webhook ``https://mywebhook.com/eod``. The cron schedule is set to ``0 22 * * 1-5``, which means "At 22:00 on every day-of-week from Monday through Friday" (you can check this `here `__). + + .. tab:: CLI + + You can define a cron trigger by adding it to the ``cron_triggers.yaml`` file inside the ``metadata`` directory: + + .. code-block:: yaml + + - name: eod_reports + webhook: https://mywebhook.com/eod + schedule: 0 22 * * 1-5 + include_in_metadata: true + payload: {} + + Apply the metadata by running: + + .. code-block:: yaml + + hasura metadata apply + + .. tab:: API + + You can define a cron trigger via the :ref:`create_cron_trigger metadata API `: + + .. code-block:: http + + POST /v1/query HTTP/1.1 + Content-Type: application/json + X-Hasura-Role: admin + + { + "type": "create_cron_trigger", + "args": { + "name": "eod_reports", + "webhook": "https://mywebhook.com/eod", + "schedule": "0 22 * * 1-5", + "payload": {}, + "include_in_metadata": true + } + } + +Step 3: Define advanced options (Optional) +------------------------------------------ + +If you like, you can also define the following values: + +- **Headers**: List of headers to be sent to the webhook. +- **Retry configuration**: In case the call to the webhook fails. +- **Include in metadata**: When set to true, the cron trigger will be included in the metadata and can be exported along with it. +- **Comment**: Custom description of the cron trigger. + +.. rst-class:: api_tabs +.. tabs:: + + .. tab:: Console + + Expand the ``Advanced`` section. + + .. thumbnail:: /img/graphql/manual/event-triggers/advanced-cron.png + :alt: Defining advanced options for a cron trigger + :width: 700px + + .. tab:: CLI + + You can define advanced options for a crone trigger when adding it to the ``cron_triggers.yaml`` file inside the ``metadata`` directory: + + .. code-block:: yaml + + - name: eod_reports + webhook: https://mywebhook.com/eod + schedule: 0 22 * * 1-5 + include_in_metadata: true + payload: {} + retry_conf: + num_retries: 3 + timeout_seconds: 120 + tolerance_seconds: 21675 + retry_interval_seconds: 12 + comment: This is a comment + + Apply the metadata by running: + + .. code-block:: yaml + + hasura metadata apply + + .. tab:: API + + You can define advanced options for a cron trigger when defining it via the :ref:`create_cron_trigger metadata API `: + + .. code-block:: http + + POST /v1/query HTTP/1.1 + Content-Type: application/json + X-Hasura-Role: admin + + { + "type": "create_cron_trigger", + "args": { + "name": "eod_reports", + "webhook": "https://mywebhook.com/eod", + "schedule": "0 22 * * 1-5", + "include_in_metadata": true, + "payload": {}, + "retry_conf": { + "num_retries": 3, + "timeout_seconds": 120, + "tolerance_seconds": 21675, + "retry_interval_seconds": 12 + }, + "comment": "sample_cron commment" + } + } + +Schedule & logs +--------------- + +Once you've created your cron trigger, you can see ``Pending events``, ``Processed events``, and ``Invocation logs`` in their respective tabs. + +.. thumbnail:: /img/graphql/manual/event-triggers/pending-cron.png + :alt: Schedule and logs for cron triggers + :width: 1200px diff --git a/docs/graphql/manual/scheduled-triggers/create-one-off-scheduled-event.rst b/docs/graphql/manual/scheduled-triggers/create-one-off-scheduled-event.rst new file mode 100644 index 00000000000..3cc1f825cb5 --- /dev/null +++ b/docs/graphql/manual/scheduled-triggers/create-one-off-scheduled-event.rst @@ -0,0 +1,133 @@ +.. meta:: + :description: Create a one-off scheduled event with Hasura + :keywords: hasura, docs, one off scheduled event, scheduled trigger, create + +.. _create_one_off_scheduled_event: + +Creating a one-off scheduled event +================================== + +.. contents:: Table of contents + :backlinks: none + :depth: 2 + :local: + +Introduction +------------ + +One-off scheduled events are used to reliably trigger an HTTP webhook to run custom business logic at a particular point in time. For example, you can create a scheduled event to send a reminder email two weeks after a user signs up. + +To add a one-off scheduled event, follow these steps: + +Step 1: Navigate to One-off Scheduled Events +-------------------------------------------- + +- Go to the ``Events`` tab in your Hasura console. +- Click ``One-off Scheduled Events``. +- Click ``Schedule an event``. + +.. thumbnail:: /img/graphql/manual/event-triggers/one-off.png + :alt: Adding a one-off scheduled event + :width: 900px + +Step 2: Define the scheduled event +---------------------------------- + +Define the following values for a scheduled event: + +- **Webhook**: Enter the HTTP endpoint that should be triggered. +- **Time**: Enter the time to trigger the event. +- **Payload**: The JSON payload which will be sent to the webhook. + +.. rst-class:: api_tabs +.. tabs:: + + .. tab:: Console + + In the form opened by the above step, fill out the following fields: + + .. thumbnail:: /img/graphql/manual/event-triggers/define-one-off-event.png + :alt: Defining the scheduled event + :width: 550px + + .. tab:: API + + You can define a scheduled event via the :ref:`create_scheduled_event metadata API `: + + .. code-block:: http + + POST /v1/query HTTP/1.1 + Content-Type: application/json + X-Hasura-Role: admin + + { + "type": "create_scheduled_event", + "args": { + "webhook": "https://send-email.com", + "schedule_at": "2022-06-18T18:45:00Z", + "payload": { "email": "bob@ross.com" } + } + } + +Step 3: Define advanced options (Optional) +------------------------------------------ + +If you like, you can also define advanced values: + +- **Headers**: List of headers to be sent to the webhook. +- **Retry configuration**: In case the call to the webhook fails. +- **Comment**: Custom description of the scheduled trigger. + +.. rst-class:: api_tabs +.. tabs:: + + .. tab:: Console + + Expand the ``Advanced`` section. + + .. thumbnail:: /img/graphql/manual/event-triggers/advanced-one-off.png + :alt: Defining advanced options for a scheduled event + :width: 700px + + .. tab:: API + + You can define advanced options when defining a scheduled event via the :ref:`create_scheduled_event metadata API `: + + .. code-block:: http + + POST /v1/query HTTP/1.1 + Content-Type: application/json + X-Hasura-Role: admin + + { + "type": "create_scheduled_event", + "args": { + "webhook": "https://send-email.com", + "schedule_at": "2022-06-18T18:45:00Z", + "payload": { + "email": "bob@ross.com" + }, + "headers": [ + { + "name": "key", + "value": "value" + } + ], + "retry_conf": { + "num_retries": 3, + "timeout_seconds": 120, + "tolerance_seconds": 21675, + "retry_interval_seconds": 12 + }, + "comment": "sample scheduled event comment" + } + } + +Schedule & logs +--------------- + +Once you've created your scheduled trigger, you can see ``Pending events``, ``Processed events``, and ``Invocation logs`` in their respective tabs. + +.. thumbnail:: /img/graphql/manual/event-triggers/pending-one-off.png + :alt: Schedule and logs for scheduled events + :width: 1200px diff --git a/docs/graphql/manual/scheduled-triggers/index.rst b/docs/graphql/manual/scheduled-triggers/index.rst new file mode 100644 index 00000000000..17f616022cf --- /dev/null +++ b/docs/graphql/manual/scheduled-triggers/index.rst @@ -0,0 +1,32 @@ +.. meta:: + :description: Create a scheduled trigger with Hasura + :keywords: hasura, docs, scheduled trigger + +.. _scheduled_triggers: + +Scheduled Triggers +================== + +.. contents:: Table of contents + :backlinks: none + :depth: 1 + :local: + +Scheduled triggers are used to execute custom business logic at a specific point in time. There are two types of timed events: cron-based or timestamp-based. + +.. admonition:: Supported from + + Scheduled triggers are supported from versions ``v1.3.0-beta.1`` and above. + +.. .. admonition:: Supported from + +.. Scheduled triggers are supported from versions ``v.1.3.0`` and above. + +**See:** + +.. toctree:: + :maxdepth: 2 + :titlesonly: + + create-cron-trigger + create-one-off-scheduled-event diff --git a/docs/img/graphql/manual/event-triggers/advanced-cron.png b/docs/img/graphql/manual/event-triggers/advanced-cron.png new file mode 100644 index 00000000000..57b5dec2c78 Binary files /dev/null and b/docs/img/graphql/manual/event-triggers/advanced-cron.png differ diff --git a/docs/img/graphql/manual/event-triggers/advanced-one-off.png b/docs/img/graphql/manual/event-triggers/advanced-one-off.png new file mode 100644 index 00000000000..9c066c46a8a Binary files /dev/null and b/docs/img/graphql/manual/event-triggers/advanced-one-off.png differ diff --git a/docs/img/graphql/manual/event-triggers/create-cron.png b/docs/img/graphql/manual/event-triggers/create-cron.png new file mode 100644 index 00000000000..c6d441a911d Binary files /dev/null and b/docs/img/graphql/manual/event-triggers/create-cron.png differ diff --git a/docs/img/graphql/manual/event-triggers/define-cron-trigger.png b/docs/img/graphql/manual/event-triggers/define-cron-trigger.png new file mode 100644 index 00000000000..2eb823f8f41 Binary files /dev/null and b/docs/img/graphql/manual/event-triggers/define-cron-trigger.png differ diff --git a/docs/img/graphql/manual/event-triggers/define-one-off-event.png b/docs/img/graphql/manual/event-triggers/define-one-off-event.png new file mode 100644 index 00000000000..ebc47d04e7d Binary files /dev/null and b/docs/img/graphql/manual/event-triggers/define-one-off-event.png differ diff --git a/docs/img/graphql/manual/event-triggers/one-off.png b/docs/img/graphql/manual/event-triggers/one-off.png new file mode 100644 index 00000000000..15409721c4f Binary files /dev/null and b/docs/img/graphql/manual/event-triggers/one-off.png differ diff --git a/docs/img/graphql/manual/event-triggers/pending-cron.png b/docs/img/graphql/manual/event-triggers/pending-cron.png new file mode 100644 index 00000000000..cc8991c85b7 Binary files /dev/null and b/docs/img/graphql/manual/event-triggers/pending-cron.png differ diff --git a/docs/img/graphql/manual/event-triggers/pending-one-off.png b/docs/img/graphql/manual/event-triggers/pending-one-off.png new file mode 100644 index 00000000000..2d254facb15 Binary files /dev/null and b/docs/img/graphql/manual/event-triggers/pending-one-off.png differ