Skip to main content

v10

help center
Submit a request
Submit a request
  1. Total Compensation Management
  2. Technical admin
  3. API

A beginner's guide to using beqom APIs

Nolwenn Marjou
  • Last updated:

A beginner's guide to using beqom APIs

An API (Application Programming Interface) is an interface that enables users to interact directly with objects in an application, without the upper programming layer that is the graphical user interface (GUI). They can be used either to perform certain direct actions in a faster manner than through the interface (create a profile, table, etc.) or to perform a number of configurations.

In the beqom Web Application, they provide extended functionality compared to the capacities offered by the application interface, mainly feature configuration capabilities.

While APIs offer a wide range of possibilities, the lack of GUI make their use difficult to grasp for beginner users. The present document presents beginners with a simple, step-by-step guide on how to use APIs of the beqom application through a third-party tool.

This is an note/information message.

This article details the methodology and tools for API use recommended by beqom for interacting with the beqom application. There are however other possible tools to use APIs.

This is an note/information message.

Please note that this entire procedure is performed on MacOS. There might be differences in the Postman interface between MacOS and Windows.

The following table outlines the installation, configuration and application steps to start using APIs to interact with the beqom application.

Step # Description Reference
1. Download and install Postman API Client. Downloading and Installing Postman API Client
2. Create and configure your beqom environment in Postman. Creating the Environment in Postman
3. Create/import the collection of calls required to log into the beqom tenant from Postman. Creating the Login Collection
4. Run the login collection in order to connect to the beqom tenant. Running the Login Collection
5. Start executing methods. Practical Application

Downloading and Installing Postman API Client

Windows Platforms

To install Postman API Client on a Windows platform, proceed as follows:

  1. Open your preferred Web browser, and then go to postman.com/downloads.
  2. Click the Download the App button.
  3. Select the version that you want to use (32bits or 64bits). Normally, the version of the Windows OS should be automatically detected. The installation package is downloaded on your computer.
  4. Click the setup.exe file. The installation starts. Once the installation is finished, the Postman application is launched.
  5. In the screen that is displayed, create a Postman account or connect with Google.

MacOS Platforms

To install Postman API Client on a MacOS platform, proceed as follows:

  1. Open your preferred Web browser, and then go to postman.com/downloads.
  2. Click the Download the App button. The version of your Mac operating system should automatically be detected. The installation package is downloaded on your computer.
  3. Go to the "Downloads" folder of your computer.
  4. Double-click the "postman-osx" zip in order to extract its contents.
  5. Double-click the Postman Application and then confirm when the system asks you whether you want to add it to the Applications. Alternatively, drag and drop the application file to the Applications folder.
  6. Open the application. When the security window opens, confirm that you want to open Postman.
  7. In the screen that is displayed, create a Postman account or connect with Google.

Creating the Environment in Postman

Once you have installed the Postman application, you need to authenticate to beqom in order to establish communication between beqom and Postman. In order to properly authenticate to beqom, you need to add an environment to Postman.

To add an environment, proceed as follows:

  1. Click the setup icon located in the upper-right corner of the Postman application window, as illustrated in the following figure:

  1. In the "Manage Environments" window, you can either:
    • Click the Add button, and then create the environment variables manually
    • Click Import, to import a json file containing the environment variables required to communicate with beqom

 

Whichever option you decide to use, the variables to use are the following:

Copy
{
"key": "passportUrl",
"value": "<place_URL_here>",
"enabled": true
},
{
"key": "passportLogin",
"value": "<place_USER_NAME_here>",
"enabled": true
},
{
"key": "passportPassword",
"value": "<place_PASSWORD_here>",
"enabled": true
},
{
"key": "classicEndpointID",
"value": "<place_ID_here>",
"enabled": true
},
{
"key": "clientUID",
"value": "<place_clientUID_here>",
"enabled": true
}
{
"key": "GatewayUrl",
"value": "<place_URL_here>",
"enabled": true
},
{
"key": "AnalyticsUrl",
"value": "<place_URL_here>",
"enabled": true
},
{
"key": "CompPlannerUrl",
"value": "<place_URL_here>",
"enabled": true
},
{
"key": "DataUrl",
"value": "<place_URL_here>",
"enabled": true
},
{
"key": "FileUrl",
"value": "<place_URL_here>",
"enabled": true
},
{
"key": "ObjectUrl",
"value": "<place_URL_here>",
"enabled": true
}

The required information, in red in the code above, is specific to your system. For more information, contact your system administrator. You can also refer to Authenticating to use beqom APIs

This is an note/information message.

Please keep in mind that, since the environment contains the information related to the tenant and the user, you need one environment per tenant on which you want to run APIs.

Creating the Login Collection

At each session that you start in Postman, you will need to run a login collection. In Postman, a collection is set of methods used to perform a specific set of actions aiming toward a single purpose.

The purpose of the login collection is to establish a connection between postman and the tenant on which you want to run APIs.

The collection can be manually created or imported. beqom recommends that you copy the following login collection to a .json file, and then import the file to Postman as described later in this section.

 

Copy
{
"info": {
"_postman_id": "c835be6a-9fd7-4f71-9684-abbc2f35c5dd",
"name": "0. Connect",
"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
},
"item": [
{
"name": "Passport Form Login",
"event": [
{
"listen": "test",
"script": {
"id": "d5889c9d-92c2-4e57-b625-cfe61e50865f",
"exec": [
"var clientID = pm.cookies.get(\"ClientID\");",
"var idsrvauth = pm.cookies.get(\"idsrvauth\");",
"var lastPassport = pm.cookies.get(\"lastPassport\");",
"",
"pm.environment.set(\"clientID\", clientID);",
"pm.environment.set(\"idsrvauth\", idsrvauth);",
"pm.environment.set(\"lastPassport\", lastPassport);",
"",
"postman.setGlobalVariable(\"clientID\", clientID);",
"postman.setGlobalVariable(\"idsrvauth\", idsrvauth);",
"postman.setGlobalVariable(\"lastPassport\", lastPassport);",
"pm.test(\"Given login is performed on passport\", function () {",
"//    pm.response.to.have.body(pm.environment.get(\"token\"));",
"});",
""
],
"type": "text/javascript"
}
}
],
"request": {
"method": "POST",
"header": [],
"body": {
"mode": "formdata",
"formdata": [
{
"key": "Password",
"value": "{{passportPassword}}",
"type": "text"
},
{
"key": "UserName",
"value": "{{passportLogin}}",
"type": "text"
},
{
"key": "clientID",
"value": "{{clientUID}}",
"type": "text"
},
{
"key": "EnableSSO",
"value": "false",
"type": "text"
}
]
},
"url": {
"raw": "{{passportUrl}}/account/signinajax",
"host": [
"{{passportUrl}}"
],
"path": [
"account",
"signinajax"
]
}
},
"response": []
},
{
"name": "Connect to endpoint",
"event": [
{
"listen": "test",
"script": {
"id": "dad70491-f8aa-4adf-8ae9-01bf49fd5ebf",
"exec": [
"var html = cheerio.load(responseBody, { decodeEntities: true, normalizeWhitespace: false, withDomLvl1: true, xmlMode: false });",
"var wa = html('input[name=\"wa\"]').attr('value');",
"var wresult = html('input[name=\"wresult\"]').attr('value');",
"var wctx = html('input[name=\"wctx\"]').attr('value');",
"var wresultHtml = cheerio.load(wresult, { decodeEntities: true, normalizeWhitespace: false, withDomLvl1: true, xmlMode: true });",
"var base64token = wresultHtml('wsse\\\\:BinarySecurityToken').html();",
"var token = CryptoJS.enc.Utf8.stringify(CryptoJS.enc.Base64.parse(base64token));",
"",
"postman.setEnvironmentVariable(\"wa\", wa);",
"postman.setEnvironmentVariable(\"wresult\", wresult);",
"postman.setEnvironmentVariable(\"wctx\", wctx);",
"postman.setEnvironmentVariable(\"token\", token);",
"",
"postman.setGlobalVariable(\"wa\", wa);",
"postman.setGlobalVariable(\"wresult\", wresult);",
"postman.setGlobalVariable(\"wctx\", wctx);",
"",
"//pm.test(pm.globals.get(\"token\"));",
"pm.globals.unset(\"token\");",
"",
"postman.setGlobalVariable(\"token\", token);",
"pm.test(pm.globals.get(\"token\"));",
"pm.test(pm.globals.get(\"token\"));",
"//pm.globals.set(\"token\", token);",
"pm.test(\"And Connection to endpoint is performed\")"
],
"type": "text/javascript"
}
}
],
"request": {
"method": "GET",
"header": [
{
"key": "Cookie",
"value": "ClientID={{clientID}};idsrvauth={{idsrvauth}};lastPassport={{lastPassport}}"
}
],
"body": {
"mode": "raw",
"raw": ""
},
"url": {
"raw": "{{passportUrl}}/issue/wsfedEndpoint?endpointId={{classicEndpointID}}",
"host": [
"{{passportUrl}}"
],
"path": [
"issue",
"wsfedEndpoint"
],
"query": [
{
"key": "endpointId",
"value": "{{classicEndpointID}}"
}
]
}
},
"response": []
},
{
"name": "Token",
"event": [
{
"listen": "test",
"script": {
"id": "a1edb0f9-dbb2-41db-b950-a6e48900e870",
"exec": [
"pm.test(\"And Response is ok (Token)\", function () {",
"    pm.response.to.have.status(200);",
"});",
""
],
"type": "text/javascript"
}
}
],
"request": {
"auth": {
"type": "noauth"
},
"method": "GET",
"header": [
{
"key": "Authorization",
"value": "bearer {{token}}"
}
],
"body": {
"mode": "raw",
"raw": ""
},
"url": {
"raw": "{{GatewayUrl}}/api/SSO/Token",
"host": [
"{{GatewayUrl}}"
],
"path": [
"api",
"SSO",
"Token"
]
}
},
"response": []
},
{
"name": "ContextID",
"event": [
{
"listen": "test",
"script": {
"id": "1f647aee-0ddd-4916-8633-3ff5657b9930",
"exec": [
"pm.test(\"And contextID response is ok\", function () {",
"    pm.response.to.have.status(200);",
"});",
"pm.environment.set(\"contextID\", responseBody);",
"postman.setGlobalVariable('contextID', responseBody);"
],
"type": "text/javascript"
}
}
],
"request": {
"auth": {
"type": "bearer",
"bearer": [
{
"key": "token",
"value": "{{token}}",
"type": "string"
}
]
},
"method": "GET",
"header": [],
"body": {
"mode": "raw",
"raw": ""
},
"url": {
"raw": "{{GatewayUrl}}/api/SSO/ContextID",
"host": [
"{{GatewayUrl}}"
],
"path": [
"api",
"SSO",
"ContextID"
]
}
},
"response": []
}
],
"auth": {
"type": "bearer",
"bearer": [
{
"key": "token",
"value": "{{token}}",
"type": "string"
}
]
},
"event": [
{
"listen": "prerequest",
"script": {
"id": "e40a6596-5d1e-4605-b506-fbe4c8728b78",
"type": "text/javascript",
"exec": [
""
]
}
},
{
"listen": "test",
"script": {
"id": "f0950fcb-6804-4fa7-b82b-6ec69e9b8053",
"type": "text/javascript",
"exec": [
""
]
}
}
]
}

 

Once you have created the json file (using any text editor), you can import it in Postman as follows:

  1. Click the Import button, located in the upper-left corner of the Postman application window, as illustrated in the following figure:

 

The Import window is opened.

  1. Click Upload Files; a file browser window is opened.
  2. Locate the json file that you created using the code above and open it. It then should appear in the "Import" window as follows:

  1. Click Import at the bottom of the "Import" window. The login collection is imported to your Postman application. It should contain four methods, as illustrated in the following figure:

Running the Login Collection

The login collection, created at the previous step needs to be run at every Postman session. This is because the login collection provides the security token for the connection, which expires after a given time.

To run the collection in Postman, proceed as follows:

  1. Hover your mouse over the collection name (header) in the list of collections. To icons are displayed at the right of the item.
  2. Click the top icon, as illustrated in the following figure:

 

A new panel, that contains the details of the collection, is opened at the right of the collection panel.

  1. Click Run, at the top of the collection detail panel. The "Collection Runner" window is opened (on top of the Postman window, as illustrated in the following figure:

 

  1. Click Run <CollectionName>, in the bottom-left corner of the runner window. The collection is run and you can see the status of each request in real time. Once the collection is finished running, you obtain a summary. All tests should be green for the login to be successful, as illustrated in the following figure:

 

Congratulations, you have established communication between Postman and the beqom application. You can now start using the beqom APIs, either by executing individual methods, or by creating collections.

For complete information the execution of API methods in Postman, refer to the Postman documentation here .

beqom Services Using APIs

The following services consume APIs in the beqom application:

  • Gateway service
  • Analytics service
  • Individual Planner service
  • Data service
  • File service
  • Object service

 

A number of beqom FAQ article describe individual APIs to use in order to perform specific operations in the application.

For more information about the services and the APIs they use, please refer to a beqom consultant.

Practical Application

The following section describes how to execute an API using Postman. This section uses two very simple examples of methods. Depending on the operations that you want to perform in the application, the methods will get more complex and will require more parameters.

Example 1 - GET Method without Parameters

For this example, we will execute a simple method from the Gateway service that does not require any parameters:

GetVersionInfo

To run this method and obtain the version information related to the tenant from Postman, proceed as follows:

  1. Open Postman and run the login collection described in Creating the Login Collection and Running the Login Collection.
  2. Click + in the center panel of the Postman interface to open a new working tab, as illustrated in the following figure:

  1. At the left of the API URL bar, located at the top of the tab, select the GET method.
  2. Enter the URL of the Gateway service. This URL should be defined in your environment (see Creating the Environment in Postman). You can either enter the full URL or the key defined in your environment. In this example, the key for the Gateway service is GatewayUrl. In Postman, the URL/URL key should be entered in between double curly brackets. Now our API method looks as follows:

GET/{{GatewayUrl}}

  1. Enter a / character and then enter the rest of the method: api/admin/GetVersionInfo. This is the name of the API. It should be used as such; any difference will cause the execution to fail. In Postman, the request URL now looks as illustrated in the following figure:

  1. Open the "Auth" tab, located under the method URL bar.
  2. In the Type drop-down list, select Bearer Token.
  3. In the Token field, type {{token}}. This corresponds to the token that was generated when you ran the login collection.

  1. Click Send at the right of the method URL field. The request is executed. If the execution was successful, you will see a "200 OK" status in the response panel, as illustrated in the following figure:

 

The response to the request is provided in the "Body" tab of the response panel, as illustrated in the following figure:

Example 2 - GET Method with Parameters

For this example, we will execute a simple method from the Gateway service that requires a single parameter:

GetTenentLocalization

This method is used to retrieve all the localization keys and their translations from the tenant.

To run this method and obtain the translations of the tenant, proceed as follows:

  1. Open Postman and run the login collection described in Creating the Login Collection and Running the Login Collection.
  2. Click + in the center panel of the Postman interface to open a new working tab.
  3. At the left of the API URL bar, located at the top of the tab, select the GET method.
  4. Enter the URL of the Gateway service. This URL should be defined in your environment (see Creating the Environment in Postman). You can either enter the full URL or the key defined in your environment. In this example, the key for the Gateway service is GatewayUrl. In Postman, the URL/URL key should be entered in between double curly brackets. Now our API method looks as follows:

    5. GET/{{GatewayUrl}}

  5. Enter a / character and then enter the rest of the method: api/admin/GetTenantLocalization. This is the name of the API. It should be used as such; any difference will cause the execution to fail.

  6. Open the "Auth" tab, located under the method URL bar.

  7. In the Token field, type {{token}}. This corresponds to the token that was generated when you ran the login collection.
  8. In the Type drop-down list, select Bearer Token.
  9. Open the "Params" tab.
  10. Enter the following key: languages.
  11. Enter the code of the language whose localization you want to retrieve (en-US for English, de-DE for German, es-ES for Spanish, fr-FR for French, it-IT for Italian, pt-BR for Brazilian Portuguese, tr-TR for Turkish, pl-PL for Polish and zh-CN for Chinese (Simplified), zh-TW for Chinese (Traditional), ja-JP for Japanese and ru-RU for Russian). If you want to retrieve several languages, enter the language codes separated by a comma, without spacing, as illustrated in the following figure:

    You notice that URL is updated when you enter the parameter.
  12. Click Send at the right of the method URL field. The request is executed. If the execution was successful, you will see a "200 OK" status in the response panel. The response to the query is displayed in the "Body" tab, in the following format:

 

The requested languages are displayed in full, one after the other. This means that, if you entered en-US,fr-FR as we did here, the method will return all the keys in English, and then all the keys in French.

Attachments
Was this article helpful?
0 out of 0 found this helpful
Return to top