This pageapplies toApigee andApigee hybrid.

View Apigee Edge documentation.

This topic discusses how to use message templates in API proxies and provides a functionreference.

What is a message template?

Amessage template permits you to performvariable string substitution incertain policy and<TargetEndpoint> elements. This feature, where supported,lets you populate strings dynamically when a proxy executes.

You can include any combination of flow variable references and literal text in a messagetemplate. Flow variable names must be enclosed in curly braces, while any text not in curly bracesis output as literal text.

See alsoWhere can you use messagetemplates?

Example

For example, theAssignMessage policy lets you use a message template within in the<Payload> element:

<AssignMessagename="AM-set-payload-with-dynamic-content"><Set><PayloadcontentType="application/json">{"name":"Alert","message":"You entered an invalid username: {user.name}"}</Payload></Set><IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables></AssignMessage>

In the above example, the value of flow variableuser.name (in curly braces) will beevaluated and substituted into the payload string at runtime. So, for example, ifuser.name=jdoe,then the resulting message output in the payload will be:You entered an invalid username:jdoe. If the variable cannot be resolved, then an empty string is output.

Example

When a quota is exceeded, it is a good practice to return a meaningful message to the caller. Thispattern is commonly used with a "fault rule" to provide output to give the caller informationabout the quota violation. In the followingAssignMessage policy, message templates are usedto populate quota information dynamically in several XML elements:

<AssignMessagename='AM-QuotaViolationMessage'><Description>messageforquotaexceeded</Description><IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables><Set><Headers><Headername='X-Quota-Reset'>{ratelimit.Quota-1.expiry.time}</Header><Headername='X-Quota-Allowed'>{ratelimit.Quota-1.allowed.count}</Header><Headername='X-Quota-Available'>{ratelimit.Quota-1.available.count}</Header></Headers><PayloadcontentType='application/json'>{"error":{"message":"you have exceeded your quota","clientId":"{request.queryparam.apikey}"}}</Payload><StatusCode>429</StatusCode></Set></AssignMessage>

In theAssignMessage policy, the following elements in the<Set>element support message templating:

• <Header>
• <QueryParam>
• <FormParam>
• <PayLoad>
• <Version>
• <Verb>
• <Path>
• <StatusCode>

Again, note that flow variables in a message templatemust be enclosed in curlybraces.

When this policy executes:

• The<Header> elements receive values of the specified flow variables.
• The Payload includes a mix of literal text and variables (theclient_id is populated dynamically).
• The<StatusCode> only includes literal text; however, this element also supports message templating if you want to use it.

Example

In a proxy<TargetEndpoint> definition, child-elements of<SSLInfo> support message templating. Following the same pattern used inpolicies, the flow variables in curly braces are replaced when the proxy executes.

<TargetEndpointname="default">...<HTTPTargetConnection><SSLInfo><Enabled>{myvars.ssl.enabled}</Enabled><ClientAuthEnabled>{myvars.ssl.client.auth.enabled}</ClientAuthEnabled><KeyStore>{myvars.ssl.keystore}</KeyStore><KeyAlias>{myvars.ssl.keyAlias}</KeyAlias><TrustStore>{myvars.ssl.trustStore}</TrustStore></SSLInfo></HTTPTargetConnection>...</TargetEndpoint>

Where can you use message templates?

Message templates are supported in severalpoliciesas well as certain elementsused in theTargetEndpoint configuration.

Enclose variable names in curly braces{ }. If the variable does not exist, an empty string is returned in the output; however, you can specify default values in message templates (values that are substituted if the variable is unresolved). SeeSetting default values in message templates.

Note that enclosing the entire message template string in quotes is permitted, but optional. Forexample, the following two message templates are equivalent:

<Set>  <Headers>    <Header name="x-h1">"Hello {user.name}"</Header>    <Header name="x-h1">Hello {user.name}</Header>  </Headers></Set>

Spaces are not allowed in function expressions

Spaces are not allowed anywhere in message template function expressions. For example:

Allowed:

{substring(alpha,0,4)}{createUuid()}{randomLong(10)}

Not Allowed:

{substring( alpha, 0, 4 )}{ createUuid( ) }{randomLong( 10 )}

Nested functions are not supported

Calling a function within another function in a template is not supported. For example, you cannot use:

{substring({timeFormat('yyyy-MM-dd','1494390266')},0,4)}

Enclose string literals in template functions in single quotes

When providing string literals in functions, enclose them in single quotes rather than double quotes.

{replaceAll('BEARER: 1234','^Bearer ','TOKEN:')}

Avoid using special characters in string literals

Avoid special characters, such as ':', '/', '\', '<', or '>', in string literals. These characters can cause errors. If a string literal requires special characters, assign the value to a variable using a Python or JavaScript policy and then use the variable in the template.

Setting default values in messagetemplates

If a templated variable can't be resolved, Apigee substitutes an empty string. However, you canspecify a default value as follows:

<Header name="x-h1">Test message. id = {request.header.id:Unknown}</Header>

In the above sample if the variablerequest.header.id cannot be resolved then itsvalue is replaced byUnknown. For example:

Test message. id = Unknown

URL templating

TheURL element supports templating following the same syntax as other elements.

This example shows a URL constructed using variables:

<URL>{targeturl}</URL>

This example shows a default value for the protocol:

<URL>{protocol:https}://{site:google.com}/path</URL>

Legacy syntax for JSON payloads

In Apigee versionsbefore Cloud release 16.08.17, you couldnotuse curly braces to denote variable references within JSON payloads. In those older versions, youneeded to use thevariablePrefix andvariableSuffix attributes to specifydelimiter characters, and use those to wrap variable names, like so:

<Set><PayloadcontentType="application/json"variablePrefix="@"variableSuffix="#">{"name":"foo","type":"@variable_name#"}</Payload></Set>

Although Apigee recommends that you use the newer curly-brace syntax, the older syntax stillworks.

Using message template functions

Apigee provides a set of functions that you can use within message templates to escape, encode, hash,and format string variables, as described below.

Example: toLowerCase()

Use the built-intoLowerCase() function to transform a string variable to lowercase:

<AssignMessagename="AM-Set-Custom-Response"><AssignTocreateNew="false"type="response"/><IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables><Set><Headers><Headername="x-h1">Testheader:{toLowerCase(foo.bar:FOO)}</Header></Headers></Set></AssignMessage>

If thefoo.bar flow variable resolves, then its characters will be all lowercase.Iffoo.bar is unresolved then the default valueFOO is substituted andconverted to lowercase characters. For example:

Test header: foo

Example: escapeJSON()

Here's an interesting use case: Let's say your backend app returns a JSON response that containsvalid escape characters. For example:

{  "code": "INVALID",  "user_message": "Invalid value for \"logonId\" check your input."}

Then, let's say you want to return this message to the client caller in a custom payload. The usualway to do this is to extract the message from the target response payload and use AssignMessageto add it to a custom proxy response (that is, send it back to the client).

Here's theExtractVariables policy that extracts theuser_message information into avariable calledstandard.systemMessage:

<ExtractVariablesname="EV-BackendErrorResponse"><DisplayName>EV-BackendErrorResponse</DisplayName><JSONPayload><Variablename="standard.systemMessage"><JSONPath>$.user_message</JSONPath></Variable></JSONPayload></ExtractVariables>

Now, here's a perfectly validAssignMessage policy that adds the extracted variable to theresponse payload (the proxy response):

<AssignMessagename="AM-SetStandardFaultResponse"><DisplayName>AM-SetStandardFaultResponse</DisplayName><Set><PayloadcontentType="application/json">{"systemMessage":"{standard.systemMessage}"}</Payload></Set><IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables><AssignTo>response</AssignTo></AssignMessage>

Unfortunately, there's a problem. TheExtractVariables policy removed the escaped quotationcharacters around part of the message. This means that the response returned to the client isinvalid JSON. This is clearly not what you intended!

{  "systemMessage": "Invalid value for "logonId" check your input."}

To work around this problem, you can modify the AssignMessage policy to use amessage template function that escapes the quotes within the JSON for you. Thisfunction,escapeJSON(), escapes any quotes or other special characters that occurwithin a JSON expression:

<AssignMessagename="AM-SetStandardFaultResponse"><DisplayName>AM-SetStandardFaultResponse</DisplayName><Set><PayloadcontentType="application/json">{"systemMessage":"{escapeJSON(standard.systemMessage)}"}</Payload></Set><IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables><AssignTo>response</AssignTo></AssignMessage>

The function escapes the embedded quotes, resulting in valid JSON, which is exactly what youwanted:

{  "systemMessage": "Invalid value for \"logonId\" check your input.",}

A message template is a dynamic string substitution feature that you can use in certain policies andin<TargetEndpoint> definitions. Message templatefunctions let you perform useful operationssuch as hashing, string manipulation, character escaping, and others within a message template.

For example, in the following AssignMessage policy, the functiontoLowerCase() isused in a message template:

<AssignMessage name="AM-Set-Custom-Response">  <AssignTo>response</AssignTo>  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>  <Set>   <Headers>     <Header name="x-h1">Test header: Hello, {toLowerCase(user.name)}</Header>   </Headers>  </Set></AssignMessage>

This section describes the message template functions, their arguments, and outputs. This topic assumesthat you are familiar with message templates and the contexts in which they are used.

Hash functions

Compute a hash value and return the string representation of that hash.

Hexadecimal hash functions

Compute a hash value and return the string representation of that hash as a hexadecimal number.

Syntax

Arguments

string: The Hash functions take a single string argument upon which the hash algorithmis computed. The argument can be a literal string(enclosed in single quotes) or a string flowvariable.

Examples

Function call:

sha256Hex('abc')

Result:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

Function call:

varstr='abc';sha256Hex(str)

Result:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

Base64 hash functions

Compute a hash value and return the string representation of that hash as a Base64 encoded value.

Syntax

Arguments

string: The Hash functions take a single string argument upon which the hash algorithm is computed. The argument can be a literal string (enclosed in single quotes) or a string flow variable.

Examples

Function call:

sha256Base64('abc')

Result:

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

Function call:

varstr='abc';sha256Base64(str)

Result:

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

String functions

Perform operations on strings within a message template.

Base64 encoding functions

Encode and decode strings using the Base64 encoding scheme.

Syntax

Arguments

string: The string to encode or decode. Can be a literal string(enclosed in single quotes) or a string flowvariable.

Example

<AssignMessagename="AM-Set-Custom-Response"><AssignTocreateNew="false"type="response"/><IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables><Set><Headers><Headername="x-h1">Hello,{decodeBase64('d29ybGQK')}</Header></Headers></Set></AssignMessage>

string: The string to convert. Can be a literal string(enclosed in single quotes) or a string flowvariable.

Example

<AssignMessagename="AM-Set-Custom-Response"><AssignTocreateNew="false"type="response"/><IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables><Set><Headers><Headername="x-h1">Hello,{toLowerCase(user.name)}</Header></Headers></Set></AssignMessage>

Substring function

Returns the characters between the starting and ending index of the specified string.

Syntax

substring(str,start_index,end_index)

Arguments

• str: A literal string (enclosed in single quotes) or string flow variable.
• start_index: The starting index into the string.
• end_index: (Optional) The ending index into the string. If not supplied, ending index is the end of the string.

Examples

For the following examples, suppose that these flow variables exist:

Here are results of function calls that use these variables:

Replace All function

Applies a regular expression to a string and for any matches, replaces the match with a replacement value.

Syntax

replaceAll(string,regex,value)

Arguments

• string - A literal string (enclosed in single quotes) or string flow variable in which to make replacements.
• regex - A regular expression.
• value - The value to replace all regex matches within the string.

Examples

For the following examples, suppose these flow variables exist:

Here are results of function calls that use these variables:

Replace First function

Replaces only the first occurrence of the specified regular expression match in the string.

Syntax

replaceFirst(string,regex,value)

Arguments

• string: A literal string (enclosed in single quotes) or string flow variable in which to make replacements.
• regex: A regular expression.
• value: The value to replace regex matches within the string.

Character escape and encoding functions

Functions that escape or encode special characters in a string.

Syntax

Arguments

string: The string to escape. Can be a literal string(enclosed in single quotes)or a string flow variable.

Usage notes

XML 1.1 can represent certain control characters, but it cannot represent the null byte orunpaired Unicode surrogate codepoints, even after escaping. TheescapeXML11() functionremoves characters that do not fit in the following ranges:

[#x1-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF]

TheescapeXML11() function escapes characters in the following ranges:

[#x1-#x8] | [#xB-#xC] | [#xE-#x1F] | [#x7F-#x84] | [#x86-#x9F]

Examples

Assume a flow variable calledfood exists with this value:"bread"& "butter". Then, the function:

{escapeHTML(food)}

Results in:

"bread" & "butter"

Time format functions

Return a string representation of the time, formatted in UTC.

Syntax

Arguments

• format: A date/time format string. Can be a literal string (enclosed in single quotes) or a string variable. Use a variable instead of a literal when the format includes a colon. See the previous note in this section.
• str: A string or string flow variable containing a time value. The value can be in seconds-since-epoch or milliseconds-since-epoch for timeFormatMs.

Examples

Assume the following values and assume the local timezone is Pacific:

• epoch_time_ms = 1494390266000
• epoch_time = 1494390266
• fmt1 = yyyy-MM-dd
• fmt2 = yyyy-MM-dd HH-mm-ss
• fmt3 = yyyyMMddHHmmss

The functions return the following results:

HMAC calculation functions

The HMAC calculation functions provide an alternative to using theHMAC policy to compute an HMAC. The functions are handy when performing a cascaded HMAC calculation, as when the output of one HMAC is used as the key for a second HMAC.

Syntax

Arguments

• key - (Required) Specifies the secret key, encoded as a string, used to compute the HMAC.
• valueToSign - (Required) Specifies the message to sign. It should be a string.
• keyencoding - (Optional) The secret key string will be decoded according to this specified encoding. Valid values:hex,base16,base64,utf-8. Default:utf-8
• outputencoding - (Optional) Specifies the encoding algorithm to use for the output. Valid values:hex,base16,base64. The values are case insensitive;hex andbase16 are synonyms. Default:base64

Examples

This example uses the AssignMessage policy to compute an HMAC-256 and assign it to a flow variable:

<AssignMessage name='AM-HMAC-1'>  <AssignVariable>    <Name>valueToSign</Name>    <Template>{request.header.apikey}.{request.header.date}</Template>  </AssignVariable>  <AssignVariable>    <Name>hmac_value</Name>    <Template>{hmacSha256(private.secretkey,valueToSign)}</Template>  </AssignVariable></AssignMessage>

This example illustrates how to generate a cascading HMAC that can be used with theAWS Signature v4 signing process. The example uses the AssignMessage policy to generate the five levels of cascaded HMAC used to calculate a signature for AWS Signature v4:

<AssignMessagename='AM-HMAC-AWS-1'><!--1--><AssignVariable><Name>DateValue</Name><Template>{timeFormatUTCMs('yyyyMMdd',system.timestamp)}</Template></AssignVariable><!--2--><AssignVariable><Name>FirstKey</Name><Template>AWS4{private.secret_aws_access_key}</Template></AssignVariable><!--3--><AssignVariable><Name>DateKey</Name><Template>{hmacSha256(FirstKey,DateValue,'utf-8','base16')}</Template></AssignVariable><!--4--><AssignVariable><Name>DateRegionKey</Name><Template>{hmacSha256(DateKey,aws_region,'base16','base16')}</Template></AssignVariable><!--5--><AssignVariable><Name>DateRegionServiceKey</Name><Template>{hmacSha256(DateRegionKey,aws_service,'base16','base16')}</Template></AssignVariable><!--6--><AssignVariable><Name>SigningKey</Name><Template>{hmacSha256(DateRegionServiceKey,'aws4_request','base16','base16')}</Template></AssignVariable><!--7--><AssignVariable><Name>aws4_hmac_value</Name><Template>{hmacSha256(SigningKey,stringToSign,'base16','base16')}</Template></AssignVariable></AssignMessage>

Other functions

Create UUID function

Generates and returns a UUID.

Syntax

createUuid()

Arguments

None.

Example

{createUuid()}

Sample result:

ec3ca9be-d1e1-4ef4-aee4-4a58f3130db8

Random Long Generator function

Returns a random long integer.

Syntax

randomLong(args)

Arguments

• If no arguments are specified, the function returns a random long integer, as computed by the Java SecureRandom class.
• If one argument is present, it is treated as the minimum value of the computation.
• If a second argument is present, it is treated as the maximum value of the computation.

Example

{randomLong()}

Results in something like this:

5211338197474042880

Regex text generator

Generate a text string that matches a given regular expression.

Syntax

xeger(regex)

Argument

regex: A regular expression.

Example

This example generates a seven digit string with no zeros:

xeger( '[1-9]{7}' )

Example result:

9857253

Null-coalescing function

Thefirstnonnull() function returns the value of the left-most, non-null argument.

Syntax

firstnonnull(var1,varn)

Argument

var1: A context variable.

varn: One or more context variables. You can set the right-most argument to a string to provide a fallback value (a value that will be set if none of the left-hand arguments are set).

Examples

The following table illustrates how to use the function:

XPath function

Applies an XPath expression to an XML variable.

Syntax

xpath(xpath_expression,xml_string[,datatype])

Arguments

xpath_expression: An XPath expression.

xml_string: A flow variable or string containing XML.

datatype: (Optional) Specifies the desired return type of the query. Valid valuesarenodeset,node,number,boolean, orstring. The default value isnodeset. The default is usually the right choice.

xml = "<tag><tagid>250397</tagid><readerid>1</readerid><rssi>74</rssi><date>2019/06/15</date></tag>"xpath = "/tag/tagid"

<AssignMessage>  <AssignVariable>    <Name>extracted_tag</Name>    <Template>{xpath(xpath,xml)}</Template>  </AssignVariable></AssignMessage>

<AssignMessage>  <AssignVariable>    <Name>soapns</Name>    <Value>soap:http://schemas.xmlsoap.org/soap/envelope/</Value>  </AssignVariable>  <AssignVariable>    <Name>xpathexpression</Name>    <Value>/soap:Envelope/soap:Body/*</Value>  </AssignVariable>  <AssignVariable>    <Name>extracted_element</Name>    <Template>{xpath(xpathexpression,xml,soapns)}</Template>  </AssignVariable></AssignMessage>

Rather than specify a XPath expressions with special characters as a string literal, use a variable to include that string in the function. SeeAvoid using special characters in string literals for details.

{xpath(xpathexpression,xml,ns1)}

Example 3: Specifying a desired return type

The optional third parameter passed to thexpath() function specifies the desired returntype of the query.

Some XPath queries can return numeric or boolean values. For example thecount() functionreturns a number. This is a valid XPath query:

count(//Record/Fields/Pair)

This valid query returns a boolean:

count(//Record/Fields/Pair)>0

In those cases invoke thexpath() function with a third parameter specifying thattype:

{xpath(expression,xml,'number')}{xpath(expression,xml,'boolean')}

If the third parameter contains a colon, then it is interpreted as a namespace argument.If not, then it is treated as the desired return type. In this case, if the third parameter is notone of the valid values (ignoring case), thexpath() function defaults to returning a nodeset.

JSON Path function

Evaluatesa JSON Path expression against a JSON variable.

Syntax

jsonPath(json-path,json-var,want-array)

Arguments

• (Required)json-path: (String) A JSON Path expression.
• (Required)json-var: (String) A flow variable or string containing JSON.
• (Optional)want-array: (String) If this parameter is set totrue and if the result set is an array, then all array elements are returned. If set to any other value or if this parameter is omitted, then only the zeroth element of a result set array is returned. If the result set is not an array, then this third parameter, if present, is ignored.

You can use variables for any of the arguments. If you use fixed strings,enclose them in single quotes.

Theaddressis{jsonPath('$.results[?(@.name == "Mae West")].address.line1',the_json_variable)}

{"results":[{"address":{"line1":"18250 142ND AV NE","city":"Woodinville","state":"Washington","zip":"98072"},"name":"Fred Meyer"},{"address":{"line1":"1060 West Addison Street","city":"Chicago","state":"Illinois","zip":"60613"},"name":"Mae West"}]}

The address is 1060 West Addison Street

{jsonPath('$.config.quota[?(@.operation=="ManageOrder")].appname',the_json_variable,true)}

{  "config": {    "quota": [      {        "appname": "A",        "operation": "ManageOrder",        "value": "900"      },      {        "appname": "B",        "operation": "ManageOrder",        "value": "1000"      },      {        "appname": "B",        "operation": "SubmitOrder",        "value": "800"      }    ]  }}

["A","B"]

{  "config": {    "quota": [      {        "appname": "A",        "operation": "ManageOrder",        "value": "900"      },      {        "appname": "B",        "operation": "ManageOrder",        "value": "1000"      },      {        "appname": "B",        "operation": "SubmitOrder",        "value": "800"      }    ]  }}

$.config.quota[?(@.operation=="ManageOrder")].appname

Using a variable for the query allows you to construct a query at runtime, using dynamic data. You can do that with the<AssignVariable> element within theAssignMessage policy.

For example, supposing the variableoperationname contains the valueManageOrder, the following policy will setthe_query to the query shown above.

<AssignMessage>    <AssignVariable>      <Name>the_query</Name>      <Template>$.config.quota[?(@.operation=="{operationname}")].appname</Template>    </AssignVariable>  </AssignMessage>