message flow variable

Access to the message flow variable and its properties depends on the point within the API Proxy Flow in which it is accessed. It is available in all contexts, whereas some objects, such as request or response are not.

Use cases

The principal use case for the message flow variable is when your proxy enters the error flow: the request and response flow variables are out of scope.

For example, in the error flow, the response object is not available. You will not be able to set response headers on the response object with the JavaScript policy if you are in the error flow. Instead, you can use one of the following:

Both of these objects are available in the error flow, and can be used to set response headers from within a JavaScript policy or be accessed in other policies that can use flow variables.

You can use the AssignMessage policy to assign values, such as headers, to the response object. Assign Message automatically handles the switch in context from request/response flow to error flow.

Another use case for the message variable is to log response data in the PostClientFlow with the MessageLogging policy. If you use the message object, you can seamlessly log response information following both success and error conditions in the proxy.

Examples

In an error flow, you can set a response header from a JavaScript policy using either error or message. For example:

context.setVariable('error.header.FOO-1', 'error_header');

OR

context.setVariable('message.header.FOO-2', 'message_header');

The following expression, however, will not work:

context.setVariable('response.header.FOO-3', 'response_header');

In this case, the response variable is out of scope in the error flow. (Note that, in a trace, this is visually indicated by variables shown with an equals sign with a slash through it.)

To set response headers for both success and error flows in a single policy, you can use message inside a JavaScript policy. For example:

<faultrules>
  <faultrule name="invalid_key_rule">
    <step>
      <name>SetResponseHeaders</name>
    </step>
    <condition>(fault.name = "InvalidApiKey")</condition>
  </faultrule>
</faultrules>

In the policy, code like the following sets the error/response header in any flow context:

context.setVariable('message.header.FOO-1', 'the header value');

You can reuse this same policy on the normal ProxyResponse flow and it will succeed because message is available from all contexts.