Send Docs Feedback

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. 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 AssignMessage.

<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 AssignMessage, 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 AssignMessage 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 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"></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. 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 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"></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 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


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 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/>
        <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">
    ...
</AssignMessage>
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. 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

The <AssignTo> element determines the variable that the AssignMessage 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 AssignMessage 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/>
        <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 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"/>
        </Headers>
        <QueryParams>
            <QueryParam name="q1"/>
        </QueryParams>
        <FormParams>
            <FormParam name="f1"/>
        </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"/>     
    </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>     
    </FormParam>
</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. Notice how this example escapes the leading "{" in the payload. Otherwise, Edge would interpret the leading "{" as the beginning of a variable reference:

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

Reference a variable in a JSON payload. You cannot use curly braces to reference variables in a JSON payload. Instead, you must declare and embed the variable delimiter characters, as follows:

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

Set a mixed payload in XML:

<Set>
    <Payload contentType="text/xml">
        <root>
          <e1>sunday</e1>
          <e2>funday</e2>
          <e3>{var1}</e3>
    </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

Sets the HTTP path of the request only when AssignTo type is request. Specify the path relative to the domain, which is defined by the target endpoint. For example, to set the request path as http://myCo.com/a/b/c, where http://myCo.com is defined by the API proxy's target endpoint, specify the path as:

<Set>
    <Path>/a/b/c</Path>
</Set>

Default:

 

Presence:

Optional

Type:

String

<Set>/<StatusCode> element

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

<Set>     
    <StatusCode>400 Bad Request</StatusCode>      
</Set>

Default:

NA

Presence:

Optional

Type:

String

<Set>/<ReasonPhrase> element

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

<Set>     
    <ReasonPhrase>true</ReasonPhrase>     
</Set>

Default:

false

Presence:

Optional

Type:

Boolean

<AssignVariable> element

Lets you assign a value to a flow 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>

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 AssignMessage 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.

<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. 

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?

  • If something's not working: Ask the Apigee Community or see Apigee Support.
  • If something's wrong with the docs: Click Send Docs Feedback on this page.
    (Incorrect? Unclear? Broken link? Typo?)