Postman Quickstart


Wiki User Guides LMS Developer Resources
Getting Started Guide Bentley Developer Network Authentication Python Authentication Examples Client ID & Secret Region & Instance ID .net SDK Guide
Postman Examples Postman Quick Start API Endpoints - Swagger Case Studies Other Topics
PowerBI Documentation

 

This article will go through how you can Postman to make your first API query for OpenGround.

Table of Contents

1. SETTING UP POSTMAN

Installing Postman

You will need to download and install Postman’s desktop application. The web-based version will have limitations in functionality.

Postman can be downloaded through this link https://www.postman.com/

Importing API Documentation

To start using OpenGround’s API with Postman, you will need to import the Postman “OpenGround API Documentation” endpoint examples and set up the Environment file to the correct region following the below images.

API documentation can be found in this Postman Collections page.

Once Imported it should look something like the below


Setting up your Environment

It is important to setup your Postman environment to allow for reuse of variables within your API requests.

Clicking on the “Environment” drop down will present a list of stored variables.

 

The “{{Region}}” variable must be replaced with the appropriate region of where your cloud instance has been setup.

Note: The region you’re operating in may not be the same region as where your cloud has been setup. If you are unsure, please contact your OpenGround Administrator within your organisation.

Cloud Regions

The list of cloud regions currently available to be used are listed below


API Authorisation – Access Token

OpenGround uses an OAuth 2.0 security protocol to authenticate users accessing the API. An access token is required to Authenticate your access to the API. All the relevant Authorisation data should be prepopulated when you import the provided “OpenGround End point Documentation” and Environment file”.

Following the steps in the image below, click “Get New Access Token” and follow the login process in the browser. If successful, this means your account is now authorised to use the API.

The authorisation settings should like the below. Full Authorization parameters is summarised below.

Note: Access tokens last for 1 hour and will require you to get a new access token.

 

Please note that ability to access certain endpoints will depend on your access levels assigned within OpenGround Professional, dditional information around API authentication/access can be found under Authentication Article.

Authorisation Parameters

HEADING

Parameters

Auth Type

 OAuth 2.0 

Add auth data to

 Request Headers 

Header Prefix

 Bearer 

Token Name

 (Optional) 

Grant Type

 Authorisation Code (With PKCE)

Callback URL

 https://callback.openground.cloud/callback.html 

Authorize using browser

 (Unchecked)

Auth URL

 https://imsoidc.bentley.com/connect/authorize 

Access Token URL

 https://imsoidc.bentley.com/connect/token 

Client ID

 openground-cloud-connector 

Client Secret

 (Leave Blank) Only required for Machine Login

Code Challenge Method

 SHA-256 

Code Verifier

 (Leave Blank)

Scope

 openground

State

 (Leave Blank)

Client Authentication

 Send client credentials in body

Note

You may notice the Imported API examples use a “{{_}}” notation, e.g {{ClientID}}. This refers to “ClientID” being used as a variable within the Environment. 

In this example {{ClientID}} references “openground-cloud-connector”, meaning You can view the variable value by hovering you mouse over the variable. You also can view/edit the full list of variables being used in the Environment options.

 

 

2. GETTING YOUR CLOUD INSTANCE ID

Before you can make a query to your OpenGround database, you will first need to define which cloud you want to direct you API query to by providing a Cloud Instance ID which is a unique ID defined per cloud instance. There are a few ways to obtain your Cloud Instance ID described below.

Via Postman

Once you have successfully imported the “API endpoints documentation”, “Postman Environment” and have gone through the Authorisation process from the previous section, you will be able to send an API request to get a response with the Cloud Parameters for the Clouds instances you have access to.

Select the query “Get Clouds” and click “Send”. No headers are required to be entered for this call


You should receive a response in JSON format, highlighting key parameters for your cloud

API EndPoint used

Method

End Point

GET

https://api.australiaeast.openground.bentley.com/api/v1.0/identity/clouds/{{Region}}


Via PowerBI

Using the “Cloud Parameters ” PowerBI report. This report displays all the parameters you need to use the API with your OpenGround instance.

Note you will need to have setup your PowerBI to connect up to your OpenGround Instance. More information around setup can be found under OpenGround PowerBI guidance.

Via Contact support

If you are still unable to get your CloudID following the above steps, please contact your organisations OpenGround manager to make a request through contact support. We can then provide you with the Cloud Instance ID.

 

3. POSTMAN EXAMPLES

Example 1 – Get Project List

In this example you will learn how to use the API to return a list of Projects from your cloud Instance.

Prerequisites 

Prerequisites can be obtained by following previous sections.

To return a list of projects on your cloud instance using the API

  1. Select “Get Projects” query under the “Get Projects” folder documentation
  2. Check you are using the correct Environment, “Australia East” has been used in this example.
  3. Open the Environments variables list and paste your Cloud Instance ID into the {{CloudId}} variable. You’ll also notice that this variable is being passed into the header key “Instanceid” and is sent along with the query.
  4. Send request and view response

 

 

 

  

Example 2 – Explore Configuration Data Model

In this example, you’ll learn how to use the API to return information about your configuration packs data model. This will include things like returning data groups, headers within that group and other useful information.

Prerequisites 

Prerequisites can be obtained by following previous sections.

Before you can return information about the data model you first need to decide which configuration pack you want to query. The “Get Config Packs” query will return a list of configuration packs on your selected cloud.

Get Config Packs Query

API Response

Your API response should look something like the below. Take note of the configuration pack ID of the configuration pack your interested in as you’ll need this to further query your data model.

 

Return Data Model Groups

Notice in this query, we are using the “{{ConfigurationPackId}}” within this query which was obtained from the previous GET response. This directs your query to the configuration pack of interest.

API Response

 

Other Explore Model Queries

Within this example you’ll also see additional queries that you can use to return other parts of the data model.

 

Example 3 – Create Project

In this example, you’ll learn how to use the API to create a project on your OpenGround Cloud instance.

Prerequisites 

The minimum amount of information required to create a project is defined below. Some of this will be defined by the user during the creation process, others fields such as picklists will require the user to use an API to return picklist information so we can fill these fields out. It may be helpful to first understand project creation workflow in OpenGround Professional before attempting this directly through the API. Mandatory fields required are listed below

 

The GET requests in this workflow has been defined sequentially to return the mandatory information.

 

 

Running these requests will return information to be automatically stored within your environment variables.

 

You can now use the “POST” request, to pass information back to OpenGround to create our Project. The default example will assume values within the body of the request.

Header: “ProjectID”
Value: “PostmanProject – {{$isoTimestamp}}”

Header: “ProjectTitle”
Value: “Created in Postman”

The data within the value fields within the Body of the request can be changed based on project requirements. Ie Created “Project title” can be altered, by replacing “Created in Postman” with the title of your choice.

Running the “GET” Projects Query will return all projects on your cloud including the project created with Postman. You will also be able to see this in OpenGround Professional.