Skip to content

Client Configuration

The Client Configuration section lets you edit and store configurations in the dashboard. JSON import and download are the only ways to move configurations between the dashboard and Surfmeter Automator.

It has four pages:

  • Study Catalog contains reusable study definitions.
  • Measurement Configs select the studies included in publicConfig.json.
  • Schedule Configs define when those studies run in automatorConfig.json.
  • Service Logins stores logins used by measurement studies.

Warning

Saving or publishing a configuration does not send it to any client. Download the published JSON files and apply them using Changing the Configuration.

Features for Surfmeter Automator 2.0

Some parts of these pages are meant for Surfmeter Automator 2.0, which will download its configuration from the dashboard. Automator 2.0 is not released yet, so you can ignore these parts for now:

  • the banner about Automator 2.0 at the top of each page
  • the Assign to Clients button and any client counts after publishing
  • the clients listed in the Used By tab of a schedule config
  • the Template and Client Tags fields when editing a schedule config
  • the Updates card in the global settings of a schedule config
  • the V2 download format
  • the Configuration tab on the client detail page

Study Catalog

Create studies in the catalog before adding them to a measurement config. The study form changes with the measurement type and checks its fields against the matching configuration schema.

Editing a study creates a new revision. Config revisions keep the study revision that was selected when the config was saved. Existing configs therefore do not change until you update them.

The study detail page has the tabs Content (the current content as fields and JSON), Used By (the measurement configs that use it), and History (its revisions). You cannot delete a catalog study while a saved config revision still refers to it.

Some studies need their own login. Add it on the study detail page. Only admins and organization admins can enter or change the username and password.

Measurement Configs

A measurement config is the source for one publicConfig.json file. The reference lists the available study types and parameters.

To create one:

  1. Open Client Configuration > Measurement Configs.
  2. Select New Measurement Config, then enter its name and optional description.
  3. Add studies from the catalog.
  4. Select Save draft.
  5. Ask an admin to review and publish the draft.

You can also import an existing publicConfig.json. The import creates any missing catalog studies and leaves the new config as a draft.

The config detail page has the tabs Studies, Used By, and History. On the Studies tab, Update all to latest switches all studies to their newest catalog revision. You can also duplicate a config and edit its name and description.

Schedule Configs

A schedule config is the source for one automatorConfig.json file. Each schedule config belongs to one measurement config, and its schedules can only use the studies of that measurement config. Choose the measurement config when you create or import the schedule config. To change it later, use Edit Details.

The schedule config detail page has these tabs:

  • Schedules – A calendar and the list of schedules. Each schedule has an ID, one or more studies, and its timing. Use New Schedule to add one.
  • Global Settings – The time zone, a random start offset, and defaults for all schedules, such as environment variables, the log file, and study options.
  • Used By – Where the config is used.
  • History – The revisions of the config.

Edit the schedules and select Save draft. An admin must publish the draft before it becomes the published version.

Schedule calendar

The calendar shows when each study runs, by hour or by week. Drag studies from the study list into the calendar to schedule them. You can move blocks, and merge or split them, to change when studies run. Click Full screen for more space.

The calendar marks studies that run at the same time, and studies that overlap with their own next run. In that case, the next run is skipped.

Note

Some schedules cannot be shown exactly in the calendar, for example cron expressions with seconds. Their blocks show approximate times and cannot be dragged. They are kept when you move other blocks.

Study checks

The dashboard makes sure that schedules only use studies that exist in the measurement config:

  • If a schedule uses a study that is no longer in the measurement config, the Studies no longer available dialog appears when you open the schedule config. The study is removed from the schedules. Save the draft to keep the change.
  • You cannot save, publish, or roll back a measurement config if that removes a study that a schedule config still uses. Remove the study from those schedules first.
  • You cannot delete a measurement config that a schedule config uses.

Publishing and rollback

Saving changes creates a draft revision. It does not replace the published revision.

Admins and organization admins can:

  • publish a draft
  • roll back to an earlier revision
  • choose the default configs
  • delete studies and configs

Editors can create studies and configs, edit drafts, import JSON, and duplicate configs. Viewers can read the configuration pages.

The default configs come as a pair: the default schedule config and its measurement config. To make a measurement config the default, choose a published schedule config that uses it under Make Default.

Deleting a published config also deletes its revision history. The dashboard asks for confirmation before doing this.

Moving configurations between the dashboard and Automator

The dashboard does not read configuration from clients and does not install configuration on them.

Use Import JSON to bring an existing publicConfig.json or automatorConfig.json into the dashboard. Imports create dashboard drafts, which you can review before publishing. When you import an automatorConfig.json, choose the measurement config whose studies it schedules. Settings that have no effect are not imported, and the import result lists them under Not imported.

Download buttons export the published version. They are disabled until the config is published.

  • A measurement config downloads as publicConfig.json.
  • A schedule config downloads as automatorConfig.json. The download button asks for the format. Choose V1 for Surfmeter Automator 1.x.

Warning

Always choose V1 when downloading a schedule config for Surfmeter Automator 1.x. Automator 1.x cannot read the V2 format.

Some schedules cannot be expressed in the V1 format, such as interval timing, cron expressions with seconds, or studies that run in parallel. In that case, the Cannot download as V1 dialog lists the schedules you need to change. The dashboard may also show notes after a V1 download, for example if two schedules may run at the same time.

Only admins and organization admins receive a measurement config with working service logins. Downloads for viewers and editors mask those values. The dashboard warns before downloading a masked file that contains affected services.

Follow Changing the Configuration to place the downloaded files in a native or Docker installation and load the schedule.

Service Logins

Service logins hold reusable usernames and passwords for services measured by the studies, such as Netflix. Admins and organization admins can create, edit, and delete them.

Deleting a login removes it from future measurement config downloads. It does not change previously downloaded files.