FlowCallout policy

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.

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>

Syntax

<Parameters>
  <Parameter name="parameter-name" value='parameter-value' />
</Parameters>