AssignMessage policy

View Apigee Edge documentation.

What

The AssignMessage policy can change an existing request or response message, or create a new request or response message during the API proxy Flow. The policy lets you perform the following actions on those messages:

Add new form parameters, headers, or query parameters to a message
Copy existing properties from one message to another
Remove headers, query parameters, form parameters, and message payloads from a message
Set the value of properties in a message

AssignMessage also allows you to set arbitrary context variables, independent of any of the above operations that might apply to a message.

With AssignMessage, you can add, change, or remove properties of either the request or response. You can alternatively use AssignMessage to create a custom request or response message and pass it to an alternative target, as described in Create custom request messages.

This policy is an Extensible policy and use of this policy might have cost or utilization implications, depending on your Apigee license. For information on policy types and usage implications, see Policy types.

Use cases

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 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 ServiceCallout to send that message to the remote API.
Add headers to requests and responses for debugging and troubleshooting.

Videos

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

Video	Description
Why Assign Message Policy?	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	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	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	Change API request or response by adding query parameters, headers, form parameters, or payloads using the AssignMessage policy.
Create custom variables using AssignMessage policy	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	Create new API request or response objects using the AssignMessage policy at API runtime.
Create a mock API using AssignMessage policy	Create a simple mock REST API by adding the AssignMessage policy in the response flow.
Set or modify the payload using AssignMessage policy	Convert REST request to SOAP request by setting SOAP Payload using the AssignMessage policy at API runtime.

The AssignMessage policy can create or change flow variables with the following child elements:

element

Defines an AssignMessage policy.

Default Value	See Default Policy tab, below
Required?	Required
Type	Complex object
Parent Element	N/A
Child Elements

The element uses the following syntax:

Syntax

The element uses the following syntax:

POLICY_NAME" >   FORMPARAM_NAME">FORMPARAM_VALUE . HEADER_NAME">HEADER_VALUE
 . QUERYPARAM_NAME">QUERYPARAM_VALUE .  DESTINATION_VARIABLE_NAME VARIABLE_NAME SOURCE_VARIABLE SOURCE_VARIABLE RESOURCE_URL_OR_TEMPLATE  or  VARIABLE_VALUE  VARIABLE_NAME"> ) --> FORMPARAM_NAME">FORMPARAM_VALUE .    HEADER_NAME"/> HEADER_NAME">[false|true]
 . [false|true] [false|true] ) --> QUERYPARAM_NAME">QUERYPARAM_VALUE . [false|true] [false|true] [false|true]  POLICY_DISPLAY_NAME [true|false] ) -->     FORMPARAM_NAME"/> FORMPARAM_NAME">[false|true] .    HEADER_NAME"/> HEADER_NAME">[false|true]
 . [false|true]    QUERYPARAM_NAME"/> QUERYPARAM_NAME">[false|true] .   FORMPARAM_NAME">FORMPARAM_VALUE . HEADER_NAME">HEADER_VALUE
 . PATH CONTENT_TYPE" variablePrefix no">PREFIX" variableSuffix no">SUFFIX">NEW_PAYLOAD QUERYPARAM_NAME">QUERYPARAM_VALUE . HTTP_STATUS_CODE or [GET|POST|PUT|PATCH|DELETE|] [1.0|1.1|]

Default Policy

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

 Assign Message-1                         GET -->  name   true

When you insert a new AssignMessage policy in the Apigee UI, the template contains stubs for all possible operations. Typically, you select which operations 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 element and 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:

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 element to label the policy in the management UI proxy editor with a different, natural-language name.

Fault rules are triggered ONLY in an error state (about continueOnError)
Handling faults within the current flow

The following table provides a high-level description of the child elements of :

Child Element	Required?	Description
Common operations
	Optional	Adds information to the message object that is specified by the element.

adds headers or parameters to the message that don't exist in the original message. Note that also provides this functionality.

To overwrite existing headers or parameters, use the element.

overwrites headers or parameters that already exist in the original message or adds new if they don't.

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 element:

  request

2: Remove payload

The following example deletes the payload from the response with the element:

 remove-1 true  response

3: Modify response

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

  false response

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

The HTTP header added to the response message by this policy is derived from a variable populated by the LookupCache policy. Therefore the response message modified by this 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.

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 Debug tool or other means.

4: Set dynamic content

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

To embed flow variables in an XML payload, wrap the designated variable in curly braces, like this: .

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

 response   false

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

For a complete list of flow variables, see Flow variables reference.

You can also use curly braces to insert variables.

5: Remove query param

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

      request

It's a best practice to strip the apikey query parameter from the request message when you use the VerifyAPIKey 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 AssignMessage policies:

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

    myAppSecret 42   config.environment test   config.protocol gopher

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

     secret myAppSecret 0   environment config.environment default   protocol config.protocol default  true

To try out this set of policies:

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

  put-em-in-the-payload   true

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:

 42 test gopher

7: Get ServiceCallout response headers

In the following example, let's say that a ServiceCallout 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.

   ">  true response

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

8: Store and remove form params, headers, query params

If you want to use to delete your headers, query parameters, or form parameters, but retain access to their values later in the policy flow, you can store their values using .

 AM-StoreAndRemove var_grant_type request.formparam.grant_type       application/x-www-form-urlencoded
 application/json
  false

Note: Form parameters, headers, and query parameters stripped using in the Assign Message policy cannot be accessed after completion of the policy flow unless their values are stored in variables as described in this example.

Each child element in this reference has additional examples. For even more examples, see AssignMessage example on GitHub.

Child element reference

This section describes the child elements of .

Adds information to the request or response, which is specified by the element.

The element adds new properties on the message that don't exist in the original message. Note that also provides this functionality. To change the values of existing properties, use the element.

Default Value	N/A
Required?	Optional
Type	Complex type
Parent Element
Child Elements

The element uses the following syntax:

Syntax

POLICY_NAME" >  FORMPARAM_NAME">FORMPARAM_VALUE . HEADER_NAME">HEADER_VALUE
 . QUERYPARAM_NAME">QUERYPARAM_VALUE .

Example 1

       request