Operations on HTTP transactions.
Use this when a user needs to create or select a HTTP transaction.
DSL type field is mandatory and must be set to "HTTP".
1. General Rules:
- If redirect url is required in transaction creation or update, provide it as a redirectUrl field in dsl,
not as a matcher.
- Assign intermediate values with {{#assign "varName"}}{{value}}{{/assign}}.
- Keep JSON objects outside helper calls; helpers should only produce values.
- A helper's output is inserted as raw text, so inside JSON wrap string values in quotes,
e.g. {"id": "{{jsonPath request.body '$.id'}}"} - without the quotes the response is invalid JSON.
- Do not nest helpers more than 1–2 levels deep.
- Each helper must have exactly one opening and one closing brace; do not add extra # or braces.
- Use handlebars helpers supported by wiremock, specified in https://wiremock.org/docs/response-templating/
- Use validate_template and convert_template actions to validate and convert templates before using them in transaction definition.
- Dataset variables (from virtual_services_test_data) are referenced with ${fieldName} syntax, NOT Handlebars.
${fieldName} is not a wildcard and does not capture request values: without a dataset it is
matched as literal text. To accept any value for a field use a path matcher with matching(.+),
e.g. [[$.id, matching(.+)]]; to put a request value into the response use Handlebars.
Matcher name rules — MUST follow exactly:
* URL path with ${fieldName}: matcherName MUST be "equals_url". NEVER use "matches_url" with variables.
* Headers / query params / cookies: matcherName must be "equals" or "equals_insensitive" only.
"contains", "matches", "not_matches" do NOT work with dataset variables.
* Body plain text: matcherName "equals"
* Body JSON: "equals_json" (embed as value e.g. {"id": "${id}"}) and "equals_xml" are the
ONLY body matchers that get an auto-populated sampleBody (backend mirrors matchingValue into it).
"matches_json" with equalTo() e.g. [[$.field, equalTo(${id})]] does NOT get a sampleBody.
If a request payload is referenced anywhere in the prompt, default to "equals_json"/"equals_xml"
for that body matcher unless there is a specific reason to use a JSONPath-style matcher —
sample bodies on transactions are important to preserve.
* Body XML: matcherName "equals_xml" or "matches_xml" with matching() helper
* Path matchers ("matches_json" JSONPath, "matches_xml" XPath): the value must be exactly ONE pair
[[<path>, fn(arg)]], where fn is equalTo(value) (exact string match) or matching(regex).
No other function is accepted (not contains, containsString, matches, ...).
Write the argument WITHOUT quotes: quotes are not stripped and would be matched literally.
Example: [[$.messages[0].content, matching(You are a friendly AI assistant.*)]]
For "anything after X" use matching(X.*).
To check several paths, create one matcher per path: extra pairs inside a single matcher
are NOT evaluated.
* matchingValue for body matchers is supplied as plain text; the tool base64-encodes it
automatically on create/update and decodes it back on read/list — never pre-encode it yourself.
* sampleBody (on a body matcher) is optional and settable directly as plain text if you want a
display value different from matchingValue; it is likewise base64-encoded/decoded by the tool.
* Response content: base64-encode the string containing ${fieldName} — resolves at runtime.
Extra rules:
* Same variable used multiple times (path + header + body) must match the SAME value in the request.
* Undefined variables are treated as literal strings — request must contain the exact text "${varName}".
- IMPORTANT: When a transaction DSL contains Handlebars templates, always use
create_and_test instead of create. A transaction is only complete when sandbox
returns matched=true for all test cases. If matched=false, read mismatch_reasons,
fix the DSL with update, re-init with virtual_services_sandbox init, then re-test with virtual_services_sandbox test_request.
Actions:
- read: Read an HTTP Transaction. Get the information of a transaction.
args(dict): Dictionary with the following required parameters:
workspace_id (int): Mandatory. The id of the workspace to list transactions from.
id (int): Mandatory. The id of the transaction to get information.
- list: List all HTTP transactions.
args(dict): Dictionary with the following required parameters:
workspace_id (int): Mandatory. The id of the workspace to list transactions from.
serviceId (int): Optional. The id of the service to list transactions from. Without this it will list all transactions in the workspace.
virtual_service_id (int): Optional. The id of the virtual service to list transactions from. Without this it will list all transactions in the workspace.
limit (int, default=10, valid=[1 to 50]): The number of transactions to list.
offset (int, default=0): Number of transactions to skip.
- validate_template: Validate template. Validates template used in transaction definition.
args:
template (str): Mandatory. The handlebars template to validate.
- convert_template: Convert template. Converts template to blazemeter format.
args:
template (str): Mandatory. The handlebars template to validate.
encode (bool, default=True): Whether to encode the converted template to Base64.
- create_and_test: Create a new HTTP transaction and immediately validate it in sandbox.
Use this instead of `create` when the DSL contains Handlebars templates.
A transaction is only complete when sandbox returns matched=true for all test cases.
On all-fail: error contains the failure summary; transaction still exists — use update to fix the DSL,
then re-init with virtual_services_sandbox init and re-test with virtual_services_sandbox test_request.
On partial fail: warning lists failures; transaction still exists.
Same sampleBody placement and plain-text/no-pre-encoding rules as `create` apply here — see `create`.
args:
name (str): Mandatory. The name of the transaction.
serviceId (int): Mandatory. The id of the service.
dsl (GenericDsl): Mandatory. The DSL definition.
workspace_id (int): Mandatory. The id of the workspace.
delay (int): Optional. Response delay in milliseconds.
test_cases (list[SandboxRequest]): Mandatory. At least one test request.
Each entry has: method (str), path (str), name (str),
queryParameters (list, optional), headers (list, optional),
body (str, optional): the request body as plain text - the tool base64-encodes it;
never pre-encode it.
sampleBody (str): Optional. Fallback only — prefer setting sampleBody on the body matcher itself.
Returns:
info: ["transaction_id=<id>", "tests_passed=<n>", "tests_total=<n>"]
result: List of SandboxResponse per test case.
result[].matched: True if the test request matched the transaction.
result[].body: Decoded response body (plain text or JSON).
result[].mismatch_reasons: Why the request did not match (when matched=False).
error: All test cases failed, or creation/sandbox init failed.
On sandbox init failure, info still contains transaction_id so the transaction can be recovered.
warning: Some (not all) test cases failed.
- create: Create a new HTTP transaction.
Important: before using template in transaction definition validate it and
convert it first using validate_template and convert_template actions.
IMPORTANT — sampleBody placement: put it INSIDE the body matcher object, not as a
top-level sibling of name/dsl/workspace_id.
Correct shape:
dsl.requestDsl.body = [
{"key": "body", "matcherName": "equals_json",
"matchingValue": "{\"foo\": \"bar\"}",
"sampleBody": "{\"foo\": \"bar\"}"}
]
matchingValue and sampleBody are ALWAYS supplied as plain text. Do NOT base64-encode
them yourself before calling this tool (e.g. do not run a manual base64 command on the
payload first) — this tool base64-encodes them on create/update and decodes them back
on read/list automatically. Pre-encoding yourself causes a double-encoded value.
A top-level `sampleBody` arg is also accepted as a defensive fallback: it is applied to
any body matcher missing its own sampleBody, and if there is no body matcher at all to
attach it to, the response comes back with a warning saying so. The per-matcher
placement above is still the correct, primary way; do not rely on the fallback.
args(Transaction): A Transaction object with the following fields:
name (str): Mandatory. The name of the transaction.
serviceId (int): Mandatory. The id of the service to create the transaction in.
dsl (GenericDsl): Mandatory. The DSL definition of the transaction.
workspace_id (int): Mandatory. The id of the workspace.
delay (int): Optional. Response delay in milliseconds.
sampleBody (str): Optional. Fallback only — prefer setting sampleBody on the body matcher itself.
- update: Updates a certain transaction.
Important: before using template in transaction definition validate it and
convert it first using validate_template and convert_template actions.
Same sampleBody placement and plain-text/no-pre-encoding rules as `create` apply here.
args(Transaction): A Transaction object with the following fields:
id (int): Mandatory. The id of the transaction.
name (str): Mandatory. The new name of the transaction.
dsl (GenericDsl): Mandatory. The DSL definition of the transaction.
workspace_id (int): Mandatory. The id of the workspace.
delay (int): Optional. Response delay in milliseconds.
sampleBody (str): Optional. Fallback only — prefer setting sampleBody on the body matcher itself.
- assign_keystore: Assign keystore asset to the transaction.
args(dict):
id (int): Mandatory. The id of the transaction.
asset_id (int): Mandatory. The id of the keystore asset to assign.
alias (str): Mandatory. The certificate alias to use.
workspace_id (int): Mandatory. The id of the workspace.
- assign_certificate: Assign certificate asset to the transaction.
args(dict):
id (int): Mandatory. The id of the transaction.
asset_id (int): Mandatory. The id of the certificate asset to assign.
workspace_id (int): Mandatory. The id of the workspace.
Transaction Schema (including full GenericDsl with RequestDsl and ResponseDsl):
{'$defs': {'AssignedAsset': {'properties': {'assetId': {'description': 'The identifier of the asset', 'title': 'Assetid', 'type': 'integer'}, 'assetUsageType': {'description': 'The usage type of the asset', 'title': 'Assetusagetype', 'type': 'string'}, 'alias': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'default': None, 'description': 'The asset certificate alias', 'title': 'Alias'}}, 'required': ['assetId', 'assetUsageType'], 'title': 'AssignedAsset', 'type': 'object'}, 'GenericDsl': {'additionalProperties': True, 'properties': {'requestDsl': {'$ref': '#/$defs/RequestDsl', 'description': 'Request DSL for the transaction request matching'}, 'responseDsl': {'$ref': '#/$defs/ResponseDsl', 'description': 'Response DSL for the transaction response matching'}, 'redirectUrl': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'default': None, 'description': 'Redirect URL for the transaction', 'title': 'Redirecturl'}, 'type': {'default': 'HTTP', 'description': "The type of the transaction. Supported value is 'HTTP'.", 'title': 'Type', 'type': 'string'}}, 'required': ['requestDsl', 'responseDsl'], 'title': 'GenericDsl', 'type': 'object'}, 'HttpHeader': {'additionalProperties': True, 'properties': {'name': {'description': 'HTTP header name', 'title': 'Name', 'type': 'string'}, 'value': {'description': 'HTTP header value', 'title': 'Value', 'type': 'string'}}, 'required': ['name', 'value'], 'title': 'HttpHeader', 'type': 'object'}, 'MatcherDsl': {'additionalProperties': True, 'properties': {'key': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'default': None, 'description': "Matcher key. For URL matchers has static value 'url', for header matchers - header name, for body matchers static name 'body', for query parameter matchers - query parameter name", 'title': 'Key'}, 'matcherName': {'description': "The name of the matcher. Supported values for URL matchers: 'matches_url', 'equals_url'. Supported values for header/query matchers: 'equals', 'equals_insensitive', 'contains', 'matches', 'not_matches', 'absent'. Supported values for body matchers: 'equals', 'equals_insensitive', 'contains', 'matches', 'not_matches', 'absent', 'equals_json', 'equals_xml', 'matches_json', 'matches_xml', 'matches_xml_schema', 'matches_xml_cdata'.", 'title': 'Matchername', 'type': 'string'}, 'matchingValue': {'description': "Value to match against. Not used for 'absent' matcher_name. ", 'title': 'Matchingvalue', 'type': 'string'}, 'optional': {'default': False, 'description': 'If true, the matcher is optional and does not need to be present to match.', 'title': 'Optional', 'type': 'boolean'}, 'namespaces': {'anyOf': [{'items': {'$ref': '#/$defs/XmlMatcherNamespace'}, 'type': 'array'}, {'type': 'null'}], 'default': None, 'description': "Namespaces used for XML matching. Only used if matcher_name is one of 'equals_xml', 'matches_xml', 'matches_xml_schema', 'matches_xml_cdata'.", 'title': 'Namespaces'}, 'cdataXpath': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'default': None, 'description': "CDATA XPath expression used for XML CDATA matching. Only used if matcher_name is 'matches_xml_cdata'.", 'title': 'Cdataxpath'}, 'sampleBody': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'default': None, 'description': "Human-readable request body shown for display purposes on a body matcher. The backend auto-populates this from matchingValue for 'equals_json'/'equals_xml' body matchers. It can also be set explicitly on other body matchers, e.g. 'matches_json' (verified against the live backend).", 'title': 'Samplebody'}}, 'required': ['matcherName', 'matchingValue'], 'title': 'MatcherDsl', 'type': 'object'}, 'RequestDsl': {'additionalProperties': True, 'properties': {'method': {'default': 'GET', 'description': "HTTP method of the request for the transaction request matching. Uppercase, e.g., 'GET', 'POST'", 'title': 'Method', 'type': 'string'}, 'path': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'default': None, 'description': "Mandatory.Path of the request for the transaction request matching. E.g., '/api/v1/resource'. Used instead of matcher_name for URL matcher definition. Important: Should have same value as url.matchingValue.", 'title': 'Path'}, 'url': {'$ref': '#/$defs/MatcherDsl', 'default': None, 'description': 'Mandatory. Matcher definition for the full URL of the request'}, 'headers': {'anyOf': [{'items': {'$ref': '#/$defs/MatcherDsl'}, 'type': 'array'}, {'type': 'null'}], 'default': [], 'description': 'List of matchers for the headers of the request', 'title': 'Headers'}, 'queryParams': {'anyOf': [{'items': {'$ref': '#/$defs/MatcherDsl'}, 'type': 'array'}, {'type': 'null'}], 'default': [], 'description': 'List of matchers for the query parameters of the request', 'title': 'Queryparams'}, 'body': {'anyOf': [{'items': {'$ref': '#/$defs/MatcherDsl'}, 'type': 'array'}, {'type': 'null'}], 'default': [], 'description': 'List of matchers for the body of the request', 'title': 'Body'}}, 'title': 'RequestDsl', 'type': 'object'}, 'ResponseDsl': {'additionalProperties': True, 'properties': {'status': {'description': 'HTTP status code of the response for the transaction response matching. E.g., 200, 404.', 'title': 'Status', 'type': 'integer'}, 'headers': {'anyOf': [{'items': {'$ref': '#/$defs/HttpHeader'}, 'type': 'array'}, {'type': 'null'}], 'default': [], 'description': 'List of response headers', 'title': 'Headers'}, 'content': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'default': None, 'description': 'Body of the response. Plain text is accepted and base64-encoded by the tool; values that are already base64 (e.g. convert_template output) are kept as-is.', 'title': 'Content'}, 'statusCodeConditions': {'anyOf': [{'items': {'$ref': '#/$defs/StatusCodeCondition'}, 'type': 'array'}, {'type': 'null'}], 'default': [], 'description': 'Status code conditions for the response', 'title': 'Statuscodeconditions'}}, 'required': ['status'], 'title': 'ResponseDsl', 'type': 'object'}, 'StatusCodeCondition': {'additionalProperties': True, 'properties': {'status': {'default': 200, 'description': 'Status code', 'title': 'Status', 'type': 'integer'}, 'statusMessage': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'default': 'OK', 'description': 'HTTP header name', 'title': 'Statusmessage'}, 'matcher': {'$ref': '#/$defs/MatcherDsl', 'description': 'Condition matcher'}}, 'required': ['matcher'], 'title': 'StatusCodeCondition', 'type': 'object'}, 'XmlMatcherNamespace': {'properties': {'prefix': {'description': 'XML namespace prefix.', 'title': 'Prefix', 'type': 'string'}, 'uri': {'description': 'XML namespace URI.', 'title': 'Uri', 'type': 'string'}}, 'required': ['prefix', 'uri'], 'title': 'XmlMatcherNamespace', 'type': 'object'}}, 'additionalProperties': True, 'properties': {'id': {'default': None, 'description': 'The unique identifier of the transaction', 'title': 'Id', 'type': 'integer'}, 'name': {'description': 'The name of the transaction', 'title': 'Name', 'type': 'string'}, 'serviceId': {'anyOf': [{'type': 'integer'}, {'type': 'null'}], 'default': None, 'description': 'The unique identifier of the service where the transaction belongs', 'title': 'Serviceid'}, 'dsl': {'$ref': '#/$defs/GenericDsl', 'description': 'Transaction DSL'}, 'assets': {'anyOf': [{'items': {'$ref': '#/$defs/AssignedAsset'}, 'type': 'array'}, {'type': 'null'}], 'default': None, 'description': 'List of assets', 'title': 'Assets'}}, 'required': ['name', 'dsl'], 'title': 'HttpTransaction', 'type': 'object'}
