Use Postman to Call Visier APIs

Install and configure Postman's desktop application to send API requests.

What is Postman?

Postman is an API tool for building and testing API requests. It’s free to use and allows you to make requests to an API from an easy to use interface. Postman allows you to organize API endpoints into collections, which are structured in a folder hierarchy, and store the collections within a workspace.

To make it easy for you to get started with our APIs, we’ve created workspaces with a pre-configured environments and collections. The collections include a variety of examples and endpoints that allow you to quickly dive into exploring the functionality of the APIs, see How to use Visier's Postman collections. If you want to manually create your own workspace, environment, and collections, see Set up your collection and environment manually.

You can access the following Postman workspaces:

• Visier Alpine Platform
• Visier Alpine Datasets

Prerequisites

Before you start you will need an API key. For more information, see API Authentication.

Install Postman

Download and install the Postman desktop application. For more information and troubleshooting tips, see Postman Learning Center.

Create a workspace

After you install Postman and create an account, Postman creates a personal workspace for you to organize your work. If you already have an account and want to create a new workspace, follow the steps below.

1. Open Postman.
2. In the header, click Workspaces > Create Workspace.
3. Type a name for your workspace.
4. Set the workspace visibility to determine who can access your workspace.
5. Click Create Workspace.

How to use Visier's Postman collections

Learn how to use our pre-configured environment and collections.

Fork collection and environment into your workspace

To send requests or make changes to a collection from a Visier workspace, you first need to fork the collection and environment into a personal or team workspace you belong to.

1. To access Visier’s workspaces, do one of the following.

   Postman application type	Do this
   Desktop	Open the Postman desktop application. In the search box, type Visier. In the results list, select the Visier workspace that you want to use.
   Web client	Click one of the following workspace links. Visier Alpine Platform Visier Alpine Datasets

2. In the sidebar, select the environment or collection that you want to fork.

3. In the Overview tab, select Fork in the upper right.

4. Type a label for your fork and select a workspace to save the fork to.

5. Click Fork Collection or Fork Environment.

6. Repeat steps 1 to 5 to fork the environment.

Configure forked environment

Visier's pre-configured environments include variables that allow you to store and reuse values in Postman.

By including a value as a variable, you can reference it throughout your requests without entering the value manually. This is helpful if you are using the same values in multiple places. The value stored in the variable is included wherever you’ve referenced the variable when your requests run.

After you’ve forked the environment, you can now update the current values before running your first request.

1. In the sidebar, click Environments.
2. Select the forked environment.
3. Update the current value for each variable. If empty, the current value uses the initial value. By specifying a current value, your local instance uses the current value in your requests.

The following table shows the variables used throughout our collections. Each API has it's own set of variables, refer to the environment that you are configuring.

Variable	Description
username	Your Visier username.
password	Your Visier password.
baseUrl	The base URL is made up of the vanity name and domain name. https://{vanity_name}.api.visier.io Replace {vanity_name} with your Visier tenant name.
asidToken	Your Visier security token. The security token will automatically insert once requested.
apiKey	Your API key.
vanityName	Your Visier tenant name.

Request a security token

After configuring your environment, you can request Visier's security token within the forked collection.

1. In the sidebar, click Collections.
2. Select the collection you want to use.
3. Click the Authentication folder.
4. Click the POST Security Token request.
5. In the environment selector in the upper-right corner of the workbench, select the environment you want to use.

6. Click Send.

   Result: Postman returns a security token. This request includes a script that instructs Postman to insert the security token into the environment.

   Note: The security token has a 60 minute expiration window. You will have to make this request again each time it expires.

Make a request from the collection

After successfully requesting a security token, you can use any of the pre-built requests within the collection. As an example, let’s send a GET request to retrieve all the metrics in our Visier solution using Metrics endpoint in the Data Model API collection.

1. In the sidebar, click Collections.
2. Select the Data Model API collection.
3. Click the GET Metrics request.

4. Click Send.

   If the request is successful, you should see a similar response:

   Copy

   Sample response

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   {
       "metrics": [
           {
               "id": "employeeCount",
               "displayName": "Headcount",
               "description": "The number of employees in the organization.",
               "dataStartDate": "1522627200000",
               "dataEndDate": "1604102400000",
               "analyticObject": "Employee",
               "parameters": []
           },
           {
               "id": "employeeTenureAverage",
               "displayName": "Tenure",
               "description": "The time in years that employees have worked for the organization.",
               "dataStartDate": "1522627200000",
               "dataEndDate": "1604102400000",
               "analyticObject": "Employee",
               "parameters": []
           }
       ]
   }

   Note: Each data model is unique to each Visier tenant, depending on purchased applications and any custom objects. The objects in the response are retrieved from the tenant specified by the tenant name in the request.

Set up your collection and environment manually

Rather than using Visier’s pre-configured environments and collections, you can instead set up your own environment and collection manually.

Set up an environment

After you create your workspace, you can set up an environment.

First, define the environment’s variables. Variables allow you to store and reuse values in Postman. By including a value as a variable, you can reference it throughout your requests without entering the value manually. This is helpful if you are using the same values in multiple places. The value stored in the variable is included wherever you’ve referenced the variable when your requests run.

1. In your workspace, on the right side of the workspace name, click New.

2. In the dialog, select Environment.

3. Type a name for your environment.
4. Add the following variables and type the initial and current values for each variable. If the current value is left empty, the current value uses the initial value.

Create a collection

Next, create a collection to group saved requests together. By creating a collection, you can keep your workspace organized and run requests in a specified sequence using the Collection Runner. For more information, see Using the Collection Runner.

1. In your workspace, on the right side of the workspace name, click New.
2. In the dialog, select Collection.
3. Type a name for your collection.

Request a security token

After you create your collection, you can add a request to the collection to retrieve Visier’s security token. This should be the first request in the collection as it enables you to use the Collection Runner.

1. In your collection, on the right side of the collection name, click the More actions button .

2. In the More actions list, select Add request.

3. Type a name for your request.

4. In the methods list, select POST.

5. In the URL field, type or paste the URL:

   {{baseUrl}}/v1/admin/visierSecureToken

   The following image shows the URL pasted into the URL field.

   

6. In the Body tab, do the following:

   1. Select x-www-form-urlencoded as the data type.

   2. Add the following key-value pairs.

      Double curly braces instructs Postman to insert the variable that you set up in the environment.

   Key	Value
   username	{{username}}
   password	{{password}}
   vanityName	{{vanityName}}

7. In the Tests tab, copy and paste the following script. The script instructs Postman to insert the security token into the environment.

   Copy

   1
   2
   3
   4
   5
   6
   7
   pm.response.to.have.status(200);
   pm.test("Successfully logged on", function () {
       console.info(pm.response.text())
       if (pm.response.code == 200) {
           pm.environment.set("asidToken", pm.response.text());
       }
   });

8. To use the variables from the environment that you set up, select it from the environment selector in the upper right corner of the workbench.

9. Click Send to request a security token.

   Note: The security token has a 60 minute expiration window. You will have to make this request again each time it expires.

Make your first request using Postman

To test that you have everything set up correctly, we'll add a request to the collection to retrieve all the metrics in your Visier solution using /v1/data/model/metrics endpoint.

1. In your collection, on the right side of the collection name, click the More actions button .

2. In the More actions list, select Add request.

3. Type a name for your request.

4. In the methods list, select GET.

5. In the URL field, type or paste the URL:

   {{baseUrl}}/v1/data/model/metrics

   The following image shows the URL pasted into the URL field.

   

6. In the Headers tab, add the following key-value pairs.

   Key	Value
   apiKey	{{apiKey}}
   Cookie	VisierASIDToken={{asidToken}}

7. Click Send.

   If the request is successful, you should see a similar response:

   Copy

   Sample response

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   {
       "metrics": [
           {
               "id": "employeeCount",
               "displayName": "Headcount",
               "description": "The number of employees in the organization.",
               "dataStartDate": "1522627200000",
               "dataEndDate": "1604102400000",
               "analyticObject": "Employee",
               "parameters": []
           },
           {
               "id": "employeeTenureAverage",
               "displayName": "Tenure",
               "description": "The time in years that employees have worked for the organization.",
               "dataStartDate": "1522627200000",
               "dataEndDate": "1604102400000",
               "analyticObject": "Employee",
               "parameters": []
           }
       ]
   }

   Note: Each data model is unique to each Visier tenant, depending on purchased applications and any custom objects. The objects in the response are retrieved from the tenant specified by the tenant name in the request.

Run your collection

After you test your workspace, environment, and collection set up, you can use the Collection Runner to run the collection's requests in a specified sequence. By including the security token request as the first request in your collection, the runner will run and retrieve the security token prior to running other requests. This is helpful when running requests as it avoids having an expired security token.

1. In your collection, on the right side of the collection name, click the More actions button .

2. In the More actions list, select Run collection.