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.

Traffic Parrot ships a large catalogue of response-templating helpers. To make them easy to discover while you are building a mapping, the mapping editors include an Available helpers panel. You no longer need to leave the product to look up a helper name or its syntax. The same panel is available in the HTTP stub editor and in the messaging (JMS, IBM MQ and file-message) mapping editor.

Open the HTTP stub editor (HTTP » Add/Edit). The panel is a collapsible card titled Available helpers that sits at form level below both the Request and Response cards, so it reads as applying to the whole mapping rather than only the response body. It is collapsed by default, so it never pushes the rest of the form around — expand it when you need it.

The same panel appears in the same place on the messaging Add and Edit mapping forms (JMS, IBM MQ and file messages): a collapsible Available helpers card at form level, below the request and response. Open a messaging Add/Edit page and expand it — it behaves exactly as it does for HTTP.

Expand the panel and you will see a Filter helpers box, then a Response templating helpers section that lists the catalogue. The panel is a sectioned shell: future Traffic Parrot releases add further sections to it, and the filter narrows every section at once.

The panel lists the helpers grouped by category — for example Traffic Parrot data ({{dataSource}}, {{databaseQuery}}, {{objectStore}}, {{parseCsv}}), State & control ({{select}}, {{manageState}}, {{assign}}), Transform & compute ({{cast}}, {{math}}), Date & time ({{now}}, {{dateOffset}}), Random ({{randomValue}}), Extract ({{jsonPath}}, {{xPath}}) and Financial messaging ({{swiftField}}, {{fixField}}). Each entry shows a one-line description, a copy-ready snippet that is already scaffolded with example parameters, and a docs link to the relevant section of this page.

To work with the panel:

• Type in the Filter helpers box to narrow the list as you go. The filter matches both the helper name and its description, and is case-insensitive.
• Click the Copy link next to a helper to copy its snippet to the clipboard. The link briefly changes to Copied to confirm. Paste the snippet into the response body and adjust the example parameters to suit your mapping.

The response-body editor also offers the same helpers as inline autocomplete. Type {{ in the response body and a dropdown of matching helpers appears, filtered by whatever you type after the {{; select one to insert its scaffolded snippet at the cursor. Use the panel to browse and copy helpers, or type {{ to insert one inline without leaving the editor — both draw on the same catalogue.

The same {{ autocomplete is available in the messaging (JMS, IBM MQ and file-message) response-body editor, where it behaves exactly as it does for HTTP. On an IBM MQ mapping with several responses, each response body has its own autocomplete — including any responses you add with Add response message.

The panel is read-only — it helps you discover and copy helpers, and does not change how mappings are saved or how responses are rendered.

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}}
}

Use {{parseCsv}} to parse a CSV string into rows that you can iterate over. This is useful when the CSV data is part of the request body or a variable rather than a file on disk.

The first row of the CSV is treated as the header row and the column names become the keys for each row.

Basic usage

Given a variable csv containing:

name,age
Alice,30
Bob,25

You can iterate over the rows:

{{#each (parseCsv csv)}}Name: {{this.name}}, Age: {{this.age}}
{{/each}}

You can count the number of rows using the size helper:

Total rows: {{size (parseCsv csv)}}

Custom delimiter

Use the delimiter parameter for non-comma-separated data:

{{#each (parseCsv csv delimiter=';')}}{{this.name}}{{/each}}

Custom quote character

Use the quote parameter to change the quote character:

{{#each (parseCsv csv quote="'")}}{{this.name}}{{/each}}

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

The {{image}} Handlebars helper renders a placeholder PNG — a grey rectangle with the dimensions text drawn in the centre — and returns it as a Base64-encoded string. Combine it with the base64-decode-body response transformer to serve the rendered Base64 string as raw PNG bytes.

This is useful for stubbing endpoints that return images (avatars, thumbnails, product photos) without bundling real binary assets with your mappings. The helper uses only the JDK (BufferedImage, Graphics2D, ImageIO) — no extra dependencies, no network calls — so it works in air-gapped environments.

Arguments:

Argument	Default	Description
width	400	Image width in pixels.
height	300	Image height in pixels.
text	"{width}x{height}"	Overlay text drawn in the centre of the image. Defaults to the rendered dimensions (e.g. 400x300). Rendered with the JDK logical font Font.SANS_SERIF.

Example mapping:

{
  "request": { "method": "GET", "url": "/avatar" },
  "response": {
    "status": 200,
    "headers": { "Content-Type": "image/png" },
    "body": "{{image width=400 height=300}}",
    "transformers": ["base64-decode-body"]
  }
}

A GET /avatar against this mapping returns a 400×300 PNG with Content-Type: image/png. The Content-Type header is set in the mapping's headers field — the helper itself does not set any response headers.

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. The default number helpers
4. 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.

The default file extension is .hbs, you can use a different file extension as follows:

{{>example.txt}}

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 (also supports mixedcase=true)
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
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 an environment variable or system property in a response. Only keys named wiremock* are permitted, and environment-variable names use an underscore (wiremock_VARIABLE) rather than a dot — see the dedicated how-to page for the type='PROPERTY' variant, the default= fallback, header usage, and the allow-list rules.
23. {{#assign 'name'}}value{{/assign}} - Set a string variable with assign block
24. {{val 1234 assign='numberVar'}} - Set a variable of any type with val (preserves type, unlike assign which always stores strings)
25. {{val request.query.example or='default'}} - Get a variable with a default value
26. {{lookup object 'field'}} - Object field lookup
27. {{arrayAdd (array 'example1' 'example2') 'example-middle' position=1}} - Array element add
28. {{arrayRemove (array 'example1' 'middle' 'example2') position=1}} - Array element remove
29. {{arrayJoin ',' (array '1' '2' '3')}} - Array join with separator
30. {{formatJson jsonObject}} - Format JSON in pretty or compact form (supports format='compact')
31. {{formatXml xmlString}} - Format XML in pretty or compact form (supports format='compact')
32. {{toJson someObject}} - Convert any object to a JSON string
33. {{jsonMerge json1 json2}} - Merge two JSON objects recursively (supports removeNulls=true)
34. {{jsonRemove jsonString jsonPath='$.field'}} - Remove elements from JSON by JSON path
35. {{jsonArrayAdd existingJson jsonPath='$.items' newItem}} - Add items to a nested JSON array

The following WireMock Handlebars helpers have alternatives in Traffic Parrot.

1. {{math}} - See Arithmetic operations
2. {{now}} - See Transform strings and Date offset
   • The default implementation of {{now}} can be toggled using trafficparrot.properties
     • To use the Handlebars.java {{now}} helper:

       trafficparrot.virtualservice.handlebars.now.provider=HANDLEBARS

     • To use the WireMock {{now}} helper:

       trafficparrot.virtualservice.handlebars.now.provider=WIREMOCK

   • Alternatively, you can add the provider parameter per call to dynamically switch between them, otherwise the default implementation specified in trafficparrot.properties will be used
     • To enable this set in trafficparrot.properties:

       trafficparrot.virtualservice.handlebars.now.dynamic=true

     • To use the Handlebars.java implementation:

       {{now format='short' provider='HANDLEBARS'}}

     • To use the WireMock implementation:

       {{now offset='2 years' format='epoch' provider='WIREMOCK'}}

WireMock JWT helpers

The JWT Extension for WireMock is supported.

JWT usage examples, typically mocked via an /oauth/token endpoint:

{{jwt maxAge='12 days'}}
{{jwt exp=(parseDate '2041-02-23T21:22:23Z')}}
{{jwt nbf=(parseDate '2019-02-23T21:22:23Z')}}
{{jwt iss='https://issuer.trafficparrot.com/'}}
{{jwt aud='https://audience.trafficparrot.com/'}}
{{jwt sub='subject'}}
{{jwt alg='RS256'}}
{{jwt
    customBoolClaim=true
    customIntClaim=23
    customStringClaim='example@x.y.z'
    customDateClaim=(parseDate '2024-01-02T03:04:05Z')
}}

JSON Web Key Set (JWKS) usage example, typically mocked via an /.well-known/jwks.json endpoint:

{{jwks}}

Settings also visible via http://localhost:8080/api/http/__admin/settings as:

{
  "settings" : {
    "extended" : {
      "jwt" : {
        "hs256Secret" : "...",
        "rs256PublicKeyId" : "...",
        "rs256PublicKey" : "-----BEGIN RSA PUBLIC KEY-----\n...\n-----END RSA PUBLIC KEY-----\n",
        "rs256PrivateKey" : "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----\n"
      }
    }
  }
}

Enable in trafficparrot.properties by setting:

trafficparrot.http.jwt.enabled=true

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
• response header values

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}}

3. Modify a header value:

   {{ modifyResponse 'headerValue' 'header-name' 'header-value' }}

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
5. {{#if (cast value type='boolean') }}value cast to true{{/if}} - example if conditional usage
6. {{#if (not (cast value type='boolean') ) }}value cast to false{{/if}} - example if not conditional usage
7. {{#unless (cast value type='boolean') }}value cast to false{{/unless}} - example unless conditional 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
• type='boolean' - convert to boolean

When casting to boolean, the semantics are:

• The string 'true' casts to boolean true
• The string 'false' casts to boolean false
• Blank strings like '' or ' ' cast to boolean false
• Empty collections cast to boolean false
• Non-empty collections cast to boolean true
• The number zero casts to boolean false
• Non-zero numbers cast to boolean true

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 }} - add 1 day to the 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	Batch Update	Multiple Results	Multiple Conditions	Default Values
CSV
XLS
JDBC
Couchbase1

¹ Couchbase uses N1SQL aka SQL++ statements which also includes other operations such as UPSERT and MERGE

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"
      }
    }
  ]

Couchbase

• The following Couchbase SDK JARs must be placed in the lib/external/*.jar directory:
  • com.couchbase.client:java-client
  • com.couchbase.client:core-io
  • io.projectreactor:reactor-core
  • org.reactivestreams:reactive-streams
• The bucket 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": "couchbase.db",
      "type": "COUCHBASE_CONNECTION",
      "connectionString": "couchbase://localhost:32784",
      "username": "Administrator",
      "password": "password",
      "warmupQuery": "SELECT COUNT(*) FROM bucket_a UNION SELECT COUNT(*) FROM bucket_b",
      "enableDnsSrv": true,
      "networkResolution": "auto"
    }
  ]

• Couchbase uses N1SQL aka SQL++ statements in the following syntax:

  {{ dataSource 'couchbase.db' 'INSERT INTO PERSON(KEY, VALUE) VALUES ("$id", {"id" : $id,"name" : $name})' id=1000 name='some-name' syntax='N1QL' }}
  {{ dataSource 'couchbase.db' 'SELECT name FROM PERSON USE KEYS "$id"' id=1000 single=true syntax='N1QL' }}
  {{ dataSource 'couchbase.db' 'INSERT INTO PERSON(KEY, VALUE) VALUES ("$id", $object)' id=1000 object=example syntax='N1QL' }}

• You can control query scan consistency using the scanConsistency parameter:
  • scanConsistency='REQUEST_PLUS' - consistent results, waits for all pending mutations to be indexed (default)
  • scanConsistency='NOT_BOUNDED' - faster queries, results may not include the most recent mutations
  For example:

  {{ dataSource 'couchbase.db' 'SELECT name FROM PERSON USE KEYS "$id"' id=1000 single=true syntax='N1QL' scanConsistency='NOT_BOUNDED' }}

• Couchbase queries that fail due to a missing document return an empty result, which can be handled using default='' for clean conditional logic. Other Couchbase errors (e.g. syntax errors or connection issues) return an error message instead of throwing an exception. You can use the default option to provide a fallback value.

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

Manage state

The {{ manageState }} helper can be used to manage simple key-value state across requests. You can set a value in one response and retrieve it in a subsequent response, enabling stateful mock behaviour.

State can be organized into namespaces using the namespace/variableName syntax. If no namespace is specified, the variable is stored in the global namespace. This matches the namespace convention used by the state management REST API.

Operations:

1. Set a global variable:

   {{ manageState 'counter' 'set' 1234 }}

2. Get a global variable:

   {{ manageState 'counter' 'get' }}

3. Increment a global variable by a numeric value:

   {{ manageState 'counter' '+' 1 }}

4. Set a variable in a specific namespace:

   {{ manageState 'scenario-1/counter' 'set' 42 }}

5. Get a variable from a specific namespace:

   {{ manageState 'scenario-1/counter' 'get' }}

6. Increment a variable in a specific namespace:

   {{ manageState 'scenario-1/counter' '+' 1 }}

7. Use a custom separator (default is /):

   {{ manageState 'scenario-1::counter' 'get' separator='::' }}

Variables in different namespaces are isolated from each other. For example, scenario-1/counter and scenario-2/counter are independent variables. Variables without a namespace prefix (e.g. counter) use the global namespace and can be accessed via the REST API at GET /api/state/global/counter.

Namespaced variables can be accessed via the REST API at GET /api/state/{namespace}/{name}, for example GET /api/state/scenario-1/counter. You can also reset all state using DELETE /api/state or clear a single namespace using DELETE /api/state/{namespace}.

Evaluate

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

NOTE: this requires a scripting engine such as Nashhorn or GraalVM to be installed, either as part of the JRE or placed in the lib/external/*.jar directory.

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 HTTP, JMS, IBM MQ 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!

You can also use JsonPath conditional expressions, for example to check for the presence of a field:

{{#if (jsonPath request.body '$.[?(@.field)]') }}field is present{{/if}}
{{#if (not (jsonPath request.body '$.[?(@.field)]') ) }}field is not present{{/unless}}
{{#if (jsonPath request.body '$.[?(!(@.field))]') }}field is not present{{/unless}}
{{#unless (jsonPath request.body '$.[?(@.field)]') }}field is not present{{/unless}}

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

swiftField

You can use it to extract a field value from a SWIFT MT message by its tag number. This is useful when creating dynamic responses that reference specific fields from a SWIFT message request body.

Syntax:

{{swiftField sourceAttribute 'TagNumber'}}

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

Transaction reference: {{swiftField request.body '20'}}

and then send a request with a SWIFT MT103 message body:

{1:F01BANKBEBBAXXX0000000000}{2:I103BANKDEFFXXXXN}{4:
:20:TXNREF001
:23B:CRED
:32A:230101EUR1000,00
:50K:/1234567890
ACME CORP
:59:/9876543210
BENEFICIARY NAME
123 MAIN STREET
LONDON
:71A:SHA
-}

you will see a response:

Transaction reference: TXNREF001

The helper also works with bare Block 4 content (without the SWIFT envelope blocks). For example:

{{swiftField request.body '59'}}

applied to:

:20:REF001
:59:/9876543210
BENEFICIARY NAME
123 MAIN STREET
LONDON
:71A:SHA

returns the full multi-line value:

/9876543210
BENEFICIARY NAME
123 MAIN STREET
LONDON

If the specified tag is not present, or if the input is not a SWIFT message, the helper returns an empty string. If the tag appears multiple times, the first occurrence is returned.

fixField

You can use it to extract a field value from a FIX protocol message by its tag number. This is useful when creating dynamic responses that echo specific tags (such as ClOrdID) from a FIX request body.

Syntax:

{{fixField sourceAttribute 'TagNumber'}}

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

Order id was: {{fixField request.body '11'}}

and then send a request with a FIX NewOrderSingle body (SOH-delimited, shown here with | for readability):

8=FIX.4.4|9=176|35=D|49=SENDER|56=TARGET|11=ORDER-1|55=AAPL|54=1|10=000|

you will see a response:

Order id was: ORDER-1

Tag numbers are treated as opaque string keys, so the helper works across FIX 4.2, 4.4, 5.0, and FIXT without any FIX-dictionary validation. If the specified tag is not present, or if the input is not a FIX message, the helper returns an empty string. If the tag appears multiple times (for example inside a repeating group), the first occurrence is returned.

fixWithChecksum, fixBodyLength, fixCheckSum

Together these three helpers let you author a FIX 4.x response template without hand-calculating tag 9 (BodyLength) and tag 10 (CheckSum). {{#fixWithChecksum}}...{{/fixWithChecksum}} is a block helper that renders its inner template and then substitutes the two inline placeholders:

• {{fixBodyLength}} — expands to the FIX 4.x BodyLength: the number of UTF-8 bytes between the SOH after 9= and the start of 10=.
• {{fixCheckSum}} — expands to the FIX 4.x CheckSum: a 3-digit zero-padded modulo-256 sum of every byte before 10=.

Syntax (where {soh} denotes the literal SOH byte, ASCII 0x01, used as the FIX field delimiter):

{{#fixWithChecksum}}8=FIX.4.4{soh}9={{fixBodyLength}}{soh}35=8{soh}49=TARGET{soh}56=SENDER{soh}11=ORDER-1{soh}10={{fixCheckSum}}{soh}{{/fixWithChecksum}}

When the template above is used as a response body, Traffic Parrot computes both values from the rendered bytes and writes the standard FIX 4.x values into the message — for example, 9=54 and 10=128. The BodyLength is substituted first so the CheckSum is computed over the final message bytes (including the rendered BodyLength value), matching the FIX 4.x semantics where the checksum protects the entire wire message except the trailer.

{{fixBodyLength}} and {{fixCheckSum}} only work inside a {{#fixWithChecksum}} block. Used outside the block they render as the literal error string {{ fixBodyLength ERROR: can only be used inside a fixWithChecksum block }} (or the equivalent for fixCheckSum), matching the error format used by other Traffic Parrot helpers such as fixField.

The block composes with fixField so a response template can echo tags from the inbound request and still get correct BodyLength and CheckSum values. For example:

{{#fixWithChecksum}}8=FIX.4.4{soh}9={{fixBodyLength}}{soh}35=8{soh}49=TARGET{soh}56=SENDER{soh}11={{fixField request.body '11'}}{soh}10={{fixCheckSum}}{soh}{{/fixWithChecksum}}

The {{fixField request.body '11'}} call extracts the ClOrdID from the inbound request body; the block then computes the correct 9= and 10= values for the rendered response.

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}}

{{#eq x y}}
  PASS
{{else}}
  FAIL
{{/eq}}

{{eq x y}}

{{eq x y yes='y' no='n'}}

{{#neq x y}}
  PASS
{{else}}
  FAIL
{{/eq}}

{{neq x y}}

{{neq x y yes='y' no='n'}}

{{#gt x y}}
yes
{{else}}
no
{{/gt}}

{{gt x y}}

{{gt x y yes='y' no='n'}}

{{#gte x y}}
yes
{{else}}
no
{{/gt}}

{{gte x y}}

{{gte x y yes='y' no='n'}}

{{#lt x y}}
yes
{{else}}
no
{{/gt}}

{{lt x y}}

{{lt x y yes='y' no='n'}}

{{#lte x y}}
yes
{{else}}
no
{{/gt}}

{{lte x y}}

{{lte x y yes='y' no='n'}}

{{#and x y}}
 yes
{{else}}
 no
{{/and}}

{{#and x y z zz}}
 yes
{{else}}
 no
{{/and}}

{{and x y}}

{{and x y yes='y' no='n'}}

{{#or x y}}
 yes
{{else}}
 no
{{/and}}

{{#or x y z zz}}
 yes
{{else}}
 no
{{/and}}

{{or x y}}

{{or x y yes='y' no='n'}}

{{#not x}}
 yes
{{else}}
 no
{{/not}}

{{not x}}

{{not x yes='y' no='n'}}

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

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

{{ equal a b }}

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

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

{{#times number}} repeated content {{/times}}

{{#times 5}}{{@index}}{{#unless @last}},{{/unless}}{{/times}}

{{#times (jsonPath request.body '$.orderItemCount')}}item {{@index}}
{{/times}}

{{#times request.query.repeat defaultTimes=3}}{{@index}}{{/times}}

{{ helperName ERROR: error message here }}

trafficparrot.virtualservice.handlebars.throwErrors=true

{
  "request": {
    "url": "/generate-pdf",
    "method": "POST"
  },
  "response": {
    "status": 200,
    "transformers": ["requestToPdf"]
  }
}

{
  "request": {
    "url": "/get-report",
    "method": "GET"
  },
  "response": {
    "status": 200,
    "body": "<report><data>Sample content</data></report>",
    "transformers": ["responseToPdf"]
  }
}

{
  "request": {
    "urlPattern": "/stream/.*",
    "method": "GET"
  },
  "response": {
    "status": 200,
    "body": "{\"segmentsDir\": \"stream/\", \"playlistType\": \"vod\"}",
    "transformers": ["hlsStreamTransformer"]
  }
}

__files/
  stream/
    segment0.ts
    segment1.ts
    segment2.ts

ffmpeg -i input.mp4 -c copy -map 0 -f segment -segment_time 2 segment%d.ts

{
  "variants": [
    {"name": "low",  "bandwidth":  800000, "resolution":  "426x240", "segmentsDir": "stream/low/"},
    {"name": "mid",  "bandwidth": 2000000, "resolution":  "640x360", "segmentsDir": "stream/mid/"},
    {"name": "high", "bandwidth": 5000000, "resolution": "1280x720", "segmentsDir": "stream/high/"}
  ],
  "playlistType": "vod"
}

{
  "request": {
    "urlPattern": "/stream/.*",
    "method": "GET"
  },
  "response": {
    "status": 200,
    "body": "{\"variants\":[{\"name\":\"low\",\"bandwidth\":800000,\"resolution\":\"426x240\",\"segmentsDir\":\"stream/low/\"},{\"name\":\"mid\",\"bandwidth\":2000000,\"resolution\":\"640x360\",\"segmentsDir\":\"stream/mid/\"},{\"name\":\"high\",\"bandwidth\":5000000,\"resolution\":\"1280x720\",\"segmentsDir\":\"stream/high/\"}],\"playlistType\":\"vod\"}",
    "transformers": ["hlsStreamTransformer"]
  }
}

__files/
  stream/
    low/
      segment0.ts
      segment1.ts
      segment2.ts
    mid/
      segment0.ts
      segment1.ts
      segment2.ts
    high/
      segment0.ts
      segment1.ts
      segment2.ts

{
  "priority": 1,
  "request": {
    "urlPattern": "/stream/high/.*\\.ts",
    "method": "GET"
  },
  "response": {
    "status": 503
  }
}

{
  "priority": 1,
  "scenarioName": "hls-abr",
  "requiredScenarioState": "Started",
  "request": {
    "urlPattern": "/stream/high/.*\\.ts",
    "method": "GET"
  },
  "response": {
    "status": 503
  }
}

{
  "priority": 1,
  "scenarioName": "hls-abr",
  "requiredScenarioState": "HIGH_READY",
  "request": {
    "urlPattern": "/stream/high/.*\\.ts",
    "method": "GET"
  },
  "response": {
    "status": 200
  }
}

PUT http://localhost:18080/api/http/__admin/scenarios/hls-abr/state
Content-Type: application/json

{"state": "HIGH_READY"}

{
  "request": {
    "url": "/webhook/callback",
    "method": "POST"
  },
  "response": {
    "status": 200,
    "body": "{\"event\": \"payment.completed\", \"amount\": 99.99}",
    "headers": {
      "Content-Type": "application/json"
    },
    "transformerParameters": {
      "hmacSigning": {
        "algorithm": "HmacSHA256",
        "secretKey": "my-secret-key",
        "headerName": "X-Signature"
      }
    }
  }
}

{
  "request": { "method": "GET", "url": "/avatar" },
  "response": {
    "status": 200,
    "headers": { "Content-Type": "image/png" },
    "body": "{{image width=400 height=300}}",
    "transformers": ["base64-decode-body"]
  }
}

# trafficparrot.properties
trafficparrot.http.externalprocess.enabled=true
trafficparrot.http.externalprocess.allowedDir=/opt/tp-middleware

{
  "request": {
    "url": "/api/widgets/42",
    "method": "GET"
  },
  "response": {
    "status": 200,
    "body": "{\"name\":\"widget\"}",
    "headers": { "Content-Type": "application/json" },
    "transformers": ["external-process"],
    "transformerParameters": {
      "external-process": {
        "executable": "/opt/tp-middleware/uppercase-body.py",
        "args": [],
        "timeoutMs": 5000,
        "onError": "fail-open"
      }
    }
  }
}

{
  "meta": {
    "contractVersion": "1",
    "protocol": "http",
    "transformer": "external-process",
    "mappingId": "<stub uuid>"
  },
  "request": {
    "method": "GET",
    "url": "/api/widgets/42",
    "headers": { "Accept": ["application/json"] },
    "body": "",
    "bodyEncoding": "identity"
  },
  "response": {
    "status": 200,
    "headers": { "Content-Type": ["application/json"] },
    "body": "{\"name\":\"widget\"}",
    "bodyEncoding": "identity"
  }
}

#!/usr/bin/env python3
import json, sys

env = json.load(sys.stdin)
resp = env["response"]
if resp.get("bodyEncoding", "identity") == "identity":
    resp["body"] = resp.get("body", "").upper()
resp.setdefault("headers", {})["X-Transformed-By"] = ["uppercase-body.py"]
json.dump(env, sys.stdout)