Cancel or Overwrite a Timer

Capella Operational

Create, cancel, and overwrite Timers.

The OnUpdate JavaScript handler listens to mutations or data changes within a specified source collection. When you create or modify data in the source collection, the Eventing Function executes its JavaScript code.

The Timer callback function relies on a control document which, if mutated, controls whether a Timer is created, cancelled, or overwritten.

This page contains the following:

An example where a control document is created or mutated, which creates a Timer. This Timer fires every 60 seconds and writes a document to another collection. The original document in the source collection does not change.
An example where a control document is mutated, which cancels any existing Timer with a reference that matches the control document’s meta.id.
An example where a control document is mutated, which overwrites any existing Timer with a reference that matches the control document’s meta.id. This is similar to cancelling a Timer that already exists, and then creating a new Timer that fires 60 seconds after it has been overwritten.

Prerequisites

Before trying out the examples on this page, you must first:

Create two buckets called bulk and rr100 with a minimum size of 100MB.
Inside the bulk bucket, create two keyspaces called bulk.data.source and bulk.data.target.
Inside the rr100 bucket, create one keyspace called rr100.eventing.metadata.

For more information about creating buckets, scopes, and collections, see Manage Buckets.

Do not add, modify, or delete documents in the Eventing storage keyspace rr100.eventing.metadata while your Eventing Functions are in a deployed state.

Setup

Before following the examples on this page, you must set up a control document and an Eventing Function.

Create the Control Document

To create the control document:

Go to Data Tools Documents.
Select the keyspace bulk.data.source in the Get documents from list.
Click Create Document.
In the Document ID field, enter type_of_interest::1.

Replace the JSON text with the following:

{
  "type": "type_of_interest",
  "id": 1,
  "needed_condition": false,
  "cancel_timer": false,
  "overwrite_timer": false,
  "a_number": 1
}

Click Save to create the document.

Create an Eventing Function

To create a new Eventing Function:

Go to Data Tools Eventing.
Click Add Function.
In the Settings page, enter the following Function settings:
- cancel_overwrite_timer under Name.
- Create, cancel, and overwrite Timers. under Description.
- The keyspace bulk.data.source under Listen to Location.
- The keyspace rr100.eventing.metadata under Eventing Storage.
Click Next.
In the Bindings page, click Add Binding and create the following binding:
- Select Bucket.
- Enter tgt_col as the Alias Name.
- Enter the keyspace bulk.data.target under Bucket, Scope, and Collection.
- Select Read and Write under Permission.
Click Next.

In the code editor, replace the placeholder JavaScript code with the following code sample:

function DocTimerCallback(context) {
   log('From DocTimerCallback: timer fired', context);

   // Creates a new document in another collection
   tgt_col[context.docId] = context; // upserts the context as our new document
}

function OnUpdate(doc,meta) {
   // Filters mutations of interest
   if (doc.type != 'type_of_interest') return;

   // Looks at key conditions to decide what to do
   if (doc.needed_condition === true && doc.cancel_timer === false) {
       if (doc.overwrite_timer === true) {
         log('From OnUpdate: overwriting timer with same reference', meta.id);
       } else {
         log('From OnUpdate: creating timer', meta.id);
       }
       // Creates a timestamp 60 seconds from now
       var oneMinuteFromNow = new Date(); // Gets current time & add 60 seconds to it
       oneMinuteFromNow.setSeconds(oneMinuteFromNow.getSeconds() + 60);

       // Creates a document to use as the context
       var context = {docId : meta.id, random_text : "arbitrary text", "tmr_time_to_fire": oneMinuteFromNow};
       createTimer(DocTimerCallback, oneMinuteFromNow, meta.id, context);
    }
    if (doc.cancel_timer === true && doc.overwrite_timer === false) {
       // Cancels an existing timer (if it is active) by reference meta.id
       if (cancelTimer(DocTimerCallback, meta.id)) {
           log('From OnUpdate: cancel request, timer was canceled',meta.id);
       } else {
           log('From OnUpdate: cancel request, no such timer may have fired',meta.id);
       }
    }
    if (doc.cancel_timer === true && doc.overwrite_timer === true) {
        log('From OnUpdate: both cancel and overwrite, will ignore',meta.id);
    }
}

Click Create function to create your Eventing Function.

When a change happens to the data inside the source collection, the OnUpdate handler targets the control document by ignoring all documents that do not have a doc.type of type_of_interest. It then uses the fields needed_condition, cancel_timer, and overwrite_timer to determine which action to take:

If needed_condition is true but both cancel_timer and overwrite_timer are false, the Eventing Function creates a Timer that fires 60 seconds into the future.
If both needed_condition and cancel_timer are true, the Eventing Function cancels the existing Timer.
If both needed_condition and overwrite_timer are true, the Eventing Function overwrites the existing Timer with a new Timer that fires 60 seconds into the future.
If both cancel_timer and overwrite_timer are true, the Eventing Function throws an error and nothing happens.

When a Timer created by the Eventing Function fires, the callback DocTimerCallback executes and writes a new document in the target collection with the same key as the document in the source collection.

Deploy the Eventing Function

Deploy your Eventing Function:

Go to Data Tools Eventing.
Click More Options (⋮) next to cancel_overwrite_timer.
Click Deploy to deploy your Function.

After it’s deployed, the Eventing Function executes on all existing documents and any documents you create in the future.

Example: Create a Timer and Allow the Timer to Fire

This example walks you through how to create a Timer and have the Timer fire.

Edit the Control Document

To edit the control document:

Go to Data Tools Documents.
Select the keyspace bulk.data.source in the Get documents from list.
Click the control document type_of_interest::1 to open the Edit Document dialog.

Change needed_condition to true:

{
  "type": "type_of_interest",
  "id": 1,
  "needed_condition": true,
  "cancel_timer": false,
  "overwrite_timer": false,
  "a_number": 1
}

Click Save to create a mutation.

The document mutation causes the Eventing Function to create a Timer.

Check the Eventing Function Log

To check the Eventing Function log:

Go to Data Tools Eventing.
Click the Log icon next to the cancel_overwrite_timer Eventing Function. You should see the line "From OnUpdate: creating timer" "type_of_interest::1" in the debug log.
Wait a few minutes and click the Log icon again. The Timer should have fired and executed the DocTimerCallback callback, and you should see the line "From DocTimerCallback: timer fired" {"docId":"type_of_interest::1 ","random_text":"arbitrary text","tmr_time_to_fire":"2022-05-10T23:07:54.226Z"} in the debug log.

Check the Results in the Target Collection

To check that a new document has been created in the target collection:

Go to Data Tools Documents.
Select the keyspace bulk.data.target in the Get documents from list.
Click type_of_interest::1 to open the Edit Document dialog. The JSON document includes data written by the Timer’s callback.
```
{
  "docId": "type_of_interest::1",
  "random_text": "arbitrary text",
  "tmr_time_to_fire": "2022-05-10T23:07:54.226Z"
}
```
Close the Edit Document dialog.
Click the Delete icon next to type_of_interest::1.
In the Delete Document dialog, enter delete and click Delete document.

Example: Create a Timer and Cancel the Timer

This example walks you through how to create a Timer and cancel the Timer.

Edit the Control Document

To edit the control document:

Go to Data Tools Documents.
Select the keyspace bulk.data.source in the Get documents from list.
Click the control document type_of_interest::1 to open the Edit Document dialog.

Change a_number to 2:

{
  "type": "type_of_interest",
  "id": 1,
  "needed_condition": true,
  "cancel_timer": false,
  "overwrite_timer": false,
  "a_number": 2
}

Click Save to create a mutation.

The document mutation causes the Eventing Function to create a Timer.

Check the Eventing Function Log

To check the Eventing Function log:

Go to Data Tools Eventing.
Click the Log icon next to the cancel_overwrite_timer Eventing Function. You should see the line "From OnUpdate: creating timer" "type_of_interest::1" in the debug log.

Edit the Control Document Again

To edit the control document:

Go to Data Tools Documents.
Select the keyspace bulk.data.source in the Get documents from list.
Click the control document type_of_interest::1 to open the Edit Document dialog.

Change cancel_timer to true:

{
  "type": "type_of_interest",
  "id": 1,
  "needed_condition": true,
  "cancel_timer": true,
  "overwrite_timer": false,
  "a_number": 2
}

Click Save to create a mutation.

Check the Eventing Function Log Again

To check the Eventing Function log:

Go to Data Tools Eventing.
Click the Log icon next to the cancel_overwrite_timer Eventing Function. You should see the line "From OnUpdate: cancel request, timer was canceled" "type_of_interest::1" in the debug log.

The Timer has been cancelled and did not fire.

Example: Create a Timer and Overwrite the Timer

This example walks you through how to create a Timer and overwrite the Timer.

Edit the Control Document

To edit the control document:

Go to Data Tools Documents.
Select the keyspace bulk.data.source in the Get documents from list.
Click the control document type_of_interest::1 to open the Edit Document dialog.

Change cancel_timer to false:

{
  "type": "type_of_interest",
  "id": 1,
  "needed_condition": true,
  "cancel_timer": false,
  "overwrite_timer": false,
  "a_number": 2
}

Click Save to create a mutation.

The document mutation causes the Eventing Function to create a Timer.

Check the Eventing Function Log

To check the Eventing Function log:

Go to Data Tools Eventing.
Click the Log icon next to the cancel_overwrite_timer Eventing Function. You should see the line "From OnUpdate: creating timer" "type_of_interest::1" in the debug log.

Edit the Control Document Again

To edit the control document:

Go to Data Tools Documents.
Select the keyspace bulk.data.source in the Get documents from list.
Click the control document type_of_interest::1 to open the Edit Document dialog.

Change overwrite_timer to true:

{
  "type": "type_of_interest",
  "id": 1,
  "needed_condition": true,
  "cancel_timer": true,
  "overwrite_timer": true,
  "a_number": 2
}

Click Save to create a mutation.

Check the Eventing Function Log Again

To check the Eventing Function log:

Go to Data Tools Eventing.
Click the Log icon next to the cancel_overwrite_timer Eventing Function. You should see the line "From OnUpdate: overwriting timer with same reference" "type_of_interest::1" in the debug log.
Wait a few minutes and click the Log icon again. The Timer should have fired and executed the "From DocTimerCallback: timer fired" {"docId":"type_of_interest::1","random_text":"arbitrary text","tmr_time_to_fire":"2022-05-10T23:13:57.125Z"} in the debug log.

Check the Results in the Target Collection

To check that a new document has been created in the target collection:

Go to Data Tools Documents.
Select the keyspace bulk.data.target in the Get documents from list.

Click type_of_interest::1 to open the Edit Document dialog. The JSON document includes data written by the Timer’s callback.

{
  "docId": "type_of_interest::1 ",
  "random_text": "arbitrary text",
  "tmr_time_to_fire": "2022-05-10T23:13:57.125Z"
}

Close the Edit Document dialog.
Click the Delete icon next to type_of_interest::1.
In the Delete Document dialog, enter delete and click Delete document.