You can extract request values to populate responses by using data banks or inline expressions.

Using Data Banks to Extract Request Values

A Data Bank tool extracts a JSON or XML value from an incoming request so it can be used to populate an element of the associated response. You can add Data Bank tools to the incoming request of any available message responder. Data Banks are discussed extensively elsewhere in this documentation. See any of the following links to get started:

Adding Responders, Output Tools, and Validations

Data Exchange Tools

Parameterizing Tools with Data Source Values, Variables, and Extracted Values

Using Inline Expressions to Extract Request Values

You can use inline expressions to extract request values using XPath expressions. When creating your expressions, be sure to adhere to the following rules:

• Use single quotes ( ' ) only.
• Do not use curly brackets ( {} ) inside the expression or in the default value.

You can parameterize text content by using expressions that are evaluated against the incoming request by using the

${{=expression}}

syntax. Expressions written to extract, for example, the value of a name field in the incoming request could use

${{=/root/name/text()}} 

where the incoming request is an XML payload such as

<root>
   <name>my name</name>
</root>

Functions for Date-Time Manipulations

You can use functions to manipulate the date-time by establishing an offset value, either positive or negative, to shift the date or time forward or backward. The format '1y 2M 34d 567h 8m 9s' is used to specify how many years/months/days/hours/minutes/seconds to offset. These offsets can be positive or negative, any of the units can be missing, and spacing between units is ignored. For example, each of the following offsets would move the date forward one year, one month, and one day:

'1y1M1d'
'1y 1M 1d'
'+1y1M1d'

To move the date backward one year, one month, and one day instead, use a minus ( - ) prefix. For example:

'-1y1M1d' 

Date-time functions take either one or two format parameters. If different formats are needed for the input or output date-time, two parameters are used, otherwise only one format is needed. Java date formatting is used, so any of the examples shown below would be accepted:

'yyyy-dd-MM'
'ddMMyyyy'
'yyyyMMdd HH:mm'
'dd-MM-yyyy HH:mm:ss'

Sample Functions

How you create your date-time function depends on a few factors, including what date and time you want to offset from (the current time or one you specify) and whether or not you want to use the same date-time format for the input and output times.

Offset from current time

sv:date-math('offset', 'outFormat')

Offsets the current date-time and returns it in the specified format. For example,

${{=sv:date-math('-1y 2d 3h', 'yyyy-MM-dd HH:mm:ss')}}

will return a date 1 year, 2 days, and 3 hours from the current time.

Offset from specified date in the same format

sv:date-math('offset', 'format', 'date')

Offsets the specified date, in the format specified, and returns it in the same format. For example,

${{=sv:date-math('1y', 'yyyy-MM-dd', '2022-08-11')}}

will return '2023-08-11'.

Offset from specified date in a different format

sv:date-math('offset', 'outFormat', 'date', 'inFormat')

Offsets the given date, given in the inFormat specified, and returns it in the outFormat specified. For example,

${{=sv:date-math('1y', 'MM/yyyy', '2022-08-11', 'yyyy-MM-dd')}}

will return '08/2023'.

Using XPath

The parameters can also be provided as XPath expressions that resolve to the expected values. For example:

sv:date-math('1y', 'yyyy-MM-dd', /root/date/text())
sv:date-math(/root/offset/text(), 'MM/yyyy', /root/date/text(), 'yyyy-MM-dd')

All the functions are in the "sv" namespace. They can be used like other supported XPath expressions. For example:

"nextYear" : "${{=sv:date-math('1y', 'yyyy-MM-dd', /root/date/text())#2023-01-01}}"

If the function cannot evaluate something (for example, the given XPath expression does not evaluate to a value), the expression will return the default value specified, or "" if no default value is specified. For example, what the expression

"${{=sv:date-math('1y', 'yyyy-MM-dd', /root/date/text())#2000-01-01}}"

returns will depend on what date element the request payload contains. Say it contains the date element '2022-08-11', then the expression will return '2023-08-11', but if the request payload does not have a date element, the expression will return '2000-01-01' instead.

If the function cannot evaluate due to an error (for example, an invalid offset format) an error will be returned.

Functions for Extracting Information from Headers or URLs

You can use one of several supported functions to extract information from the request that is not part of the payload, specifically from the header or the URL.

Sample Functions 

You can extract the whole URL, specified path segments of the URL, or URL parameters. You can extract the header as well.

Extract the URL

sv:url()

Returns the full URL of the request's destination. For example:

"http://localhost:9080/path1/path2/?param1=val1$param2=val2"

Extract the header

sv:header('headerName')

Returns the value of that header. If there are multiple headers with the same name, they can be distinguished by index. For example,

${{=sv:header('name', 2)}}

will give the value of the second occurrence of the header "name". If there are multiple headers with the same name and you do not distinguish them by index, the value of the first occurrence will be returned.

Extract URL parameter

sv:url-parameter('parameterName')

Returns the value of that URL parameter. If there are multiple parameters with the same name, they can be distinguished by index. For example,

${{=sv:url-parameter('name', 2)}}

will give the value of the second occurrence of the URL parameter "name". If there are multiple parameters with the same name and you do not distinguish them by index, the value of the first occurrence will be returned.

Extract a URL path segment

sv:url-path(index)

Returns the URL path segment at the given index. For example,

${{=sv:url-path(0)}}

returns the first path segment. In the earlier URL example of "http://localhost:9080/path1/path2/?param1=val1$param2=val2", this would mean "path1" would be returned.

Using XPath

Parameters can also be provided as XPath expressions that resolve to the expected type. For example:

sv:header(/root/headerName/text(), /root/index/text())

All the functions are in the "sv" namespace. They can be used like other supported inline expressions. For example:

"nameValue" : "${{=sv:header('name')#foo}}"

If the function cannot evaluate as expected (for example, the specified header value is missing), the expression will return the default value specified, or "" if no default value is specified. For example, the expression,

"${{=sv:header('header1')#defaultHeader1Value}}"

will return "header1Value" if header1 is present, or "defaultHeader1Value" if it is not present.

Generating Inline Expressions for Responders

You can generate inline expressions for message responders based on the responder's request template, which makes parameterizing the response payload faster. This functionality is available for message responders using Literal, Multiple Responses, or Sequence Responses input modes.

There are a few prerequisites:

• The request template in the message responder (or in the individual multiple/sequence response) must be populated. See "Request Template" on the Message Responder Overview page for more information.
  • When setting up fixed message responders, you can configure them to automatically populate the request template by enabling the "Store request for each response" option. See Creating Fixed Message Responders from Traffic for more information.
• The request payload should contain values that match those in a response payload.
• The appropriate date-time formats have been entered in the Date Time Format preference panel. This makes it possible for string values that represent date-times to be correctly recognized and parsed. See "Date Time Format" on the Additional Preference Settings  page. 

To generate inline expressions:

1. Open the message responder.
2. Click the Response tab. If the input mode of the responder is either Multiple Responses or Sequence Responses, click the Message sub-tab.
3. Right-click inside the text box and choose Generate Inline Expressions.
   • If the input mode for the responder is either Multiple Responses or Sequence Responses, you can also right-click on a response in the left panel and choose Generate Inline Expressions.
     
4. Save your changes.