Configuring the ForgeRock Identity Cloud Postman Collection

All about Postman variables (Part 1 of 3)

This series of posts explains how to effectively configure and use the ForgeRock Postman collection for use with multiple clients/departments or projects.

We will start with a foundational topic that is skimmed over in the docs, but is critical to understanding how to use the collection: Postman variables.

Postman is a powerful API development and testing tool that allows you to send HTTP requests and manage their responses. Variables in Postman enable you to store and reuse values dynamically throughout your requests and tests. This flexibility is particularly useful when you need to work with dynamic data or perform repetitive tasks.

Here’s a step-by-step guide on how to use variables in Postman:

Variable Scoping:

Postman follows a specific scoping hierarchy when resolving variables, as shown in the diagram below:

The rule is that more specific (smaller box) overrides the general (larger box). So, local variables override environment variables, which in turn override global variables, etc.

Understanding scoping is crucial to ensure the desired variable value is used.

Source: https://learning.postman.com/docs/sending-requests/variables/

Global Variables:
These variables can be accessed across different requests within the Postman environment. To define a global variable, go to the “Manage Environments” option in the top-right corner of the Postman interface. Create or select an environment, click on the “Globals” tab, and define your variable key-value pairs.

Collection Variables:
These variables can be accessed across different requests within the Postman collection. To define a collection variable, click on the collection name, click on the “variables” tab, and define your variable key-value pairs.

Environment Variables:
These variables are specific to a particular environment and can be used within requests associated with that environment. Similarly, go to the “Manage Environments” option, create or select an environment, click on the “Variables” tab, and define your variable key-value pairs.

For completeness, these are the other two variables types, but we will not be using them with the ForgeRock Postman collection…

Local Variables:
Local variables are specific to a single request and can be defined within the request’s “Pre-request Script” or within tests. These are not used extensively in the ForgeRock Identity Cloud Postman collection.

Data Variables:
Values that are stored in external files, which are consumed during a collection execution. These values do persist past the request or collection. These are not used in the ForgeRock Identity Cloud Postman collection, but it is conceivable that they could be used for testing in certain scenarios.

Using Variables in Requests:

URL and Request Body:
To use a variable in the URL or request body, enclose the variable name in double curly braces ({{variable_name}}). For example, if you have a variable named "base_url," you can use it in the URL as {{base_url}}/endpoint.

Headers:
You can also use variables in request headers. To do this, select the “Headers” tab in the request, provide the header key-value pairs, and use variables in the value field as {{variable_name}}.

Assigning Values to Variables:

Pre-request Script:

To assign values to local variables specific to a single request, you can use the “Pre-request Script” feature. In the request, select the “Pre-request Script” tab, and write JavaScript code to set the variable values.

Note: The ForgeRock Postman collection does not use pre-request scripts on requests. The only place this is used in the collection, is on the collection level, to define a few utolity functions.

Response Data (tests script):

Once a response is received, you can extract values from the response and store them in variables for future use. For instance, if the response contains a JSON object with a field named “user_id,” you can extract it using the following code in the “Tests” tab:

pm.globals.set("authId", JSONResponse.authId);

Note: The ForgeRock Postman collection makes extensive use of this functionality via “Tests” scripts.

Using Variables in Tests:

Variables can be used in tests to perform validations or pass dynamic values. In the “Tests” tab, write JavaScript code using the pm object to access and manipulate variables.

Tests allow you to assert that the response contains a specific value:

pm.test("Status code is 200.", () => {
  pm.expect(pm.response.code).to.eql(200);
});

Dynamic Values can be set in “Tests” scripts so that subsequent requests can use the returned value:

// Did request return SSO Token?
if(JSONResponse.tokenId && JSONResponse.tokenId != "")
{
  // Set `demoSSOToken` variable
  pm.globals.set("demoSSOToken", JSONResponse.tokenId);
}

That’s a basic overview of using variables in Postman. Variables greatly enhance the flexibility and reusability of your requests and tests, allowing you to handle dynamic scenarios and streamline your API testing and development workflows.

Continue reading with part 2:
Configuration for working with multiple environments (Part 2 of 3)

Continue reading with part 3:
Preparing Your Tenant (Part 3 of 3)