Building workflows

When you start a collection run, all requests are run in the order you see them in the main app. So all requests are executed first, by order of the folder, and then any requests in the root of the collection.

However, you can override this behavior using a built-in function called postman.setNextRequest(). This function, as the name suggests, allows you to specify which request runs next.

Let's look at a sample collection to understand this function.

Getting started

Before you start, download and import collection.json for the example we'll discuss in this topic.

Basic workflow

If you run an example collection containing four requests directly, the collection runner runs all four requests in order.

setNextRequest in tests tab

collection runner view

Let's now add postman.setNextRequest() to Request 1's test script, as shown. postman.setNextRequest() is a function with one argument, which is the name or ID of the request you want to run next.

In the example, we're setting the next request to Request 4 in the test script for Request 1. So the execution jumps to Request 4 after Request 1 has completed. If you run the same collection now, you'll see that only two requests are run now.

setNextRequest with request name as parameter

collection runner view

Note that postman.setNextRequest() only works with the collection runner and Newman where the intent is to run a collection, as opposed to sending a single request.

Advanced workflow

Once you're comfortable using setNextRequest(), you can progress to more advanced actions.

Since you are no longer restricted by the order in which you define your requests, you can jump around your collection, establish conditional logic, or skip unnecessary requests.

This blog post explains how you can write a collection that will generate Spotify playlists for you based on your favorite musical artists.

Remember these two facts as you use this workflow:

  • postman.setNextRequest() is always executed at the end of the current request. This means that if you put this function before other code blocks anywhere in pre-request or test script, these blocks will still execute.
  • postman.setNextRequest() has a scope, which is the source of your collection run. If you run a collection, you can jump to any request in the collection (even requests inside folders, using the same syntax). However, if you run a folder, the scope of postman.setNextRequest() is limited to that folder. So you can jump to any request in this folder, but not ones that are outside of the folder. It includes requests inside other folders, and also root-level requests in the collection. To read more about running collections or folders.

For more information on collection runs, see: