Dynamic Data and Request Chaining

Variables allow you to dynamically insert data into a request using built-in functions (timestamps, random strings, hashes), configuration data from environments and data extracted from a previous response in a test run. Data is inserted into requests using a simple template format.

Use Variables to Pass Data Between Steps (Chained Requests)

Request steps can define variables that extract data from HTTP responses returned when running the test.

To create a variable, follow these steps:

  1. Expand a request within your test.
  2. Click Variables.
  3. Specify the location of the data you want to extract from the response.
  4. Choose a variable name to reference it in a subsequent request.

Source
The location of the data to extract. Data can be extracted from HTTP header values, JSON body, response size or time, response status code, text body, or XML body.

source data

Property
The property of the source data to retrieve. For HTTP headers this is the name of the header. For XML and JSON content, see below. This field is unused for Text Body and Status Code.

Variable Name
The name of the variable to assign the extracted value to. In subsequent requests you can retrieve the value of the variable by this name. See Using Variables in Requests.

You can extract data through the following methods:

  • Extract data from JSON Body Content
    Data from a JSON response body can be extracted by specifying the path of the target data using standard JavaScript notation. View sample JSON expressions for data extraction.
  • Extract data from XML Body Content
    Data from an XML response body can be extracted by specifying the path of the target data using XPath. In the 'Property' box of a variable definition that uses 'XML Body' as the source, enter an XPath expression to locate the data to extract and assign to the variable.
  • Extract data from Text Body
    Saves the entire text of the response to a variable.
  • Extract data from Text Body using Post-response Scripts
    You can specify the start and end boundaries of data to be extracted by running an extractor script through Post-response Scripts.

Environment Variables

Environments allow you to manage configuration on a per-test or per-bucket level. Common values (base URLs, API tokens, etc.) that are shared across requests within a test, or tests within a bucket, should be stored in an Initial Variable or Initial Script within an environment. Once defined, the variable is available to all requests within the test.

Initial Variables

Initial Variables specify data available to all requests in a test, including the first request. This can be useful for storing values that are common to all requests (like API keys) or other data required to set up the test run. Each test run will use the initial variables specified by the selected environment. To override variables on a per-run basis, use a Trigger URL with Custom Initial Variables.

Initial Script

Initial Scripts are executed before the first request in a test is made, but after the Initial Variables have been evaluated. variables.get() and variables.set() can be used to read and write variable values to be used by requests in the test. See: Scripts: Initial Script and Evaluation Order of Initial Variables.

Use Built-in Variables and Functions

In addition to the variables you define yourself, you can use these built-in variables and functions to generate common types of data.

Variable/Function Description Example Output
{{timestamp}} Integer Unix timestamp (seconds elapsed since January 1, 1970 00:00 UTC) 1384035195
{{utc_datetime}} UTC datetime string in ISO 8601 format. 2013-11-07T19:24:41.418968
{{format_timestamp(value, format)}} Timestamp of the specified value in the specified
format. Any delimiters (e.g. -, /, ., *, etc.) can
be used in the format with a combination
of any of the following date/time format
options. Also accepts variables. E.g.
{{format_timestamp({{timestamp}}, YYYY-MM-DD)}}
  • YYYY - 4 digit year (e.g. 2016)
  • YY - 2 digit year (e.g. 16)
  • MM - month
  • DD - day
  • HH - 24 hour (e.g. 13 == 1pm)
  • hh - 12 hour (e.g. 01 == 1pm)
  • mm - minutes
  • ss - seconds
2013-31-03
{{timestamp_offset(value)}} Integer Unix timestamp offset by the specified value in seconds (going back in time would be a negative offset value). Values should be passed without surrounding quotes. 1383948795
{{random_int}} Random integer between 0 and 18446744073709551615. 407370955
{{random_int(a,b)}} Random integer value between a and b, inclusive. 44674407370
{{random_string(length)}} Random alphanumeric string of the specified length (max 1000 characters). ddo1qlQR81
{{uuid}} Random universally unique identifier (UUID). 99386c08-6da7-4833-bb31-e70ce747c921
{{encode_base64(value)}} Encodes value in Base64. Values should be passed without surrounding quotes. Also accepts variables e.g. {{encode_base64({{username}}:{{password}})}} dTpwDQo=
{{md5(value)}} Generate an MD5 hash based on value. Values should be passed without surrounding quotes. Also accepts variables e.g. {{md5({{timestamp}})}} 50b7fe4da64720232c25bc7c6d66f6c5
{{sha1(value)}} Generate an SHA-1 hash based on value. Values should be passed without surrounding quotes. Also accepts variables e.g. {{sha1({{timestamp}})}} e0bd9304537cd8cb4e69ef5d73771fe218c484f5
{{sha256(value)}} Generate an SHA-256 hash based on value. Values should be passed without surrounding quotes. Also accepts variables e.g. {{sha1({{timestamp}})}} e3376ffb4b1e2c04b0fe68b52e8654696814b4883b47a56ff5a7df883725d8c1
{{hmac_sha1(value,key)}} Generate an HMAC using the SHA-1 hashing algorithm based on value and key. Values should be passed without surrounding quotes. Also accepts variables e.g. {{hmac_sha1({{timestamp}},key)}} 163a04cd86a82b948a7e85f0ed3cd3b5929a7d0c
{{hmac_sha256(value,key)}} Generate an HMAC using the SHA-256 hashing algorithm based on value and key. Values should be passed without surrounding quotes. Also accepts variables e.g. {{hmac_sha1({{timestamp}},key)}} eb0b5c5b2a04ac25ff52c886e115f2e60c0dd8d50bab076dc065e95f5fd37fb9
{{url_encode(value)}} Create a percent-encoded string suitable for URL querystrings. This is not required for URL or form parameters defined in the request editor which are automatically encoded. Only use this if you need to double encode a value in a URL or include a URL encoded string in a header value. This%20is%20100%25%20URL%20encoded.
{{runscope_environment}} The name of the environment used for this test run. prod
{{runscope_environment_uuid}} The unique ID of the environment used for this test run. ab34b187-bcde-4f41-9ec1-ff77e99aa2d6
{{runscope_bucket}} The bucket key for the API Monitoring Bucket the executing test is contained within. y0z5xkr1oa3m
{{runscope_bucket_name}} The name of the API Monitoring Bucket the executing test is contained within. Jumping Rabbit
{{runscope_test_uuid}} The unique identifier for the API Monitoring test. a8ea3ddd-73bb-435c-bc44-7c4bc8d99647
{{runscope_test_name}} The name of the API Monitoring test. Sample Test
{{runscope_region}} The region code indicating the location in which this test run was initiated. eu1
{{runscope_agent}} The unique identifier for the agent which is running the agent. Blank if run from a API Monitoring location. 83a24630-323d-501a-74a1-a7e51485ca12

Note: These built-in functions are only available in the web-based variable editor and not Scripts.

Request an additional built-in variable or function by contacting support.

When using a built-in variable in the value of an initial variable, the value will be generated once and remain constant across all the requests in a test (unless later overridden by another variable definition).

Override Built-in Variables

You can define a variable that uses the same name as a built-in variable or function. This will override the built-in value with the value extracted from the test response.

Use Variables in Requests

Once a variable has been defined, you can use it in any subsequent request. The test steps editor will display the 'Available Variables' that have been defined prior to the selected request. Variables can be used in any request data field including the method, URL, header values, parameter values and request bodies.

To include the value of a variable in a request, enter the name of the variable surrounded by double braces e.g. {{variable_name}}.

If a variable is undefined when a request using that variable is executed, the test will fail.

Evaluation Order of Initial Variables

Variables can be set at various points in the setup of a test run. At each step of the setup, a variable value specified in an earlier step can be overridden. Variables defined via Trigger URLs, Initial Scripts and Initial Variables will be evaluated in the following order:

  1. Variables defined in a shared environment (if the selected environment for a test run inherits from one).
  2. Variables defined in an individual test environment.
  3. Variables set via an environment-specific or a bucket-wide Trigger URL.
  4. Variables set using variables.set() in a shared environment's Initial Script.
  5. Variables set using variables.set() in an individual test environment's Initial Script.