Generate or modify messages using AssignMessage

The AssignMessage policy is used to generate or modify messages during an API proxy Flow. The messages that are generated or modified can be used, for example, by a subsequent ServiceCallout policy as a request to a remote service or API.

AssignMessage is so named because the policy requires a message to be 'assigned' as a variable. Therefore to use AssignMessage you select any variable and assign a message to it.

AssignMessage is often used to generate the request message sent by a ServiceCallout policy to a remote HTTP service.

In the following example, the request message generated by the AssignMessage policy is assigned to a variable called partner.request. The message generated is available to later policies or code executing in the flow, which can access the message through the variable.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AssignMessage enabled="true" continueOnError="false" async="false" name="partnerRequest">
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <AssignTo createNew="true" transport="http" type="request">partner.request</AssignTo>
</AssignMessage>

The following AssignMessage policy creates a new request message, populated with the user-agent HTTP header from the source message, along with one query parameters derived from the source. Since the message generated by this policy is a request, the HTTP verb is also set to GET.

<AssignMessage name="GenerateRequest">
  <AssignTo createNew="true" type="request">Request</AssignTo>
  <Copy>
	<Headers>
	  <Header name="user-agent">{request.header.user-agent}</QueryParam>
	</Headers>
  </Copy>
  <Set>
    <QueryParams>
      <QueryParam name="address">{request.queryparam.address}</QueryParam>
    </QueryParams>
    <Verb>GET</Verb>
  </Set>
</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. Thus, 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.

<AssignMessage enabled="true" continueOnError="false" async="false" name="api-token-cache-hit-header">
    <AssignTo createNew="false" transport="http" type="response">response</AssignTo>
    <Set>
        <Headers>
            <Header name="API-Token-Cache-Hit">{lookupcache.api-token-lookup-cache.cachehit}</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

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.

Policy schema

Each policy must conform to a policy schema. All policy constructs such as elements and attributes mentioned above are defined in a schema. To download the schema, click here.

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>