env Requests

Environment variables are key-value pairs that can be set on the Notecard, or on a device, project and fleet in Notehub.

note

The Hierarchy of Environment Variables

Environment variables can be defined in a number of locations, from the Notecard, to Notehub device settings, the device's Fleet, and the Notehub project. Variables set at different levels of this hierarchy can override one another. When obtaining an environment variable, the Notecard uses the following priority order, where the first matched result is returned:

  1. The local value.
  2. The value set in Notehub directly on Notehub's record for the Device.
  3. The value set in Notehub on a Fleet to which the Device belongs.
  4. The value set in Notehub on the Project to which the Device belongs.
  5. The default value defined with the env.default request.

env.default

Used by the Notecard host to specify a default value for an environment variable until that variable is overridden by a device, project or fleet-wide setting at Notehub.

Arguments

name

string

The name of the environment variable (case-insensitive).

text

string (optional)

The value of the variable. Pass "" or omit from the request to delete it.

      {
  "req": "env.default",
  "name": "monitor-pump",
  "text": "on"
}
      J *req = NoteNewRequest("env.default");
JAddStringToObject(req, "name", "monitor-pump");
JAddStringToObject(req, "text", "on");

NoteRequest(req);
      req = {"req": "env.default"}
req["name"] = "monitor-pump"
req["text"] = "on"
card.Transaction(req)
        {
  "req": "env.default",
  "name": "monitor-pump"
}
        J *req = NoteNewRequest("env.default");
JAddStringToObject(req, "name", "monitor-pump");

NoteRequest(req);
        req = {"req": "env.default"}
req["name"] = "monitor-pump"
card.Transaction(req)
        Response Members
        None: an empty object {} means success.

        env.get

        Returns a single environment variable, or all variables according to precedence rules.

        Arguments

        name

        string (optional)

        The name of the environment variable (case-insensitive). Omit to return all environment variables known to the Notecard.

        names (Added in v3.4.1)

        Array (optional)

        An list of one or more variables to retrieve, by name (case-insensitive).

        time (Added in v3.4.1)

        UNIX Epoch time (optional)

        Request a modified environment variable or variables from the Notecard, but only if modified after the time provided.

            {
  "req": "env.get",
  "name": "monitor-pump-one"
}
            J *req = NoteNewRequest("env.get");
JAddStringToObject(req, "name", "monitor-pump-one");

NoteRequest(req);
            req = {"req": "env.get"}
req["name"] = "monitor-pump-one"
rsp = card.Transaction(req)
              {
  "req": "env.get",
  "name": "monitor-pump-one",
  "time": "1656315835"
}
              J *req = NoteNewRequest("env.get");
JAddStringToObject(req, "name", "monitor-pump-one");
JAddNumberToObject(req, "time", 1656315835);

NoteRequest(req);
              req = {"req": "env.get"}
req["name"] = "monitor-pump-one"
req["time"] = 1656315835
rsp = card.Transaction(req)
                {
  "req": "env.get",
  "names": ["monitor-pump-one", "monitor-pump-two"]
}
                J *req = NoteNewRequest("env.get");

J *names = JAddArrayToObject(req, "names");
JAddItemToArray(names, JCreateString("monitor-pump-one"));
JAddItemToArray(names, JCreateString("monitor-pump-two"));

NoteRequest(req);
                req = {"req": "env.get"}
req["names"] = ["monitor-pump-one","monitor-pump-two"]
rsp = card.Transaction(req)
                  {
  "req": "env.get"
}
                  J *req = NoteNewRequest("env.get");

NoteRequest(req);
                  req = {"req": "env.get"}
rsp = card.Transaction(req)
                  Response Members

                  text

                  string

                  If a name was specified, the value of the environment variable.

                  body

                  JSON object

                  If a name was not specified, an object with name and value pairs for all environment variables.

                  time (Added v3.4.1.)

                  UNIX Epoch time

                  The time of the Notecard variable or variables change.

                      {
  "text": "on",
  "time": 1656315835
}
                        {
  "err": "environment hasn't been modified {env-not-modified}"
}
                          {
  "body": {
    "monitor-pump-one": "on",
    "monitor-pump-two": "off"
  },
  "time": 1656315835
}
                            {
  "body": {
    "monitor-pump-one": "on",
    "monitor-pump-two": "off",
    "monitor-pump-three": "on"
  },
  "time": 1656315835
}

                            env.modified

                            Get the time of the update to any environment variable managed by the Notecard.

                            Arguments

                            time (Added in v3.4.1)

                            UNIX Epoch time (optional)

                            Request whether the Notecard has detected an environment variable change since a known epoch time.

                                {
  "req": "env.modified"
}
                                J *req = NoteNewRequest("env.modified");

NoteRequest(req);
                                req = {"req": "env.modified"}
rsp = card.Transaction(req)
                                Response Members

                                time

                                UNIX Epoch time

                                Timestamp indicating the last time any environment variable was changed on the device.

                                Example Response
                                {
  "time": 1605814493
}
                                More information:

                                env.set

                                Sets a local environment variable on the Notecard. Local environment variables cannot be overridden by a Notehub variable of any scope.

                                Arguments

                                name

                                string

                                The name of the environment variable (case-insensitive).

                                text

                                string (optional)

                                The value of the variable. Pass "" or omit from the request to delete it.

                                    {
  "req": "env.set",
  "name": "monitor-pump",
  "text": "on"
}
                                    J *req = NoteNewRequest("env.set");
JAddStringToObject(req, "name", "monitor-pump");
JAddStringToObject(req, "text", "on");

NoteRequest(req);
                                    req = {"req": "env.set"}
req["name"] = "monitor-pump"
req["text"] = "on"
card.Transaction(req)
                                      {
  "req": "env.set",
  "name": "monitor-pump"
}
                                      J *req = NoteNewRequest("env.set");
JAddStringToObject(req, "name", "monitor-pump");

NoteRequest(req);
                                      req = {"req": "env.set"}
req["name"] = "monitor-pump"
card.Transaction(req)
                                      Response Members

                                      time (Added v3.4.1.)

                                      UNIX Epoch time

                                      The logged time of the variable change.

                                      More information: