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>