Define a Value¶

Overview¶

You can define a new Realm Value from the Realm UI or by importing an application directory that contains one or more Value configuration files. Select the tab below that corresponds to the method that you want to use.

Procedure¶

Realm UI
Realm CLI

1

Create a New Value¶

You can define a new Value for your application in the Realm UI. To navigate to the Value configuration screen, click Values & Secrets in the left navigation menu. Ensure that the Values tab is selected and then click Create New Value.

2

Name the Value¶

Enter a unique Value Name. This name is how you refer to the value in functions and rules.

Value Name Restrictions

Value names must not exceed 64 characters and may only contain ASCII letters, numbers, underscores, and hyphens. The first character must be a letter or number.

3

Define the Value¶

Specify the Value Type. You can define two different types of Value: plain text and secret.

Plain Text Value
Secret Value

A plain text value is a string, array, or object that you define manually using standard JSON syntax.

To define a plain text value, select the Plain Text radio button and then enter the value in the input box.

A secret value exposes a Secret for use in Functions and rules.

To reference an existing Secret, select the Secret radio button and then select the name of the Secret that the value should reference from the Secret Name dropdown.

Alternatively, you can create and reference a new Secret by entering the new Secret’s name in the Secret Name dropdown and then clicking Create. Enter the new Secret Value in the input box that appears.

The value secret selection dropdown in the UI

4

Save the Value¶

After you have named and defined the new Value, click Save. Once saved, you can immediately access the Value in Functions and rules.

1

Export Your Realm Application¶

To define a Value using realm-cli you need to export an application directory for your application.

You can export your application from the Import/Export App tab of the Deploy page in the Realm UI, or by running the following command from an authenticated instance of realm-cli:

copy

realm-cli export --app-id=<App ID>

2

Add a Value Configuration File¶

Each Value is defined in its own JSON file in the values subdirectory of your exported application. For example, a Value named myValue would be defined in the file /values/myValue.json.

Add a configuration file for the new Value to the values directory:

copy

touch values/<Value Name>.json

The configuration file should have the following general form:

copy

{
  "name": "<Value Name>",
  "from_secret": <boolean>,
  "value": <Stored JSON Value|Secret Name>
}

Field Description

name A unique name for the value. This name is how you refer to the value in functions and rules.

from_secret Default: false. If true, the Value exposes a Secret instead of a plain-text JSON value.

value

The stored data that Realm exposes when the Value is referenced.

If from_secret is false, value can be a standard JSON string, array, or object.

If from_secret is true, value is a string that contains the name of the Secret the value exposes.

3

Import Your Application Directory¶

Ensure that the Value configuration file is saved and then navigate to the root of your exported application directory. Log in to MongoDB Atlas with realm-cli:

copy

realm-cli login --api-key="<my api key>" --private-api-key="<my private api key>"

Once you’re logged in, import the directory:

copy

realm-cli import

Once the import completes, you can immediately begin to access the Value in rules and functions.

Summary¶

You can use the Realm UI or Realm CLI to create and define Realm Values.

← Values & Secrets Define a Secret →