FlowCallout policy

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation.
info

Use the FlowCallout policy to call out to a shared flow from either an API proxy or another shared flow.

In a shared flow, you create a sequence of steps that you can reuse at run time from multiple places. These steps are implemented as policies, as within an API proxy. The FlowCallout policy gives you a way to invoke the shared flow from API proxies and other shared flows. It works like a function call in a traditional programming language.

  • For example, imagine that you've built a shared flow with security features such as API key verification, OAuth token validation, and regular expression protection. This shared flow represents your convention for a way to check inbound requests. Using the FlowCallout policies, you can invoke that shared flow from multiple API proxies.
  • You can call one shared flow from another by implementing a FlowCallout policy from within a shared flow.

Samples

Verify API key in shared flow

In this example a shared flow is used to perform common security-related tasks. Here the shared flow validates an API key. API proxies and other shared flows can use the FlowCallout policy to make calls into this shared flow.

The following shared flow definition includes a Verify-API-Key policy that executes when the shared flow is called from a FlowCallout policy in an API proxy.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SharedFlow name="default">
    <Step>
        <Name>Verify-API-Key</Name>
    </Step>
</SharedFlow>

The VerifyAPIKey policy within the preceding shared flow retrieves the key value and verifies it.

<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key">
    <DisplayName>Verify API Key</DisplayName>
    <APIKey ref="request.queryparam.apikey"/>
</VerifyAPIKey>

The following FlowCallout policy, used in an API proxy, calls the preceding shared flow to verify the API key. The verify-apikey-shared shared flow bundle (not shown here) configures the shared flow in the way an APIProxy bundle configures a proxy.

<FlowCallout async="false" continueOnError="false" enabled="true" name="Auth-Flow-Callout">
    <DisplayName>Auth Flow Callout</DisplayName>
    <SharedFlowBundle>verify-apikey-shared</SharedFlowBundle>
</FlowCallout>

Pass parameters to a shared flow

This example illustrates how to pass parameters from a FlowCallout policy to a shared flow. Here, a FlowCallout policy calls to a shared flow designed to perform common string handling functions. The shared flow includes JavaScript that concatenates its input, lower-cases its input, or both. The FlowCallout policy defines parameters that specify the string input, output, and what to do with the input.

  1. The String-Handler FlowCallout policy calls the shared flow, passing parameters specifying the variable to store the shared flow's output, what shared flow operation to use, and what input to use (here, a string literal, but it could also be a flow variable). The Parameter elements specify the names and values of variables to create runtime. The shared flow can retrieve these variables for use in its own code.

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <FlowCallout async="false" continueOnError="false" enabled="true" name="String-Handler">
      <DisplayName>String Handler</DisplayName>
      <Parameters>
        <Parameter name="input">Gladys Kravitz</Parameter>
        <Parameter name="operations">concatenate tolowercase</Parameter>
        <Parameter name="outputVariable">string.handler.output</Parameter>
      </Parameters>
      <SharedFlowBundle>StringHandler</SharedFlowBundle>
    </FlowCallout>
    
  2. The following default shared flow includes a SharedStringFunctions JavaScript policy that executes when the shared flow is called from a FlowCallout policy.

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <SharedFlow name="default">
      <Step>
        <Name>SharedStringFunctions</Name>
      </Step>
    </SharedFlow>
  3. In the shared flow, the following SharedStringFunctions JavaScript policy specifies the SharedStringFunctions.js JavaScript file with the code to execute.

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <Javascript async="false" continueOnError="false" enabled="true" timeLimit="200" name="SharedStringFunctions">
      <DisplayName>SharedStringFunctions</DisplayName> <Properties/>
      <ResourceURL>jsc://SharedStringFunctions.js</ResourceURL>
    </Javascript>
  4. The following JavaScript, SharedStringFunctions.js, executes from the SharedStringFunctions JavaScript policy. This script retrieves values from variables created from FlowCallout policy Parameter elements.

    // Input value from the calling API proxy.
    var handledString = context.getVariable("input");
    // Variable to use for output from this script.
    var outputVariable = context.getVariable("outputVariable");
    // A space-separated list of things to do to the input string.
    // Convert to lower case to handle unintentional capitals in configuration.
    var operation = context.getVariable("operations").toLowerCase();
    
    // If "lowercase" was given as an operation, convert the input to lowercase.
    if (operation.includes("tolowercase")) {
        handledString = handledString.toLowerCase();
    }
    
    // If "concatenate" was given as an operation, concatenate the input.
    if (operation.includes("concatenate")) {
        handledString = handledString.replace(/\s+/g, '');
    }
    // Assign the resulting string to the output variable specified by
    // the calling API proxy.
    context.setVariable(outputVariable, handledString);
  5. Execution flows back from the JavaScript policy, to the shared flow, then to the FlowCallout policy in the originating API proxy.

Element reference

Following are elements and attributes you can configure on this policy:

<FlowCallout async="false" continueOnError="false" enabled="true" name="Flow-Callout-1">
    <DisplayName>Custom label used in UI</DisplayName>
    <SharedFlowBundle>thereferencedsharedflowbundle</SharedFlowBundle>
</FlowCallout>

<FlowCallout> attributes

<FlowCallout async="false" continueOnError="false" enabled="true" name="Flow-Callout-1">

The following table describes attributes that are common to all policy parent elements:

Attribute Description Default Presence
name

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

N/A Required
continueOnError

Set to false to return an error when a policy fails. This is expected behavior for most policies.

Set to true to have flow execution continue even after a policy fails.

false Optional
enabled

Set to true to enforce the policy.

Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.

true Optional
async

This attribute is deprecated.

false Deprecated

<DisplayName> element

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>
Default

N/A

If you omit this element, the value of the policy's name attribute is used.

Presence Optional
Type String

<SharedFlowBundle> element

Specifies the name of the shared flow to call. This element's value should be the same as the value of the target SharedFlowBundle element's name attribute.

<SharedFlowBundle/>

In the simplest example, you give the name of the shared flow being called as a value for this element. That is, this element's value must be the same as the shared flow's name attribute value.

<SharedFlowBundle>Shared-Flow-Name</SharedFlowBundle>
 
Default N/A
Presence

Required.

Type N/A

Attributes

None.

<Parameter> element

Specifies a parameter and value (or value source) to pass as a variable into the shared flow called by this policy.

By using a parameter, you can specify a value (or a variable containing a value) that should be passed to the shared flow called by the policy. This is conceptually similar to specifying a parameter in a function call. As with a function parameter, a FlowCallout parameter's value can vary based on the context of the shared flow call.

FlowCallout parameters are visible only during the shared flow's execution.

Syntax

You can use this element with any one of the following syntax forms. Note that where you use a literal value, the format of the value you specify will depend on the code that consumes it.

<!- A literal value in an attribute. --/>
<Parameter name="parameter-name" value='parameter-value' />
<!- A reference to a variable in an attribute. --/>
<Parameter name="parameter-name" ref='source-variable-name' />
<!- A literal value in the element content. --/>
<Parameter name="parameter-name">parameter-value</Parameter>
<!- An reference to an attribute in the element content. --/>
<Parameter name="parameter-name">{source-variable-name}</Parameter>

Example

This String-Handler FlowCallout policy passing parameters that specify where to store the shared flow's output and what input to use. The Parameter elements specify the names and values of variables to create runtime. The shared flow can retrieve these variables for use in its own code.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<FlowCallout async="false" continueOnError="false" enabled="true" name="String-Handler">
  <DisplayName>String Handler</DisplayName>
  <Parameters>
    <Parameter name="input">Gladys Kravitz</Parameter>
    <Parameter name="outputVariable">string.handler.output</Parameter>
  </Parameters>
  <SharedFlowBundle>StringHandler</SharedFlowBundle>
</FlowCallout>
Default N/A
Presence

Required.

Type N/A

Attributes

Attribute Description Default Presence Type
name The name of the runtime variable to create with this parameter. None. Required. String
ref

The variable the contains the value to use at runtime. Omit this attribute if you're specifying a literal value to use.

None. Optional. String
value The value to use in the runtime variable created with this parameter. Omit this attribute if you're specifying the name of a variable that should be the value source. None. Optional. String

<Parameters> element

Specifies the set of <Parameter> elements to pass as variables into the shared flow called by this policy.

Syntax

<Parameters>
  <Parameter name="parameter-name" value='parameter-value' />
</Parameters>
Default N/A
Presence

Optional.

Type N/A

Attributes

None.

Schemas

Flow variables

Flow variables enable dynamic behavior of policies and flows at runtime, based on HTTP headers, message content, or flow context. For more information about Flow variables, see Variables reference.

Variable Description

apigee.edge.sharedflow.name

Scope: During the shared flow execution
Type: String
Permission: Read

The value of the shared flow's name attribute.

apigee.edge.flowhook.name

Scope: During execution of the shared flow attached to the flow hook.
Type: String
Permission: Read

The name of the flow hook.

Error reference

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause Fix
flow.SharedFlowNotFound 500 Either the shared flow does not exist, or the shared flow exists but is not deployed.

Deployment errors

N/A

Related topics