Powering recurring digests with Knock

In this guide, we'll create a simple recurring digest notification for our customers that will execute a digest every Monday at 9am to summarize information that the users might have missed in the past week.

To do so, we'll use the schedules API and the fetch function to build a powerful, flexible notification workflow that is driven by dynamic data from your service.

Creating your Knock workflow

We're going to create a Knock workflow named "Recurring digest" from the Knock dashboard. To do so, navigate to your Development environment and click the "Create workflow" button in the top right corner. We'll then be prompted to name the workflow and have a key generated, which will be autogenerated as recurring-digest from the name by default.

Next, let's configure our newly created workflow to do something. To do so we'll click the "Edit steps" button to be taken to the workflow builder which is where we can add steps to our workflow and configure the templates that will generate notifications.

Fetching data for our digest

In this digesting example, we'll use the workflow fetch function to retrieve information that we wish to digest as part of the notification. The fetch step will make a call per recipient to an HTTP endpoint to retrieve this information.

In our example, we'll implement this as a simple Node.JS server that returns some static digest information per recipient, but you can return any information from any HTTP endpoint to power your digest.

Next, we'll add a fetch function to our workflow, and configure the fetch function to hit the endpoint. We'll do this by adding a 'Fetch function' to the workflow and clicking the 'Edit request' button.

In this example, we're going to pass the current recipient's id as a parameter in the endpoint URL using liquid. We'll use ngrok to hit our local endpoint, but in production, we'd point this to a deployed, hosted service that's publically accessible.

When the fetch step is executed the JSON response returned from the HTTP endpoint will be merged into the current workflow run scope making all of that data accessible to be used in your notification templates.

Designing your notification template

The last step in building our workflow is to add a channel step to our Knock workflow to send a notification out. Here we'll send an email, but we could use any supported channel type in Knock, or even create a cross-channel digest notification if we wanted.

Once we've added our email channel step, we can edit the underlying template associated by clicking "Edit template." We'll add a markdown block to the email builder and we can copy in the template below:

Here we're using the items array that we returned from the fetch step to render each notification. Notice how each item corresponds to the data structure we're defining above in our node service.

We can also set some preview data in Knock to help with seeing what our email template will look like. To do so, click "Edit preview data" in the left hand variable pane and add the following JSON:

At this point, it's probably a good idea to run a test of our workflow using the test runner to execute an end-to-end workflow run for a single recipient by clicking "Run a test" in the top right corner of the workflow builder.

Finally, we'll need to Commit our workflow to the development environment by clicking the "Commit to development" button in the top right corner of the workflow page. We'll also need to activate our workflow before we can use it by marking the status as "Active."

Once we're satisfied with the email notification, we can move on to running the scheduled digest for our recipients.

Creating digest schedules

Finally, we'll want to create a recurring schedule for our users. To do so we'll use the Schedules API which lets us trigger a workflow for one or more recipients on a defined schedule.

Each schedule is defined per recipient, but the createSchedules method lets us create a schedule for up to 100 recipients at a time. The schedule defines which workflow to trigger, as well as the rules for when to repeat the schedule.

In our case, we'll create a weekly notification that goes out every Monday at 9am, for chris and sam.

Once our schedules are created, they will start running on the next occurrence date. We can even see these in the Knock dashboard under Workflows > Recurring digest > Schedules and see when the schedules will run next for our recipients.

Wrapping up

That's it! We just created our first recurring notification for our users that will run every Monday at 9am. If you want to think about extending this example you could consider:

• Adding more supported channel types for the notification. You could add an in-app notification or a Slack notification for your users.
• Making schedules configurable by your users. Because each schedule is per-user, you can easily make schedules configurable at the user level using the update schedule endpoint.
• Adding timezone support. Schedules natively support timezones per recipient, so we can easily allow our recurring digests to run at a specific time in the users timezone.