You're viewing **Apigee Edge** documentation.  
[Go to the
**Apigee X** documentation](http://cloud.google.com/apigee/docs). info

![](https://docs.apigee.com/static/api-platform/images/icon_policy_assign-message.jpg)

## What

The AssignMessage policy changes or creates new request and response messages during the API proxy Flow.
The policy lets you perform the following actions on those messages:

- [Add](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#add) new form parameters, headers, or query parameters to a message
- [Copy](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#copy) existing properties from one message to another
- [Remove](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#remove) headers, query parameters, form parameters, and/or message payloads from a message
- [Set](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#set) the value of existing properties in a message

With AssignMessage policy, you typically add, change, or remove properties of either the
request or response. However, you can also use AssignMessage policy to create a custom
request or response message and pass it to an alternative target, as described in
[Create custom request messages](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#customrequests).

## Use cases

There are many situations in which you might want to modify a request or a response message
during processing by Apigee Edge. For example:

- Define a default value for a query string parameter or other type of input.
- Strip HTTP headers from a request message before the message is forwarded to the backend service.
- Add HTTP headers before a response is sent to the consumer app.
- Insert JSON or XML message content before a response is sent.
- Generate complete request or response messages. For example, you might use a [ServiceCallout policy](https://docs.apigee.com/api-platform/reference/policies/service-callout-policy) to invoke a remote API from an API proxy. You can use the AssignMessage policy to create a custom request message and assign it to a variable. Then, use Service Callout to send that message to the remote API.
- Add headers to requests and responses for debugging and troubleshooting.

The AssignMessage policy can create or change messages or flow variables.
Use this policy to modify request messages before sending them via a proxy to upstream systems,
or to modify response messages before relaying them to API consumer applications.

## `<AssignMessage>` element

Defines an AssignMessage policy.

|---|---|
| **Default Value** | See **Default Policy** tab, below |
| **Required?** | Required |
| **Type** | Complex object |
| **Parent Element** | n/a |
| **Child Elements** | [`<Add>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#add) [`<AssignTo>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignto) [`<AssignVariable>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignvariable) [`<Copy>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#copy) [`<DisplayName>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#displayname) [`<IgnoreUnresolvedVariables>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#ignoreunresolvedvariables) [`<Remove>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#remove) [`<Set>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#set) |

The `<AssignMessage>` element uses the following syntax:

### Syntax

The `<AssignMessage>` element uses the following syntax:

```
<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <!-- All AssignMessage child elements are optional -->
  <Add>
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
  </Add>

  <AssignTo createNew="[true|false]" transport="http"
    type="[request|response]">destination_variable_name</AssignTo>

  <AssignVariable>
    <Name>variable_name</Name>
    <Ref>source_variable</Ref>
    <Template>message_template</Template>
    or
    <Template ref='template_variable'></Template>
    <Value>variable_value</Value>
  </AssignVariable>

  <Copy source="[request|response]">
    <!-- Can also be an empty array (<FormParams/>) -->
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
    <!-- Can also be an empty array (<Headers/>) -->
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
    <Path>[false|true]</Path>
    <Payload>[false|true]</Payload>
    <!-- Can also be an empty array (<QueryParams/>) -->
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
    <ReasonPhrase>[false|true]</ReasonPhrase>
    <StatusCode>[false|true]</StatusCode>
    <Verb>[false|true]</Verb>
    <Version>[false|true]</Version>
  </Copy>

  <DisplayName>policy_display_name</DisplayName>

  <IgnoreUnresolvedVariables>[true|false]
  </IgnoreUnresolvedVariables>

  <Remove>
    <!-- Can also be an empty array (<FormParams/>) -->
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
    <!-- Can also be an empty array (<Headers/>) -->
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
    <Payload>[false|true]</Payload>
    <!-- Can also be an empty array (<QueryParams/>) -->
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
  </Remove>

  <Set>
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
    <Path>path</Path>
    <Payload contentType="content_type" variablePrefix="prefix"
        variableSuffix="suffix">new_payload</Payload>
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
    <ReasonPhrase>reason_for_error or {variable}</ReasonPhrase>
    <StatusCode>HTTP_status_code or {variable}</StatusCode>
    <Verb>[GET|POST|PUT|PATCH|DELETE|{variable}]</Verb>
    <Version>[1.0|1.1|{variable}]</Verb>
  </Set>

</AssignMessage>
```

### Default Policy

The following example shows the default settings when you add an AssignMessage policy
to your flow in the Edge UI:

```
<AssignMessage continueOnError="false" enabled="true" name="assign-message-default">
  <DisplayName>Assign Message-1</DisplayName>
  <Properties/>
  <Copy source="request">
    <Headers/>
    <QueryParams/>
    <FormParams/>
    <Payload/>
    <Verb/>
    <StatusCode/>
    <ReasonPhrase/>
    <Path/>
  </Copy>
  <Remove>
    <Headers>
      <Header name="h1"/>
    </Headers>
    <QueryParams>
      <QueryParam name="q1"/>
    </QueryParams>
    <FormParams>
      <FormParam name="f1"/>
    </FormParams>
    <Payload/>
  </Remove>
  <Add>
    <Headers/>
    <QueryParams/>
    <FormParams/>
  </Add>
  <Set>
    <Headers/>
    <QueryParams/>
    <FormParams/>
    <!-- <Verb>GET</Verb> -->
    <Path/>
  </Set>
  <AssignVariable>
    <Name>name</Name>
    <Value/>
    <Ref/>
  </AssignVariable>
  <IgnoreUnresolvedVariables>true
  </IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>
```

When you insert a new AssignMessage policy in the Edge UI, the template contains stubs for all
possible operations. Typically, you select which operation(s) you want to perform with this policy
and remove the rest of the child elements. For example, if you want to perform a copy operation, use the
`<Copy>` element and remove `<Add>`, `<Remove>`, and other child elements from the
policy to make it more readable.

This element has the following attributes that are common to all policies:

| **Attribute** | **Default** | **Required?** | **Description** |
|---|---|---|---|
| `name` | N/A | **Required** | The internal name of the policy. The value of the `name` attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters. Optionally, use the `<DisplayName>` element to label the policy in the management UI proxy editor with a different, natural-language name. |
| `continueOnError` | false | Optional | 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. |
| `enabled` | true | Optional | 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. |
| `async` | false | Deprecated | This attribute is deprecated. |

The following table provides a high-level description of the child elements of
[`<AssignMessage>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignmessage):

| Child Element | Required? | Description |
|---|---|---|
| Common operations |||
| [`<Add>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#add) | Optional | Adds information *to* the message object that is specified by the [`<AssignTo>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignto) element. `<Add>` adds headers or parameters to the message that don't exist in the original message. To overwrite existing headers or parameters, use the [`<Set>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#set) element. |
| [`<Copy>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#copy) | Optional | Copies information *from* the message specified by the `source` attribute *to* the message object specified by the [`<AssignTo>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignto) element. |
| [`<Remove>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#remove) | Optional | Deletes the specified elements from the message variable specified in the [`<AssignTo>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignto) element. |
| [`<Set>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#set) | Optional | Replaces values of existing properties on the request or response, which is specified by the [`<AssignTo>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignto) element. `<Set>` overwrites headers or parameters that *already exist* in the original message. To add new headers or parameters, use the [`<Add>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#add) element. |
| Other child elements |||
| [`<AssignTo>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignto) | Optional | Specifies which message the AssignMessage policy operates on. This can be the standard request or response, or it can be a new, custom message. |
| [`<AssignVariable>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignvariable) | Optional | Assigns a value to a flow variable. If the variable does not exist, then `<AssignVariable>` creates it. |
| [`<IgnoreUnresolvedVariables>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#ignoreunresolvedvariables) | Optional | Determines whether processing stops when an unresolved variable is encountered. |

Each of these child elements is described in the sections that follow.

## Examples

The following examples show some of the ways in which you can use the AssignMessage policy:

### 1: Add header

The following example adds a header to the request with the
[`<Add>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#add) element:

```
<AssignMessage name="AM-add-headers-1">
  <Add>
    <Headers>
      <Header name="partner-id">{verifyapikey.VAK-1.developer.app.partner-id}</Header>
    </Headers>
  </Add>
  <AssignTo>request</AssignTo>
</AssignMessage>
```

### 2: Remove payload

The following example deletes the payload from the response with the [`<Remove>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#remove)
element:

```
<AssignMessage name="AM-remove-1">
  <DisplayName>remove-1</DisplayName>
  <Remove>
    <Payload>true</Payload>
  </Remove>
  <AssignTo>response</AssignTo>
</AssignMessage>
```

### 3: Modify response

The following example modifies an existing response object by adding a header to it:

```
<AssignMessage name="AM-modify-response">
  <Set>
    <Headers>
      <Header name="Cache-Hit">{lookupcache.LookupCache-1.cachehit}</Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>false
  </IgnoreUnresolvedVariables>
  <AssignTo>response</AssignTo>
</AssignMessage>
```

This example does not create a new message. Instead, it modifies an
existing response message by adding an HTTP header.


Because this example specifies `response` as the variable name in the
[`<AssignTo>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignto) element, this policy modifies the response object that was originally
set with data 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](https://docs.apigee.com/api-platform/reference/policies/lookup-cache-policy). Therefore the response message modified by this
Assign Message 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.

> [!IMPORTANT]
>
> ### TIP
>
> 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.

### 4: Set dynamic content

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

To embed Edge flow variables in an XML payload, wrap the designated variable in curly
braces, like this: `{prefix.name}`.

The following example embeds the value of the `user-agent` HTTP header flow variable
in an XML element called `User-agent`:

```
<AssignMessage name="AM-set-dynamic-content">
  <AssignTo>response</AssignTo>
  <Set>
    <Payload contentType="text/xml">
      <User-agent>{request.header.user-agent}</User-agent>
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>false
  </IgnoreUnresolvedVariables>
</AssignMessage>
```

For JSON payloads, you can insert variables using the `variablePrefix` and
`variableSuffix` attributes with delimiter characters as shown in the following
example:

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

For a complete list of flow variables, see [Flow variables reference](https://docs.apigee.com/api-platform/reference/variables-reference).

As of cloud release 16.08.17, you can also use curly braces to insert variables.

### 5: Remove query param

The following example removes the `apikey` query parameter from the request:

```
<AssignMessage name="AM-remove-query-param">
  <Remove>
    <QueryParams>
      <QueryParam name="apikey"/>
    </QueryParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>
```

It's a best practice to strip the `apikey` query parameter from the request
message when you use the [VerifyAPIKey policy](https://docs.apigee.com/api-platform/reference/policies/verify-api-key-policy) for user authentication. You do this to prevent
sensitive key information from being passed to the backend target.

### 6: Set/get variables

The following example uses three Assign Message policies:

1. Creates three flow variables in the request, with static values
2. Gets the flow variables dynamically in a second policy in the request flow
3. Sets them in the payload of the response

```
<!-- Policy #1: Set variables in the request -->

<AssignMessage name="AM-set-variables">
    <!-- Create a variable named myAppSecret -->
    <AssignVariable>
        <Name>myAppSecret</Name>
        <Value>42</Value>
    </AssignVariable>
    <!-- Create a variable named config.environment -->
    <AssignVariable>
        <Name>config.environment</Name>
        <Value>test</Value>
    </AssignVariable>
    <!-- Create a variable named config.protocol -->
    <AssignVariable>
        <Name>config.protocol</Name>
        <Value>gopher</Value>
    </AssignVariable>
</AssignMessage>
```

In the first policy, the [`<AssignVariable>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignvariable) element creates and sets three
variables in the request. Each [`<Name>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignvariable-name) element specifies
a variable name, and [`<Value>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignvariable-value) specifies the value.

The second policy uses the `<AssignVariable>` element to read in the values and creates three
new variables:

```
<!-- Policy #2: Get variables from the request -->
<AssignMessage continueOnError="false" enabled="true" name="get-variables">
  <AssignTo createNew="false" transport="http" type="request"/>
  <!-- Get the value of myAppSecret and create a new variable, secret -->
  <AssignVariable>
    <Name>secret</Name>
    <Ref>myAppSecret</Ref>
    <Value>0</Value>
  </AssignVariable>
  <!-- Get the value of config.environment and create a new variable, environment -->
  <AssignVariable>
    <Name>environment</Name>
    <Ref>config.environment</Ref>
    <Value>default</Value>
  </AssignVariable>
  <!-- Get the value of config.protocol and create a new variable, protocol -->
  <AssignVariable>
    <Name>protocol</Name>
    <Ref>config.protocol</Ref>
    <Value>default</Value>
  </AssignVariable>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>
```

In the second policy, the [`<Ref>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignvariable-ref) element references the source variable,
and `<Name>` elements specify the names of the new variables. If the variable
referenced by the `<Ref>` element is not accessible, you can use the value
specified by the `<Value>` element.

**To try out this set of policies:**

1. Add policies #1 and #2 to the request flow. Be sure to put policy #1 *before* policy #2.
2. Add the third policy in the *response* flow.
3. The third policy uses the `<Set>` element to add the variables to the response. The following example constructs an XML payload in the response that Edge returns to the client:

   ```
   <!-- Policy #3: Add variables to the response -->
   <AssignMessage continueOnError="false" enabled="true" name="put-em-in-the-payload">
     <DisplayName>put-em-in-the-payload</DisplayName>
     <Set>
       <Payload contentType="application/xml">
         <wrapper>
           <secret>{secret}</secret>
           <config>
             <environment>{environment}</environment>
             <protocol>{protocol}</protocol>
           </config>
         </wrapper>
       </Payload>
     </Set>
     <IgnoreUnresolvedVariables>true
     </IgnoreUnresolvedVariables>
     <AssignTo createNew="false" transport="http" type="response"/>
   </AssignMessage>
   ```

   Note that the syntax to access flow variables in `<Set>` is to wrap them in
   curly braces.

   Be sure to set the `<Payload>` element's `contentType` attribute to
   "application/xml".
4. Send a request to your API proxy; for example:

   ```
   curl -vL https://ahamilton-eval-test.apigee.net/myproxy
   ```

   Optionally, you can pipe the results through a utility such as `xmllint` so that
   the XML is displayed in a nicely formatted structure:

   ```
   curl -vL https://ahamilton-eval-test.apigee.net/myproxy | xmllint --format -
   ```

   The body of the response should look like the following:

   ```
   <wrapper>
     <secret>42</secret>
     <config>
       <environment>test</environment>
       <protocol>gopher</protocol>
     </config>
   </wrapper>
   ```

### 7: Get Service Callout response headers

In the following example, let's say that a [ServiceCallout policy](https://docs.apigee.com/api-platform/reference/policies/service-callout-policy) is in the API proxy request,
and the callout response contains multiple headers of the same name
(`Set-Cookie`). Assuming the Service Callout's response variable is the default
`calloutResponse`, the following policy gets the second `Set-Cookie`
header value.

```
<AssignMessage name="AM-Payload-from-SC-header">
  <Set>
    <Payload contentType="application/json">
      {"Cookies from Service Callout":" {calloutResponse.header.Set-Cookie.2}"}
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true
  </IgnoreUnresolvedVariables>
  <AssignTo>response</AssignTo>
</AssignMessage>
```

To list *all* header values, use the following variable instead:

```
{calloutResponse.header.Set-Cookie.values}
```

Each child element in this reference has additional examples. For even more examples, see
[AssignMessage example](https://gist.github.com/ApigeeSamples/3414852)
on GitHub.

## Child element reference

This section describes the child elements of [`<AssignMessage>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignmessage).

### `<Add>`

Adds information to the request or response, which is specified by the [`<AssignTo>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignto)
element.

The `<Add>` element adds new properties on the message that don't exist in the original
message. To change the values of *existing* properties, use the [`<Set>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#set)
element.

|---|---|
| **Default Value** | n/a |
| **Required?** | Optional |
| **Type** | Complex type |
| **Parent Element** | [`<AssignMessage>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignmessage) |
| **Child Elements** | [`<FormParams>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#add-formparams) [`<Headers>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#add-headers) [`<QueryParams>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#add-queryparams) |

The `<Add>` element uses the following syntax:

### Syntaxs1

```
<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Add>
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
  </Add>
</AssignMessage>
```

### Example 1s2

The following example uses the [`<FormParams>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#add-formparams) element to get the values of
three query string parameters from the initial request and set them as form parameters on the
target endpoint request:

```
<AssignMessage name="AM-add-formparams-3">
  <Add>
    <FormParams>
      <FormParam name="username">{request.queryparam.name}</FormParam>
      <FormParam name="zip_code">{request.queryparam.zipCode}</FormParam>
      <FormParam name="default_language">{request.queryparam.lang}</FormParam>
    </FormParams>
  </Add>
  <Remove>
    <QueryParams/>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>
```

### Example 2s3

The following example uses the [`<Headers>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#add-headers) element to add a
`partner-id` header to the request that will be sent to the target endpoint:

```
<AssignMessage name="AM-add-headers-1">
  <Add>
    <Headers>
      <Header name="partner-id">{verifyapikey.VAK-1.developer.app.partner-id}</Header>
    </Headers>
  </Add>
  <AssignTo>request</AssignTo>
</AssignMessage>
```

### Example 3s4

The following example uses the [`<QueryParams>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#add-queryparams) element to add a single query
parameter with a static value to the request:

```
<AssignMessage name="AM-add-queryparams-1">
  <Add>
    <QueryParams>
      <QueryParam name="myParam">42</QueryParam>
    </QueryParams>
  </Add>
  <AssignTo>request</AssignTo>
</AssignMessage>
```

This example uses `<Add>` in the request preflow. If you look at the results in a tool
such as the [Trace tool](https://docs.apigee.com/api-platform/debug/using-trace-tool-0), the request to `https://example-target.com/get` becomes
`https://example-target.com/get?myParam=42`.

The child elements of `<Add>` support dynamic string substitution, known as
[message templating](https://docs.apigee.com/api-platform/reference/message-template-intro).

#### `<FormParams>` (child of [`<Add>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#add))

Adds new form parameters to the request message. This element has no effect on a response
message.

|---|---|
| **Default Value** | n/a |
| **Required?** | Optional |
| **Type** | Array of `<FormParam>` elements |
| **Parent Element** | [`<Add>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#add) |
| **Child Elements** | `<FormParam>` |

The `<FormParams>` element uses the following syntax:

### Syntaxs5

```
<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Add>
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
  <AssignTo createNew="[true|false]" transport="http"
    type="[request|response]">destination_variable_name</AssignTo>
  </Add>
</AssignMessage>
```

### Example 1s6

The following example adds a single form parameter ("answer") and a static value ("42") to
the request:

```
<AssignMessage name="AM-add-formparams-1">
  <Add>
    <FormParams>
      <FormParam name="answer">42</FormParam>
    </FormParams>
  </Add>
  <AssignTo>request</AssignTo>
</AssignMessage>
```

### Example 2s7

The following example gets the value of the `name` query parameter and
adds it to the request as a form parameter, and then removes the query parameter:

```
<AssignMessage name="AM-Swap-QueryParam-to-FormParams">
  <Add>
    <FormParam name="name">{request.queryparam.name}</FormParam>
  </Add>
  <Remove>
    <QueryParam name="name"/>
  </Remove>
</AssignMessage>
```

Note that this example does not specify a target with `<AssignTo>`. This policy adds the
parameter to the request only.

### Example 3s8

The following example adds multiple form parameters to the request:

```
<AssignMessage name="AM-add-formparams-3">
  <Add>
    <FormParams>
      <FormParam name="username">{request.queryparam.name}</FormParam>
      <FormParam name="zip_code">{request.queryparam.zipCode}</FormParam>
      <FormParam name="default_language">{request.queryparam.lang}</FormParam>
    </FormParams>
  </Add>
  <Remove>
    <QueryParams/>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>
```

This example gets the query string parameters from the originating request and adds them
as form parameters with different names. Then it removes the original query parameters.
Apigee will send the modified request to the target endpoint.

You can use the [Trace tool](https://docs.apigee.com/api-platform/debug/using-trace-tool-0) to look at the flow. You'll see that the body of the request
contains the URL-encoded form data, which was originally passed in as query string
parameters:

```
username=nick&zip_code=90210&default_language=en
```

You can use `<FormParams>` only when the following criteria are met:

- HTTP verb: POST
- Message type: Request
- One (or both) of the following:
  - Form data: Set to some value, or "" (the empty string). For example, with `curl`, add `-d ""` to your request.
  - `Content-Length` header: Set to 0 (if no data is in the original request; otherwise, the current length, in bytes). For example, with `curl` add `-H "Content-Length: 0"` to your request.

For example:

```
curl -vL -X POST -d "" -H "Content-Type: application/x-www-form-urlencoded"
  https://ahamilton-eval-test.apigee.net/am-test
```

When you add `<FormParams>`, Edge sets the request's `Content-Type` header to
"application/x-www-form-urlencoded" before sending the message to the target service.

#### `<Headers>` (child of [`<Add>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#add))

Adds new headers to the specified request or response, which is specified by the
[`<AssignTo>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignto) element.

|---|---|
| **Default Value** | n/a |
| **Required?** | Optional |
| **Type** | Array of `<Header>` elements |
| **Parent Element** | [`<Add>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#add) |
| **Child Elements** | `<Header>` |

The `<Headers>` element uses the following syntax:

### Syntaxs9

```
<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Add>
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
  </Add>
</AssignMessage>
```

### Example 1s10

The following example adds a `partner-id` header to the request message, and
assigns the value of the `verifyapikey.VAK-1.developer.app.partner-id` flow variable to that header.

```
<AssignMessage name="AM-add-headers-1">
  <Add>
    <Headers>
      <Header name="partner-id">{verifyapikey.VAK-1.developer.app.partner-id}</Header>
    </Headers>
  </Add>
  <AssignTo>request</AssignTo>
</AssignMessage>
```

#### `<QueryParams>` (child of [`<Add>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#add))

Adds new query parameters to the request. This element has no effect on a response.

|---|---|
| **Default Value** | n/a |
| **Required?** | Optional |
| **Type** | Array of `<QueryParam>` elements |
| **Parent Element** | [`<Add>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#add) |
| **Child Elements** | `<QueryParam>` |

The `<QueryParams>` element uses the following syntax:

### Syntaxs11

```
<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Add>
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
  </Add>
</AssignMessage>
```

### Example 1s12

The following example adds the query parameter "myParam" to the request and assigns the value
"42" to it:

```
<AssignMessage name="AM-add-queryparams-1">
  <Add>
    <QueryParams>
      <QueryParam name="myParam">42</QueryParam>
    </QueryParams>
  </Add>
  <AssignTo>request</AssignTo>
</AssignMessage>
```

You can use `<QueryParams>` only when the following criteria are met:

- HTTP verb: GET
- Message type: Request

In addition, you can only set query parameters when the `<AssignTo>` element's
`type` attribute is a request message. Setting them on the response has no effect.

If you define an empty array of query parameters in your policy
(`<Add><QueryParams/></Add>`), the policy does not add any query
parameters. This is the same as omitting `<QueryParams>`.

### `<AssignTo>`

Determines which object the AssignMessage policy operates on. The options are:

- **Request message:** The [`request`](https://docs.apigee.com/api-platform/reference/variables-reference#request) received by the API proxy
- **Response message:** The [`response`](https://docs.apigee.com/api-platform/reference/variables-reference#response) returned from the target server
- **Custom message:** A custom request or response object

Note that in some cases, you cannot change the object on which the AssignMessage policy acts.
For example, you cannot use [`<Add>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#add) or [`<Set>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#set) to add or change query parameters
(`<QueryParams>`) or form parameters (`<FormParams>`) on the response. You can only
manipulate query parameters and form parameters on the request.

|---|---|
| **Default Value** | n/a |
| **Required?** | Optional |
| **Type** | String |
| **Parent Element** | [`<AssignMessage>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignmessage) |
| **Child Elements** | None |

If you do not specify `<AssignTo>`, or if you specify the `<AssignTo>` element, but do
not specify a text value for the element, the policy acts on the default request or response, which is based on where the policy executes. If the policy executes in the request flow, it
affects the request message. If it executes in the response flow, the policy affects the response
by default.

The `<AssignTo>` element uses the following syntax:

### Syntaxs13

```
<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <AssignTo createNew="[true|false]" transport="http"
    type="[request|response]">destination_variable_name</AssignTo>
</AssignMessage>
```

### Example 1s14

The following example specifies that the target is the original request that will be sent to the
target endpoint:

```
<AssignMessage name="assignto-1">
<!-- DO NOT do this -->
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>
```

> [!NOTE]
> **Note:** When the `createNew` attribute is set to `false` and no explicit message is provided, the `AssignTo` element has no functional impact. In such cases, its inclusion is redundant and equivalent to omitting the element entirely. For practical implementation and examples of effective `AssignTo` element usage, consult the other provided samples.

### Example 2s15

The following example creates a new request object:

```
<AssignMessage name="AM-assignto-2"> 
  <AssignTo createNew="true" transport="http" type="request">NameOfNewMessage</AssignTo> 
</AssignMessage>
```

When you create a new request or response object, the other elements of the AssignMessage policy
policy (such as [`<Add>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#add), [`<Set>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#set), and [`<Copy>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#copy)) act on that new
request object.

You can access the new request object in other policies later in the flow, or send the new
request object to an external service with a [ServiceCallout policy](https://docs.apigee.com/api-platform/reference/policies/service-callout-policy).

### Example 3s16

The following example creates a new request object named "MyRequestObject":

```
<AssignMessage name="assignto-2">
  <AssignTo createNew="true" transport="http" type="request"&gt;MyRequestObject&lt;/AssignTo>
</AssignMessage>
```

When you create a new request or response object, the other elements of the AssignMessage policy
policy (such as [`<Add>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#add), [`<Set>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#set), and [`<Copy>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#copy)) act on that new
request object.

You can access the new request object in other policies later in the flow, or send the new
request object to an external service with a [ServiceCallout policy](https://docs.apigee.com/api-platform/reference/policies/service-callout-policy).

The following table describes the attributes of `<AssignTo>`:

| Attribute | Description | Required? | Type |
|---|---|---|---|
| `createNew` | Determines whether this policy creates a new message when assigning values. If "true", then the policy creates a new variable of the type specified by `type` (either "request" or "response"). 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] > **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 "false", then the policy responds in one of two ways: - If `<AssignTo>` can resolve the variable name to a request or response, 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 policy responds in one of two ways: - If the text value of `<AssignTo>` resolves to a message, then processing advances to the next step. - If the text value of `<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. The default value is "http" (the only supported value). | Optional | String |
| `type` | Specifies the type of the new message, when `createNew` is "true". Valid values are "request" or "response". If you omit this attribute, then Edge creates either a request or a response, depending on where in the flow this policy executes. | Optional | String |

### `<AssignVariable>`

Assigns a value to a flow variable. If the flow variable does not exist, then
`<AssignVariable>` creates it.

|---|---|
| **Default Value** | n/a |
| **Required?** | Optional |
| **Type** | Complex type |
| **Parent Element** | [`<AssignMessage>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignmessage) |
| **Child Elements** | [`<Name>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignvariable-name) **(required)** [`<Ref>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignvariable-ref) [`<Template>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignvariable-template) [`<Value>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignvariable-value) |

The value that you assign to the flow variable can be one of the following:

- Literal string: Use the [`<Value>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignvariable-value) child element to specify a literal string value for the flow variable.
- Flow variable: Use the [`<Ref>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignvariable-ref) child element to specify the value of an existing flow variable for the destination flow variable. For a complete list of flow variables that can be used as a source, see [Flow variables reference](https://docs.apigee.com/api-platform/reference/variables-reference).
- Message template: Use the [`<Template>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignvariable-template) child element to specify a [message template](https://docs.apigee.com/api-platform/reference/message-template-intro) to interpolate, to get the value to place into the destination flow variable.

The `<AssignVariable>` element uses the following syntax:

### Syntaxs17

```
<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <AssignVariable>
    <Name>variable_name</Name>
    <Ref>source_variable</Ref>
    <Template>message_template</Template>
    or
    <Template ref='template_variable'></Template>
    <Value>variable_value</Value>
  </AssignVariable>
</AssignMessage>
```

Use the [`<Ref>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignvariable-ref) element to specify the source variable. If the
variable referenced by `<Ref>` is not accessible, Edge uses the value
specified by the [`<Value>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignvariable-value) element. If you define
[`<Template>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignvariable-template), it takes precedence over the other child elements.

### Example 1s18

The following example sets the value of a new variable, `myvar`, to the literal
value "42":

```
<AssignMessage name="assignvariable-1">
  <AssignVariable>
    <Name>myvar</Name>
    <Value>42</Value>
  </AssignVariable>
</AssignMessage>
```

### Example 2s19

The following example assigns the value of the flow variable
`request.header.user-agent` to the destination flow variable `myvar`
and the value of the query parameter `country` to the destination flow variable
`Country`:

```
<AssignMessage name="assignvariable-2">
  <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>
</AssignMessage>
```

If either assignment fails, Edge instead assigns the value "ErrorOnCopy" to
the destination flow variable.

If the `myvar` or `Country` flow variables do not exist,
`<AssignVariable>` creates them.

### Example 3s20

The following example uses the `<Template>`
child element to concatenate two context variables
with a literal string (a hyphen) between them:

```
<AssignMessage name='AV-via-template-1'>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignVariable>
    <Name>my_destination_variable</Name>
    <Value>BADDBEEF</Value>
    <Template>{system.uuid}-{messageid}</Template>
  </AssignVariable>
</AssignMessage>
```

A common use for `<AssignVariable>` is to set a default value for a query parameter, header, or
other value that can be passed in with the request. You do this with a combination of both the
[`<Ref>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignvariable-ref) and [`<Value>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignvariable-value) child elements. For more
information, see the examples for `<Ref>`.

#### `<Name>` (child of [`<AssignVariable>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignvariable))

Specifies the name of the destination flow variable (e.g., the variable whose value is set by
the AssignMessage policy). If the variable named in `<AssignVariable>` does not exist, the
policy creates one with that name.

|---|---|
| **Default Value** | n/a |
| **Required?** | Required |
| **Type** | String |
| **Parent Element** | [`<AssignVariable>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignvariable) |
| **Child Elements** | None |

The `<Name>` element uses the following syntax:

### Syntaxs21

```
<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <AssignVariable>
    <Name>variable_name</Name>
  </AssignVariable>
</AssignMessage>
```

### Example 1s22

The following example specifies the destination variable as `myvar`, and sets it
to the literal value "42":

```
<AssignMessage name="assignvariable-1">
  <AssignVariable>
    <Name>myvar</Name>
    <Value>42</Value>
  </AssignVariable>
</AssignMessage>
```

If `myvar` does not exist, `<AssignVariable>` creates it.

> [!NOTE]
> **Note** : The name "ratelimit" is reserved. For more information, see [Quota Policy Throws NullPointerException](https://discuss.google.dev/t/quota-policy-throws-nullpointerexception/11361) in the Apigee Community.

#### `<Ref>` (child of [`<AssignVariable>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignvariable))

Specifies the source of the assignment as a flow variable. The flow variable can be one of the
pre-defined flow variables (as listed in the [Flow variables reference](https://docs.apigee.com/api-platform/reference/variables-reference)), or a custom flow variable
that you created.

The value of `<Ref>` is always interpreted as a flow variable; you cannot
specify a literal string as the
value. To assign a literal string value, use the [`<Value>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignvariable-value) element
instead.

|---|---|
| **Default Value** | n/a |
| **Required?** | Optional |
| **Type** | String |
| **Parent Element** | [`<AssignVariable>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignvariable) |
| **Child Elements** | None |

When you specify a flow variable with `<Ref>`, omit the
enclosing brackets "{}" that you would normally use to reference a flow variable. For example,
to set the value of your new variable to the value of the `client.host` flow
variable:

```
Do this (no brackets):
  <Ref>client.host</Ref>

Do NOT do this (brackets):
  <Ref>{client.host}</Ref>
```

To define a default value for the destination flow variable, use [`<Value>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignvariable-value)
in combination with `<Ref>`. If the flow variable specified by
`<Ref>` does not exist, cannot be read, or is null, then Edge assigns the value
of `<Value>` to the destination flow variable instead.

The `<Ref>` element uses the following syntax:

### Syntax

```
<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <AssignVariable>
    <Name>variable_name</Name>
    <Ref>source_variable</Ref>
  </AssignVariable>
</AssignMessage>
```

### Example 1s23

The following example assigns the value of the flow variable
`request.header.user-agent` to the destination flow variable `myvar` and
the value of the query parameter `country` to the `Country` variable:

```
<AssignMessage name="assignvariable-4">
  <AssignVariable>
    <Name>myvar</Name>
    <Ref>request.header.user-agent</Ref>
  </AssignVariable>
  <AssignVariable>
    <Name>Country</Name>
    <Ref>request.queryparam.country</Ref>
  </AssignVariable>
</AssignMessage>
```

In this example, Edge does not have a default (or fallback value) specified for either
assignment.

### Example 2s23

The following example assigns the value of the flow variable `request.header.user-agent`
to the destination flow variable `myvar` and the value
of the query parameter `country` to the `Country` variable:

```
<AssignMessage name="assignvariable-2">
  <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>
</AssignMessage>
```

In this example, if the values of the `request.header.user-agent` flow variable
or the `Country` query parameter are null, unreadable, or malformed, Edge assigns
the value "ErrorOnCopy" to the new variables.

### Example 3s24

A common use case for `<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=city_ID
```

To define a default value for "w", create an AssignMessage policy like the
following:

```
<AssignMessage continueOnError="false" enabled="true" name="assignvariable-3">
  <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, `<AssignVariable>` gets the value of `request.queryparam.w`
and assigns it to itself. If the flow variable is null, meaning the "w" query parameter was
omitted from the request, then this example uses the default value from the
[`<Value>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignvariable-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.

Unlike when using `<Value>`, the value of `<Ref>` must be a
flow variable, such as a property of a [`request`](https://docs.apigee.com/api-platform/reference/variables-reference#request), [`response`](https://docs.apigee.com/api-platform/reference/variables-reference#response), or
[`target`](https://docs.apigee.com/api-platform/reference/variables-reference#target) object. The value can also be a custom flow variable that you created.

If you specify a flow variable that does not exist for the value of `<Ref>`,
and the value of [`<IgnoreUnresolvedVariables>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#ignoreunresolvedvariables) is "true", Edge throws an error.

#### `<Template>` (child of [`<AssignVariable>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignvariable))

Specifies a
[message template](https://docs.apigee.com/api-platform/reference/message-template-intro). A message
template allows you to perform variable string substitution when the policy executes, and
can combine literal strings with variable names wrapped in curly
braces. In addition, message templates
support [functions](https://docs.apigee.com/api-platform/reference/policies/api-platform/reference/message-template-intro#using-message-template-functions) such as escaping and case conversion.

Use the `ref` attribute to specify a flow variable where the value of the variable
is a message template. For example, you could store a message template as a
[custom attribute
on a developer app](https://docs.apigee.com/api-platform/publish/creating-apps-surface-your-api#register). When Edge identifies the developer app after it verifies the API key
or security token (through an additional policy), the `<AssignVariable>`
element could use the message template from the app's custom attribute, which is available
as a flow variable from the security policy.

|---|---|
| **Default Value** | n/a |
| **Required?** | Optional |
| **Type** | String |
| **Parent Element** | [`<AssignVariable>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignvariable) |
| **Child Elements** | None |

The `<Template>` element uses the following syntax:

### Syntaxs25

```
<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <AssignVariable>
    <Template>message_template</Template>
    or
    <Template ref='template_variable'></Template>
  </AssignVariable>
</AssignMessage>
```

### Example 1s26

The following example uses message templating syntax to concatenate two context variables
with a literal string (a hyphen) between them:

```
<AssignMessage name='AV-via-template-1'>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignVariable>
    <Name>my_destination_variable</Name>
    <Value>BADDBEEF</Value>
    <Template>{system.uuid}-{messageid}</Template>
  </AssignVariable>
</AssignMessage>
```

### Example 2s27

The following example specifies a flow variable, where the value of the variable
is a pre-defined message template. Use this option if you want to inject a pre-defined template at
runtime without having to modify the policy:

```
<AssignMessage name='AV-via-template-indirectly'>  
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignVariable>
    <Name>my_destination_variable</Name>
    <Value>BADDBEEF</Value>
    <Template ref='my_template_variable'/>
  </AssignVariable>
</AssignMessage>
```

### Example 3s28

The following example specifies a flow variable and a text value. In this case, if
the referenced variable is non-null, that value is used as the template. If the referenced
value is null, then the text value (in this case, `{system.uuid}-{messageid}`)
is used as the template. This pattern is useful to provide an "override" value, where
in some cases you want to override the default template (the text part) with values
that are set dynamically. For example, a conditional statement might grab a value
from a key-value map and set the referenced variable to that value:

```
<AssignMessage name='AV-template-with-fallback'> 
 <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignVariable>
    <Name>my_destination_variable</Name>
    <Value>BADDBEEF</Value>
    <Template ref='my_variable'>{system.uuid}-{messageid}</Template>
  </AssignVariable>
</AssignMessage>
```

#### `<Value>` (child of [`<AssignVariable>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignvariable))

Defines the value of the destination flow variable set with [`<AssignVariable>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignvariable). The
value is always interpreted as a literal string; you cannot use a flow variable as the value, even
if you wrap the value in brackets ("{}"). To use a flow variable, use [`<Ref>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignvariable-ref)
instead.

|---|---|
| **Default Value** | n/a |
| **Required?** | Optional |
| **Type** | String |
| **Parent Element** | [`<AssignVariable>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignvariable) |
| **Child Elements** | None |

When used in combination with the `<Ref>` element, `<Value>`
acts as the default (or fallback) value. If `<Ref>` is not specified, is
unresolvable, or is null, the value of `<Value>` is used.

The `<Value>` element uses the following syntax:

### Syntaxs29

```
<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <AssignVariable>
    <Name>variable_name</Name>
    <Value>variable_value</Value>
  </AssignVariable>
</AssignMessage>
```

### Example 1

The following example sets the value of the destination flow variable, `myvar`,
to the literal value "42":

```
<AssignMessage name="assignvariable-1">
  <AssignVariable>
    <Name>myvar</Name>
    <Value>42</Value>
  </AssignVariable>
</AssignMessage>
```

### Example 2

The following 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:

```
<AssignMessage name="assignvariable-2">
  <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>
</AssignMessage>
```

If either assignment fails, `<AssignVariable>` instead assigns the value "ErrorOnCopy" to
the destination flow variable.

### `<Copy>`

Copies values *from* the message specified by the `source` attribute
*to* the message specified by the [`<AssignTo>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignto) element. If you do not specify
a target with `<AssignTo>`, then this policy copies the values to the request or the response, depending on where in the flow this policy executes.

|---|---|
| **Default Value** | n/a |
| **Required?** | Optional |
| **Type** | String |
| **Parent Element** | [`<AssignMessage>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignmessage) |
| **Child Elements** | [`<FormParams>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#copy-formparams) [`<Headers>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#copy-headers) [`<Path>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#copy-path) [`<Payload>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#copy-payload) [`<QueryParams>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#copy-queryparams) [`<ReasonPhrase>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#copy-reasonphrase) [`<StatusCode>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#copy-statuscode) [`<Verb>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#copy-verb) [`<Version>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#copy-version) |

If you specify no child elements beneath the `<Copy>` element, then it will copy all parts
of the designated source message.

The `<Copy>` element uses the following syntax:

### Syntaxs30

    <AssignMessage
        continueOnError="[false|true]"
        enabled="[true|false]"
        name="policy_name" >
      <Copy source="[request|response]">
        <!-- Can also be an empty array (<FormParams/>) -->
        <FormParams>
          <FormParam name="formparam_name">formparam_value</FormParam>
          ...
        </FormParams>
        <!-- Can also be an empty array (<Headers/>) -->
        <Headers>
          <Header name="header_name">header_value</Header>
          ...
        </Headers>
        <Path>[false|true]</Path>
        <Payload>[false|true]</Payload>
        <!-- Can also be an empty array (<QueryParams/>) -->
        <QueryParams>
          <QueryParam name="queryparam_name">queryparam_value</QueryParam>
          ...
        </QueryParams>
        <ReasonPhrase>[false|true]</ReasonPhrase>
        <StatusCode>[false|true]</StatusCode>
        <Verb>[false|true]</Verb>
        <Version>[false|true]</Version>
      </Copy>
      <!-- Used as the destination for the <Copy> values -->
      <AssignTo createNew="[true|false]" transport="http"
        type="[request|response]">destination_variable_name</AssignTo>
    </AssignMessage>
      
### Example 1s31

The following example copies a header, three form parameters, the path, and all query
parameters from the `request` message to a new, custom request named `newRequest`:

```
<AssignMessage name="AM-copy-1">
  <AssignTo createNew="true" transport="http" type="request">newRequest</AssignTo>
  <Copy source="request">
    <Headers>
      <Header name="Header_Name_1"/>
    </Headers>
    <FormParams>
      <FormParam name="Form_Param_Name_1"/>
      <FormParam name="Form_Param_Name_2"/>
      <FormParam name="Form_Param_Name_3"/>
    </FormParams>
    <Path>true</Path>
    <QueryParams/>
  </Copy>
</AssignMessage>
```

Because elements like [`<Payload>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#copy-payload) and [`<Verb>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#copy-verb) are not present, the
policy does not copy those parts of the message.

### Example 2s32

The following example first removes everything in the existing `response` message, then
copies all the values from a different message called `secondResponse` into the
`response` message:

```
<AssignMessage name='AM-Copy-Response'>
  <AssignTo createNew="false" transport="http" type="response">response</AssignTo>
  <!-- first remove any existing values -->
  <Remove/>
  <!-- then copy everything from the designated message -->
  <Copy source="secondResponse"/>
</AssignMessage>
```

The `<Copy>` element has a single attribute:

| Attribute | Description | Required? | Type |
|---|---|---|---|
| source | Specifies the source object of the copy. - If `source` is not specified, it defaults to `message`, which takes a different value depending on the flow in which the policy executes. If the policy executes within the request flow, then the `message` variable refers to the `request` object. If the policy executes within the response flow, then the `message` variable refers to the `response` object. - If the source variable cannot be resolved, or resolves to a non-message type, `<Copy>` fails to respond. | Optional | String |

#### `<FormParams>` (child of [`<Copy>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#copy))

Copies form parameters from the request specified by the
[`<Copy>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#copy) element's `source` attribute *to* the request
specified by the [`<AssignTo>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignto) element. This element has no effect on a
response.

|---|---|
| **Default Value** | n/a |
| **Required?** | Optional |
| **Type** | Array of `<FormParam>` elements or an empty array |
| **Parent Element** | [`<Copy>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#copy) |
| **Child Elements** | `<FormParam>` |

The `<FormParams>` element uses the following syntax:

### Syntaxs33

```
<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <!-- Can also be an empty array (<FormParams/>) -->
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
  </Copy>
</AssignMessage>
```

### Example 1s34

The following example copies a single form parameter from the request to the
custom request "MyCustomRequest":

```
<AssignMessage name="copy-formparams-1">
  <Copy source="request">
    <FormParams>
      <FormParam name="paramName">Form param value 1</FormParam>
    </FormParams>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>
```

### Example 2s35

The following example copies all form parameters to the custom request
"MyCustomRequest":

```
<AssignMessage name="copy-formparams-2">
  <Copy source="request">
    <FormParams/>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>
```

### Example 3s36

The following example copies three form parameters to the custom request
"MyCustomRequest":

```
<AssignMessage name="copy-formparams-3">
  <Copy source="request">
    <FormParams>
      <FormParam name="paramName1"/>
      <FormParam name="paramName2"/>
      <FormParam name="paramName3"/>
    </FormParams>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>
```

### Example 4s37

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

```
<AssignMessage name="copy-formparams-4">
  <Copy source="request">
    <FormParams>
      <FormParam name="f1"/>
      <FormParam name="f2"/>
      <FormParam name="f3.2"/>
    </FormParams>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>
```

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

You can use `<FormParams>` only when the following criteria are met:

- HTTP verb: POST
- Message type: Response
- One (or both) of the following:
  - Form data: Set to some value, or "" (the empty string). For example, with `curl`, add `-d ""` to your request.
  - **`Content-Length` header:** Set to 0 (if no data is in the original request; otherwise, the current length. For example, with `curl` add `-H "Content-Length: 0"` to your request.

When you copy `<FormParams>`, `<Copy>` sets the message's `Content-Type` to
"application/x-www-form-urlencoded" before sending the message to the target service.

#### `<Headers>` (child of [`<Copy>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#copy))

Copies HTTP headers *from* the request or response message specified by
the [`<Copy>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#copy) element's `source` attribute *to* the request
or response message specified by the [`<AssignTo>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignto) element.

|---|---|
| **Default Value** | n/a |
| **Required?** | Optional |
| **Type** | An array of `<Header>` elements or an empty array |
| **Parent Element** | [`<Copy>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#copy) |
| **Child Elements** | `<Header>` |

The `<Headers>` element uses the following syntax:

### Syntaxs38

```
<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <!-- Can also be an empty array (<Headers/>) -->
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
  </Copy>
</AssignMessage>
```

### Example 1s39

The following example copies the `user-agent` header from the request to the
new, custom request object:

```
<AssignMessage name="copy-headers-1">
  <Copy source="request">
    <Headers>
      <Header name="user-agent"/>
    </Headers>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>
```

### Example 2s40

To copy all headers, use an empty `<Headers>` element, as the following example
shows:

```
<AssignMessage name="copy-headers-2">
  <Copy source="request">
    <Headers/>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>
```

### Example 3s41

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

```
<AssignMessage name="copy-headers-3">
  <Copy source="request">
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>
```

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

#### `<Path>` (child of [`<Copy>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#copy))

Determines whether the path should be copied from the source request to the destination
request. This element has no effect on a response.

If "true", this policy copies the path *from* the request message specified by the
[`<Copy>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#copy) element's `source` attribute *to* the request
message specified by the [`<AssignTo>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignto) element.

|---|---|
| **Default Value** | False |
| **Required?** | Optional |
| **Type** | Boolean |
| **Parent Element** | [`<Copy>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#copy) |
| **Child Elements** | None |

The `<Path>` element uses the following syntax:

### Syntax

```
<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <Path>[false|true]</Path>
  </Copy>
</AssignMessage>
```

### Example 1s42

The following example indicates that AssignMessage policy should copy the path from the source
request to the new, custom request object:

```
<AssignMessage name="copy-path-1">
  <Copy source="request">
    <Path>true</Path>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>
```

You can use `<Path>` only when the following criteria are met:

- Message type: Request

#### `<Payload>` (child of [`<Copy>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#copy))

Determines whether the payload should be copied from the source to the destination.
The source and destination can be requests or responses.

If "true", this policy copies the payload *from* the message specified by the
[`<Copy>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#copy) element's `source` attribute *to* the message
specified by the [`<AssignTo>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignto) element.

|---|---|
| **Default Value** | False |
| **Required?** | Optional |
| **Type** | Boolean |
| **Parent Element** | [`<Copy>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#copy) |
| **Child Elements** | None |

The `<Payload>` element uses the following syntax:

### Syntaxs43

```
<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <Payload>[false|true]</Payload>
  </Copy>
</AssignMessage>
```

### Example 1s44

The following example sets `<Payload>` to "true" so that the request payload is
copied from the request to the response:

```
<AssignMessage name="AM-copy-payload-1">
  <Copy source="request">
    <Payload>true</Payload>
  </Copy>
  <AssignTo>response</AssignTo>
</AssignMessage>
```

#### `<QueryParams>` (child of [`<Copy>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#copy))

Copies query string parameters *from* the request specified by the
[`<Copy>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#copy) element's `source` attribute *to* the request specified
by the [`<AssignTo>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignto) element. This element has no effect on a response.

|---|---|
| **Default Value** | n/a |
| **Required?** | Optional |
| **Type** | An array of `<QueryParam>` elements or an empty array |
| **Parent Element** | `<QueryParam>` |
| **Child Elements** | None |

The `<QueryParams>` element uses the following syntax:

### Syntaxs45

```
<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <!-- Can also be an empty array (<QueryParams/>) -->
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
  </Copy>
</AssignMessage>
```

### Example 1s46

The following example copies the "my_param" query parameter from the request into a new,
custom request object:

```
<AssignMessage name="copy-queryparams-1">
  <Copy source="request">
    <QueryParams>
      <QueryParam name="my_param"/>
    </QueryParams>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>
```

### Example 2s47

The following example copies all query parameters from the request into a new, custom
request object:

```
<AssignMessage name="copy-queryparams-2">
  <Copy source="request">
    <QueryParams/>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>
```

### Example 3s48

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

```
<AssignMessage name="copy-queryparams-3">
  <Copy source="request">
    <QueryParams>
      <QueryParam name="qp1"/>
      <QueryParam name="qp2"/>
      <QueryParam name="qp3.2"/>
    </QueryParams>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>
```

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

You can use `<QueryParams>` only when the following criteria are met:

- HTTP verb: GET
- Message type: Request

#### `<ReasonPhrase>` (child of [`<Copy>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#copy))

Determines whether the reason phrase should be copied from the source response to the
destination response. This element has no effect on a request.

If "true", this policy copies the `ReasonPhrase` *from* the response
specified by the [`<Copy>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#copy) element's `source` attribute *to* the response
specified by the [`<AssignTo>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignto) element.

|---|---|
| **Default Value** | False |
| **Required?** | Optional |
| **Type** | Boolean |
| **Parent Element** | [`<Copy>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#copy) |
| **Child Elements** | None |

The `<ReasonPhrase>` element uses the following syntax:

### Syntaxs49

```
<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <ReasonPhrase>[false|true]</ReasonPhrase>
  </Copy>
</AssignMessage>
```

### Example 1s50

The following example sets `<ReasonPhrase>` to `true`. With the source and
[`<AssignTo>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignto) element as specified, this causes `<Copy>`
to copy the reason phrase from the named response message to the `response` object:

```
<AssignMessage name="AM-copy-reasonphrase-1">
  <Copy source="serviceCalloutResponse">
    <ReasonPhrase>true</ReasonPhrase>
  </Copy>
  <AssignTo>response</AssignTo>
</AssignMessage>
```

You can use `<ReasonPhrase>` only when the source and destination messages are of type Response.

#### `<StatusCode>` (child of [`<Copy>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#copy))

Determines whether the status code is copied from the source response to the destination
response. This element has no effect on a request.

If "true", this policy copies the status code *from* the response message specified by
the [`<Copy>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#copy) element's `source` attribute *to* the response
message specified by the [`<AssignTo>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignto) element.

|---|---|
| **Default Value** | False |
| **Required?** | Optional |
| **Type** | Boolean |
| **Parent Element** | [`<Copy>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#copy) |
| **Child Elements** | None |

The `<StatusCode>` element uses the following syntax:

### Syntaxs52

```
<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <StatusCode>[false|true]</StatusCode>
  </Copy>
</AssignMessage>
```

### Example 1s53

The following example sets `<StatusCode>` to "true", which copies the status code
from the default response object to a new, custom response object:

```
<AssignMessage name="copy-statuscode-1">
  <Copy source="response">
    <StatusCode>true</StatusCode>
  </Copy>
  <AssignTo createNew="true" transport="http" type="response">MyCustomResponse</AssignTo>
</AssignMessage>
```

You can use `<StatusCode>` only when the source and destination messages are of type Response.

A common use of `<StatusCode>` is to set the proxy response status code to
a different value than that received from the target.

#### `<Verb>` (child of [`<Copy>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#copy))

Determines whether the HTTP verb is copied from the source request to the destination
request. This element has no effect on a response.

If "true", copies the verb found in the `<Copy>` element's `source` attribute
to the request specified in the [`<AssignTo>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignto) element.

|---|---|
| **Default Value** | False |
| **Required?** | Optional |
| **Type** | Boolean |
| **Parent Element** | [`<Copy>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#copy) |
| **Child Elements** | None |

The `<Verb>` element uses the following syntax:

### Syntaxs54

```
<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <Verb>[false|true]</Verb>
  </Copy>
</AssignMessage>
```

### Example 1s55

The following example sets `<Verb>` to "true", which copies the verb from the
default request to a new, custom request:

```
<AssignMessage name="copy-verb-1">
  <Copy source="request">
    <Verb>true</Verb>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>
```

You can use `<Verb>` only when the following criteria are met:

- Message type: Request

#### `<Version>` (child of [`<Copy>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#copy))

Determines whether the HTTP version is copied from the source request to the
destination request. This element has no effect on a response.

If "true", copies the HTTP version found in the `<Copy>` element's `source` attribute
to the object specified by the [`<AssignTo>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignto) element.

|---|---|
| **Default Value** | False |
| **Required?** | Optional |
| **Type** | Boolean |
| **Parent Element** | [`<Copy>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#copy) |
| **Child Elements** | None |

The `<Version>` element uses the following syntax:

### Syntaxs56

```
<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <Version>[false|true]</Version>
  </Copy>
</AssignMessage>
```

### Example 1s57

The following example sets `<Version>` to "true" on the request, which copies the
version from the default request object to a new, custom request object:

```
<AssignMessage name="copy-version-1">
  <Copy source="request">
    <Version>true</Version>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>
```

You can use `<Version>` only when the following criteria are met:

- Message type: Request

### `<DisplayName>`

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

The `<DisplayName>` element is common to all policies.

|---|---|
| **Default Value** | n/a |
| **Required?** | Optional. If you omit `<DisplayName>`, the value of the policy's `name` attribute is used |
| **Type** | String |
| **Parent Element** | \<<var translate="no">PolicyElement</var>\> |
| **Child Elements** | None |

The `<DisplayName>` element uses the following syntax:

### Syntax

```
<PolicyElement>
  <DisplayName>policy_display_name</DisplayName>
  ...
</PolicyElement>
```

### Example

```
<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>
```

The `<DisplayName>` element has no attributes or child elements.

### `<IgnoreUnresolvedVariables>`

Determines whether processing stops when an unresolved variable is encountered.

|---|---|
| **Default Value** | False |
| **Required?** | Optional |
| **Type** | Boolean |
| **Parent Element** | [`<AssignMessage>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignmessage) |
| **Child Elements** | None |

Set to `true` to ignore unresolved variables and continue processing; otherwise
`false`. The default value is `false`.

Setting `<IgnoreUnresolvedVariables>` to `true` is different from setting the
[`<AssignMessage>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignmessage)'s `continueOnError` to `true` in that it is specific to
setting and getting values of variables. If you set `continueOnError` to
`true`, then Edge ignores all errors, not just errors encountered when using
variables.

The `<IgnoreUnresolvedVariables>` element uses the following syntax:

### Syntaxs58

```
<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <IgnoreUnresolvedVariables>[true|false]
  </IgnoreUnresolvedVariables>
</AssignMessage>
```

### Example 1s59

The following example sets `<IgnoreUnresolvedVariables>` to "true":

```
<AssignMessage name="AM-Set-Headers">
  <Set>
    <Headers>
      <Header name='new-header'>{possibly-defined-variable}<Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>true
  </IgnoreUnresolvedVariables>
</AssignMessage>
```

Because `<IgnoreUnresolvedVariables>` is set to `true`, if
the `possibly-defined-variable` variable is not defined, this policy will
not throw a fault.

### `<Remove>`

Removes headers, query parameters, form parameters, and/or the message payload from
a message. The message can be a request or a response. You specify which message `<Remove>`
acts on by using the [`<AssignTo>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignto) element.

|---|---|
| **Default Value** | n/a |
| **Required?** | Optional |
| **Type** | Complex type |
| **Parent Element** | [`<AssignMessage>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignmessage) |
| **Child Elements** | [`<FormParams>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#remove-formparams) [`<Headers>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#remove-headers) [`<Payload>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#remove-payload) [`<QueryParams>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#remove-queryparams) |

A common use case for `<Remove>` is to delete a query parameter or header that contains sensitive information from the incoming request object, to avoid passing it to the backend server.

The `<Remove>` element uses the following syntax:

### Syntaxs60

```
<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Remove>
    <!-- Can also be an empty array (<FormParams/>) -->
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
    <!-- Can also be an empty array (<Headers/>) -->
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
    <Payload>[false|true]</Payload>
    <!-- Can also be an empty array (<QueryParams/>) -->
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
  </Remove>
</AssignMessage>
```

### Example 1s61

The following example removes the message's body from the response:

```
<AssignMessage name="AM-remove-1">
  <DisplayName>remove-1</DisplayName>
  <Remove>
    <Payload>true</Payload>
  </Remove>
  <AssignTo>response</AssignTo>
</AssignMessage>
```

In the response flow, this policy removes the body of the response, returning only HTTP
headers to the client.

### Example 2s62

The following example removes all form parameters and a query parameter from
the `request` object:

```
<AssignMessage name="AM-remove-2">
  <Remove>
    <!-- Empty (<FormParams/>) removes all form parameters -->
    <FormParams/>
    <QueryParams>
      <QueryParam name="qp1"/>
    </QueryParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>
```

### Example 3s63

The following example removes everything from a message object:

```
<AssignMessage name="AM-remove-3">
  <Remove/>
  <AssignTo>request</AssignTo>
</AssignMessage>
```

Typically you would do this only if you were going to use the [`<Set>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#set) element or
the [`<Copy>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#copy) element to set some replacement values in the message.

#### `<FormParams>` (child of [`<Remove>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#remove))

Removes the specified form parameters from the request. This element has no effect on a
response.

|---|---|
| **Default Value** | n/a |
| **Required?** | Optional |
| **Type** | Array of `<FormParam>` elements or an empty array |
| **Parent Element** | [`<Remove>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#remove) |
| **Child Elements** | `<FormParam>` |

The `<FormParams>` element uses the following syntax:

### Syntaxs64

```
<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Remove>
    <!-- Can also be an empty array (<FormParams/>) -->
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
  </Remove>
</AssignMessage>
```

### Example 1s65

The following example removes three form parameters from the request:

```
<AssignMessage name="AM-remove-formparams-1">
  <Remove>
    <FormParams>
      <FormParam name="form_param_1"/>
      <FormParam name="form_param_2"/>
      <FormParam name="form_param_3"/>
    </FormParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>
```

### Example 2s66

The following example removes all form parameters from the request:

```
<AssignMessage name="AM-remove-formparams-2">
  <Remove>
    <FormParams/>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>
```

### Example 3s67

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

```
<AssignMessage name="AM-remove-formparams-3">
  <Remove>
    <FormParams>
      <FormParam name="f1"/>
      <FormParam name="f2"/>
      <FormParam name="f3.2"/>
    </FormParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>
```

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

You can use `<FormParams>` only when the following criteria are met:

- Message type: Request
- `Content-Type`: "application/x-www-form-urlencoded"

#### `<Headers>` (child of [`<Remove>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#remove))

Removes the specified HTTP headers from the request or response, which is specified by the
[`<AssignTo>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignto) element.

|---|---|
| **Default Value** | n/a |
| **Required?** | Optional |
| **Type** | Array of `<Header>` elements or an empty array |
| **Parent Element** | [`<Remove>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#remove) |
| **Child Elements** | `<Header>` |

The `<Headers>` element uses the following syntax:

### Syntax

```
<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Remove>
    <!-- Can also be an empty array (<Headers/>) -->
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
  </Remove>
</AssignMessage>
```

### Example 1s68

The following example removes the `user-agent` header from the request:

```
<AssignMessage name="AM-remove-one-header">
  <Remove>
    <Headers>
      <Header name="user-agent"/>
    </Headers>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>
```

### Example 2s69

The following example removes all headers from the request:

```
<AssignMessage name="AM-remove-all-headers">
  <Remove>
    <Headers/>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>
```

### Example 3s70

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

```
<AssignMessage name="AM-remove-headers-3">
  <Remove>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>
```

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

#### `<Payload>` (child of [`<Remove>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#remove))

Determines whether `<Remove>` deletes the payload in the request or response, which is
specified by the [`<AssignTo>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignto) element. Set to "true" to
clear the payload; otherwise "false". The default value is "false".

|---|---|
| **Default Value** | False |
| **Required?** | Optional |
| **Type** | Boolean |
| **Parent Element** | [`<Remove>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#remove) |
| **Child Elements** | None |

The `<Payload>` element uses the following syntax:

### Syntax

```
<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Remove>
    <Payload>[false|true]</Payload>
  </Remove>
</AssignMessage>
```

### Example 1s71

The following example sets `<Payload>` to "true" so that the request payload is
cleared:

```
<AssignMessage name="AM-remove-payload-1">
  <Remove>
    <Payload>true</Payload>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>
```

#### `<QueryParams>` (child of [`<Remove>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#remove))

Removes the specified query parameters from the request. This element has no effect on a
response.

|---|---|
| **Default Value** | n/a |
| **Required?** | Optional |
| **Type** | Array of `<QueryParam>` elements or an empty array |
| **Parent Element** | [`<Remove>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#remove) |
| **Child Elements** | `<QueryParam>` |

The `<QueryParams>` element uses the following syntax:

### Syntaxs72

```
<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Remove>
    <!-- Can also be an empty array (<QueryParams/>) -->
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
  </Remove>
</AssignMessage>
```

### Example 1s73

The following example removes a single query parameter from the request:

```
<AssignMessage name="AM-remove-queryparams-1">
  <Remove>
      <QueryParams>
        <QueryParam name="qp1"/>
      </QueryParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>
```

### Example 2s74

The following example removes all query parameters from the request:

```
<AssignMessage name="AM-remove-queryparams-2">
  <Remove>
      <QueryParams/>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>
```

### Example 3s75

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

```
<AssignMessage name="AM-remove-queryparams-3">
  <Remove>
      <QueryParams>
        <QueryParam name="qp1"/>
        <QueryParam name="qp2"/>
        <QueryParam name="qp3.2"/>
      </QueryParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>
```

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

### Example 4s76

The following example removes the `apikey` query parameter from the request:

```
<AssignMessage name="AM-remove-query-param">
  <Remove>
    <QueryParams>
      <QueryParam name="apikey"/>
    </QueryParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>
```

You can use `<QueryParams>` only when the following criteria are met:

- HTTP verb: GET
- Message type: Request

### `<Set>`

Sets information in the request or response message, which is specified by the
[`<AssignTo>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignto) element. `<Set>` overwrites headers or
query or form parameters that already exist in the original message. Headers and query and form parameters
in an HTTP message may hold multiple values. To add additional values for a header or parameter, use
the [`<Add>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#add) element instead.

|---|---|
| **Default Value** | n/a |
| **Required?** | Optional |
| **Type** | Complex type |
| **Parent Element** | [`<AssignMessage>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignmessage) |
| **Child Elements** | [`<FormParams>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#set-formparams) [`<Headers>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#set-headers) [`<Payload>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#set-payload) [`<Path>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#set-path) [`<QueryParams>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#set-queryparams) [`<ReasonPhrase>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#set-reasonphrase) [`<StatusCode>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#set-statuscode) [`<Verb>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#set-verb) [`<Version>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#set-version) |

> [!NOTE]
> **Note** : The sub-elements of `<Set>` support the dynamic string substitution feature called [message templating](https://docs.apigee.com/api-platform/reference/message-template-intro).

The `<Set>` element uses the following syntax:

### Syntax

```
<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
    <Path>path</Path>
    <Payload contentType="content_type" variablePrefix="prefix"
        variableSuffix="suffix">new_payload</Payload>
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
    <ReasonPhrase>reason_for_error or {variable}</ReasonPhrase>
    <StatusCode>HTTP_status_code or {variable}</StatusCode>
    <Verb>[GET|POST|PUT|PATCH|DELETE|{variable}]</Verb>
    <Version>[1.0|1.1|{variable}]</Verb>
  </Set>
</AssignMessage>
```

### Example 1s77

The following example sets a specific header. When this policy is attached in the Request flow,
it will allow the upstream system to receive an additional header that was not included in the
original inbound request.

```
<AssignMessage name="AM-Set-Header">
  <Set>
    <Headers>
        <Header name="authenticated-developer">{verifyapikey.VAK-1.developer.id}</Header>
    </Headers>
  </Set>
  <AssignTo>request</AssignTo>
</AssignMessage>
```

### Example 2s78

The following example overwrites the payload for a response, as well as the `Content-Type` header.

```
<AssignMessage name="AM-Overwrite-Payload">
  <Set>
    <Payload contentType="application/json">{ "status" : 42 }</Payload>
  </Set>
  <AssignTo>response</AssignTo>
</AssignMessage>
```

#### `<FormParams>` (child of [`<Set>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#set))

Overwrites existing form parameters on a request and replaces them with the new values that you
specify with this element. This element has no effect on a response.

|---|---|
| **Default Value** | n/a |
| **Required?** | Optional |
| **Type** | Array of `<FormParam>` elements |
| **Parent Element** | [`<Set>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#set) |
| **Child Elements** | `<FormParam>` |

The `<FormParams>` element uses the following syntax:

### Syntaxs79

```
<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
  </Set>
</AssignMessage>
```

### Example 1s80

The following example sets a form parameter called "myparam" to the value of the
`request.header.myparam` variable in a new, custom request:

```
<AssignMessage name="AM-set-formparams-1">
  <Set>
    <FormParams>
      <FormParam name="myparam">{request.header.myparam}</FormParam>
    </FormParams>
  </Set>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>
```

You can use `<FormParams>` only when the following criteria are met:

- HTTP verb: POST
- Message type: Request

If you define empty form parameters in your policy
(`<Add><FormParams/></Add>`), the policy does not add any form
parameters. This is the same as omitting the `<FormParams>`.

`<Set>` changes the `Content-Type` of the message to
"application/x-www-form-urlencoded" before sending it to the target endpoint.

#### `<Headers>` (child of [`<Set>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#set))

Overwrites existing HTTP headers in the request or response, which is specified by the
[`<AssignTo>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignto) element.

|---|---|
| **Default Value** | n/a |
| **Required?** | Optional |
| **Type** | Array of `<Header>` elements |
| **Parent Element** | [`<Set>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#set) |
| **Child Elements** | `<Header>` |

The `<Headers>` element uses the following syntax:

### Syntaxs81

```
<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
  </Set>
</AssignMessage>
```

### Example 1s81

The following example sets the `x-ratelimit-remaining` header to the value of the
`ratelimit.Quota-1.available.count` variable:

```
<AssignMessage name="AM-Set-RateLimit-Header">
  <Set>
    <Headers>
      <Header name="X-RateLimit-Remaining">{ratelimit.Quota-1.available.count}</Header>
    </Headers>
  </Set>
  <AssignTo>response</AssignTo>
</AssignMessage>
```

If you define empty headers in your policy
(`<Set><Headers/></Set>`), the policy does not set any headers. This
will have the same effect as omitting `<Headers>`.

#### `<Path>` (child of [`<Set>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#set))

> [!NOTE]
> **Note** :
>
> 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 AssignMessage 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 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](https://docs.apigee.com/api-platform/reference/policies/javascript-policy) in the TargetEndpoint to
> override the `target.url`.

#### `<Payload>` (child of [`<Set>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#set))

Defines the message body for a request or response, which is specified by the
[`<AssignTo>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignto) element. The payload can be any valid content type, such as plain
text, JSON, or XML.

|---|---|
| **Default Value** | empty string |
| **Required?** | Optional |
| **Type** | String |
| **Parent Element** | [`<Set>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#set) |
| **Child Elements** | None |

The `<Payload>` element uses the following syntax:

### Syntaxs82

```
<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <Payload contentType="content_type" variablePrefix="prefix"
        variableSuffix="suffix">new_payload</Payload>
  </Set>
</AssignMessage>
```

### Example 1s83

The following example sets a plain text payload:

```
<AssignMessage name="set-payload-1">
  <Set>
    <Payload contentType="text/plain">42</Payload>
  </Set>
</AssignMessage>
```

### Example 2s84

The following example sets a JSON payload:

```
<AssignMessage name="set-payload-2">
  <Set>
    <Payload contentType="application/json">
      {"name":"foo", "type":"bar"}
    </Payload>
  </Set>
</AssignMessage>
```

### Example 3s85

The following example inserts variable values into the payload by wrapping variable names
in curly braces:

```
<AssignMessage name="set-payload-3">
  <Set>
    <Payload contentType="application/json">
      {"name":"foo", "type":"{variable_name}"}
    </Payload>
  </Set>
</AssignMessage>
```

In previous versions of Apigee, you could
not use curly braces to denote variable references within JSON payloads. In those releases, you
needed to use the `variablePrefix` and `variableSuffix` attributes to
specify delimiter characters, and use those to wrap variable names, like so:

```
<AssignMessage name="set-payload-3b">
  <Set>
    <Payload contentType="application/json" variablePrefix="@" variableSuffix="#">
      {"name":"foo", "type":"@variable_name#"}
    </Payload>
  </Set>
</AssignMessage>
```

This older syntax still works.

### Example 4s86

The content of `<Payload>` is treated as a message template. This means that the
AssignMessage policy replaces variables wrapped in curly braces with the value of the
referenced variables at runtime.

The following example uses the curly braces syntax to set part of the payload to a
variable value:

```
<AssignMessage name="set-payload-4">
  <Set>
    <Payload contentType="text/xml">
      <root>
        <e1>sunday</e1>
        <e2>funday</e2>
        <e3>{var1}</e3>
      </root>
    </Payload>
  </Set>
</AssignMessage>
```

> [!NOTE]
> **Note**: Do not include the XML prologue in the payload; otherwise, you will get XML validation errors.

The following table describes the attributes of `<Payload>`:

| Attribute | Description | Presence | Type |
|---|---|---|---|
| `contentType` | If specified, the value of `contentType` is assigned to the `Content-Type` HTTP header. | Optional | String |
| `variablePrefix` | Optionally specifies the leading delimiter on a flow variable. Defaults to "{". For more information, see [Flow variables reference](https://docs.apigee.com/api-platform/reference/variables-reference). | Optional | Char |
| `variableSuffix` | Optionally specifies the trailing delimiter on a flow variable. Defaults to "}". For more information, see [Flow variables reference](https://docs.apigee.com/api-platform/reference/variables-reference). | Optional | Char |

#### `<QueryParams>` (child of [`<Set>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#set))

Overwrites existing query parameters in the request with new values. This element has no effect
on a response.

|---|---|
| **Default Value** | n/a |
| **Required?** | Optional |
| **Type** | Array of `<QueryParam>` elements |
| **Parent Element** | [`<Set>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#set) |
| **Child Elements** | `<QueryParam>` |

The `<QueryParams>` element uses the following syntax:

### Syntaxs87

```
<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
  </Set>
</AssignMessage>
```

### Example 1s88

The following example sets the "address" query parameter to the value of the
`request.header.address` variable:

```
<AssignMessage name="AM-set-queryparams-1">  <Set>
    <QueryParams>
      <QueryParam name="address">{request.header.address}</QueryParam>
    </QueryParams>
  </Set>
</AssignMessage>
```

You can use `<QueryParams>` only when the following criteria are met:

- HTTP verb: GET
- Message type: Request

If you define empty query parameters in your policy
(`<Set><QueryParams/></Set>`), the policy does not set any query
parameters. This is the same as omitting `<QueryParams>`.

#### `<ReasonPhrase>` (child of [`<Set>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#set))

Sets the reason phrase on the response. This is normally done for debugging in combination with
`<StatusCode>`. This element has no effect on a request.

|---|---|
| **Default Value** | n/a |
| **Required?** | Optional |
| **Type** | String |
| **Parent Element** | [`<Set>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#set) |
| **Child Elements** | None |

The `<ReasonPhrase>` element uses the following syntax:

### Syntaxs89

```
<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <ReasonPhrase>reason_for_error or {variable}</ReasonPhrase>
  </Set>
</AssignMessage>
```

### Example 1s90

The following example defines a simple reason phrase:

```
<AssignMessage name="set-reasonphrase-1">
  <Set>
    <ReasonPhrase>Bad medicine</ReasonPhrase>
  </Set>
  <AssignTo createNew="true" transport="http" type="response"/>
</AssignMessage>
```

### Example 2s91

The content of `<ReasonPhrase>` is treated as a message template. This means
a variable name wrapped in curly braces will be replaced at runtime with the value of the
referenced variable, as the following example shows:

```
<AssignMessage name="AM-set-reasonphrase-2">
  <Set>
    <ReasonPhrase>{calloutresponse.reason.phrase}</ReasonPhrase>
  </Set>
  <AssignTo>response</AssignTo>
</AssignMessage>
```

You can use `<ReasonPhrase>` only when the following criteria are met:

- Message type: Response

#### `<StatusCode>` (child of [`<Set>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#set))

Sets the status code on the response. This element has no effect on a request.

|---|---|
| **Default Value** | '200' (when [`<AssignTo>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignto)'s `createNew` attribute is set to 'true') |
| **Required?** | Optional |
| **Type** | String or <var translate="no">variable</var> |
| **Parent Element** | [`<Set>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#set) |
| **Child Elements** | None |

The `<StatusCode>` element uses the following syntax:

### Syntaxs92

```
<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <StatusCode>HTTP_status_code or {variable}</StatusCode>
  </Set>
</AssignMessage>
```

### Example 1

The following example sets a simple status code:

```
<AssignMessage name="AM-set-statuscode-404">
  <Set>
    <StatusCode>404</StatusCode>
  </Set>
  <AssignTo>response</AssignTo>
</AssignMessage>
```

### Example 2

The content of `<StatusCode>` is treated as a message template. This means a
variable name wrapped in curly braces will be replaced at runtime with the value of the
referenced variable, as the following example shows:

```
<AssignMessage name="set-statuscode-2">
  <Set>
    <StatusCode>{calloutresponse.status.code}</StatusCode>
  </Set>
  <AssignTo>response</AssignTo>
</AssignMessage>
```

You can use `<StatusCode>` only when the following criteria are met:

- Message type: Response

#### `<Verb>` (child of [`<Set>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#set))

Sets the HTTP verb on the request. This element has no effect on a response.

|---|---|
| **Default Value** | n/a |
| **Required?** | Optional |
| **Type** | String or <var translate="no">variable</var> |
| **Parent Element** | [`<Set>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#set) |
| **Child Elements** | None |

The `<Verb>` element uses the following syntax:

### Syntax

```
<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <Verb>[GET|POST|PUT|PATCH|DELETE|{variable}]</Verb>
  </Set>
</AssignMessage>
```

### Example 1s93

The following example sets a simple verb on the request:

```
<AssignMessage name="AM-set-verb-1">
  <Set>
    <Verb>POST</Verb>
  </Set>
  <AssignTo>request</AssignTo>
</AssignMessage>
```

### Example 2s94

The content of `<Verb>` is treated as a message template. This means a variable name
wrapped in curly braces will be replaced at runtime with the value of the referenced
variable.

The following example uses a variable to populate a verb:

```
<AssignMessage name="AM-set-verb-to-dynamic-value">
  <Set>
    <Verb>{my_variable}</Verb>
  </Set>
  <AssignTo>request</AssignTo>
</AssignMessage>
```

You can use `<Verb>` only when the following criteria are met:

- Message type: Request

#### `<Version>` (child of [`<Set>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#set))

Sets the HTTP version on a request. This element has no effect on a response.

|---|---|
| **Default Value** | n/a |
| **Required?** | Optional |
| **Type** | String or <var translate="no">variable</var> |
| **Parent Element** | [`<Set>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#set) |
| **Child Elements** | None |

The `<Version>` element uses the following syntax:

### Syntaxs95

```
<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <Version>[1.0|1.1|{variable}]</Verb>
  </Set>
</AssignMessage>
```

### Example 1s96

The following example sets the version number to "1.1":

```
<AssignMessage name="AM-set-version-1">
  <Set>
    <Version>1.1</Version>
  </Set>
 </AssignMessage>
```

### Example 2

The following uses a variable in curly braces to set the version number:

```
<AssignMessage name="AM-set-version-2">
  <Set>
    <Version>{my_version}</Version>
  </Set>
  <AssignTo>request</AssignTo>
</AssignMessage>
```

The content of `<Version>` is treated as a message template. This means a
variable name wrapped in curly braces will be replaced at runtime with the value of the referenced
variable.

You can use `<Version>` only when the following criteria are met:

- Message type: Request

## Create custom request messages

You can use AssignMessage policy to create a custom request message. After you create a custom
request, you can use it in the following ways:

- Access its variables in other policies
- Pass it to an external service

> [!NOTE]
> **Note** : You cannot pass a custom request message to the target endpoint in the flow. Edge only passes the *original request* (with any modifications you might have made) to the target endpoint.

To create a custom request message, use the [`<AssignTo>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#assignto) element in your AssignMessage policy
policy. Set `createNew` to "true" and specify the name of the new message in the body
of the element, as the following example shows:

```
<AssignMessage name="AM-assignto-2"> 
  <AssignTo createNew="true" transport="http" type="request">NameOfNewMessage</AssignTo> 
</AssignMessage>
```

By default, Edge does nothing with the custom request message. After creating it, Edge will
continue through the flow with the original request. To use the custom request, add a policy such
as the [ServiceCallout policy](https://docs.apigee.com/api-platform/reference/policies/service-callout-policy) to your proxy that can pass the custom request to an external
service.

The following examples create custom request messages:

### Example 1s97

The following example creates a custom request object with Assign Message:

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

This example:

- Creates a new request message object called "MyCustomRequest".
- On MyCustomRequest, this policy:
  - Copies the value of the `user-agent` HTTP header from the incoming request to the new message. Because [`<Copy>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#copy) uses an absolute reference to the `user-agent` flow variable, there is no need to specify the `source` attribute to `<Copy>`.
  - Sets the `address` query parameter on the custom message to the value of the incoming request's `addy` query parameter.
  - Sets the HTTP verb to `GET`.
- Sets [`<IgnoreUnresolvedVariables>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#ignoreunresolvedvariables) to "false". When `<IgnoreUnresolvedVariables>` is "false", if one of the variables the policy tries to add does not exist, Edge will stop processing in the API flow.

### Example 2s98

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

This example creates a new custom request called "partner.request". It then sets the
[`<Verb>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#set-verb) and [`<Payload>`](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#set-payload) on the new request.

You can access a custom request message in another AssignMessage policy that occurs later in
the flow. The following example gets the value of the custom request message's
`user-agent` header:

```
<AssignMessage name="custom-request-1-access">
  <DisplayName>custom-request-1-access</DisplayName>
  <AssignTo>partner.request</AssignTo>
  <Set>
    <Headers>
      <Header name="user-agentCopyCustomRequest">{MyCustomRequest.header.user-agent}</Header>
    </Headers>
  </Set>
</AssignMessage>
```

## Videos

Watch the following videos to learn more about the AssignMessage policy.

| Video | Description |
|---|---|
| [Why Assign Message Policy?](https://www.youtube.com/watch?v=-goGhTJoeB8) | Learn about the benefits of using AssignMessage policy to modify the API request or response without modifying the backend code. |
| [Copy API elements using AssignMessage policy](https://www.youtube.com/watch?v=cgRPbgKNpQI) | Copy elements from an API request or response and construct a new request or response object using the AssignMessage policy. |
| [Remove API elements using AssignMessage policy](https://www.youtube.com/watch?v=r9MJxUbwMko) | Remove API elements and modify the API before it reaches the target backend using the AssignMessage policy. |
| [Add and set API elements using AssignMessage policy](https://www.youtube.com/watch?v=kpXhNrZCwR4) | Change API request or response by adding query parameters, headers, form parameters, or payloads using the AssignMessage policy. |
| [Create custom variables using AssignMessage policy](https://www.youtube.com/watch?v=RyZI--auWfA) | Set custom flow variables using AssignMessage policy and leverage the variables in other policies in the API proxy. |
| [Create new request or response objects using AssignMessage policy](https://www.youtube.com/watch?v=Fk5EDazB4-Y) | Create new API request or response objects using the AssignMessage policy at API runtime. |
| [Create a mock API using AssignMessage policy](https://www.youtube.com/watch?v=grNhwkrFBxg) | Create a simple mock REST API by adding the AssignMessage policy in the response flow. |
| [Set or modify the payload using AssignMessage policy](https://www.youtube.com/watch?v=PUDogzEAZ-Y) | Convert REST request to SOAP request by setting SOAP Payload using the AssignMessage policy policy at API runtime. |

## Error codes


This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error.
This information is important to know if you are developing fault rules to
handle faults. To learn more, see [What you need to know
about policy errors](https://docs.apigee.com/api-platform/fundamentals/what-you-need-know-about-policy-errors) and [Handling
faults](https://docs.apigee.com/api-platform/fundamentals/fault-handling).

### Runtime errors

These errors can occur when the policy executes.

> [!IMPORTANT]
> Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

> [!IMPORTANT]
> **Tip:** Use [API Monitoring](https://docs.apigee.com/api-monitoring) to investigate fault codes and diagnose issues faster. See [Set up a policy fault code alert](https://docs.apigee.com/api-monitoring/alerts-notifications#fault-code-alert) for an example. See [Fault code reference](https://docs.apigee.com/api-monitoring/fault-codes) for a complete list of all fault codes that you can handle with API Monitoring.

| Fault code | HTTP status | Cause | Fix |
|---|---|---|---|
| `steps.assignmessage.SetVariableFailed` | 500 | The policy was not able to set a variable. See the fault string for the name of the unresolved variable. |   |
| `steps.assignmessage.VariableOfNonMsgType` | 500 | This error occurs if the `source` attribute in the `<Copy>` element is set to a variable which is not of type [message](https://docs.apigee.com/api-platform/reference/variables-reference#messagevariables). Message type variables represent entire HTTP requests and responses. The built-in Edge flow variables `request`, `response`, and `message` are of type message. To learn more about message variables, see the [Variables reference](https://docs.apigee.com/api-platform/reference/variables-reference#messagevariables). | [](https://docs.apigee.com/api-platform/troubleshoot/policies/runtime/assign-message-runtime-errors#variableofnonmsgtype) |
| `steps.assignmessage.UnresolvedVariable` | 500 | This error occurs if a variable specified in the Assign Message policy is either: - out of scope (not available in the specific flow where the policy is being executed) or - can't be resolved (is not defined) | [](https://docs.apigee.com/api-platform/troubleshoot/policies/runtime/assign-message-runtime-errors#unresolvedvariable) |

### Deployment errors

These errors can occur when you deploy a proxy containing this policy.

> [!IMPORTANT]
> Need help resolving an error? Click next to the error's cause description to visit the troubleshooting page.

| Error name | Cause | Fix |
|---|---|---|
| `InvalidIndex` | If the index specified in the `<Copy>` and/or `<Remove>` elements of the Assign Message policy is 0 or a negative number, then deployment of the API Proxy fails. | [](https://docs.apigee.com/api-platform/troubleshoot/policies/deployment/assign-message-deployment-errors#invalidindex) |
| `InvalidVariableName` | If the child element `<Name>` is empty or not specified in the `<AssignVariable>` element, then the deployment of the API proxy fails because there is no valid variable name to which to assign a value. A valid variable name is required. | [](https://docs.apigee.com/api-platform/troubleshoot/policies/deployment/assign-message-deployment-errors#invalidvariablename) |
| `InvalidPayload` | A payload specified in the policy is invalid. |   |

### Fault variables

These variables are set when this policy triggers an error at runtime. For more information,
see [What you
need to know about policy errors](https://docs.apigee.com/api-platform/fundamentals/what-you-need-know-about-policy-errors).

| Variables | Where | Example |
|---|---|---|
| `fault.name="fault_name"` | <var translate="no">fault_name</var> is the name of the fault, as listed in the [Runtime errors](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy#runtime-errors) table above. The fault name is the last part of the fault code. | `fault.name Matches "UnresolvedVariable"` |
| `assignmessage.policy_name.failed` | <var translate="no">policy_name</var> is the user-specified name of the policy that threw the fault. | `assignmessage.AM-SetResponse.failed = true` |

### Example error response

> [!NOTE]
> **Note:** For error handling, the best practice is to trap the `errorcode` part of the error response. Do not rely on the text in the `faultstring`, because it could change.

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

### Example fault rule

```
    <FaultRule name="Assign Message Faults">    <Step>
        <Name>AM-CustomNonMessageTypeErrorResponse</Name>
        <Condition>(fault.name Matches "VariableOfNonMsgType") </Condition>
    </Step>
    <Step>
        <Name>AM-CustomSetVariableErrorResponse</Name>
        <Condition>(fault.name = "SetVariableFailed")</Condition>
    </Step>
    <Condition>(assignmessage.failed = true) </Condition>
</FaultRule>
```

<br />

## Schemas

Each policy type is defined by an XML schema (`.xsd`). For reference, [policy schemas](https://github.com/apigee/api-platform-samples/tree/master/schemas/policy)
are available on GitHub.

## Related topics

[Working
samples of the AssignMessage](https://github.com/apigee/api-platform-samples/tree/master/sample-proxies/pagination) policy are available in the [API Platform samples](https://github.com/apigee/api-platform-samples).

For a more advanced example of how to override the `target.url` from the
ProxyEndpoint, see [this Apigee Community article](https://discuss.google.dev/t/how-do-i-transform-the-path-between-the-proxy-and-the-target/8875/4).

To see a "set path" in action in a [ServiceCallout policy](https://docs.apigee.com/api-platform/reference/policies/service-callout-policy), check out this [Learn by doing example](https://github.com/apigee/api-platform-samples/tree/master/learn-edge/service-callout-1) in the Apigee GitHub samples. Just clone the repository and
follow the instructions in that topic. The example uses AssignMessage policy to set a request path,
then uses a Service Callout policy to make the request to an external service.