Python API

[TIm W]

Hi,

I've been tasked with adding assets into Hornbill from our internal CMDB using python, all of which is a bit new to me and I'm struggling with where to start and find examples of how to use the Python API.

Can anyone provide an example of using the Python API to find an asset by it's name, add an asset and update an asset.

Thanks in advance.

Tim

[Steve G]

Hi @TIm W,

Sure. Here are a couple of examples of how you can do what you need using the Hornbill Python API Library, which contains examples and is documented over on Github.

This is a basic code snippet that will return details of an asset with an exact match on name, where the name of the asset is SGMAC2011:

from xmlmc import XmlmcService
from xmlmc import XmlmcHelper

xmlmc = XmlmcService("yourinstanceid")
xmlmc.set_api_key("yourapikey")
xmlmc.add_param("application", "com.hornbill.servicemanager")
xmlmc.add_param("entity", "Asset")
elem = xmlmc.add_param("searchFilter")
elem.add_child("column", "h_name")
elem.add_child("value", "SGMAC2011")
elem.add_child("matchType", "exact")
json_string = xmlmc.invoke("data", "entityBrowseRecords2")
if XmlmcHelper.is_call_success(json_string):
    assetRecords = XmlmcHelper.get_param_value(json_string, "params/rowData/row")[0]
    assetId = assetRecords['h_pk_asset_id']
    assetClass = assetRecords['h_class']
    for attr, value in assetRecords.items():
        print (attr, value)
else:
    print(XmlmcHelper.get_error_message(json_string))

Note, we're using the data::entityBrowseRecords2 API to search through the Asset entity in Service Manager, and return the record. We're providing the instance ID (stevegdev here, but replace that with whatever yours is), and an API Key to authenticate the request. The image below shows the returned fields (I'm just looping through the properties of the returned object), and how they can be assigned to new variables you use later in the script.

To add an asset, you can use the relevant Asset Creation API for the class of Asset you are creating. An example being AssetsComputer::addAssetComputer API, which will create a computer type asset:

from xmlmc import XmlmcService
from xmlmc import XmlmcHelper

xmlmc = XmlmcService("yourinstanceid")
xmlmc.set_api_key("yourapikey")
xmlmc.add_param("name", "MYNEWASSET")
xmlmc.add_param("type", "1")
xmlmc.add_param("version", "1")
json_string = xmlmc.invoke("apps/com.hornbill.servicemanager/AssetsComputer", "addAssetComputer")
if XmlmcHelper.is_call_success(json_string):
    assetId = XmlmcHelper.get_param_value(json_string, "params/assetId")
    print(assetId)
else:
    print(XmlmcHelper.get_error_message(json_string))

Note, if you have a look at the API documentation, it gives you a list of the input parameters. name, type and version are mandatory, and the rest are optional. 

With regards to the type input, this is the primary key of the asset type that the new asset should be. The easiest way to find out what value you should use here is in the Asset Type Details form in the main app:

To update assets of class Computer, you can use the AssetsComputer::updateAssetComputer API. The code for that will be almost identical to the create code above, except you need to provide the asset ID to update.

If you do a page search for addAsset, or updateAsset in the Service Manager API documentation, you can find the API's for creating and updating assets of different class.

Hope this helps,

Steve

[Steve G]

@TIm W Also, with regards to updating assets using the API's, check this post out as it contains some more useful information:

Cheers,

Steve

[TIm W]

Thanks for the help. I've managed to get what I needed to do done.

[RichardD]

On 08/07/2020 at 16:49, Steve G said:

elem = xmlmc.add_param("searchFilter")
elem.add_child("column", "h_name")
elem.add_child("value", "SGMAC2011")
elem.add_child("matchType", "exact")

 

Hi @Steve G

How may I add a second set of child parameters for searchFilter, please?
(A second searchColumnType object? https://docs.hornbill.com/esp-api/types/complex/searchColumnType)

In my case, I am searching against h_email rather than h_name (which I have working in isolation) but I would like to also specify a filter against column: h_account_status for value: 0.

Thanks in advance of your kind response.

Edited October 24, 2023 by RichardD
added link to API docs

[Steve G]

Hi @RichardD,

searchFilter is unbounded, as per the API reference guide, so you can simply add another searchFilter element to the request as so:

elem = xmlmc.add_param("searchFilter")
elem.add_child("column", "h_name")
elem.add_child("value", "Asset00")
elem.add_child("matchType", "wildcard")
elem = xmlmc.add_param("searchFilter")
elem.add_child("column", "h_class")
elem.add_child("value", "computer")
elem.add_child("matchType", "exact")

You can use print_params() to review the request payload params before it's sent to Hornbill too, as you can see in this really basic example:

 

Hope this helps,

Steve
 

[RichardD]

Thanks @Steve G

Apologies for missing the unbounded.

C# version that's now working for me...

xmlmc.AddParam("application", "com.hornbill.core");
xmlmc.AddParam("entity", "UserAccount");
xmlmc.AddParam("searchFilter", new List<XmlmcParam>() {
    new XmlmcParam() { Name = "column", Value = "h_email" },
    new XmlmcParam() { Name = "value", Value= email },
    new XmlmcParam() { Name = "matchType", Value="exact" }
});
xmlmc.AddParam("searchFilter", new List<XmlmcParam>() {
    new XmlmcParam() { Name = "column", Value = "h_account_status" },
    new XmlmcParam() { Name = "value", Value="0" },
    new XmlmcParam() { Name = "matchType", Value="exact" }
});
xmlmc.AddParam("maxResults", 1);
xmlmc.Invoke("data", "entityBrowseRecords2");

 

[RichardD]

Sorry @Steve G
Hopefully my last question...
How do you specify a list of values for a searchFilter, please?
When searching for Requests for a specified h_fk_user_id, I have tried a few random variations of formatting the value, with the matchType as both wildcard and exact. The request is working for a single value. Just need to get it working for these three open call types.

xmlmc.AddParam("searchFilter", new List<XmlmcParam>() {
   new XmlmcParam() { Name = "column", Value = "h_status" },
   new XmlmcParam() { Name = "value", Value="status.onHold,status.open,status.new" },
   new XmlmcParam() { Name = "matchType", Value="wildcard" }
});

 

[Steve G]

Hi @RichardD,

The matchScope input param is your friend here, with a value of any (basically an OR) and each value set as its own exact match search filter, as follows   

xmlmc.AddParam("matchScope", "any");
xmlmc.AddParam("searchFilter", new List<XmlmcParam>() {
   new XmlmcParam() { Name = "column", Value = "h_status" },
   new XmlmcParam() { Name = "value", Value="status.onHold" },
   new XmlmcParam() { Name = "matchType", Value="exact" }
});
xmlmc.AddParam("searchFilter", new List<XmlmcParam>() {
   new XmlmcParam() { Name = "column", Value = "h_status" },
   new XmlmcParam() { Name = "value", Value="status.open" },
   new XmlmcParam() { Name = "matchType", Value="exact" }
});
xmlmc.AddParam("searchFilter", new List<XmlmcParam>() {
   new XmlmcParam() { Name = "column", Value = "h_status" },
   new XmlmcParam() { Name = "value", Value="status.new" },
   new XmlmcParam() { Name = "matchType", Value="exact" }
});

Cheers,

Steve

[RichardD]

Thanks @Steve G

If I am also including a searchFilter for column h_fk_user_id. (Probably should have mentioned that in my previous post, sorry.)
Will the 'any' matchType return all calls for the user and all calls with one of the three status?

Or is there a way to cunning way to do the equivalent of a T-SQL WHERE user="1" AND (status =1 OR status=2 OR status=3)

(I would of course use an T-SQL IN rather than the parenthesised ORs)

[RichardD]

Or would I be better off sticking with https://api.hornbill.com/apps/com.hornbill.servicemanager/Requests?op=getCustomerRequests in this instance?

[RichardD]

xmlmc.AddParam("queryName", "getCustomersRequests");
xmlmc.AddParam("resultType", "allData");
xmlmc.AddParam("customerId", "USER-ID");
xmlmc.AddParam("rowstart", "0");
xmlmc.AddParam("limit", "10");
xmlmc.AddParam("statusFilter", "status.onHold");
xmlmc.AddParam("statusFilter", "status.new");
xmlmc.AddParam("statusFilter", "status.open");
xmlmc.Invoke("apps/com.hornbill.servicemanager/Requests", "getCustomerRequests");
var responseJSON = xmlmc.GetResponseParamAsString("queryExecJSON");

 

[RichardD]

Hmmm. That only returns a single Request, even if I remove the rowstart, limit and statusFilter params.