Dynamic Responses

You can use several types of extensions to add dynamic content to response headers and response body.

For example, if you create a response with body { "Number": "{{randomInteger}}", "Date": "{{httpNow}}" } it will be rendered as { "Number": "165007562", "Date": "Sat, 02 Apr 2017 18:41:35 GMT" }

Below you will find all available extensions.

For a basic introduction to dynamic responses with examples have a look at Dynamic responses tutorial.

Look up by row and column

Save your data in trafficparrot-x.y.z/data/data.csv in CSV format.

To load the data in the response use {{csvDataFile 'row,col'}} in the response definition.

For example, {{csvDataFile '2,4'}} will read file trafficparrot-x.y.z/data/data.csv then load the 2nd row in the file and then lookup the 4th column value.

Select data using condition

For more advanced CSV data loading, you can put your CSV file with any name in the trafficparrot-x.y.z/data directory.

To select data from a CSV use {{select 'a from x.csv where b equals' value}} in the response definition.

For example, {{select 'title from jobs.csv where name equals' 'example' }} will read the file trafficparrot-x.y.z/data/jobs.csv then load the value of the column title where the value of the column name is equal to the value example.

The value parameter passed to the {{select}} can be a dynamic value that is taken from the request e.g. xPath or jsonPath. For example:

{{select 'Age from UserData.csv where Username equals' (xPath request.body '//User/Username/text()')}}

You can enable the "select" helper CSV file indexing and caching for performance improvement by setting the property:

trafficparrot.virtualservice.handlebars.select.indexAndCacheCsvFiles=true

Computed values with arithmetic operations

After loading a value from a CSV file, you can include it in an arithmetic operation to compute a value. For example:

{
{{#with (jsonPath request.body '$.id') as |id|}}
"id": {{ id }},
"total": {{ math (select 'quantity from sales.csv where id equals' id) '*' (select 'price from sales.csv where id equals' id) }}
{{/with}}
}

To generate a random value in the response use one of the following:

1. {{randomInteger}} - A random integer, e.g. 1543243211
2. {{randomInteger min max}} - A random integer between the given min and max, e.g. 10
3. {{randomDouble}} - A random double, e.g. -0.3476573
4. {{randomString}} - A random String, e.g. lW7H2gRfFqALsev0zDoJ4o3qGMtNYYgs
5. {{randomUUID}} - A random UUID, e.g. 5d0d4989-b5c1-412e-bbe6-457fd5d58493

All of the default functionality provided by the jknack Java Handlebars implementation is available. You can find more information on the Handlebars.java blog or Handlebars.js guide.

We have support for:

1. The default string helpers
2. The default conditional helpers
3. Separate template files using partials including template reuse and inheritance

Template files

You can place .hbs files in the installation root directory and reference them in your primary response template.

This can be useful to either reuse the same template many times, or to organize response template in separate files, with proper .hbs syntax highlighting in your editor or IDE.

The syntax

{{>responses/example-response}}

will load the content from the plain text template file responses/example-response.hbs.

The syntax

{{>(stringFormat 'responses/example-response-%s' 'some-value' )}}

allows you to construct the name of the template file dynamically using a string format for the name of the template file.

You can also pass in parameters to templates

{{>responses/example-response parameter=1234 }}

or reference parameters that exist already in the surrounding context.

More advanced usage is possible with template inheritance which you can use to parameterize blocks in a template:

base.hbs

Something before
{{#block "content"}}
Some default content
{{/block}}
Something after

override.hbs:

{{#partial "content" }}
Some override content
{{/partial}}
{{> base}}

WireMock helpers

The following WireMock Handlebars helpers are available for use.

1. {{xPath request.body '/a/b/text()'}} - Extract XML values or sub documents via XPath
2. {{soapXPath request.body '/a/b/text()'}} - Extract SOAP XML values or sub documents via XPath
3. {{jsonPath request.body '$.outer.inner'}} - Extract JSON values or sub documents via JSONPath
4. {{randomValue length=32 type='ALPHANUMERIC' uppercase=true}} - Generate random strings
5. {{pickRandom 'A' 'B' 'C'}} - Pick a random value from a list of alternatives
6. {{randomInt lower=1 upper=10}} - Pick a random value in an integer range (lower inclusive, upper exclusive)
7. {{randomDecimal lower=1.0 upper=1.5}} - Pick a random value in a decimal range (lower inclusive, upper exclusive)
8. {{range -2 2}} - Generate a list of integers list of integers
9. {{array 1 'string' true}} - Put given values in a list literal
10. {{hostname}} - Print the local machine hostname
11. {{date (parseDate request.headers.SomeDate format='dd-MM-yyyy')}} - Date parsing
12. {{date (truncateDate (parseDate request.headers.SomeDate) 'first day of month')}} - Date truncation
13. {{#trim}} text with whitespace {{/trim}} - Remove whitespace
14. {{#base64 padding=false decode=false}}content{{/base64}} - Base64 encoding and decoding
15. {{#urlEncode decode=false}}content{{/urlEncode}} - URL encoding and decoding
16. {{formData request.body 'form' urlDecode=true}}{{form.formField3}} - HTTP form parsing
17. {{regexExtract request.body '([a-z]+)-([A-Z]+)-([0-9]+)' 'parts'}}{{parts.0}},{{parts.1}},{{parts.2}} - Regular expression extraction
18. {{#if (matches '1234' '[0-9]+')}}OK{{/if}} - Regular expression conditional
19. {{#if (contains 'abcde123' 'bcd')}}OK{{/if}} - String or array contains conditional
20. {{parseJson request.body 'bodyJson'}}{{bodyJson.name}} - Parse string into a named JSON object
21. {{size request.query.things}} - Number of elements in a string/list/map
22. {{systemValue type='ENVIRONMENT' key='wiremock.VARIABLE'}} - Use system properties or environment variables

The following WireMock Handlebars helpers have alternatives in Traffic Parrot.

1. {{math}} - See Arithmetic operations
2. {{now}} - See Transform strings and Date offset

Transform strings

All of jknack Handlebars string helpers are available for use in both HTTP and JMS response headers and body.

1. {{defaultIfEmpty value ["default value"]}} - Render a default value if the specified value is not available, for example {{defaultIfEmpty request.query.username "Username parameter was not present in the request"}}
2. {{substring value start end}} - Render the beginning of the string value, for example {{defaultIfEmpty request.query.username 0 3}}
3. {{substring value start}} - Render the end of the string value, for example {{defaultIfEmpty request.query.username 5}}
4. {{replace value "aaa" "bbb"}} - Replace string aaa with bbb
5. {{abbreviate value 5}} - Render a truncated version of a string. Minimum value is 4.
6. {{yesno value [yes="yes"] [no="no"] maybe=["maybe"]}} - Convert a boolean "true", "false" to a string representation
7. {{capitalize value [fully=false]}} - Capitalize a string
8. {{stripTags value}} - Remove all HTML or XML tags from the string
9. {{stringFormat string param0 param1 ... paramN}} - Format the string
10. {{slugify value}} - Create a slug, for example "a b c" will be rendered as "a-b-c"
11. {{numberFormat number ["format"] [locale=default]}} - Format a number for a given locale or format
12. {{now ["format"] [tz=timeZone|timeZoneId]}} - Date is a specified format and timezone
13. {{upper value}} - Uppercase string
14. {{lower value}} - Lowercase string
15. {{rjust value 20 [pad=" "]}} - Right adjust string
16. {{ljust value 20 [pad=" "]}} - Left adjust string
17. {{cut value [" "]}} - Cut out all the occurrences in the string
18. {{center value size=19 [pad="char"]}} - Center string value padded with the specified character
19. {{capitalizeFirst value}} - Capitalize first word
20. {{join value "," [prefix="aPrefix"] [suffix="aSuffix"]}} - Join an array of values

Arithmetic operations

The math helper can be used to perform arithmetic operations:

1. {{math a "+" b}} - Addition
2. {{math a "-" b}} - Subtraction
3. {{math a "*" b}} - Multiplication
4. {{math a "/" b}} - Division
5. {{math a "%" b}} - Modulus
6. {{math "-" x}} - Negate
7. {{math "round" x}} - Round

Supported options:

• scale=N - the result will have N digits to the right of the decimal point

Modify response

The {{ modifyResponse }} helper can be used to modify the response HTTP status code.

Examples:

1. Modify the response status code:

   {{ modifyResponse 'statusCode' 404 }}

2. Modify the response status code conditionally:

   {{#contains request.body 'A'}}
       {{ modifyResponse 'statusCode' 400 }}
   {{else contains request.body 'B'}}
       {{ modifyResponse 'statusCode' 500 }}
   {{else}}
       {{ modifyResponse 'statusCode' 200 }}
   {{/contains}}

Convert data type

The {{ cast }} helper can be used to convert between data types.

Examples:

1. {{ cast value type='int' }} - convert value to an int
2. {{ cast list type='string' }} - convert list of elements to list of strings
3. {{ cast list type='string' single=true }} - extract only element from a list and convert to a string type
4. {{ randomInteger 0 (cast (xPath request.body '/Node/Max/text()') type='int') }} - example nested usage

Supported options:

• single=true - extract only element from a single element list
• type='string' - convert to string representation
• type='long' - convert to long
• type='int' - convert to int
• type='short' - convert to short
• type='double' - convert to float
• type='float' - convert to double

Date offset

The {{ dateOffset }} helper can be used to calculate an offset from a given date. This can be combined with extracting data from the request to dynamically offset a date in the response based on a date in the request.

Examples:

• {{ dateOffset "2018-07-09" add=true format="yyyy-MM-dd" days=1 }} - subtract 1 day from given date
• {{ dateOffset "2017-10-31T16:16:10" inFormat="yyyy-MM-dd'T'HH:mm:ss" outFormat="yyyy-MM-dd'T'HH:mm:ssZ" zone="America/Los_Angeles" days=1 hours=4 }} - subtract 1 day and 4 hours from given local date and reformat as a timestamp in time zone

Supported options:

• add=true - add to the input date rather than the default of subtracting
• format="yyyy-MM-dd" - specify a date format for both parsing and formatting using standard date and time formatting options
• inFormat="yyyy-MM-dd" - specify a date format for parsing using standard date and time formatting options
• outFormat="yyyy-MM-dd" - specify a date format for formatting using standard date and time formatting options
• zone="UTC" - specify a time zone ID for both parsing and formatting e.g. America/Los_Angeles or UTC or -08:30
• inZone="UTC" - specify a time zone ID for parsing e.g. America/Los_Angeles or UTC or -08:30
• outZone="UTC" - specify a time zone ID for formatting e.g. America/Los_Angeles or UTC or -08:30
• days=1 - number of days to offset by
• minutes=1 - number of minutes to offset by
• seconds=1 - number of seconds to offset by
• millis=1 - number of milliseconds to offset by
• nanos=1 - number of nanoseconds to offset by

Data source

The {{ dataSource }} helper can be used to query or update an existing data source using a SQL style syntax. This can be combined with extracting data from the request to dynamically select a response field or update state for later use.

Currently supported data source features:

Source	CREATE	SELECT	INSERT	UPDATE	DELETE	Caching	Multiple Results	Multiple Conditions	Default Values
CSV
XLS
JDBC

Please contact us if you require any data source operation compatibility that is not currently available.

Examples:

1. Select a single value from data/isoCountryCodes.csv or default to GBR:

   {{ dataSource '.csv'
   'SELECT isoCountryCode
   FROM isoCountryCodes.csv
   WHERE internalCode = :1'
   (jsonPath request.body '$.internalCode')
   single=true
   default='GBR' }}

2. Select multiple rows and columns from the JDBC database with id example.db:

   [
   {{#each (dataSource 'example.db' 'SELECT * FROM table') }}
       {
           "A": {{ A }},
           "B": {{ B }}
       }{{#unless @last}},{{/unless}}
   {{/each}}
   ]

3. Insert single record into the JDBC database with id example.db:

   {{ dataSource 'example.db'
   'INSERT INTO PERSON(ID, NAME) VALUES(:id, :name)'
   id=(jsonPath request '$.id')
   name=(jsonPath request '$.name') }}

4. Insert multiple records into the JDBC database with id example.db:

   {{ dataSource 'example.db'
   'INSERT INTO PERSON(ID, NAME) VALUES(:ids, :names)'
   ids=(jsonPath request '$.data[*].id')
   names=(jsonPath request '$.data[*].name') }}

5. Select multiple columns and single row from XLS file data/example.xlsx and sheet ExampeSheet:

   {{#with (dataSource 'example.xlsx' 'SELECT * FROM ExampleSheet' singleRow=true ) }}
   {
       "A": {{ A }},
       "B": {{ B }}
   }
   {{/with}}

6. Select single value using positional argument :1

   {{dataSource 'example.xlsx'
   'SELECT name
   FROM ExampleSheet
   WHERE id = :1'
   (jsonPath request.body '$.id')
   single=true }}

7. Select single value using named argument :id

   {{dataSource 'example.xlsx'
   'SELECT name
   FROM ExampleSheet
   WHERE id = :id'
   id=(jsonPath request.body '$.id')
   single=true }}

Supported options:

• single=true - extract single row single column result
• singleRow=true - extract single row result
• maxRows=N - limit number of rows returned
• default=value - provide default value to be used on error or no result
• shared=true - use configuration from installation root when true or configuration from scenarios/ScenarioName/* when false

Further details on the specifics of each data source can be found below.

CSV

• The .csv files should be placed in the data directory
• To configure caching of CSV files for improved performance use the propertytrafficparrot.virtualservice.handlebars.select.indexAndCacheCsvFiles=true
• Column names must be defined in the first row

XLS

• The .xls or .xlsx files should be placed in the data directory
• Sheet names are used as the "table" to select from
• Column names must be defined in the first row

JDBC

• Supported databases include:
  • MySQL
  • MariaDB
  • PostgreSQL
  • Oracle
  • Microsoft SQL Server MSSQL
  • and any other database that has a JDBC driver
• The database driver JAR must be placed in the lib/external/*.jar directory
• The database schema and tables must already exist before attempting to use as a data source
• The database connection should be defined in the database-connections.json file, for example:

  [
    {
      "connectionId": "example.db",
      "type": "JDBC_CONNECTION",
      "driverClass": "org.h2.Driver",
      "jdbcUrl": "jdbc:h2:mem:example",
      "properties": {
        "user": "sa",
        "password": "sa"
      }
    },
    {
      "connectionId": "postgres.db",
      "type": "JDBC_CONNECTION",
      "driverClass": "org.postgresql.Driver",
      "jdbcUrl": "jdbc:postgresql://host:port/database",
      "properties": {
        "user": "user",
        "password": "password"
      }
    }
  ]

Object store

The {{ objectStore }} helper can be used to query or update a JSON object. This can be combined with extracting data from the request to manage simple persistent object state across requests.

Examples:

1. Create a new object in data/person-uuid.json using the incoming JSON request body and unique id:

   {{ objectStore 'person.json' operation='create' id=(jsonPath request.body '$.id') object=request.body }}

2. Create a new object in data/person-uuid.json using the incoming JSON request body and generated unique id:

   {{#trim}}
   {{#with (randomValue type='UUID') }}
   {{ objectStore 'person.json' operation='create' id=. object=request.body }}
   {{ objectStore 'person.json' operation='put' id=. path='$' key='id' object=. }}
   {{ objectStore 'person.json' operation='get' id=. path='$' }}
   {{/with}}
   {{/trim}}

3. Get an existing object stored in data/person-uuid.json:

   {{ objectStore 'person.json' operation='get' id=(jsonPath request.body '$.id') path='$' }}

4. Get a particular field from an existing object stored in data/person-1.json:

   {{ objectStore 'person.json' operation='get' id=(jsonPath request.body '$.id') path='$.field' }}

5. Set an existing field to the value of a field in the request:

   {{ objectStore 'person.json' operation='set' id=(jsonPath request.body '$.id') path='$.field' object=(jsonPath request.body '$.field') }}

6. Delete an existing field:

   {{ objectStore 'person.json' operation='delete' id=(jsonPath request.body '$.id') path='$.field' }}

7. Delete entire object:

   {{ objectStore 'person.json' operation='delete' id=(jsonPath request.body '$.id') path='$' }}

8. Add or update a field at the root of the object:

   {{ objectStore 'person.json' operation='put' id=(jsonPath request.body '$.id') path='$' key='field' object=(jsonPath request.body '$.field') }}

9. Add or update a field at a child of the object:

   {{ objectStore 'person.json' operation='put' id=(jsonPath request.body '$.id') path='$.child' key='field' object=(jsonPath request.body '$.child.field') }}

10. Add an element to an existing array:

    {{ objectStore 'person.json' operation='add' id=(jsonPath request.body '$.id') path='$.names' object=(jsonPath request.body '$.name') }}

Supported options:

• operation='name' - supported operations are: create, get, set, delete, add, put
• overwrite=true - allows the create operation to overwrite an existing object when true
• id='' - a unique id must be provided to identify the object
• default=null - if specified, the provided default value will be returned if an object is not found with the given id
• path='$' - a JSONPath expression used by the operation
• object='' - a JSON object used by the operation
• key='' - the name of the new field to be added by the put operation
• shared=true - use configuration from installation root when true or configuration from scenarios/ScenarioName/* when false

Evaluate

The {{ evaluate }} helper can be used to evaluate an expression in a scripting language such as JavaScript.

NOTE: this requires a JRE with a scripting engine such as Nashhorn or GraalVM to be installed.

Examples:

1. Complex boolean expression:

   {{ evaluate '/[0-9]+/.test(request.headers["request-id"]) && JSON.parse(request.body)["name"].contains("123123")' }}

2. Using if statements:

   {{#evaluate}}
   if (key === 123) {
     'hello world 123'
   } else {
     'hello non 123 world'
   }
   {{/evaluate}}

3. Render current epoch time:

   {{ evaluate 'new Date().getTime()' }}

4. Render using print statement:

   {{ evaluate 'print("hello world print")'}}

Supported options:

• language='js' - currently only js is supported, which is also the default
• redirectOutput='RESULT' - RESULT will enable print statements LOGS will suppress print statements from the result and instead put them in the Traffic Parrot logs

Supported context items:

• Use the keyword self to reference the current context object:

  {{#with 'test' }}{{ evaluate 'self' }}{{/with}}

• Use the name of any context variable to reference it:

  {{ evaluate 'name' }}

• Use the syntax parameters[i] to reference parameters by index:

  {{ evaluate 'parameters[2]' 'zero' 'one' 'two' }}

• Use the syntax options["name"] to reference named options by name:

  {{ evaluate 'options["example"]' example='value' }}

Extract data from request fields and attributes

The following additional helpers are available in both HTTP, JMS and File response templates.

xPath

You can use it to extract a value from a field using an XPath.

Syntax:

{{xPath sourceAttribute 'TheXPathValue'}}

For example, if you use the following handlebar in a HTTP response body:

Request foobar value was: {{xPath request.body '/foo/bar/text()'}}

and then send a HTTP request:

<foo><bar>Long live mocking!</bar></foo>

you will see a HTTP response:

Request foobar value was: Long live mocking!

xPathList

You can use it to extract a list of nodes from a field using an XPath. Can be combined with loop iterators to transform a request body.

Syntax:

{{xPathList sourceAttribute 'TheXPathValue'}}

For example, if you use the following handlebar in a HTTP response body:

<items>
  {{#each (xPathList request.body '/request/items') }}
    <item id="{{ xPath this '/item/@id' }}" status="OK">{{ xPath this '/item/text()' }}</item>
  {{/each}}
</items>

and send a HTTP request:

<request>
    <items>
        <item id="one" ignored="any">body1</item>
        <item id="two" ignored="any">body2</item>
    </items>
</request>

you will see a HTTP response:

<items>
    <item id="one" status="OK">body1</item>
    <item id="two" status="OK">body2</item>
</items>

jsonPath

You can use it to extract a value from a field using an JsonPath.

Syntax:

{{jsonPath sourceAttribute 'TheJsonPathValue'}}

For example, if you use the following handlebar in a HTTP response body:

Request foobar value was: {{jsonPath request.body '$.foo.bar'}}

and then send a HTTP request:

{"foo":{"bar":"Long live mocking!"}}

you will see a HTTP response:

Request foobar value was: Long live mocking!

jsonPathList

You can use it to extract a list of values from a field using an JsonPath. Can be combined with loop iterators to transform a request body.

Syntax:

{{jsonPathList sourceAttribute 'TheJsonPathValue'}}

For example, if you use the following handlebar in a HTTP response body:

[
  {{#each (jsonPathList request.body '$.items') }}
    { id: {{ jsonPath this '$.id' }}", status: "OK" }{{#unless @last}},{{/unless}}
  {{/each}}
]

and send a HTTP request:

{
    items: [
        { id: 1234, ignored: "any" },
        { id: 1235, ignored: "any" }
    ]
}

you will see a HTTP response:

[
    { id: 1234, status: "OK" },
    { id: 1235, status: "OK" }
]

regex

You can use it to extract a value from a field using a single regular expression capturing group.

Syntax:

{{regex sourceAttribute 'TheRegex(.*)Value'}}

For example, if you use the following handlebar in a HTTP response body:

Request value was: {{regex request.body '.+? ([0-9A-Za-z]+Camel-[0-9A-Za-z]+).*'}}

and then send a HTTP request:

before 001116059c5549a0tOACamel-116059c554a20tOH after

you will see a HTTP response:

Request value was: 001116059c5549a0tOACamel-116059c554a20tOH

Nested handlebars helpers

You can call helpers inside other helpers. You just have to wrap them in parenthesis.

For example, if you use the following handlebar in a HTTP response body:

Bar was equal to xxx: {{#equal (jsonPath request.body '$.foo.bar') 'xxx'}}true{{else}}false{{/equal}}'

and then send a HTTP request:

{"foo":{"bar":"xxx"}}

you will see a HTTP response:

Bar was equal to xxx: true

All block helpers defined in the handlebars specification are available. As an example the following use of {{#each}} in a response body will render all request headers:

<requestHeaders>
  {{#each request.headers}}
    <name>{{@key}}</name>
    <value>{{this}}</value>
  {{/each}}
</requestHeaders>

{{#with (jsonPath request.body '$.internalCode') as |internalCode|}}
  "internalCode": {{ internalCode }},
  "isoCountryCode": "{{select 'isoCountryCode from isoCountryCodes.csv where internalCode equals' internalCode }}"
{{/with}}

{{#if request.query.password}}
  Password was present in the request.
{{else}}
  Please provide a password!
{{/if}}

{{#equal attributeValue1 attributeValue2}} result if true {{else}} result if false {{/equal}}

Is user Bob? {{#equal request.query.user 'Bob'}} Yes! {{else}} No! {{/equal}}

{{#ifEven attributeValue}} result if true {{else}} result if false {{/equal}}

{{#ifEven (jsonPath request.body '$.orderItem')}}number is even{{else}}number is odd{{/ifEven}}