Assign Message policy

About | Samples | Element reference | Flow variables | Error codes  | Related topics

What

Creates or modifies HTTP request or response messages during an API proxy flow. Also creates 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 AssignMessage.

<AssignMessage name="AssignMessage-3">
  <AssignTo createNew="true" type="request">request1</AssignTo>
  <Copy source='request'>
    <Headers>
     <Header name="user-agent">{request.header.user-agent}</Header>
    </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 AssignMessage, and then send it to a backend target using the ServiceCallout 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 (specified by the source attribute).
  • 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.

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

<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, AssignMessage 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">response</AssignTo>
  <Set>
    <Headers>
      <Header name="Cache-Hit">{lookupcache.LookupCache-1.cachehit}</Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

This sample AssignMessage policy does not create a new message. Instead, it modifies an existing response message by adding an HTTP header. 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 AssignMessage 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">response</AssignTo>
  <Set>
    <Payload contentType="text/xml">
      <User-agent>{request.header.user-agent}</User-agent>
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

Note: With a JSON payload, you cannot use curly braces to identify variables. Instead, you must declare and embed the delimiter characters, as follows:

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

This policy removes the apikey parameter from the request.

<AssignMessage name="AssignMessage-1">
  <AssignTo createNew="false">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

Copy the user-agent header to the HTTP message variable specified with the <AssignTo> element.


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

Element reference

The element reference describes the elements and attributes of the AssignMessage 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 probably 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>
    <FaultRules/>
    <Properties/>
    <AssignTo createNew="false" transport="http" type="request"/>
    <Copy source="request">
        <Headers/>
        <QueryParams/>
        <FormParams/>
        <Payload/>
        <Verb/>
        <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/>
        <Verb/>
        <Path/>
    </Set>
    <AssignVariable>
        <Name>name</Name>
        <Value/>
        <Ref/>
    </AssignVariable>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

<AssignMessage> attributes

<AssignMessage async="false" continueOnError="false" enabled="true" name="a_name">
Field Name Description Default Presence
async

Set to true to specify that the policy should be run in a thread pool different than the pool servicing the request/response flow. Default is false.

Note: This setting is only used for for internal optimization. Contact Apigee support at the Support Portal for more information.

false Optional
continueOnError

Most policies are expected to return an error when a failure occurs (for example, when a Quota is exceeded). By setting this attribute to true, Flow execution continues on failure.

false Optional
enabled Determines whether a policy is enforced or not. If set to false, a policy is 'turned off', and not enforced (even though the policy remains attached to a Flow). true Optional
name

The internal name of the policy. This name is referenced in Step elements to attach the policy to a Flow.

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

N/A Required

<AssignTo> element

Assigns a value that was copied, added or set by this policy to a specified HTTP message variable. For example, if you use this policy to copy a query parameter from a request object, that query parameter will be added to the message object specified in the type attribute of this element. If the <AssignTo> element is missing, the policy assigns values to either the request or response, depending on the Flow to which the policy is attached. If attached to a request Flow, for example, the default type is request.

Attributes

<AssignTo createNew="false" transport="http" type="request"/>
Attribute Description Default Presence Type
createNew
If createNew is set to true, then a new variable of the type specified in type is created.
If createNew is set to false, then AssignTo responds in one of two ways:
  • If AssignTo resolves to a message, then it continues to the next flow.
  • If AssignTo cannot be resolved, or resolves to a non-message type, then the policy throws an error.
 
If createNew is not specified, AssignTo 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 Optional  
type
Specifies the type of the variable.
Valid values: request/response
Default value: request
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 in with this policy's <AssignTo> element.

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

Default:

N/A

Presence:

Optional

Type:

String

Attributes

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

Copies the specified information from the <source> to the variable specified in the <AssignTo> element.

  • If the source is not specified, it is treated as a simple message.
  • If the source variable can not be resolved, or resolves to a non-message type, <Copy> fails to respond.
Optional String

<Copy>/<Headers> element

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

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

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'>   
 <QueryParam>      
        <QueryParam name="address">{request.queryparam.address}</QueryParam>     
    </QueryParam> 
</Copy>

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:

<FormParam source='request'> 
    <FormParams> 
        <FormParam name="myparam">{request.formparams.myparam}</FormParam> 
    </FormParam> 
</FormParam>

Default:

N/A

Presence:

Optional

Type:

String

<Copy>/<Payload> element

If true, the Content-Type header 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"></Header>
        </Headers>
        <QueryParams>
            <QueryParam name="q1"></QueryParam>
        </QueryParams>
        <FormParams>
            <FormParam name="f1"></FormParam>
        </FormParams>
        </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"></Header>     
    </Headers> 
</Remove>

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"></QueryParam>     
    </QueryParams> 
</Copy>

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.

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

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

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

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.

<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: This option only works when the <AssignTo> type is request.

<Add>     
    <QueryParams>      
        <QueryParam name="param_name">{param_value}</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: 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.

<FormParams>      
        <FormParam name="{my_username}"></FormParam>     
</FormParams> 

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>     
    <QueryParam>      
        <QueryParam name="address">{request.queryparam.address}</QueryParam>     
    </QueryParam> 
</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.formparams.myparam}</FormParam>     
    </FormParam>
</Set>

Default:

N/A

Presence:

Optional

Type:

String

<Set>/<Payload> element

You are allowed to set mixed payload contents. For example, <root><e1>sunday</e1><e2>funday</e2><e3>{var1}</e3></root>.

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

Default:

false

Presence:

Optional

Type:

Boolean

Attributes

<Payload contentType="content_type">
Attribute Description Presence Type
contentType

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

Optional String

<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 source='request'>     
    <Version>true</Version>     
</Set>

Default:

false

Presence:

Optional

Type:

Boolean

<Set>/<Verb> element

Sets the HTTP verb and path only when AssignTo type is request.

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

Default:

false

Presence:

Optional

Type:

Boolean

<Set>/<Path> element

Sets the HTTP verb and path only when AssignTo type is request.

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

Default:

false

Presence:

Optional

Type:

Boolean

<Set>/<StatusCode> element

Sets the status code and reason phrase only when AssignTo type is response.

Default:

false

Presence:

Optional

Type:

Boolean

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

<Set>/<ReasonPhrase> element

Sets the status code and reason phrase only when AssignTo type is response.

Default:

false

Presence:

Optional

Type:

Boolean
<Set source='request'>     
    <ReasonPhrase>true</ReasonPhrase>     
</Set>

<AssignVariable> element

Lets you assign a value to an arbitrary flow variable. This example assigns the value of the flow variable client-ip to the flow variable myvar:

<AssignVariable>
    <Name>myvar</Name>
    <Value>{client-ip}</Value>
    <Ref/>
</AssignVariable>

<AssignVariable>/<Name> element

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

<AssignVariable>
    <Name>myvar</Name>
    <Value>aValue</Value>
    <Ref/>
</AssignVariable>

<AssignVariable>/<Ref> element

References an existing flow variable. The value of that variable is assigned to the new one.

<AssignVariable>
    <Name>myvar</Name>
    <Value/>
    <Ref>{client-ip}
</AssignVariable>

<AssignVariable>/<Value> element

If <Ref> is not specified or is unresolvable, this value is assigned to the variable. 

<AssignVariable>
    <Name>myvar</Name>
    <Value>Undefined</Value>
    <Ref>{a_flow_variable}</Ref>
</AssignVariable>

Usage notes

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 AssignMessage 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 a request message. Then, The employ a ServiceCallout policy that references the variable to send that message to a remote service or API.

The AssignMessage policy type is used 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.

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

To use AssignMessage, 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 ambient request or response, respectively. If you use any other name, it will refer to a custom variable to hold the message.

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

This policy defines the following error codes. For guidance on handling errors, see Fault handling.

The default format for error codes returned by Policies is:

{
  "code" : " {ErrorCode} ",
  "message" : " {Error message} ",
  "contexts" : [ ]
}

The AssignMessage Policy type defines the following error codes:

Error Code Message
UnresolvedVariable AssignMessage[{0}]: unable to resolve variable {1}
VariableOfNonMsgType AssignMessage[{0}]: value of variable {1} is not of type Message
SetVariableFailed AssignMessage[{0}]: failed to assign message to {1}
InvalidIndex AssignMessage[{0}]: index must be greater than zero in {1}
InvalidVariableName AssignMessage schema validation failed: invalid variable name - {0} - in assign variable
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?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)