User-defined Templates

User-defined templates allow you create a set of tests, alert rules, dashboards, and tags from a single template configuration file that you define. The ThousandEyes platform supports many monitoring scenarios and third-party applications, such as Microsoft 365, Webex, and others using a predefined set of certified templates. You may, however, have additional needs that are not covered. You can use user-defined templates to support monitoring use cases that the ThousandEyes platform doesn't currently offer through its certified offerings. For more information about templates, see Templates.

Permissions

When you create a template, all users within your account group can have the option to select it when deploying a new test template. To grant access to users in your account group, enable the View Test Templates permission for each user. Users will also need the "Edit Tests" permission to deploy the templates. If the template has other assets, such as alert rules, tags, or dashboards, users in the account group will also need to have the respective edit permission for each asset type.

Creating a User-defined Template with the ThousandEyes API

If this is your first time using the ThousandEyes API, see Thousand Eyes Developer Reference: Overview to get started.

Using createTestTemplate

To create a new template, use the createTestTemplate endpoint (https://api.thousandeyes.com/v7/tests/templates).

Assets

Templates currently support configuring tags, tests, alert rules, and dashboards. Each of these assets is configured using a schema you can specify in your configuration file. The API documentation for each type of asset is listed in the table below. Examples of each asset's configuration are in the next section, Example Schemas.

The table below lists where you can find a reference to the schema for each type of asset:

Asset Type	Schema Reference Link
Tags (formerly "Labels")	Tags (v7)
Tests	Tests (v7)
Alert Rules	Alert Rule (v7)
Dashboards	Dashboards (v7)

You can also reference the id of another type of asset within each schema you define for each asset. For example, to assign an alert rule asset to a test asset, you can reference the id of a test you are already defining in the configuration file for the template you are creating. Because the ThousandEyes platform creates each template asset type in a specific order, an asset can only reference other assets that are created before it.

The order the ThousandEyes platform creates template assets is:

1. Tags (formerly "Labels")

2. Tests

3. Alert Rules

4. Dashboards

The following table illustrates which assets of a different type each asset can reference:

Asset Type	Can Reference
Tags	none
Tests	Tags
Alert Rules	Tags, Tests
Dashboards	Tags, Tests, Alert Rules

Example Schema

The template schema below describes a straightforward Slack monitor that includes an HTTP server, API test, and DNS test. The target is automatically determined from the Slack tenant name, and the DNS test will automatically determine the name servers.

{
    "name": "Slack",
    "description": "Template for creating a set of tests to monitor Slack; will monitor your Slack vanity URL (<tenant>.slack.com), Slack DNS servers, and the Slack API (api.slack.com).",
    "summary": "A template for monitoring your <tenant>.slack.com instance and api.slack.com includes Network, DNS, and Web tests",
    "icon": "slack",
    "isBuiltIn": false,
    "certificationLevel": "user",
    "userInputs": {
        "tenant": {
            "name": "Slack Tenant Name",
            "title": "",
            "description": "Your Slack tenant name; will be used to determine target as &lt;tenant&gt;.slack.com",
            "type": "string"
        },
        "agents": {
            "name": "Which agents should we run tests from?",
            "title": "",
            "type": "any"
        }
    },
    "tests": {
        "apiTest": {
            "interval": 60,
            "type": "http-server",
            "url": "https://api.slack.com",
            "testName": "{{name}} - {{userInputs.tenant}} - API",
            "agents": "{{userInputs.agents}}"
        },
        "tenantTest": {
            "httpInterval": 60,
            "interval": 60,
            "type": "page-load",
            "url": "https://{{userInputs.tenant}}.slack.com",
            "testName": "{{name}} - {{userInputs.tenant}} - Web",
            "agents": "{{userInputs.agents}}"
        },
        "dnsTest": {
            "domain": "{{userInputs.tenant}}.slack.com A",
            "interval": "60",
            "type": "dns-server",
            "dnsServers": [],
            "testName": "{{name}} - {{userInputs.tenant}} - DNS",
            "agents": "{{userInputs.agents}}"
        }
    },
    "labels": {},
    "tags": {},
    "alertRules": {},
    "dashboards": {}
}

User-Defined Templates in ThousandEyes

To view a list of available templates in ThousandEyes, navigate to Cloud and Enterprise Agents > Test Settings and click on the menu arrow next to Add New Test. Select "Add From Template". For more information about selecting a template, see Selecting a Template.

Add From Template dialog

From the list of templates, you can add a new template, duplicate a template, and edit and/or delete user-defined templates your team has created.

Creating a User-defined Template from Scratch

To define your own template from scratch, follow the steps to select a template from Test Settings and use the New Template feature to add your own template specification using JSON.

1. From the Deploy Template screen, click on the + New Template button in the upper right-hand corner.

Add New Template button

1. Specify a JSON schema for your template in the text field. For more information about creating a template schema, see Example Schema.

Create New Template dialog

1. You can preview the template in the next screen. Click the Confirm & Publish button to make the template available to users in your account group.

Creating a User-defined Template from an Existing Template

You don't have to create a template from scratch. You can duplicate an existing template and modify it instead.

1. Find the template you want to duplicate and click the ... button. Select Duplicate.
2. Modify the JSON schema and click Preview to preview the template.
3. Click the Confirm & Publish button to make the template available to users in your account group.