HaloPSA

HaloPSA Guides

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

Guides > Importing Additional Fields via CSV

Importing Additional Fields via CSV

In this guide we will cover:

- How to find the API Name of a field

- Worked Example - Including the Reference in Client Imports



Halo provides a series of example import sheets that can be used to import your data from a spreadsheet. However, you may find the need to import/bulk update extra fields that are not included in the example spreadsheets.


If this is the case, you will first want to find the name of relevant fields in our API as the API field names are required for the header for the spreadsheet. 


Finding API Field Names

View Example response in API documentation

There are several ways you can go about obtaining the field names for API resources. If you head to Configuration>Integrations>Halo API>API Documentation, you will find a list of resources with respective field names. Make sure to look at the Example Response for single objects, as these return a more complete set of fields:


Fig 1. API documentation for item records in Halo


Field names are not always immediately obvious as to what they are referring to, so you may want to use Swagger to look at the data in your instance, as opposed to example responses.


Using Swagger

Head to your Halo URL + '/api/swagger' (If my instance is https://HaloAcademy.halopsa.com, then I would want to head to https://HaloAcademy.halopsa.com/api/swagger). The first thing you'll want to do once you're in here is authorize Swagger to get your data.


Authorizing Swagger will require you to provide an access token:


Fig 2. Access token for swagger


I'll cover one such means of obtaining an access token in this article, but feel free to use whichever method you prefer (Postman, PowerShell etc..).


Obtain access token for Swagger

When in Halo, open your browsers developer tools (f12 in Chrome, for example). Head to the Network tab & clear your Network Activity:


Fig 3. Clear network activity


Then refresh the page. You should find when expanding the first record in your network activity you see something similar to:

Fig 4. Network activity


Scroll down to the 'Request Headers' section. You'll see part of the text in here gives you the Access Token:


Fig 5. Access token in request header


Copy the value ('CfDJ8...' in the above screenshot) and paste this into Swagger. Upon clicking 'Authorize' you should see that you are Authorized:


Fig 6. Enter access token


Now you should be able to query your desired resource - again, ensure you query a single entity instead of the whole list:


Fig 7. query specified resource 


The ID of the entity you are querying will be returned in the URL in Halo:



This response shows the data being returned for that item:

Fig 8. Response data for specified item


This way, you can manipulate the details of your desired resource to see what fields change in the API & what they change from/to.


Note: Several fields in Halo's API resources provide an 'ID' field and a corresponding 'Name' field (Notice both the AssetGroup_ID & AssetGroup_name fields in the above screenshot). As a general rule, you should always use the ID field (if the field is not already included in the example spreadsheets).


Obtaining the ID for your field can be achieved via heading to the respective entity in Halo & reading the ID in the URL:


Fig 9. ID of resource is found in URL


Worked Example - Including the Reference in Client Imports

Let's say I'm importing my client list into Halo and would like to populate the 'Reference' field when performing this import. I have obtained my access code & plugged this into Swagger (as per the above) & now I will look at the 'Area' resource.


I have added some example text into my 'Reference' field in Halo to allow me to easily find this in Swagger:

Fig 10. Entering text in field to make it easily identifiable in swagger


So from this, I know that I need to add a column to my Clients & Sites import sheet with column header "Ref".

Popular Guides