Send Docs Feedback

Assign Message policy

What

Creates or modifies HTTP request or response messages during an API proxy flow. For example, you can use this policy to modify the request message before it is sent to the target server, modify the response returned by the target server, or create a custom request or response object. You often create custom request and response objects when using a ServiceCallout policy. See Service Callout policy for more. 

You can also use this policy to create and populates new flow variables.

Where

This policy can be attached in the following locations. See the samples for specific attachment guidance in different situations.

ProxyEndpoint TargetEndpoint
    PreFlow Flow PostFlow PreFlow Flow PostFlow    
Request    
    Response
    PostFlow Flow PreFlow PostFlow Flow PreFlow    

Samples

This sample shows how to build up a custom request object with Assign Message.

<AssignMessage name="AssignMessage-3">
  <AssignTo createNew="true" type="request">request1</AssignTo>
  <Copy>
    <Headers>
     <Header name="user-agent"/>
    </Headers>
  </Copy>
  <Set>
    <QueryParams>
      <QueryParam name="address">{request.queryparam.address}</QueryParam>
    </QueryParams>
    <Verb>GET</Verb>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

It's a common use case to build up a custom request object using Assign Message, and then send it to a backend target using the Service Callout policy. This sample:

  • Creates a new request message object called request1.
  • Copies the value of the user-agent HTTP header from the incoming request message object. Because the <Copy> element uses an absolute reference to the user-agent flow variable, there is no need to specify the source attribute to <Copy>
  • Sets a query parameter on the request1 message object.
  • Sets the HTTP verb for the request1 message object to GET.
  • Sets the IgnoreUnresolvedVariables element to false. So, if one of the variables we are trying to copy or set does not exist, processing in the API flow will stop.

You can then access the request1 object in another Assign Message policy as shown below: 

<AssignMessage name="CopyExample1ToRequest">
  <DisplayName>AccessRequest1</DisplayName>
  <AssignTo createNew="false" type="request"></AssignTo>
  <Set>
    <Headers>
      <Header name="user-agentCopyRequest1">{request1.header.user-agent}</Header>
    </Headers>
  </Set>
</AssignMessage>

Here's another example demonstrating how to create a custom request object with Assign Message.

<AssignMessage name="AssignMessage-2">
  <AssignTo createNew="true" type="request">partner.request</AssignTo>
  <Set>
    <Verb>POST</Verb>
    <Payload contentType="text/xml">
      <request><operation>105</operation></request>
    </Payload>
  </Set>
</AssignMessage>

To work with message content, Assign Message defines a set of elements that enable you to populate or modify HTTP headers, query parameters, and XML or JSON payload content. This sample policy creates a new HTTP request message, and assigns that message to the variable called partner.request.

If the createNew attribute is set to false, then the policy will modify the designated message.

This sample shows how to modify an existing response object by adding a Header to it.

<AssignMessage name="assignMessage-4">
  <AssignTo createNew="false" type="response"></AssignTo>
  <Set>
    <Headers>
      <Header name="Cache-Hit">{lookupcache.LookupCache-1.cachehit}</Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

This sample Assign Message policy does not create a new message. Instead, it modifies an existing response message by adding an HTTP header. THis policy would be attached to a response flow in the API proxy. Because you omitted a variable name in the <AssignTo> tag, and specified a type as response, this policy modifies the response object returned by the target server. 

The HTTP header added to the response message by this policy is derived from a variable populated by the LookupCache policy. Therefore the response message modified by this AssignMessage policy contains an HTTP header that indicates whether the results have been pulled from the Cache or not. Setting headers in the response can be handy for debugging and troubleshooting.

This pattern of setting headers for debugging and troubleshooting is a common practice. You can see what header value was sent back by inspecting the response with the Trace tool or other means.

You can use Assign Message to embed dynamic content in the payload of XML or JSON response and request messages.

To embed Edge flow variables in an XML payload, wrap the designated variable in curly braces, like this: {prefix.name}. This sample policy embeds the value of the HTTP user-agent header flow variable in an XML element called User-agent:

<AssignMessage name="api-token-cache-hit-header">
  <AssignTo createNew="false" type="response"></AssignTo>
  <Set>
    <Payload contentType="text/xml">
      <User-agent>{request.header.user-agent}</User-agent>
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

Note: In a JSON payload, you can insert variables using the variablePrefix and variableSuffix attributes with delimiter characters as shown in the following example. As of cloud release 16.08.17, you can also use curly braces to insert variables.

<Payload contentType="application/json" variablePrefix="@" variableSuffix="#">
{
   "user-agent": "@request.header.user-agent#"
}
</Payload>

This policy removes the apikey query parameter from the request.

<AssignMessage name="AssignMessage-1">
  <AssignTo createNew="false" type="request"></AssignTo>
  <Remove>
    <QueryParams>
      <QueryParam name='apikey'/>
    </QueryParams>
  </Remove>
</AssignMessage>

It's a best practice to strip the apikey query parameter from the request message when you use the APIKey policy for user authentication. You do this to prevent sensitive key information from being passed to the backend target. This sample pattern is a common use case for AssignMessage. For details on APIKey, see Verify API Key policy.

This sample uses two Assign Message policies: the first sets three variables in the request and the second gets them from the request.

<AssignMessage async="false" continueOnError="false" enabled="true" name="Assign-Message-1">
  <AssignTo createNew="false" transport="http" type="request"/>
  <AssignVariable>
    <Name>appSecretSet</Name>
    <Value>abcdedl1234</Value>
  </AssignVariable>
  <AssignVariable>
    <Name>config.environmentSet</Name>
    <Value>test</Value>
  </AssignVariable>
  <AssignVariable>
    <Name>config.protocolSet</Name>
    <Value>https</Value>
  </AssignVariable>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

In this policy, use the <AssignVariable> tag to create and set three variables to a value in the request. The <Name> tag specifies the variable name, and the <Value> tag specifies the value.

In the second policy, you use the <AssignVariable> tag to read the variables and set three new variables:

<AssignMessage async="false" continueOnError="false" enabled="true" name="Assign-Message-1">
  <AssignTo createNew="false" transport="http" type="request"/>
  <AssignVariable>
    <Name>appSecretGet</Name>
    <Ref>appSecretSet</Ref>
    <Value>0</Value>
  </AssignVariable>
  <AssignVariable>
    <Name>config.environmentGet</Name>
    <Ref>config.environmentSet</Ref>
    <Value>default</Value>
  </AssignVariable>
  <AssignVariable>
    <Name>config.protocolGet</Name>
    <Ref>config.protocolSet</Ref>
    <Value>default</Value>
  </AssignVariable>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

In this example, the <Ref> tag references the source variable, and <Name> tag specifies the name of the new variable. If the variable referenced by the <Ref> tag is not accessible, use the value specified by the <Value> tag. 

In the following example, let's say that a Service Callout in is the API proxy request, and the callout response contains multiple headers of the same name (Set-Cookie). Assuming the Service Callout's resopnse variable is the default calloutResponse, the following policy gets the second Set-Cookie header value.

<AssignMessage async="false" continueOnError="false" enabled="true" name="Assign-Message-1">
  <DisplayName>Assign Message-1</DisplayName>
  <Set>
    <Payload contentType="application/json">{"Cookies from Service Callout" : "{calloutResponse.header.Set-Cookie.2}"}</Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

If you wanted to list all header values, you'd use the following variable instead:

{calloutResponse.header.Set-Cookie.values}

For more use case examples, see https://community.apigee.com/articles/11172/various-uses-of-assign-message-policy.html.


About the Assign Message policy

Use the Assign Message policy to generate or modify request or response messages during an API proxy Flow. With this policy, you can assign the verb, the payload, the status code, and more - everything pertaining to an HTTP request or response message.

Assign Message is so named because the policy requires a message to be 'assigned' to a variable. (See Variables reference for more on variables.) In the case of Assign Message, the variable holds a message - which is a complex data type with multiple fields.

To use Assign Message, you must select a variable name and specify the message content to assign to it. If you use the one of the built-in names - request or response - the message will be assigned to the request or response, respectively. If you use any other name, it refers to a custom variable that holds the message.

There are many situations in which a request or a response message must be modified during processing by Apigee Edge. For example, you might need to strip HTTP headers from a request message before the message is forwarded to the backend service. You might also need to add HTTP headers or insert JSON or XML message content before a response is sent to the consumer app. You can do both operations using the Assign Message policy type.

In other situations, you need to generate complete request or response messages. For example, you might use a ServiceCallout policy to invoke a remote API from an API proxy. You can use the AssignMessage policy to generate the request message and assign it to a variable. Then, use a ServiceCallout policy that references the variable to send that message to the remote API.

Element reference

The element reference describes the elements and attributes of the Assign Message policy.

This policy handles a number of use cases. Typically, you select which operation(s) you wish to perform with this policy and delete the rest of the elements. For example, if you know you want to do a Copy, then you can delete the Remove, Add, and other elements if you wish.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AssignMessage async="false" continueOnError="false" enabled="true" name="a_name">
    <DisplayName>a_display_name</DisplayName>
    <AssignTo createNew="false" transport="http" type="request"/>
    <Copy source="request">
        <Headers/>
        <QueryParams/>
        <FormParams/>
        <Payload/>
        <Verb/>
        <Version/>
        <StatusCode/>
        <ReasonPhrase/>
        <Path/>
    </Copy>
    <Remove>
        <Headers>
            <Header name="a_header_name"></Header>
        </Headers>
        <QueryParams>
            <QueryParam name="a_query_param_name"></QueryParam>
        </QueryParams>
        <FormParams>
            <FormParam name="a_form_param_name"></FormParam>
        </FormParams>
        <Payload> </Payload>
    </Remove>
    <Add>
        <Headers/>
        <QueryParams/>
        <FormParams/>
    </Add>
    <Set>
        <Headers/>
        <QueryParams/>
        <FormParams/>
        <Payload/>
        <Verb/>
        <Version/>
        <Path/>      
        <ReasonPhrase/>
        <StatusCode/>
    </Set>
    <AssignVariable>
        <Name>name</Name>
        <Value/>
        <Ref/>
    </AssignVariable>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

<AssignMessage> attributes

<AssignMessage async="false" continueOnError="false" enabled="true" name="Assign-Message-1">

The following attributes are common to all policy parent elements.

Attribute Description Default Presence
name

The internal name of the policy. Characters you can use in the name are restricted to: A-Z0-9._\-$ %. However, the Edge management UI enforces additional restrictions, such as automatically removing characters that are not alphanumeric.

Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.

N/A Required
continueOnError

Set to false to return an error when a policy fails. This is expected behavior for most policies.

Set to true to have flow execution continue even after a policy fails.

false Optional
enabled

Set to true to enforce the policy.

Set to false to "turn off" the policy. The policy will not be enforced even if it remains attached to a flow.

true Optional
async

This attribute is deprecated.

false Deprecated

<DisplayName> element

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>
Default:

N/A

If you omit this element, the the value of the policy's name attribute is used.

Presence: Optional
Type: String

 

<AssignTo> element

The <AssignTo> element determines the variable that the Assign Message policy operates on. The options are:

  • The request object received by the API proxy
  • The response object returned from the target server
  • A custom request or response object

For example, if you use the Assign Message policy to add a query parameter, the query parameter is added to the variable specified by the <AssignTo> element. 

If the <AssignTo> element is missing, or if the element does not explicitly specify the name of the destination variable, then the policy assigns values to either the request or response object, depending on the Flow to which the policy is attached. For example, if you attach the policy to a request Flow, the default object is the request object.

Attributes

No destination variable:

<AssignTo createNew="false" transport="http" type="request"/>

Explicit destination variable:

<AssignTo createNew="true" transport="http" type="request">destRequestObj</AssignTo>
Attribute Description Default Presence Type
createNew
If createNew is set to true, then a new variable of the type specified by type is created. If you do not specify the name of the new variable, then the policy creates a new request or response object, based on the value of type.
 
Caution: When creating a new request or response object, the existing request or response object is deleted and replaced by the new one, meaning all information in the object is lost. 
 
If createNew is false, then the policy responds in one of two ways:
  • If AssignTo can resolve the variable name to a message, then it continues processing. For example, if the policy is in a request flow, the variable is the request object. If the policy is in a response, the variable is the response object.
  • If AssignTo cannot be resolved, or resolves to a non-message type, then the policy throws an error.
If createNew is not specified, the poplicy responds in one of two ways:
  • If AssignTo resolves to a message, then processing advances to the next step.
  • If AssignTo cannot be resolved, or resolves to a non-message type, a new variable of type specified in type is created.
Optional Boolean
 
transport Specifies the transport type for the request or response message type. http (the only supported value) Optional String
type
Specifies the type of the variable.
Valid values: request or response
request Optional String

Example

For sample code and discussion, see the Modify Request tab under Samples

<Copy> element

Copies information from the message specified by the source attribute to the message object specified by this policy's <AssignTo> element.

    <Copy source="request">
        <Headers/>
        <QueryParams/>
        <FormParams/>
        <Payload> </Payload>
        <Verb/>
        <Version/>
        <StatusCode/>
        <ReasonPhrase/>
        <Path/>
    </Copy>

Default:

N/A

Presence:

Optional

Type:

String

Attributes

<Copy source="request">
Attribute Description Presence Type
source

Specifies the source object of the copy.

  • If source is not specified, it is treated as a simple message. For example, if the policy is in the request flow, then the source defaults to the request object. If the policy is in the response flow, it defaults to the response object. If you omit source, you can use an absolute reference to a flow variable as the source of the copy. For example, specify the value as {request.header.user-agent}.
  • If the source variable cannot be resolved, or resolves to a non-message type, <Copy> fails to respond.
Optional String

<Copy>/<Headers> element

Copies the specified HTTP header from the source to the message variable specified with the <AssignTo> element. To copy all headers, specify <Copy><Headers/></Copy>.

<Copy source='request'>
    <Headers>      
        <Header name="headerName"/>     
    </Headers> 
</Copy>

If there are multiple headers with the same name, use the following syntax:

<Copy source='request'>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
</Copy>

This example copies "h1", "h2", and the second value of "h3". If "h3" has only one value, then it is not copied.

Default:

N/A

Presence:

Optional

Type:

String

<Copy>/<QueryParams> element

Copies query parameters. Note that the QueryParams is copied only when both the source and AssignTo type are request. To copy all query parameters, specify <Copy><QueryParams/></Copy>. This example copies the user-agent header to the message variable specified with the <AssignTo> element:

<Copy source='request'>   
    <QueryParams>      
        <QueryParam name="paramName"/>     
    </QueryParams> 
</Copy>

If there are multiple query params with the same name, use the following syntax:

<Copy source='request'>
    <QueryParams>
      <QueryParam name="qp1"/>
      <QueryParam name="qp2"/>
      <QueryParam name="qp3.2"/>
    </QueryParams>
</Copy>

This example copies "qp1", "qp2", and the second value of "qp3". If "qp3" has only one value, then it is not copied.

Default:

N/A

Presence:

Optional

Type:

String

<Copy>/<FormParams> element

Copies the form parameters. Note that the FormParams is copied only when the contentType is source and AssignTo is application/x-www-form-urlencoded. To copy all form parameters, specify <Copy><FormParams/></Copy>. This example copies specified form parameter from the object specified in the source attribute to the variable specified in the <AssignTo> element:

<Copy source='request'> 
    <FormParams> 
        <FormParam name="paramName"/> 
    </FormParams> 
</Copy>

If there are multiple form params with the same name, use the following syntax:

<Copy source='request'>
    <FormParams>
      <FormParam name="f1"/>
      <FormParam name="f2"/>
      <FormParam name="f3.2"/>
    </FormParams>
</Copy>

This example copies "f1", "f2", and the second value of "f3". If "f3" has only one value, then it is not copied.

Default:

N/A

Presence:

Optional

Type:

String

<Copy>/<Payload> element

If true, the payload is copied from the object specified in the source attribute to the variable specified in the <AssignTo> element.

<Copy source='request'>     
    <Payload>true</Payload>      
</Copy>

Default:

false

Presence:

Optional

Type:

Boolean

<Copy>/<Version> element

If true, the HTTP version is copied from the object specified in the source attribute to the variable specified in the <AssignTo> element. 

<Copy source='request'>
    <Version>true</Version>
</Copy>

Default:

false

Presence:

Optional

Type:

Boolean

<Copy>/<Verb> element

If true, copies the verb found in the source attribute object to the variable specified in the <AssignTo> variable. The verb is assigned only when both the source and AssignTo type are request.

<Copy source='request'>
    <Verb>true</Verb>
</Copy>

Default:

false

Presence:

Optional

Type:

Boolean

<Copy>/<Path> element

Copies the path found in the source attribute object to the variable specified in the <AssignTo> variable. The path is assigned only when both the source and AssignTo type are request.

<Copy source='request'>
    <Path>true</Path>
</Copy>

Default:

false

Presence:

Optional

Type:

Boolean

<Copy>/<StatusCode> element

If true, copies the StatusCode from the object specified by the source attribute to the variable specified in the AssignType element. The StatusCode is copied only when both the source and AssignTo type are response.    

<Copy source='request'>
    <StatusCode>true</StatusCode>      
</Copy>

Default:

false

Presence:

Optional

Type:

Boolean

<Copy>/<ReasonPhrase> element

If true, copies the ReasonPhrase from the object specified by the source attribute to the variable specified in the AssignType element. The ReasonPhrase is copied only when both the source and AssignTo type are response.

<Copy source='request'>     
    <ReasonPhrase>true</ReasonPhrase>     
</Copy>

Default:

false

Presence:

Optional

Type:

Boolean

<Remove> element

Removes specified elements from the message variable specified in the <AssignTo> element of this policy. For example, a common use case is to remove a query parameter that contains sensitive information from the incoming request object, to avoid passing it to the backend server.

    <Remove>
        <Headers>
            <Header name="h1"/>
        </Headers>
        <QueryParams>
            <QueryParam name="q1"/>
        </QueryParams>
        <FormParams>
            <FormParam name="f1"/>
        </FormParams>
        <Payload></Payload>
    </Remove>

Default:

N/A

Presence:

Optional

Type:

N/A

<Remove>/<Headers> element

Removes specified HTTP headers from the message variable specified in the <AssignTo> element of this policy. To remove all the headers, specify <Remove><Headers/></Remove>. This example removes the user-agent header from the message variable specified with the <AssignTo> element.

<Remove>     
    <Headers>      
        <Header name="user-agent"/>     
    </Headers> 
</Remove>

If there are multiple headers with the same name, use the following syntax:

<Remove>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
</Remove>

This example removes "h1", "h2", and the second value of "h3". If "h3" has only one value, then it is not removed.

Default:

N/A

Presence:

Optional

Type:

String

<Remove>/<QueryParams> element

Removes specified query parameters from the message variable specified in the <AssignTo> element of this policy. To remove all query paremeters, specify <Remove><QueryParams/></Remove>.

Note: This option only works when the <AssignTo> type is request.

<Remove>     
    <QueryParams>      
        <QueryParam name="param_name"/>     
    </QueryParams> 
</Remove>

If there are multiple query params with the same name, use the following syntax:

<Remove>
    <QueryParams>
      <QueryParam name="qp1"/>
      <QueryParam name="qp2"/>
      <QueryParam name="qp3.2"/>
    </QueryParams>
</Remove>

This example removes "qp1", "qp2", and the second value of "qp3". If "qp3" has only one value, then it is not removed.

Default:

N/A

Presence:

Optional

Type:

String

Example

For more sample code and discussion, see the Modify Request tab under Samples

<Remove>/<FormParams> element

Removes specified query parameters from the message variable specified in the <AssignTo> element of this policy. To remove all form parameters, specify <Remove><FormParams/></Remove>.

Note: This option only works when the contentType of <AssignTo> element is application/x-www-form-urlencoded.

<Remove>
    <FormParams>      
        <FormParam name="form_param_name"/>     
    </FormParams> 
</Remove>

If there are multiple form params with the same name, use the following syntax:

<Remove>
    <FormParams>
      <FormParam name="f1"/>
      <FormParam name="f2"/>
      <FormParam name="f3.2"/>
    </FormParams>
</Remove>

This example removes "f1", "f2", and the second value of "f3". If "f3" has only one value, then it is not removed.

Default:

N/A

Presence:

Optional

Type:

String

<Remove>/<Payload> element

If true, the payload is cleared from the message variable specified in the <AssignTo> element. 

<Remove>
    <Payload>true</Payload>
</Remove>

Default:

false

Presence:

Optional

Type:

Boolean

<Add> element

Adds information to the message object specified with this policy's <AssignTo> element.

    <Add>
        <Headers>
            <Header name="h1">value</Header>
        </Headers>
        <QueryParams>
            <QueryParam name="q1">value</QueryParam>
        </QueryParams>
        <FormParams>
            <FormParam name="f1">value</FormParam>
        </FormParams>
    </Add>

Default:

N/A

Presence:

Optional

Type:

String

<Add>/<Headers> element

Adds the headers in the variable specified in the <AssignTo> element. Note that the empty header <Add><Headers/></Add> does not add any header. The same holds true for QueryParams and FormParams. This example adds the user-agent header to the message variable specified with the <AssignTo> element, and copies the value of the request.user.agent flow variable into the header.

<Add>     
    <Headers>      
        <Header name="user-agent">{request.user.agent}</Header>     
    </Headers> 
</Add>

Default:

N/A

Presence:

Optional

Type:

String

<Add>/<QueryParams> element

Adds specified query parameters to the message variable specified in the <AssignTo> element of this policy. Note that the empty query params, <Add><QueryParams/></Add>, does not add any query params. 

Note: This option only works when the <AssignTo> type is request.

This example adds the query param named "param_name" and assign the value 27 to it:

<Add>     
    <QueryParams>      
        <QueryParam name="param_name">27</QueryParam>     
    </QueryParams> 
</Add>

Default:

N/A

Presence:

Optional

Type:

String

<Add>/<FormParams> element

Adds specified form parameters to the message variable specified in the <AssignTo> element of this policy. Note that the empty form params, <Add><FormParams/></Add> does not add any form params. 

Note: This option only works when the contentType of <AssignTo> element is application/x-www-form-urlencoded.

This example adds the specified form parameter to the message variable specified with the <AssignTo> element, and assigns it the value of the "name" query param:

<Add>
    <FormParams>      
        <FormParam name="{my_username}">{request.queryparam.name}</FormParam>     
    </FormParams>
</Add> 

Default:

N/A

Presence:

Optional

Type:

String

<Set> element

Sets information in the message object specified in with this policy's <AssignTo> element.

    <Set>
        <Headers/>
        <QueryParams/>
        <FormParams/>
        <Payload> </Payload>
        <Verb/>
        <StatusCode/>
        <ReasonPhrase/>
        <Path/>
    </Set>

Default:

N/A

Presence:

Optional

Type:

N/A

<Set>/<Headers> element

Sets or overwrites HTTP headers in the message variable specified with the <AssignTo> element. Note that the empty header <Set><Headers/></Set> does not set any header. This example sets the user-agent header to the message variable specified with the <AssignTo> element.

<Set>     
    <Headers>      
        <Header name="user-agent">{request.header.user-agent}</Header>     
    </Headers> 
</Set>

Default:

N/A

Presence:

Optional

Type:

String

<Set>/<QueryParams> element

Sets query parameters. Note that the empty query parameter <Set><QueryParams/></Set> does not set any query parameters. This example assigns a flow variable to a query parameter called "address" to the HTTP message specified with the <AssignTo> element.

<Set>     
    <QueryParams>      
        <QueryParam name="address">{request.queryparam.address}</QueryParam>     
    </QueryParams> 
</Set>

Default:

N/A

Presence:

Optional

Type:

String

<Set>/<FormParams> element

Sets/overwrites the form parameters and the contentType of message changes to application/x-www-form-urlencoded. Note that the empty form parameter <Set><FormParams/></Set> does not set any form parameters.  This example sets the specified form parameter to the object specified in the source attribute to the variable specified in the <AssignTo> element. 

<Set>
    <FormParams>     
        <FormParam name="myparam">{request.formparam.myparam}</FormParam>     
    </FormParams>
</Set>

Default:

N/A

Presence:

Optional

Type:

String

<Set>/<Payload> element

Set a plain text payload:

<Set>     
    <Payload contentType="text/plain">test1234</Payload>      
</Set>

Set a JSON payload:

<Set>
    <Payload contentType="application/json">
        {"name":"foo", "type":"bar"}
    </Payload>
</Set>

In a JSON payload, you can insert variables using the variablePrefix and variableSuffix attributes with delimiter characters as shown in the following example. As of cloud release 16.08.17, you can also use curly braces to insert variables.

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

or, as of cloud release 16.08.17, you can also curly braces to insert variables:

<Set>
    <Payload contentType="application/json">
        {"name":"foo", "type":"{variable_name}"}
    </Payload>
</Set>

Set a mixed payload in XML:

Do not include the XML prolog in the payload; otherwise, you will get XML validation errors.

<Set>
    <Payload contentType="text/xml">
        <root>
          <e1>sunday</e1>
          <e2>funday</e2>
          <e3>{var1}</e3>
        </root>
    </Payload>
</Set>          

Default:

 

Presence:

Optional

Type:

String

Attributes

<Payload contentType="content_type" variablePrefix="char" variableSuffix="char">
Attribute Description Presence Type
contentType

If contentType is specified, its value is assigned to the contentType header.

Optional String
variablePrefix Optionally specifies the leading delimiter on a flow variable because JSON payloads cannot use the default "{" character. Optional Char
variableSuffix Optionally specifies the trailing delimiter on a flow variable because JSON payloads cannot use the default "}" character. Optional Char

<Set>/<Version> element

Sets the version. Note that the content of <Version> is treated as message template. The same holds true for Verb, Path, StatusCode, and ReasonPhrase.

<Set>     
    <Version>2.1</Version>     
</Set>

Default:

false

Presence:

Optional

Type:

Boolean

<Set>/<Verb> element

Sets the HTTP verb only when AssignTo type is request.

<Set>
    <Verb>POST</Verb>
</Set>
<Set>
    <Verb>${variable.v1}</Verb>
</Set>

Default:

false

Presence:

Optional

Type:

String (a valid HTTP verb)

<Set>/<Path> element

This element isn't currently working as designed to override/rewrite a proxy's target URL. (It does work for setting the Path in Service Callouts, as shown in the Learn by Doing example below.)

Sometimes you may need to send a message to a URL other than the URL defined in an API proxy's TargetEndpoint. If you want to rewrite the target URL, override the target.url variable in the TargetEndpoint using the AssignVariable element. (You can't override target.url in the ProxyEndpoint, because Edge sets the variable in the TargetEndpoint). The following example shows how an Assign Message policy would override target.url. Again, add the policy to the TargetEndpoint request. With this policy, the proxy would call the URL below instead of the URL defined on the TargetEndpoint.

<AssignMessage async="false" continueOnError="false" enabled="true" name="Assign-Message-1">
...
  <AssignVariable>
    <Name>target.url</Name>
    <Value>http://mocktarget.apigee.net/user?user=Dude</Value>
  </AssignVariable>
...

You can also use a JavaScript policy in the TargetEndpoint to override the target.url.

For a more advanced example of how to override the target.url from the ProxyEndpoint, see this Apigee Community article.

Learn by doing!
If you want to see a "set path" in action in a Service Callout, check out this Learn by doing example in the Apigee GitHub samples. Just clone the repository and follow the instructions in that topic. The example uses Assign Message to set a request path, then uses a Service Callout policy to make the request to an external service.

<Set>/<StatusCode> element

Sets the status code only when AssignTo type is response.

<Set>     
    <StatusCode>400</StatusCode>      
</Set>

Default:

NA

Presence:

Optional

Type:

String

<Set>/<ReasonPhrase> element

Sets the reason phrase that follows the <Set><StatusCode> value when AssignTo type is response.

<Set>     
    <ReasonPhrase>Bad Request</ReasonPhrase>     
</Set>

Default:

false

Presence:

Optional

Type:

String

<AssignVariable> element

Lets you assign a value to a flow variable. If the variable does not exist, then create it.

In the first example, the <Name> tag specifies the variable name, and the <Value> tag specifies the value.

<AssignVariable>
    <Name>myvar</Name>
    <Value>10</Value>
</AssignVariable>
<AssignVariable>
    <Name>Country</Name>
    <Value>USA</Value>
</AssignVariable>

In the next example, you copy a value from one variable to another variable. This example assigns the value of the flow variable request.header.user-agent to the flow variable myvar and the value of the query parameter country to the Country variable:

<AssignVariable>
    <Name>myvar</Name>
    <Ref>request.header.user-agent</Ref>
    <Value>ErrorOnCopy</Value>
</AssignVariable>
<AssignVariable>
    <Name>Country</Name>
    <Ref>request.queryparam.country</Ref>
    <Value>ErrorOnCopy</Value>
</AssignVariable>

Use the <Ref> tag to specify the source variable. If the variable referenced by the <Ref> tag is not accessible, use the value specified by the <Value> tag.

One way to use <AssignVariable> is to set the default value of a query parameter, header, or other value that can be passed in with the request. For example, you create a weather API proxy where the request takes a single query parameter named "w". This parameter contains the ID of the city for which you want the weather. The request URL has the form:

http://myCO.com/v1/weather/forecastrss?w=12797282

To define a default value for the "w" query parameter, create an Assign Message policy as shown below:

<AssignMessage async="false" continueOnError="false" enabled="true" name="DefaultWQP">
  <AssignTo createNew="false" transport="http" type="request"/>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignVariable> 
    <Name>request.queryparam.w</Name>
    <Ref>request.queryparam.w</Ref> 
    <Value>12797282</Value>
  </AssignVariable> 
</AssignMessage>

In this example, you use <AssignVariable> to copy the request.queryparam.w flow variable to itself. If the flow variable is null, meaning the "w" query parameter was omitted from the request, then it copies the default value from the <Value> element. Therefore, you can make a request to this API proxy that omits the "w" query parameter:

http://myCO.com/v1/weather/forecastrss

And still have the API proxy return a valid result. 

<AssignVariable>/<Name> element

Specifies the name of the destination flow variable. If the variable does not exist, a new one is created.

The name ratelimit is reserved. For more information, see this Apigee Community post.

<AssignVariable>/<Ref> element

Specifies the source of the assignment as a flow variable or other value. If you specify a flow variable, omit the enclosing brackets "{}" normally used to reference a flow variable.

<AssignVariable>/<Value> element

If <Ref> is not specified or is unresolvable or null, this value is assigned to the <Name> variable. The value is always interpreted as a literal string; you cannot use a flow variable or other variable as the value. 

Flow variables

This policy does not automatically create or populate any flow variables. However, you can create and populate flow variables manually using this policy's <AssignTo>, <Copy>, <Set>, <Add>, and <AssignVariable> elements. 

Error codes

Errors returned from Edge policies follow a consistent format as described in the Error code reference.

The AssignMessage policy returns the following error codes and error messages in error responses. For guidance on catching and handling errors, see Fault handling.

UnresolvedVariable

Cause

Important: This error will only be thrown if the continueOnError policy attribute is set to false (the default).

This error means that a flow variable referenced in the policy does not exist. For example, in the following stanza, if the foo.bar variable does not exist in the flow context, this Edge throws an UnresolvedVariable error:

<Set>
    <Headers>
        <Header name="Cache-Hit">{foo.bar}</Header>
    </Headers>
</Set>
Resolution
  • If continueOnError is set to false (the default), then be sure the variable you are referencing exists. Also, be sure that the variable is in scope. Some of the built-in Edge variables are only available in certain flow contexts. For example, response variables are not generally available in the request flow. See Variables reference.
  • Set the continueOnError attribute to true. This setting causes the policy to ignore the problem and set the variable to an empty value. To read about why you might set it to true, see Handling policy errors within the flow.
Variables set These special flow variables are set when the policy throws this error. You can use these variables catch and handle this error using Fault Rules. See Fault handling.
Variable name Value
fault.name UnresolvedVariable
(What's this?)
*.failed assignmessage.{policy_name}.failed=true
(What's this?)
error.* (What's this?)
message.* (What's this?)
Default HTTP status 500 Internal Server Error
Default Error message Unresolved variable : <variable name>

Default JSON response:

{  
   "fault":{  
      "detail":{  
         "errorcode":"messaging.runtime.UnresolvedVariable"
      },
      "faultstring":"Unresolved variable : <variable_name>"
   }
}

 

VariableOfNonMsgType

Cause

The policy throws this error when it expects to assign a value to a non-message type variable. Message type variables include request and response. They also can be custom variables that are of type message. You might see this in the Copy element if you set the source attribute to a variable that is not of type Message.

For example, if you set the source to something other than request, response, or another variable of type message, you'll get this error. Here, the source variable "var.hello" happens to be of type string, and this code will throw a VariableOfNonMsgType error:

<Copy source="var.hello">
    <QueryParams>
        <QueryParam name="user-agent"/>
    </QueryParams>
</Copy>
Resolution Be sure that you are assigning to a variable of type Message when using the Copy element or any element that needs to assign a value to a Message type variable.
Variables set These special flow variables are set when the policy throws this error. You can use these variables catch and handle this error using Fault Rules. See Fault handling.
Variable name Value
fault.name VariableOfNonMsgType
(What's this?)
*.failed assignmessage.{policy_name}.failed=true
(What's this?)
error.* (What's this?)
message.* (What's this?)
Default HTTP status 500 Internal Server Error
Default Error message AssignMessage[<Policy Name>]: value of variable <Variable Name> is not of type Message

Default JSON response:

{  
   "fault":{  
      "detail":{  
         "errorcode":"steps.assignmessage.VariableOfNonMsgType"
      },
      "faultstring":"AssignMessage[Assign-Message-1]: value of variable is not of type Message"
   }
}

SetVariableFailed

Cause

Important: This error will only be thrown if the continueOnError policy attribute is set to false (the default).

This error occurs when the <AssignVariable> operation fails because it is trying to get a value from a variable that does not exist. For example, this statement tries to assign the value of a flow variable called var.bar to a new variable called foo. If var.bar doesn't exist, this error is thrown.

<AssignVariable>
    <Name>foo</Name>
    <Ref>var.bar</Ref>
</AssignVariable> 
Resolution
  • If continueOnError is set to false (the default), then be sure the variable you are referencing exists. Also, you can supply a default value with the <Value> attribute. In this configuration, if var.bar doesn't exist (can't be resolved), the default value baz is assigned to foo.
    <AssignVariable>
        <Name>foo</Name>
        <Ref>var.bar</Ref>
        <Value>baz</Value>
    </AssignVariable>
  • Also, be sure that the variable is in scope. Some of the built-in Edge variables are only available in certain flow contexts. For example, response variables are not generally available in the request flow. See Variables reference.
  • Set the continueOnError attribute to true. This setting causes the policy to ignore the problem and set the variable to an empty value. To read about why you might set it to true, see Handling policy errors within the flow.
Variables set These special flow variables are set when the policy throws this error. You can use these variables catch and handle this error using Fault Rules. See Fault handling.
Variable name Value
fault.name SetVariableFailed
(What's this?)
*.failed assignmessage.{policy_name}.failed=true
(What's this?)
error.* (What's this?)
message.* (What's this?)
Default HTTP status 500 Internal Server Error
Default Error message AssignMessage[<Policy Name>]: failed to assign message to message.

Default JSON response:

{  
   "fault":{  
      "detail":{  
         "errorcode":"steps.assignmessage.SetVariableFailed"
      },
      "faultstring":"AssignMessage[Assign-Message-1]: failed to assign message to message"
   }
}

InvalidIndex

Cause

Important: Edge checks for this error when you deploy a proxy. You must fix the problem before you can successfully deploy.

The <Copy> and <Remove> operations let you specify indexed values starting with index 1. For example, a query parameter can have multiple values.

<Remove>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.1"/>
      <Header name="h3.2"/>
    </Headers>
</Remove>
        

This error occurs if you specify an invalid index, such as 0 or a negative number.

Resolution

Use an integer index of 1 or more. If you specify an index that is not an integer, then the copy or remove operation does nothing.

Variables set None. This error prevents you from deploying the proxy.
Default HTTP status None.
Deployment error message Error in deployment for environment test. The revision is deployed, but traffic cannot flow. AssignMessage[Assign-Message-1]: index must be greater than zero in user-agent.0

InvalidVariableName

Error message

AssignMessage schema validation failed: invalid variable name - {0} - in assign variable

Resolution

Change the variable name to use valid characters.

InvalidPayload

Error message

InvalidPayload Invalid payload {0}

Schema

Each policy type is defined by an XML schema (.xsd). For reference, policy schemas are available on GitHub.

Related topics

Working samples of the AssignMessage policy are available in the API Platform samples.

 

Help or comments?