Version: 1.x

Automator Config Reference

The automatorConfig.json file is a JSON file that contains the configuration scheduling studies in Automator.

The file is usually located in the config directory of the Automator installation.

Example File

Here is an example file without content, which you can use as a template for filling out:

{
  "$schema": "https://aveq.info/jsonschema/AutomatorConfigV1.json",
  "version": 1,
  "registrationKey": "",
  "globalScheduleSettings": {
    "cronLogFile": "$HOME/logs/surfmeter-automator.log",
    "options": {},
    "env": {},
  },
  "studySchedules": [
    // (1)
  ],
  "publicConfigFile": "",
  "globalUpdateSettings": {
    "cronLogFile": "$HOME/logs/surfmeter-automator.update.log",
    "env": {},
  }
}

This is where you should specify the schedule of each study. See Schedule Entries for more information.

The $schema property is optional, but it is recommended to include it for better validation in some editors.

Now let's go through the different sections of the config file.

Properties

Root Properties

These are the root items of the config file.

Property	Value	Description
`version`	1	Internal version. Do not change this!
`revision`	`string` (optional)	The revision of the config file. Can be a Git hash, a date, or anything else that makes sense for version control.
`registrationKey`	`string` (optional)	The key with which to register the app automatically
`publicConfigFile`	`string` (optional)	Path to the default public config file to load, relative to the config directory itself
`studySchedules`	`array` of Schedule Entries (optional)	A list of schedules mapping studies from the public config to a cron schedule
`updates.automator`	Update Settings (optional)	Pulling updates to the library itself
`updates.config`	Update Settings (optional)	Pulling updates to this config file
`updates.extension`	Update Settings (optional)	Pulling updates to the extension source
`globalScheduleSettings`	Global Schedule Settings (optional)	Global settings for all schedules
`globalUpdateSettings`	Global Update Settings (optional)	Global settings for all updates

Schedule Entries

Schedule entries are the main way to configure Automator. They are used to map studies from the public config to a cron schedule.

What is cron?

Cron is a time-based job scheduler that is used to run commands at specific times. It is used by Automator to schedule the measurements. It is a very powerful tool, but it can be a bit confusing to get started with. If you are new to cron, we recommend reading this guide to get started.

Regular Schedule Entry

A regular schedule entry is a simple, static mapping of a study ID from the public config to a cron schedule.

Property	Value	Description
`id`	`string`	An internal ID. This must be unique across all schedules.
`studyId`	`string`, or `array`	The study ID to launch, or an `array` in case of parallel studies
`cronSchedule`	`string`	The schedule according to which to run the measurements. This uses cron format (e.g. `* * * * *`).
`cronLogFile`	`string` (optional)	Write the cron output to a local logfile. If you leave this out, the output will be logged via cron, or, in Docker, forwarded to the container logs
`description`	`string` (optional)	A description of the study schedule
`cmdSuffix`	`array` (optional)	Command-line arguments to append to the Automator command. Deprecated, please use 'options' instead.
`options`	`object` (optional)	Command-line options to append to the Automator command. These correspond to the general options and specific options for the `startStudy` command.
`env`	`object` (optional)	Pass custom environment variables when launching Automator

Tip: Variable Expansions

You can use the $HOME and $TMP as variables wherever a cron log file is specified, and they will be expanded automatically during loading of the schedule.

Examples

Example 1
Example 2
Example 3

This runs a YouTube study every 5 minutes:

{
    "id": "STUDY_YOUTUBE",
    "studyId": "STUDY_YOUTUBE",
    "description": "Runs a YouTube study every 5 minutes",
    "cronSchedule": "*/5 * * * *"
}

Note

The id and studyId properties are the same in this example, but they don't have to be. The id is an internal ID that is used to identify the schedule, while the studyId is the ID of the study in the public config.

This runs a YouTube study every 5 minutes, with tcpdump enabled. The tcpdump files will be written to /tmp. All options are passed to the Automator command. You can pass anything that is valid per our command and options documentation.

{
    "id": "STUDY_YOUTUBE",
    "studyId": "STUDY_YOUTUBE",
    "cronSchedule": "*/5 * * * *",
    "options": {
        "enableTcpDump": true,
        "tcpDumpDir": "/tmp"
    }
}

This runs a YouTube study every 5 minutes, outputting the cron log to a file and setting a the log level environment variable to debug (to print more messages):

{
    "id": "STUDY_YOUTUBE",
    "studyId": "STUDY_YOUTUBE",
    "description": "Runs a YouTube study every 5 minutes, with other options",
    "cronSchedule": "*/5 * * * *",
    "cronLogFile": "/tmp/cron.log",
    "env": {
        "LOG_LEVEL": "debug"
    }
}

Parameterized Schedule Entry

A parameterized schedule entry is a mapping of a study to a cron schedule, but with parameter replacements that are applied to the study ID before it is scheduled. This allows you to create random measurements, or to schedule a study multiple times with different parameters.

All the properties from the regular schedule entry apply. Here are the additional properties:

Property	Value	Description
`studyIdReference`	`string`	The study ID with the replacement variables, e.g. `STUDY_${type}_${n}`
`studyIdVariables`	`object`	A map of params to replace, each key being a replacement variable, and each value being a Replacement Specification

Replacement Specification

A replacement specification is a JSON object that specifies how to replace a variable in the study ID. The following types are supported:

randomInt: A random integer between min and max, inclusive

For example, this runs one of 10 different YouTube studies every 5 minutes — assuming you have STUDY_YOUTUBE_1 through STUDY_YOUTUBE_10 defined in your public config:

{
    "id": "STUDY_YOUTUBE_RANDOM",
    "studyIdReference": "STUDY_YOUTUBE_${n}",
    "studyIdVariables": {
        "n": {
            "type": "randomInt",
            "min": 1,
            "max": 10
        }
    },
    "description": "Runs a random YouTube study every 5 minutes",
    "cronSchedule": "*/5 * * * *"
}

Global Schedule Settings

These apply to all schedule settings. They are optional. When an individual schedule entry specifies a property, it overrides the global setting.

Property	Value	Description
`cronLogFile`	`string` (optional)	Write the cron output to a local logfile. If you leave this out, the output will be logged via cron, or, in Docker, forwarded to the container logs
`cmdSuffix`	`array` (optional)	Command-line arguments to append to the Automator command. Deprecated, please use 'options' instead.
`options`	`object` (optional)	Command-line options to append to the Automator command. These correspond to the general options and specific options for the `startStudy` command.
`env`	`object` (optional)	Pass custom environment variables when launching Automator
`randomOffset`	`integer` (optional)	A random offset where x is in minutes, which will be applied to all scheduled times during loading (the random number will be chosen in the interval `[0, x]`).

Update Settings

These specify how to pull updates to the library itself, the config file, and the extension. For more info see the updating section of Automator.

Property	Value	Description
`cronSchedule`	`string`	The schedule according to which to run the updates. This uses cron format (e.g. `* * * * *`).
`cronLogFile`	`string` (optional)	Write the cron output to a local logfile. If you leave this out, the output will be logged via cron, or, in Docker, forwarded to the container logs
`url`	`string`	The remote URL to download from
`filename`	`string` (optional)	An optional filename for the target, if not inferred by the URL
`auth`	Basic Auth	Authentication options

Basic Auth

Property	Value	Description
`user`	`string`	The username
`password`	`string`	The password

Example

This example shows how to run updates every night between 3:05 AM and 3:15 AM:

{
  "globalUpdateSettings": {
    "auth": {
      "username": "customer",
      "password": "password"
    },
    "cronLogFile": "$HOME/logs/surfmeter-automator.update.log"
  },
  "updates": {
    "automator": {
      "url": "https://download-server.customer-analytics.aveq.info/download/surfmeter-lab-automator/latest?customer=customer",
      "filename": "automator-latest.tar.bz2",
      "cronSchedule": "5 3 * * *"
    },
    "extension": {
      "url": "https://download-server.customer-analytics.aveq.info/download/surfmeter-lab/latest?customer=customer",
      "filename": "extension-latest.zip",
      "cronSchedule": "10 3 * * *"
    },
    "config": {
      "url": "https://download-server.customer-analytics.aveq.info/download/surfmeter-lab-automator-config/latest?customer=customer",
      "filename": "config-latest.tar.bz2",
      "cronSchedule": "15 3 * * *"
    }
  },
}

Global Update Settings

These apply to all update settings. They are optional. When an individual update entry specifies a property, it overrides the global setting.

Property	Value	Description
`cronLogFile`	`string` (optional)	Write the cron output to a local logfile
`auth`	Basic Auth	Authentication options

Example File​

Properties​

Root Properties​

Schedule Entries​

Regular Schedule Entry​

Examples​

Parameterized Schedule Entry​

Replacement Specification​

Global Schedule Settings​

Update Settings​

Basic Auth​

Example​

Global Update Settings​