Building workflows

Download the collection used in this example:

• collection.json

Basic usage

When you start a collection run, all requests are run in the order you see them in the main app. This means that all requests inside are executed first, by order of the folder they are in, and then any requests that are in the root of the collection. However, you can override this behavior using a built-in function called setNextRequest().

setNextRequest(), as the name suggests, will allow you to specify which request will be run next. The easiest way to understand this is to look at a sample collection.

Let’s assume that we have a collection with four requests. If you run this collection directly, the collection runner will run all four requests in order.

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. This means the execution will jump to Request 4 after Request 1 has completed. If we run the same collection now, you’ll see that only two requests are run now.

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

Advanced usage

Now that we have a good understanding of how setNextRequest() works, we can do some pretty advanced stuff with it. 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.

There are some gotchas to keep in mind:

• setNextRequest() is always executed at the end of the current script. This means that if you put setNextRequest() before other code blocks, these blocks will still be executed.
• setNextRequest() has a scope, which is the source of your collection run. This means that 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 setNextRequest() is limited to that folder. This means that you can jump to any request within this folder, but not ones that are outside of the folder. This includes requests inside other folders, and also root-level requests in the collection. To read more about running collections or folders.