Flow (conf/flow.xml)

The flow represents the user definable behavior of the FIT engine. It is started after initialization and is responsible for obtaining and parsing content. The engine requires content to be present as a DOM in the internal location fit://request/content after the flow has finished, unless the flow is terminated early by an action (such as dump).

No flow is applied to requests handled by image scaling , image compression, webfont compression, and all requests marked to bypass the flow (URL Mark pass, or URL Rewriting roles media, external).

If no flow is configured, the following default flow is used:

<flow>
  <default-request />
  <parse />
</flow>

The flow comprises actions and control structures that are executed in document order.

Example:

<flow>
  <if test="client/bot">
    <redirect location="http://example.com" rewrite="false" />
  </if>
  <default-request />
  <regex match="/foo/" replace="bar" />
  <requests xslt="fit://site/actions/load_weather_and_news.xsl" />
  <parse />
  <xslt src="../actions/mobilize.xsl" />
  <dump />
</flow>

Actions

Every action which has an input (in attribute) or output (out attribute) works by default on fit://request/content. Besides, the content will be automatically converted into the format required for the action, e.g. into the plaintext for regex or into the DOM for xslt actions.

Control structures

Control structures like if and choose allow you to group and execute actions conditionally as described in the Filter chapter.

break elements allow to terminate the flow without errors. Request processing will continue with the built-in actions such as URL rewriting and image scaling.

A break usually should be executed conditionally, because otherwise none of the following statements will ever be executed.

<flow>
  <default-request />
  <break if="..." />
  <parse />
</flow>

Note that the if attribute is not a property of the break statement but a part of the Dynamic Configuration mechanism.

In contrast to the other configuration files like urlmap.xml or sources.xml, the filters in the flow are applied step-by-step, so that certain actions may have an impact on subsequent evaluations. For example, a set-attributes action that changes an attribute in the DOM will influence the result of a subsequent flow condition checking that very attribute.

Error handling

If a flow action cannot be processed, the request will terminate immediately. That happens under the following circumstances:

  • the action is unknown
  • static parameters have invalid values
  • dynamic parameters have invalid values at runtime
  • a non recoverable error occurs during execution

During normal operation, the engine request will be terminated with a generic “site error” page that will be shown to users. (The page contains an ID that references log file entries). The HTTP response status code will be 500.

You can define your own error page templates.

When debug logging is activated for the request (e.g. with URL Mark ;d=pageend-flow-debug), the error handling will be omitted. Instead, the engine will terminate without further processing. This makes it easier for the developer to analyze the situation. The HTTP response status code will be 500, too.