Was this helpful?

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

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

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

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

To use AssignMessage, you must select a variable name and specify the message content to assign to it. If you use the one of the built-in names - request or response - the message will be assigned to the ambient request or response, respectively. If you use any other name, it will refer to a custom variable to hold the message.

Examples

For example, the policy below would modify the request message, to remove a query parameter. This might be used when you want to not pass the query parameter on to the target service.

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

To work with message content, AssignMessage defines a set of elements that enable you to populate or modify HTTP headers, query parameters, and XML or JSON payload content.

The policy below creates a new HTTP request message, and assigns that message to the variable called partner.request.

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

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

The following AssignMessage policy creates a new request message, called request1, and populates it with the user-agent HTTP header from the source message, along with one query parameter derived from the source message request. Since the message generated by this policy is a request, the HTTP verb can be set, in this example to GET.

In the configuration below, the IgnoreUnresolvedVariables element is set to false. When set to true, the API proxy Flow continues processing when a variable does not resolve to a value.

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

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

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

You can also use AssignMessage to embed dynamic content in the payload of XML or JSON messages. The standard practice for embedding variables in XML is to wrap the designated variable in curly braces: {prefix.name}. This embeds the HTTP user-agent header in an XML element called User-agent:

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

With JSON, however, curly braces cannot be used to identify variables. Instead, you must declare the delimiter characters:

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

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

Configuring an AssignMessage policy

Configure the AssignMessage policy using the following elements.

The name attribute for this policy is restricted to these characters: A-Z0-9._\-$ %. However, the Management UI enforces additional restrictions, such as automatically removing characters that are not alphanumeric.

Field Name Description
AssignTo (Optional)
Specifies the variable to which the message will be assigned.
  • If the AssignTo element is missing, it is treated as request or response, depending on the Flow to which the policy is attached. If attached to a request Flow, for example, the default type is request.
  createNew
If createNew is set to true, then a new variable of the type specified in type is created.
If createNew is set to false, then AssignTo responds in one of two ways:
  • If AssignTo resolves to a message, then it continues to the next flow.
  • If AssignTo cannot be resolved, or resolves to a non-message type, then the policy throws an error.
If createNew is not specified, AssignTo responds in one of two ways:
  • If AssignTo resolves to a message, then processing advances to the next step.
  • If AssignTo cannot be resolved, or resolves to a non-message type, a new variable of type specified in type is created.
type (Optional)
Specifies the type of the variable.
Valid values: request/response
Default value: request
IgnoreUnresolvedVariables (Optional)
If IgnoreUnresolvedVariables is set to false and any variable cannot be resolved, then the policy throws a fault. 
If it is set to true and any variable is unresolvable, the variable is treated as empty string (Null).
Valid values: true/false
Default value: false
Copy (Optional) source
Copies the specified information from the <source> to the variable specified in the <AssignTo> element.
  • If the source is not specified, it is treated as a simple message.
  • If the source variable can not be resolved, or resolves to a non-message type, <Copy> fails to respond.
Headers Copies HTTP headers. To copy all headers, specify <Copy><Headers/></Copy>
QueryParams Copies query parameters. Note that the QueryParams is copied only when both the source and AssignTo type are request. To copy all query parameters, specify <Copy><QueryParams/></Copy>.
FormParams Copies the form parameters. Note that the FormParams is copied only when the contentType is source and AssignTo is application/x-www-form-urlencoded. To copy all form parameters, specify <Copy><FormParams/></Copy>.
Payload Valid values: true/false. If true, the Content-Type header is copied.
Version Valid values: true/false. If true, the HTTP version is copied.
Verb Valid values: true/false. If true, it is assigned only when both the source and AssignTo type are request.
Path
StatusCode Valid values: true/false. If true, it is assigned only when both the source and AssignTo type are response.
ReasonPhrase
Remove (Optional) Headers Removes HTTP headers from the variable specified in the <AssignTo> element. To remove all the headers, specify <Remove><Headers/></Remove>
QueryParams Removes the query parameters. Note that the QueryParams are removed only when the AssignTo type is request. To remove all query paremeters, specify <Remove><QueryParams/></Remove>.
FormParams Removes the form parameters. Note that FormParams are removed only when the contentType of AssignTo is application/x-www-form-urlencoded. To remove all form parameters, specify <Remove><FormParams/></Remove>.
Payload Valid values: true/false. If true, the payload is cleared.
Add (Optional) Headers Adds the headers in the variable specified in the <AssignTo> element. Note that the empty header <Add><Headers/></Add> does not add any header. The same holds true for QueryParams and FormParams.
QueryParams Adds the query parameters.
FormParams Adds the form parameters and the contentType of message is changed to application/x-www-form-urlencoded.
Set (Optional) Headers Sets/overwrites the HTTP headers in the variable specified in the <AssignTo> element. Note that the empty header <Set><Headers/></Set> does not set any header. The same holds true for QueryParams and FormParams.
QueryParams Sets/overwrites the query parameters.
FormParams Sets/overwrites the form parameters and the contentType of message changes to application/x-www-form-urlencoded.
Payload You are allowed to set mixed payload contents. For example, <root><e1>sunday</e1><e2>funday</e2><e3>{var1}</e3></root>.
  contentType If contentType is specified, its value is assigned to the contentType header.
Version Sets the version. Note that the content of <Version> is treated as message template. The same holds true for Verb, Path, StatusCode, and ReasonPhrase.
Verb Sets the HTTP verb and path only when AssignTo type is request.
Path
StatusCode Sets the status code and reason phrase only when AssignTo type is response.
ReasonPhrase
AssignVariable (Optional) Name Specifies the name of the variable.
Ref Reference that assigns value to the variable.
Value If <Ref> is not specified or is unresolvable, this value is assigned to the variable.

Example - AssignMessage policy

<AssignMessage name="create1">
<AssignTo type="[request]/response" createNew="[true]/false">sc.request</AssignTo>
<IgnoreUnresolvedVariables>true/[false]</IgnoreUnresolvedVariables>

// allow any order
<Copy source="request"> // if no children do copy all
    <Headers>
        <Header name="h1"/>
        <Header name="h2"/>
    </Headers>
    <QueryParams>
        <QueryParam name="q1"/>
        <QueryParam name="q2"/>
    </QueryParams>
    <FormParams>
        <FormParam name="f1"/>
        <FormParam name="f2"/>
    </FormParams>
    <Payload>true/[false]</Payload>
    <Verb>true/[false]</Verb>
    <Path>true/[false]</Path>
</Copy>

<Remove> // if no children do remove all
    <Headers>
        <Header name="h1"/>
        <Header name="h2"/>
    </Headers>
    <QueryParams>
        <QueryParam name="q1"/>
        <QueryParam name="q2"/>
    </QueryParams>
    <FormParams>
        <FormParam name="f1"/>
        <FormParam name="f2"/>
    </FormParams>
    <Payload>true</Payload>
</Remove>

<Add>
    <Headers>
        <Header name="h1">my{variable.v1}</Header>
    </Headers>
    <QueryParams>
        <QueryParam name="q1">my{variable.v1}</QueryParam>
    </QueryParams>
    <FormParams>
        <FormParam name="f1">my{variable.v1}</FormParam>
    </FormParams>
</Add>

<Set>
    <Headers>
        <Header name="h1">my{variable.v1}</Header>
    </Headers>
    <QueryParams>
        <QueryParam name="q1">my{variable.v1}</QueryParam>
    </QueryParams>
    <FormParams>
        <FormParam name="f1">my{variable.v1}</FormParam>
    </FormParams>

    <Payload contentType="text/xml">
        <root>this is my payload {variable.v1}</root>
    </Payload>

    <Verb>${variable.v1}</Verb>
    <Path>abc/def/{varaiable.v1}/d</Path>
</Set>

<AssignVariable>
    <Name>response.header.xyz</Name>
    <Ref>request.queryparam.abc</Ref>
    <Value>hello!</Value>
</AssignVariable>
</AssignMessage>

Policy-specific error codes

The default format for error codes returned by Policies is:

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

The AssignMessage Policy type defines the following error codes:

Error Code Message
UnresolvedVariable AssignMessage[{0}]: unable to resolve variable {1}
VariableOfNonMsgType AssignMessage[{0}]: value of variable {1} is not of type Message
SetVariableFailed AssignMessage[{0}]: failed to assign message to {1}
InvalidIndex AssignMessage[{0}]: index must be greater than zero in {1}
InvalidVariableName AssignMessage schema validation failed: invalid variable name - {0} - in assign variable
InvalidPayload Invalid payload {0}

Policy schema

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

Help or comments?

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