Josman Pérez Expóstio

The aim of this tutorial is to learn how to use Custom Resolvers for complex use cases.

Realm Data Types

Realm GraphQL Demo: Custom Resolvers

Realm Series

## What is Realm?
  
Wondering what it's all about? Realm is an object-oriented data model database that will persist data on disk, doesn’t need an ORM, and lets you write less code with full offline capabilities… but Realm is also a fully-managed back-end service that helps you deliver best-in-class apps across Android, iOS, and Web.  
  
To leverage the full BaaS capabilities, Functions allow you to define and execute server-side logic for your application. You can call functions from your client applications as well as from other functions and in JSON expressions throughout Realm.  
  
Functions are written in modern JavaScript (ES6+) and execute in a serverless manner. When you call a function, you can dynamically access components of the current application as well as information about the request to execute the function and the logged-in user that sent the request.  
  
By default, Realm Functions have no Node.js modules available for import. If you would like to make use of any such modules, you can upload external dependencies to make them available to import into your Realm Functions.  
  
## Motivation 
  
This tutorial is born to show how we can create a retry mechanism for our functions. We have to keep in mind that triggers have their own internal automatic retry mechanism that ensures they are executed. However, functions lack such a mechanism. Realm functions are executed as HTTP requests, so it is our responsibility to create a mechanism to retry if they fail.  
  
Next, we will show how we can achieve this mechanism in a simple way that could be applied to any project.  
  
## Flow Diagram
  
The main basis of this mechanism will be based on states. In this way, we will be able to contemplate **four different states**. Thus, we will have:  
  
*   **0: Not tried**: Initial state. When creating a new event that will need to be processed, it will be assigned the initial status **0**.  
*   **1: Success**: Successful status. When an event is successfully executed through our function, it will be assigned this status so that it will not be necessary to retry again.  
*   **2: Failed**: Failed status. When, after executing an event, it results in an error, it will be necessary to retry and therefore it will be assigned a status **2 or failed**.  
*   **3: Error**: It is important to note that we cannot always retry. We must have a limit of retries. When this limit is exhausted, the status will change to **error or 3**.  
  
The algorithm that will define the passage between states will be the following:   
  
<img alt="Flow diagram that shows the algorithm behind the state control for events" src="https://miro.medium.com/max/1378/0*mitAXIBRT6nuYEYh" width="689" height="790" srcSet="https://miro.medium.com/max/552/0*mitAXIBRT6nuYEYh 276w, https://miro.medium.com/max/1104/0*mitAXIBRT6nuYEYh 552w, https://miro.medium.com/max/1280/0*mitAXIBRT6nuYEYh 640w, https://miro.medium.com/max/1378/0*mitAXIBRT6nuYEYh 689w" sizes="689px"/>  
  
Flow diagram  
  
## System Architecture
  
The system is based on two collections and a trigger. The trigger will be defined as a **database trigger** that will react each time there is an insert or update in a specific collection. The collection will keep track of the events that need to be processed. Each time this trigger is activated, the event is processed in a function linked to it. The function, when processing the event, may or may not fail, and we need to capture the failure to retry.  
  
When the function fails, the event state is updated in the event collection, and as the trigger reacts on inserts and updates, it will call the function again to reprocess the same.  
  
A maximum number of retries will be defined so that, once exhausted, the event will not be reprocessed and will be marked as an error in the **error** collection.  
  
## Sequence Diagram
  
The following diagram shows the three use cases contemplated for this scenario.  
  
## Use Case 1:
  
A new document is inserted in the collection of events to be processed. Its initial state is **0 (new)** and the number of retries is **0**. The trigger is activated and executes the function for this event. The function is executed successfully and the event status is updated to **1 (success).**  
  
## Use Case 2:
  
A new document is inserted into the collection of events to be processed. Its initial state is **0 (new)** and the number of retries is **0.** The trigger is activated and executes the function for this event. The function fails and the event status is updated to **2 (failed)** and the number of retries is increased to **1**.  
  
## Use Case 3:
  
A document is updated in the collection of events to be processed. Its initial status is **2 (failed)** and the number of retries is less than the maximum allowed. The trigger is activated and executes the function for this event. The function fails, the status remains at **2 (failed),** and the counter increases. If the counter for retries is greater than the maximum allowed, the event is sent to the **error** collection and deleted from the event collection.  
  
## Use Case 4:
  
A document is updated in the event collection to be processed. Its initial status is **2 (failed)** and the number of retries is less than the maximum allowed. The trigger is activated and executes the function for this event. The function is executed successfully, and the status changes to **1 (success).**  
  
<img alt="Use cases sequence diagram" src="https://miro.medium.com/max/1400/0*9juaBsYmfdWBuw27" width="700" height="708" srcSet="https://miro.medium.com/max/552/0*9juaBsYmfdWBuw27 276w, https://miro.medium.com/max/1104/0*9juaBsYmfdWBuw27 552w, https://miro.medium.com/max/1280/0*9juaBsYmfdWBuw27 640w, https://miro.medium.com/max/1400/0*9juaBsYmfdWBuw27 700w" sizes="700px"/>  
  
Sequence Diagram  
  
## Project Example Repository
  
We can find a simple project that illustrates the above [here](https://github.com/josmanperez/realmFunctionRetry).  
  
This project uses a trigger, **newEventsGenerator**, to generate a new document every two minutes through a cron job in the **Events** collection. This will simulate the creation of events to be processed.  
  
The trigger **eventsProcessor** will be in charge of processing the events inserted or updated in the **Events** collection. To simulate a failure, a function is used that generates a random number and returns whether it is divisible or not by two. In this way, both states can be simulated.  
  
```  
function getFailOrSuccess() { 
    // Random number between 1 and 10 
    const number = Math.floor(Math.random() * 10) + 1; 
    return ((number % 2) === 0);
}  
```  
  
## Conclusion
  
This tutorial illustrates in a simple way how we can create our own retry mechanism to increase the reliability of our application. Realm allows us to create our application completely serverless, and thanks to the Realm functions, we can define and execute the server-side logic for our application in the cloud.  
  
We can use the functions to handle low-latency, short-lived connection logic, and other server-side interactions. Functions are especially useful when we want to work with multiple services, behave dynamically based on the current user, or abstract the implementation details of our client applications.  
  
This retry mechanism we have just created will allow us to handle interaction with other services in a more robust way, letting us know that the action will be reattempted in case of failure.

This tutorial is born to show how we can create a retry mechanism for our functions. Realm Functions allow you to define and execute server-side logic for your application. You can call functions from your client applications as well as from other functions and in JSON expressions throughout Realm. 

Build Your Own Function Retry Mechanism with Realm

In a serverless application, one of the important features that we must implement for the success of our application is push notifications.

Realm allows us to have a complete push notification system directly in our [Services App](https://www.mongodb.com/atlas/app-services). To do this, we’ll make use of several components that we’ll explain here and develop in this tutorial. But first, let’s describe what our application does.

## Context

The application consists of a public list of books that are stored locally on the device thanks to [Atlas Device Sync](https://www.mongodb.com/atlas/app-services/device-sync), so we can add/delete or update the books directly in our Atlas collection and the changes will be reflected in our application.

We can also add as favorites any book from the list, although to do so, it’ll be necessary to register beforehand using an email and password. We will integrate email/password authentication in our application through the [Atlas App Services authentication providers](https://www.mongodb.com/docs/atlas/app-services/authentication/providers/).

The books, as they belong to a collection synchronized with Atlas Device Sync, will not only be stored persistently on our device but will also be synchronized with our user. This means that we can retrieve the list of favorites on any device where we register with our credentials. Changes made to our favorites using other devices are automatically synchronized.

![Example of the iOS app running on a device](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/books_28f8494f1d.gif)

### Firebase

The management of push notifications will be done through [Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging). In this way, we benefit from a single service to send notifications to iOS, web, and Android.

The configuration is similar to the one we would follow for any other application. The difference is that we will install the [firebase-admin](https://www.npmjs.com/package/firebase-admin) SDK in our Atlas App Services application.

### Triggers

The logic of this application for sending push notifications will be done through triggers. To do this, we will define two use cases:

1. A book has been added or deleted: For this, we will make use of the [topics in Firebase](https://firebase.google.com/docs/cloud-messaging/ios/topic-messaging), so when a user registers to receive this type of notification, they will receive a message every time a book is added/deleted from the general list of books.
2. A book added to my favorites list has been modified: We will make use of the Firebase tokens for each device. We relate the token received to the user so that when a book is modified, only the user/s that have it in their favorites list will receive the notification.

### Functions

The Atlas Triggers will have a function linked that will apply the logic for sending push notifications to the end devices. We will make use of the Firebase Admin SDK that we will install in our App Services App as a [dependency](https://www.mongodb.com/docs/atlas/app-services/functions/dependencies/).

## Overall application logic

This application will show how we can integrate push notifications with an iOS application developed in Swift. We will discuss how we have created each part with code, diagrams, and example usage.

At the end of this tutorial, you’ll find a link to a Github repository where you’ll find both the code of the iOS application as well as the code of the App Services application.

![How to request a FCMToken](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/How_to_request_a_FCM_Token_01c90dfa97.png)

When we start the application for the first time, we log in using [anonymous authentication](https://www.mongodb.com/docs/atlas/app-services/authentication/anonymous/), since to view the list of books, it’s not necessary to register using email/password. However, an anonymous user will still be created and saved in a collection Users in Atlas.

When we first access our application and enable push notifications, in our code, we register with Firebase. This will generate a [registration token](https://firebase.google.com/docs/cloud-messaging/concept-options#credentials), also known as FCMToken, that we will use later to send custom push notifications.

```swift
Messaging.messaging().token { token, error in
   if let error = error {
       print("Error fetching FCM registration token: \(error)")
   } else if let token = token {
       print("FCM registration token: \(token)")
       // Save token in user collection
       user.functions.updateFCMUserToken([AnyBSON(token), AnyBSON("add")], self.onCustomDataUpdated(result:realmError:))
   }
}
```

Once we obtain the FCM token, we will [call a function](https://www.mongodb.com/docs/realm/sdk/swift/examples/call-a-function/) through the Realm SDK to save this token in the user document corresponding to the logged-in user. Within the document, we have defined a token field that will be composed of an array of FCM tokens.

To do this, we will make use of the Firebase SDK and the `Messaging` method, so that we are notified every time the token changes or a new token is generated. In our Swift code, we will use this function to insert a new FCToken for our user.

```swift
Messaging.messaging().token { token, error in
    if let error = error {
        print("Error fetching FCM registration token: \(error)")
    } else if let token = token {
        print("FCM registration token: \(token)")
        // Save token in user collection
        user.functions.updateFCMUserToken([AnyBSON(token), AnyBSON("add")], self.onCustomDataUpdated(result:realmError:))
    }
}
```

In our App Services app, we must implement the logic of the `updateFCMUserToken` function that will store the token in our user document.

#### Function code in Atlas

```javascript
exports = function(FCMToken, operation) {

  const db = context.services.get("mongodb-atlas").db("product");
  const userData = db.collection("customUserData");
  
  if (operation === "add") {
    console.log("add");
    userData.updateOne({"userId": context.user.id},
    { "$addToSet": {
      "FCMToken": FCMToken
    }  
    }).then((doc) => {
      return {success: `User token updated`};
    }).catch(err => {
      return {error: `User ${context.user.id} not found`};
    });
  } else if (operation === "remove") {
    console.log("remove"); 
  } 
};
```

We have decided to save an array of tokens to be able to send a notification to each device that the same user has used to access the application.

The following is an example of a User document in the collection:

```JSON
{
 "_id": {
   "$oid": "626c213ece7819d62ebbfb99"
 },
 "color": "#1AA7ECFF",
 "fullImage": false,
 "userId": "6268246e3e0b17265d085866",
 "bookNotification": true,
 "FCMToken": [
   "as3SiBN0kBol1ITGdBqGS:APA91bERtZt-O-jEg6jMMCjPCfYdo1wmP9RbeATAXIQKQ3rfOqj1HFmETvdqm2MJHOhx2ZXqGJydtMWjHkaAD20A8OtqYWU3oiSg17vX_gh-19b85lP9S8bvd2TRsV3DqHnJP8k-t2WV",
   "e_Os41X5ikUMk9Kdg3-GGc:APA91bFzFnmAgAhbtbqXOwD6NLnDzfyOzYbG2E-d6mYOQKZ8qVOCxd7cmYo8X3JAFTuXZ0QUXKJ1bzSzDo3E0D00z3B4WFKD7Yqq9YaGGzf_XSUcCexDTM46bm4Ave6SWzbh62L4pCbS"
 ]
}
```

## Send notification to a topic

Firebase allows us to subscribe to a topic so that we can send a notification to all devices that have ever subscribed to it without the need to send the notification to specific device tokens.

In our application, once we have registered using an email and password, we can subscribe to receive notifications every time a new book is added or deleted.

![Setting view in the iOS app](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Settings_1136d1eb16.png)

When we activate this option, what happens is that we use the Firebase SDK to register in the topic books.

```swift
static let booksTopic = "books"

@IBAction func setBookPushNotification(_ sender: Any) {
 if booksNotificationBtn.isOn {
     Messaging.messaging().subscribe(toTopic: SettingsViewController.booksTopic)
     print("Subscribed to \(SettingsViewController.booksTopic)")
 } else {
     Messaging.messaging().unsubscribe(fromTopic: SettingsViewController.booksTopic)
     print("Unsubscribed to \(SettingsViewController.booksTopic)")
 }
}
```

### How does it work?

The logic we follow will be as below:

![How push notifications to topic works](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Push_Notifications_diagram_Send_to_topic_b517db3b91.jpg)

In our Atlas App Services App, we will have a [database trigger](https://www.mongodb.com/docs/atlas/app-services/triggers/database-triggers/) that will monitor the Books collection for any new inserts or deletes.

Upon the occurrence of either of these two operations, the linked function shall be executed and send a push notification to the “books” topic.

To configure this trigger, we’ll make use of two very important options:

* **Full Document**: This will allow us to receive the document created or modified in our change event. 
* **Document Pre-Image**: For delete operations, we will receive the document that was modified or deleted before your change event.

With these options, we can determine which changes have occurred and send a message using the title of the book to inform about the change. 

The configuration of the trigger in the App Services UI will be as follows:

![Screenshot of the trigger configuration in the Atlas App Services UI](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Trigger_for_topic_push_notification_bcbc380591.jpg)

The function linked to the trigger will determine whether the operation occurred as an `insert` or `delete` and send the push notification to the topic **books** with the title information.

Function logic:

```javascript
 const admin = require('firebase-admin');
 admin.initializeApp({
   credential: admin.credential.cert({
     projectId: context.values.get('projectId'),
     clientEmail: context.values.get('clientEmail'),
     privateKey: context.values.get('fcm_private_key_value').replace(/\\n/g, '\n'),
   }),
 });
 const topic = 'books';
 const message = {topic};
 if (changeEvent.operationType === 'insert') {
   const name = changeEvent.fullDocument.volumeInfo.title;
   const image = changeEvent.fullDocument.volumeInfo.imageLinks.smallThumbnail;
   message.notification = {
     body: `${name} has been added to the list`,
     title: 'New book added'
   };
   if (image !== undefined) {
     message.apns = {
       payload: {
         aps: {
           'mutable-content': 1
         }
       },
       fcm_options: {
         image
       }
     };
   }
 } else if (changeEvent.operationType === 'delete') {
   console.log(JSON.stringify(changeEvent));
   const name = changeEvent.fullDocumentBeforeChange.volumeInfo.title;
   message.notification = {
     body: `${name} has been deleted from the list`,
     title: 'Book deleted'
   };
 }
 admin.messaging().send(message)
   .then((response) => {
     // Response is a message ID string.
     console.log('Successfully sent message:', response);
     return true;
   })
   .catch((error) => {
     console.log('Error sending message:', error);
     return false;
 });
```

When someone adds a new book, everyone who opted-in for push notifications will receive the following:

![Screenshot of a push notification on a device](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Example_of_push_to_topic_on_device_aa8f65fd48.png)

## Send notification to a specific device

To send a notification to a specific device, the logic will be somewhat different.

For this use case, every time a book is updated, we will search if it belongs to the favourites list of any user. For those users who have such a book, we will send a notification to all registered tokens.

This will ensure that only users who have added the updated book to their favorites will receive a notification alerting them that there has been a change.

### How does it work?

![Diagram of sending push notifications to a specific list of users](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Diagram_of_sending_push_notifications_to_a_specific_list_of_users_51080e63c4.jpg)

For this part, we will need a database trigger that will monitor for updates operations on the books collection.

The configuration of this trigger is much simpler, as we only need to monitor the `updates` that occur in the book collection. 

The configuration of the trigger in our UI will be as follows:

![Screenshot of the trigger configuration in the Atlas App Services UI](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Trigger_for_checking_updates_on_book_collection_dcb9e145d0.jpg)

When such an operation occurs, we’ll check if there is any user who has added that book to their favorites list. If there is, we will create a new document in the ***pushNotifications*** collection.

This auxiliary collection is used to optimize the sending of push notifications and handle exceptions. It will even allow us to set up a monitoring system as well as retries.

Every time we send a notification, we’ll insert a document with the following:

1. The changes that occurred in the original document.
2. The FCM tokens of the recipient devices.
3. The date when the notification was registered.
4. A processed property to know if the notification has been sent.

Here’s an example of a push notification document:

```JSON
{
 "_id": {
   "$oid": "62a0da5d860040b7938eab87"
 },
 "token": [
"e_OpA2X6ikUMk9Kdg3-GGc:APA91bFzFnmAgAhbtbqXOwD6NLnDzfyOzYbG2E-d6mYOQKZ8qVOCxd7cmYo8X3JAFTuXZ0QUXKJ1bzSzDo3E0D00z3B4WFKD7Yqq9YaGGzf_XSUcCexDTM46bm4Ave6SWzbh62L4pCbS",
   "fQvffGBN2kBol1ITGdBqGS:APA91bERtZt-O-jEg6jMMCjPCfYdo1wmP9RbeATAXIQKQ3rfOqj1HFmETvdqm2MJHOhx2ZXqGJydtMWjHkaAD20A8OtqYWU3oiSg17vX_gh-19b85lP9S8bvd2TRsV3DqHnJP8k-t2WV"
 ],
 "date": {
   "$date": {
     "$numberLong": "1654708829678"
   }
 },
 "processed": true,
 "changes": {
   "volumeInfo": {
     "title": "Pacific on Linguistics",
     "publishedDate": "1964",
     "industryIdentifiers": [
       {
         "type": "OTHER",
         "identifier": "UOM:39015069017963"
       }
     ],
     "readingModes": {
       "text": false,
       "image": false
     },
     "categories": [
       "Linguistics"
     ],
     "imageLinks": {
       "smallThumbnail": "http://books.google.com/books/content?id=aCVZAAAAMAAJ&printsec=frontcover&img=1&zoom=5&source=gbs_api",
       "thumbnail": "http://books.google.com/books/content?id=aCVZAAAAMAAJ&printsec=frontcover&img=1&zoom=1&source=gbs_api"
     },
     "language": "en"
   }
 }
}
```

To process the notifications, we’ll have a database trigger that will monitor the ***pushNotifications*** collection, and each new document will send a notification to the tokens of the client devices.

#### Function logic

```javascript
exports = async function(changeEvent) {

 const admin = require('firebase-admin');
 const db = context.services.get('mongodb-atlas').db('product');

 const id = changeEvent.documentKey._id;

 const bookCollection = db.collection('book');
 const pushNotification = db.collection('pushNotification');

 admin.initializeApp({
   credential: admin.credential.cert({
     projectId: context.values.get('projectId'),
     clientEmail: context.values.get('clientEmail'),
     privateKey: context.values.get('fcm_private_key_value').replace(/\\n/g, '\n'),
   }),
 });

 const registrationToken = changeEvent.fullDocument.token;
 console.log(JSON.stringify(registrationToken));
 const title = changeEvent.fullDocument.changes.volumeInfo.title;
 const image = changeEvent.fullDocument.changes.volumeInfo.imageLinks.smallThumbnail;

 const message = {
   notification:{
     body: 'One of your favorites changed',
     title: `${title} changed`
   },
   tokens: registrationToken
 };

 if (image !== undefined) {
   message.apns = {
     payload: {
       aps: {
         'mutable-content': 1
       }
     },
     fcm_options: {
      image
     }
   };
 }

 // Send a message to the device corresponding to the provided
 // registration token.
 admin.messaging().sendMulticast(message)
   .then((response) => {
     // Response is a message ID string.
     console.log('Successfully sent message:', response);
     pushNotification.updateOne({'_id': BSON.ObjectId(`${id}`)},{
       "$set" : {
         processed: true
       }
     });
   })
   .catch((error) => {
     console.log('Error sending message:', error);
 });
};
```

Example of a push notification to a user:

![](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Screenshot_of_specific_push_notification_received_on_device_c650d5fae0.png)

## Repository

The complete code for both the App Services App as well as for the iOS application can be found in a [dedicated GitHub repository](https://github.com/josmanperez/BookRealmTutorial).

If you have found this tutorial useful, let me know so I can continue to add more information as well as step-by-step videos on how to do this.

And if you’re as excited about Atlas App Services as I am, create your [first free App](https://www.mongodb.com/atlas/app-services) today!

Use our Atlas App Services application to create a complete push notification system that fits our business logic.

Josman Pérez Expóstio

Content by Josman Pérez Expóstio

Realm GraphQL Demo: Custom Resolvers

Build Your Own Function Retry Mechanism with Realm

Push Notifications Using Atlas App Services & iOS Realm SDK