Atlas Device Sync Configuration Files

On this page

Partition-Based Sync Configuration

Flexible Sync Configuration
Type-Specific Roles
Default Roles

You can configure Atlas Device Sync for your application in the sync directory:

app/
└── sync/
    └── config.json

Partition-Based Sync Configuration

When you use Partition-Based Sync, your App Services app uses this Sync configuration:

sync/config.json

{
  "state": <"enabled" | "disabled">,
  "development_mode_enabled": <Boolean>,
  "service_name": "<Data Source Name>",
  "database_name": "<Development Mode Database Name>",
  "partition": {
    "key": "<Partition Key Field Name>",
    "type": "<Partition Key Type>",
    "permissions": {
      "read": { <Expression> },
      "write": { <Expression> }
    }
  },
  "last_disabled": <Number>,
  "client_max_offline_days": <Number>
}

Field	Description
`state` String	The current state of the sync protocol for the application. Valid Options: `"enabled"` `"disabled"`
`service_name` String	The name of the MongoDB data source to sync. You cannot use sync with a serverless instance or Federated database instance.
`development_mode_enabled` Boolean	If `true`, Development Mode is enabled for the application. While enabled, App Services automatically stores synced objects in a specific database (specified in `database_name`) and mirrors objects types in that database's collection schemas.
`database_name` String	The name of a database in the synced cluster where App Services stores data in Development Mode. App Services automatically generates a schema for each synced type and maps each object type to a collection within the database.
`partition.key` String	The field name of your app's partition key. This field must be defined in the schema for object types that you want to sync.
`partition.type` String	The value type of the partition key field. This must match the type defined in the object schema. Valid Options: `"string"` `"objectId"` `"long"`
`partition.permissions.read` Expression	An expression that evaluates to `true` when a user has permission to read objects in a partition. If the expression evaluates to `false`, App Services does not allow the user to read an object or its properties.
`partition.permissions.write` Expression	An expression that evaluates to `true` when a user has permission to write objects in a partition. If the expression evaluates to `false`, App Services does not allow the user to modify an object or its properties. Write permission requires read permission. A user cannot write to a document that they cannot read.
`last_disabled` Number	The date and time that sync was last paused or disabled, represented by the number of seconds since the Unix epoch (January 1, 1970, 00:00:00 UTC).
`client_max_offline_days` Number	Controls how long the backend compaction process waits before aggressively pruning metadata that some clients require to synchronize from an old version of a realm.

Flexible Sync Configuration

When you use Flexible Sync, your App uses this Sync configuration:

sync/config.json

{
  "type": "flexible",
  "development_mode_enabled": <Boolean>,
  "service_name": "<Data Source Name>",
  "database_name": "<Development Mode Database Name>",
  "state": <"enabled" | "disabled">,
  "permissions": {
    "rules": {
      "<Type Name>": [
        {
          "name": <String>,
          "applyWhen": { <Expression> },
          "read": <Expression>,
          "write": <Expression>,
          "fields": {
            "<Field Name>": {
              "read": <Boolean>,
              "write": <Boolean>,
              "fields": <Embedded Object Fields>
            }
          }
          "additional_fields": {
            "read": <Boolean>,
            "write": <Boolean>
          }
        }
      ]
    },
    "defaultRoles": [
      {
        "name": <String>,
        "applyWhen": { <Expression> },
        "read": <Expression>,
        "write": <Expression>
      }
    ]
  },
  "queryable_fields_names": [
    <Array of String Field Names>
  ]
}

Field

Description

type

String

The Sync Mode for the application.

Valid Options:

"flexible"

development_mode_enabled

Boolean

If true, Development Mode is enabled for the application. While enabled, App Services automatically stores synced objects in a specific database (specified in database_name) and mirrors objects types in that database's collection schemas.

service_name

String

The name of the Atlas cluster data source to sync. You cannot use sync with a serverless instance.

database_name

String

The name of a database in the synced cluster where App Services stores data in Development Mode. App Services automatically generates a schema for each synced type and maps each object type to a collection within the database.

state

String

The current state of the sync protocol for the application.

Valid Options:

"enabled"
"disabled"

permissions.rules

Object

An object that maps object type names to Type-Specific Roles.

{
  "<Type Name>": [ <Role>, ... ]
}

permissions.defaultRoles

Array<Object>

An array of Default Roles.

[ <Role>, ... ]

queryable_fields_names

Array<String>

The names of the fields that your client application can query to determine which data to synchronize.

last_disabled

Number

The date and time that sync was last paused or disabled, represented by the number of seconds since the Unix epoch (January 1, 1970, 00:00:00 UTC).

client_max_offline_days

Number

Controls how long the backend compaction process waits before aggressively pruning metadata that some clients require to synchronize from an old version of a realm.

Type-Specific Roles

The permissions.rules field maps object type names to sets of roles that apply specifically to each object type.

For more information, see Type-Specific Roles.

Tip

Roles are evaluated in order starting from the beginning of the array, so define the most specific roles first.

name
String
Required

The name of the role. You might use a descriptive name, such as "adminReadWrite" or "employeeReadOnly", to make it easier to understand the rules.

applyWhen
Expression
Required

An expression that evaluates to true when the role applies to the user.

Example

The following expression defines a role that applies when a user's custom data contains a field named isGlobalAdmin with the value set to true:

{
  "%%user.custom_data.isGlobalAdmin": true
}

read
Expression
Optional

An expression that determines whether or not the user can read data. If the expression evaluates to true, the user has permission to read objects of this type. If false, the user cannot read an object or any of its properties.

write
Expression
Optional

An expression that determines whether or not the user can write data. If the expression evaluates to true, the user has permission to write objects of this type. If false, the user cannot write an object or any of its properties.

Write permission requires read permission. A user cannot write to a document that they cannot read.

fields
Object
Optional

An object that defines read and write permissions for specific fields. A field-level permission definition has the following form:

"fields": {
  "<Field Name>": {
    "read": <Boolean>,
    "write": <Boolean>,
    "fields": <Embedded Object Fields>
  }
}

fields.<Field Name>.read
Boolean
Required

If true, the role has permission to read this field. If false, the user cannot read the field.

fields.<Field Name>.write
Boolean
Required

If true, the role has permission to write this field. If false, the user cannot write the field.

Write permission requires read permission. A user cannot write to a field that they cannot read.

fields.<Field Name>.fields
Object
Optional

Nested field-level permissions for an embedded object.

Example

The following role defines read and write permissions for the embedded field address.street:

{
  "fields": {
    "address": {
      "fields": {
        "street": {
          "read": true,
          "write": true
        }
      }
    }
  }
}

additional_fields
Object
Optional

An object that defines read and write permissions for all fields that do not have any permissions defined in fields. A field-level permission definition for generic fields has the following form:

"additional_fields": {
  "read": <Boolean>,
  "write": <Boolean>
}

additional_fields.read
Boolean
Required

If true, the role has permission to read any field that isn't defined in fields. If false, the user can only read a field with specific permissions.

additional_fields.write
Boolean
Required

If true, the role has permission to write any field that isn't defined in fields. If false, the user can only write a field with specific permissions.

Write permission requires read permission. A user cannot write to a field that they cannot read.

Default Roles

The permissions.defaultRoles field contains an array of generic roles that apply to all object types. Type-specific roles defined in the rules property always take precedence over default roles. A user may be assigned a default role when type-specific roles do not apply or are not defined.

For more information, see Default Roles.

Tip

Roles are evaluated in order starting from the beginning of the array, so define the most specific roles first.

`name` String Required	The name of the role in the `defaultRoles` array. You might use a descriptive name to make it easier to parse the roles, such as "adminReadWrite" or "employeeReadOnly".
`applyWhen` Expression Required	An expression that evaluates to `true` when the role should be applied. An example might be `{"%%user.custom_data.isGlobalAdmin": true}`. This reads the value of the `isGlobalAdmin` bool from the user's custom data, and applies the role when the value of this bool is `true`.
`read` Expression Optional	An expression that determines whether or not the user can read data. If the expression evaluates to `true`, the user has permission to read objects. If `false`, the user cannot read an object or any of its properties.
`write` Expression Optional	An expression that determines whether or not the user can write data. If the expression evaluates to `true`, the user has permission to write objects. If `false`, the user cannot write an object or any of its properties. Write permission requires read permission. A user cannot write to a document that they cannot read.

← MongoDB Data Source Configuration Files Function Configuration Files →