[DOCS-14930] Update all documents to include reset logic. Created: 13/Nov/21  Updated: 29/Jan/24  Resolved: 29/Jan/24

Status: Closed
Project: Documentation
Component/s: Mobile Sync, Realm
Affects Version/s: None
Fix Version/s: None

Type: Task Priority: Major - P3
Reporter: Garrett Leonard (Inactive) Assignee: Unassigned
Resolution: Won't Do Votes: 0
Labels: request
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Participants:
Days since reply: 2 years, 11 weeks, 5 days ago
Epic Link: DOCSP-19536

 Description   

Multiple tickets that could have been prevented if we instructed customers to implement working reset logic from the beginning while making their first applications with Realm.

https://mongodb.lightning.force.com/lightning/r/Case/5002K00000zDKUUQA4/view
https://mongodb.lightning.force.com/lightning/r/Case/5002K00000zDHF1QAO/view

Two cases in the last few hours alone, and there are about a dozen others in the last few days.

We need to push and encourage the implementation of reset logic the same time they are implementing their sync logic in our documents.



 Comments   
Comment by Garrett Leonard (Inactive) [ 19/Nov/21 ]

Hello chris.bush caleb.thompson I want to apologize for the P1 earlier. I wasn't aware DOCSPs had a different ticketing protocol. We have had about 3 dozen customers in the past several months who did not have working reset logic and opened tickets that often required extended zoom calls.

There are several places throughout the Realm docs that cover Sync and Resync logic on the client side. By combining Client Reset Logic and Sync Logic into the same sections, we can walk customers through the process of establishing reset logic as a forethought rather than an afterthought. Since customers tend to expect that this functionality is automatic, adding this documentation should save them from the tribulations of discovering in production that it is not. Reach out to me if you would like to hear about some specific customers and their costs that have been associated with dealing with not having the logic in place. I’ve heard a number of stories during marathon zoom calls. (A side benefit is that it will also save Support cases, we expect!)

By combining the Client Reset Logic with the Client Sync Logic, we can bring the "common sense functionality" (using a customer’s wording), into fruition prior to potentially disastrous discoveries in production. Unfortunately, if no client reset logic is present in the application, their partial outage can become a complete outage when some of our remedies are attempted.

Changes proposed below are relatively simple. For example, you could combine all of the client reset pages with the client sync pages, and join the code on top of each other in our examples to make reset logic just as much a forethought as the sync logic is. In the example below, I have ensured that references, e.g. Cat versus Dog, are aligned.

Using React.Native Guides as examples:
https://docs.mongodb.com/realm/sdk/react-native/#std-label-react-native-intro
https://docs.mongodb.com/realm/sdk/react-native/advanced/client-reset/

var config = {
  schema: [Cat], // predefined schema
  sync: {
    user: app.currentUser,
    partitionValue: "MyPartitionValue",
  },
};
// Open a realm with a configuration object that has a SyncConfiguration
// A SyncConfiguration requires both a logged-in user and a partition value
let realm = await Realm.open(config);
 
// start a write transaction
let darukCat;
realm.write(() => {
  // get a cat from the database to update
  darukCat = realm.objects("Cat").filtered("name = 'Daruk")[0];
  // change the cat's name
  darukCat.name = "Daruk Goron";
}); // when the transaction completes, the cat's name is updated in the database
// and synced to the connected Realm App
 
let realm = await Realm.open(config);
function errorSync(_session, error) {
  if (realm) {
    if (error.name === "ClientReset") {
      const realmPath = "<Your Realm Path>";
 
      realm.close();
 
      console.log(`Error ${error.message}, need to reset ${realmPath}…`);
      Realm.App.Sync.initiateClientReset(app, realmPath); // pass your realm app instance, and realm path to initiateClientReset()
      console.log(`Creating backup from ${error.config.path}…`);
      // Move backup file to a known location for a restore
      fs.renameSync(error.config.path, realmPath + "~");
      // Discard the reference to the realm instance
      realm = null;
    } else {
      console.log(`Received error ${error.message}`);
    }
  }
}
var config = {
  schema: [CatSchema], // predefined schema
  sync: {
    user: app.currentUser,
    partitionValue: "MyPartitionValue",
    error: errorSync,
  },
};

Your team does amazing knowing the amount of materials that you have to write, draft, change. I’m very appreciative! The information overall that we have on both subjects is pretty good. It's just improving visibility and encouraging the customers to implement it all together.

Let me know if you would like me to test out any example code that you want to include in the documentation or ask me about any of the technical details. Find me on slack anytime.

Comment by Chris Bush [ 15/Nov/21 ]

We don't have access to the linked issues and can't see the details. Could you provide access or copy the details?

Generated at Thu Feb 08 08:11:33 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.