Control Blocks

info

Control Blocks are GA for Cloud customers! Release for On-Premise Agent customers is coming soon.

Control Blocks make it easy to control how an API behaves, with all the power you’d expect from custom code but in an easy to use drag and drop interface.

With Control Blocks, you can:

• Conditionally run different branches of logic
• Loop over items and run many steps for each item
• Run many steps in parallel
• Handle errors gracefully

To use Control Blocks, select the Control Blocks tab when adding any backend API block.

Learn more on how to use each of the different Control Blocks below.

Block	Description
Condition	Conditionally run steps
Loop	Use a loop to iteratively run a step
Break	Break out of a loop when a condition is met
Parallel	Run multiple steps at the same time
Wait	Waits for a Parallel Block to complete before executing the next step
Try Catch	Handle an error and run other blocks if an error is encountered
Throw Error	Throw a custom error message
Variables	Set variables to be used in other blocks
Return	Return data from an API

Condition

The Condition block allows you to run different sets of API blocks depending on whether or not a condition is true (like if, else if, and else statements in code). Add blocks under the if or else conditions to run when the condition is true or false, respectively. Optionally, you can add else if conditions and toggle off the else condition in the Condition block edit pane.

Condition output

Access the output of the Condition block by referencing its output property (e.g.Condition1.output). The output of the Condition block is the output of the last block that ran. For example, if the else condition is met, then the output of the Condition block will be the output of last block in the else section.

In this example, the value of Condition1.output is equal to the output of the Python step, Step3, because the condition 1 > 100 is not true.

Loop

The Loop block allows you to run sets of API blocks in a loop, much like loops in code. There are 3 types of Loop blocks:

• For Each Loop
• For Loop
• While Loop

For Each Loop

The For Each loop runs the child blocks for every item in the List of items input in the Loop edit pane.

Access the current item and current loop iteration index inside any of the child blocks using the item.value and index.value variables. Note, these variables can be renamed in the Loop edit pane.

For Loop

The For loop runs the child blocks N times, as defined by the Number of iterations input in the Loop edit pane. Access the current loop iteration index inside any of the child blocks using the index.value variable. Note, this variable can be renamed in the Loop edit pane.

While Loop

The While loop runs the child blocks while the condition field in the Loop edit pane is true. Access the current loop iteration index inside any of the child blocks using the index.value variable. Note, this variable can be renamed in the Loop edit pane. Check out this example guide that leverages the While loop to fetch paginated data from an API.

caution

Your loop will run forever if you don’t update the variables that the condition field references. If your condition never becomes false, you will hit Superblocks rate limits and your API will stop running. Read more about API rate limits here.

Loop output

Access the output of the Loop block by referencing its output property (e.g., Loop1.output). The Loop block's output is an array with an item for every iteration of the loop. Each item is equal to the output from the last child block.

In the following example, the output of this loop block is 5 items, each of which is the output of Step3 for the iteration of the loop. It ran 5 times because Step1.output was an array with 5 items.

Loop variables

Loop type	Default variables
For Each	index, item
For	index
While	index

info

Loop index variables start at 0.

Renaming Loop variables

Inside the Loop edit pane, click the variable name to open an input popover for renaming your variable. After renaming it, the variable will update across all blocks in the Loop where it is referenced.

Advanced - setting Loop variables

If you have an advanced use case that requires updating the item or index values in a language block, use item.set(YOUR_VALUE) and index.set(YOUR_VALUE). Just like code, setting the index value with index.set() will change the loop iteration to the index you’ve set.

Break

The Break block allows you to break out of a loop if a condition is true. It can only be used inside a Loop block. Set the If condition in the Break block edit pane to any code that will result in breaking out of the loop if true.

info

The Break block has no output.

Parallel

The Parallel block allows you to run sets of API blocks at the same time. This is a powerful block that unlocks the ability to parallelize work in your APIs.

There are 2 types of Parallel blocks:

• Static Parallel
• Dynamic Parallel

Static Parallel

A Static Parallel block is useful when you need to run a specific number of paths simultaneously, each with their own set of blocks. The number of paths for this type of parallel does not change dynamically. You can also rename paths for readability, similar to how you can rename blocks.

Static Parallel output

Access the output of the Static Parallel block by referencing its output property (e.g., Parallel1.output). The output of a Static Parallel block is an object with a key for each path name, whose value is the output of the last step in that path. For example:

Dynamic Parallel

A Dynamic Parallel block is a very powerful block type. It will run all the child blocks for every item in the List of items field, similar to a For Each Loop block. However, unlike the Loop block, the Dynamic Parallel block will run the child blocks at the same time for every item in the list, just like parallelized code.

Access the current path's item inside any of the child blocks using the item.value variable. Note, this variable can be renamed in the Parallel block edit pane.

Dynamic Parallel output

Access the output of the Dynamic Parallel block by referencing its output property (e.g., Parallel1.output). The output of a Dynamic Parallel block is an array with an item for every iteration path of the parallel, whose value is equal to the output from the last child block in each path. For example:

Dynamic Parallel variables

item is the default variable name.

Waiting configuration in Parallel blocks

Under Wait for, control whether the API should wait for all paths to complete (default) or if the API should continue without waiting.

Note, changing this to wait for none of the paths means the output of the Parallel block is not guaranteed when used in downstream blocks. In this case, use the Wait block to wait for the paths of a Parallel block to complete at a later point in the API.

Wait

The Wait block allows you to wait for an upstream Parallel block’s paths to complete.

Define the Parallel block to wait on in the Wait for parallel block field in the Wait block edit pane. When the Wait block runs, the API will wait until all paths from that Parallel block have finished, if they haven't already. The Parallel block's output is now guaranteed beyond this point, so all blocks after the Wait block can reference the Parallel block's output with confidence.

info

The Wait block has no output.

Try Catch

The Try Catch block allows you to handle errors in any of the child blocks and run other blocks as a result of encountering an error (like try...catch...finally in Javascript or try...except...finally in Python). For example, if an error is encountered trying to run some error prone code, perform an action like sending an email or alert to another system, and finally perform some clean up actions.

Add blocks under the try, catch, or if enabled, finally sections. If an error is encountered running the blocks in the try section, access the error value using the error.value variable. Note, this variable can be renamed in the Try Catch block edit pane.

Try Catch output

Access the output of the Try Catch block by referencing its output property (e.g, TryCatch1.output). The output of the Try Catch block is the output of the last block that ran. For example, If the try section runs without hitting an error, the Try Catch output is equal to the output of the last block in the try section. If it does encounter an error in the try section, then the output is equal to the output of the last block in the catch section. If the finally section enabled, then the output is equal to the output of the last block in the finally section, regardless of whether an error was encountered or not.

Try Catch variables

error is the default variable name.

Throw Error

The Throw Error block allows you to throw an error in an API with a specific error message. Define the error message inside the Error to throw field. This is the text that will be accessible from the error variable. Note, you can use a Try Catch block to catch errors thrown by the Throw Error block.

info

The Throw Error block has no output.

Variables

The Variables block allows you to create variables whose values can be updated at any point in an API. The Variables block is useful for updating a value over time in a Loop or Condition block, or for referencing a frequently used value across an API.

Access the variable value using .value property on the variable name (e.g., myVar.value).

Variable scoping

Variables follow lexical scoping like variables in code. As such, a variable is available to other API blocks at the same nesting level (or below), relative to where the Variables block is defined.

Updating / setting variable values

Variables are not typed so they can be updated to any value. In the example below, a variable called nextPage is initialized to true at the start of a backend API that is used to iterate through a paginated REST API. When a condition is met inside a While Loop further down in the API, the variable is updated to false. This can be done with either another Variables block or by setting the variable in code.

Update Variable(s) with a Variables Block

Define a new Variables block in the same scope as the original Variables block, using the same variable name whose value you want to update.

Update Variable(s) with code

Use the .set() function call to update a variable’s value in a code block (e.g., myVar.set(“my new value”))

info

You cannot initialize a variable in code. Setting the initial value requires a Variables block.

Return

The Return block allows you to return from an API with data you specify. Note, you can "early return" just like in code (i.e., return before the end of the API so the remaining blocks do not run). Specify what to return in the Data to return field in the Return block edit pane.

Return output

The Return block has no output, as the API execution is terminated. The response of the API will be the data specified in the Data to return field and can be referenced via API_NAME.response.