HaloITSM

HaloITSM Guides

Documentation to assist with the setup and configuration of the HaloITSM platform

Guides > Using Postman

Using Postman

Postman is a tool which can be used to make direct API calls & view the response returned from such calls. 


Download Postman @: https://www.postman.com/downloads/


Getting Authentication Credentials 


The first thing you will need to do to allow for Postman to connect to your API is provide a client ID/Secret (effectively 'log in' to Halo via Postman). To do this, head (in Halo) to Configuration>Integrations>API>View Applications, then add to your records. You should see something similar to:


(Fig 1)


Give your application a sensible name 'Postman', an Authentication Method of 'Client ID & Secret' & set an 'Agent to Log in as'. On the permissions tab, select the permissions you want to grant (effectively setting the 'Role' & associated permissions for this connection). 


(fig 2)


Copy your Client Secret & save.


Creating a Collection in Postman


Head in to Postman, then to 'Workspaces':


(Fig 3)


Go to 'My Workspaces' then create a collection:


(Fig 4)


You can rename this collection by right-clicking on the record (once created):


(Fig 5)


To give it a more meaningful name.


In the 'Authorization' tab, select OAuth 2.0:


(Fig 6)



Fill the contents out as follows:

  • Add Auth Data To - 'Request Headers'
  • Header Prefix - 'Bearer'
  • Token Name - Give this a sensible Name
  • Grant Type - 'Client Credentials'
  • Access Token URL - (The URL of the instance you would like to connect) ../auth/token?tenant=<TENANT NAME>
    • You can get the <TENANT NAME> from heading to <THE HALO URL>/api/authinfo:
    • Ensure this is the same instance where you generated your client ID/Secret
    • If the instance is on-prem, you can just use /auth/token
  • Client ID - The Client ID generated in Halo previously (Fig 1)
  • Client Secret - The Client Secret generated in Halo previously (Fig 1)
  • Scope - all
  • Client Authentication - 'Send as Basic Auth Header'

Click 'Get New Access Token', at which point you should see the following screen (provided you have entered details correctly):


(Fig 7)


Click 'Proceed', then give your Token a sensible name & click 'Use Token':


(Fig 8)


Making API Requests


Now you've authenticated & got your Access Token, you can start making API requests.


Under your collection, you will see an option to 'Add a Request':


(Fig 9)


You should then be presented with a screen similar to:


(Fig 10)


Firstly, head to the Authorisation tab. If you pick your Auth type as 'Oauth 2.0', you will then be able to use the Token you have generated in the previous step:


(Fig 11)


Now you should be ready to make your API requests! Simply enter your request method & URL:


(Fig 12) 


You can find details on request URLs for API endpoints via our API Documentation - simply add /apidoc to your url (i.e: https://haloAcademy.halopsa.com/apidoc) to access our API documentation.


Bulk Updating Data


Postman can also be an effective way of bulk updating data. The procedure consists of the following steps:

  • Determining what needs updating - this will be done via writing a report, including the ID of the entity you need to update.
  • Determining the syntax for the payload - using the Dev Tools of the browser to get an idea of how the body of the request needs to be formatted.
  • Writing a basic formula in Excel - to get the structure for the desired payload, which can be used as a template and and applied to the report (upon exporting said report to CSV).
  • Copying & Pasting into Postman


Example - Bulk updating the Product Tax rate for all Clients to '20% (Sales)'


Step 1 should be pretty straightforward - write a report to get the ID of all clients. Export this report to CSV. To figure out the formatting for the request body/payload, head into a client record, open the Dev Tools (f12 in Chrome) & then to the 'Network' tab:




In the UI, change the property you're looking to bulk update (for this example, I changed the product tax code for a client) and check the network tab for a record with a status of 201:



Click into this row, then head to the 'Payload' tab. This will give you an indication as to the names of the API fields/attributes that need changing:



Generally, your request body will need to look something like:

"[

     {"<NAME OF API ATTRIBUTE 1>": <INTEGER VALUE>,

      "<NAME OF API ATTRIBUTE 2>": "<STRING VALUE>",

       etc..

     }

 ]"


So, to produce a similar result to the above screenshot, I would need something similar to:


"[

    {

        "id": 12,

        "item_tax_code": 1

    }

 ]

"



Popular Guides

Pin It on Pinterest