This functionality was first introduced in the Hillary release series. The specific methods described on this page work with Hillary R2 and later releases.

...

The file is uploaded to the server using the HTTP PUT POST method (not a GET method) http://<youriqsonarinstance>/api/v1/targets where the body of the request contains the JSON data.

...

{
	"message": "Completed",
	"details": "",
	"request_id": "1"
}

JSON Data file format

A tutorial on how to create JSON data files is beyond the scope of this article. For a full description of the JSON data format see the wikipedia page or the JSON.org website. Users are expected to be familiar with this format before using the RestAPI to configure iQSonar. In many cases it may be easier to configure the Locations using a CSV import or the manual method if the JSON data is not being generated programatically.

The JSON data file should contain the fields "Name" (the value MUST be "LOCATION TARGET"), "Version" (the value MUST BE "1.3")and "Locations", where the Locations field contains an array of locations.

{
    "Name":"LOCATION TARGET",
    "Version":"1.3",
    "Locations":
    [
		{ "comment": "Array of locations belongs here" }
	]
}

Each Location should contain the following fields:

For a row where the value can be empty, you can either omit the row, or pass in an empty string ("")

The list of valid Device Target types is:

...

{
    "Name":"LOCATION TARGET",
    "Version":"1.3",
	"Locations":
	[
		{
			"LocationPath":"Demo|TestScan",
			"Target":"Device",
			"Type":"Hostname",
			"Name":"Hostname Target 1",
			"InstanceName":"",	
			"Hostname":"vm-myserver",
			"StartIP":"",
			"EndIP":"",
			"SubnetMask":"0",
			"Port":"",
			"Exclusion":"False"
		},
		{
			"LocationPath":"Demo|TestScan",
			"Target":"Device",
			"Type":"Single",
			"Name":"Single IP Address",
			"InstanceName":"",	
			"Hostname":"",
			"StartIP":"10.0.0.1",
			"EndIP":"",
			"SubnetMask":"0",
			"Port":"",
			"Exclusion":"False"
		},
		{
			"LocationPath":"Demo|TestScan",
			"Target":"Device",
			"Type":"Range",
			"Name":"Multiple IP Addresses",
			"InstanceName":"",	
			"Hostname":"",
			"StartIP":"10.0.0.2",
			"EndIP":"10.0.0.99",
			"SubnetMask":"0",
			"Port":"",
			"Exclusion":"False"
		},
		{
			"LocationPath":"Demo|SecondNetwork",
			"Target":"Device",
			"Type":"Subnet",
			"Name":"Different network",
			"InstanceName":"",	
			"Hostname":"",
			"StartIP":"192.168.1.0",
			"EndIP":"",
			"SubnetMask":"24",
			"Port":"",
			"Exclusion":"False"
		}
	]
}

How to invoke the command

...

Call the RestAPI using cURL

Note: the encoded username and password pair in the CURL call corresponds to the login 'admin' and password 'password' which are the default iQSonar credentials you are forced to change on when you log in the first time.

curl --data "@file.json" \
    -H 'Authorization: Basic YWRtaW46cGFzc3dvcmQ=' \
	-H "Content-Type: application/json" \
    -X 'POST' 'http://youriqsonarserver/api/v1/targets'

Call the RestAPI using PowershellPowerShell

$cred = Get-Credential
$body = Get-Content file.json
$url = 'http://youriqsonarserver/api/v1/targets'
Invoke-RestMethod -Method POST -ContentType 'application/json' -Credential $cred -Body $body -Uri $url

Worked Example using PowerShell

In the screenshot below, we add two targets (one hostname target and one IP Address target) to the location QALab | MikeTest. The host running iQSonar is on vm-mike-rc

{
    "Name":"LOCATION TARGET",
    "Version":"1.3",
    "Locations":
    [
        {
            "LocationPath":"QALab|MikeTest",
            "Target":"Device",
            "Type":"Hostname",
            "Name":"Hostname Target 1",
            "InstanceName":"", 
            "Hostname":"vm-mike-se-w16",
            "StartIP":"",
            "EndIP":"",
            "SubnetMask":"0",
            "Port":"",
            "Exclusion":"False"
        },
		{
            "LocationPath":"QALab|MikeTest",
            "Target":"Device",
            "Type":"Single",
            "Name":"IP Address Target",
            "StartIP":"192.168.0.79",
            "Exclusion":"False"
        },
		{
            "LocationPath":"QALab|MikeTest",
            "Target":"Device",
            "Type":"Single",
            "Name":"IP Address Target 2",
            "StartIP":"192.168.0.148",
            "Exclusion":"False"
        }
	]
}

PowerShell screenshot:

Image Added

Resulting Targets in the Locations screen in iQSonar

Image Added

Error handling

If there is an error in your JSON data (for example a row that duplicates an existing target, or a syntaxt error) then rather than a result that shows "Completed" with an empty details column, you will get an error message in the Details column. PowerShell truncates this error message (see the screenshot below), but you can view the complete diagnostic error message in the back-end database

Image Added

Query to return the diagnostic message:

SELECT TargetConfig, DataOut
  FROM [jobs].[t_TargetConfigRequest]
  WHERE TargetRequestID=4

Related articles

...