The xAssets API - Method : AssetXML

Summary

This function performs multiple actions

  • Run a query and return the data as an XML table
  • Create the XML template required for a new asset record
  • Return the XML for a single asset or a group of assets, for use in editing or bulk update

Any query can be run, this function is the primary way to execute a query in an API call, and queries are not restricted to being based on the asset table, but can query any set of tables in the data model

All XML is represented in the standardized structure documentelement - records - fields

Parameters

Parameter : sArguments

Passing Argument 0 as a query ID or query name is sufficient to run a query that does not expect parameters

0
Action_Or_QueryID

"NEW" to return the XML template needed to create a new asset record

"EDIT" All asset fields

SavedSelectID Run the query with this ID

SavedSelectName Run the query with this name

When argument 0 = NEW or EDIT

1
AssetID
2
FieldList
3
ValueList

When argument 0 implies a query

1
FilterType - "FIXEDLIST", "SINGLEASSET" , "DIRECT", sSqlQuery, sXMLQuery, sQueryName, sTableName, or an AssetID if editing a record
2
RecordIDArray - a CSV array of record IDs
3
Not used
4
Parameters XML
5
Drilldown Level - an integer specifying the level of drilldown to start at
6
Orderby - a comma separated values list of fields to sort by, optionally with " desc" appended to fields to be sorted descending
7
Page size - the number of rows to display on each page
8
Page wanted - the page number required
9
Tree name - the name of the tree to be displayed at the left of the query. See topic:treenames for more information
10
Tree level - the level of the tree to be displayed at the left of the query
11
Tree current key + ^ + Tree top key - determine the selected node in the tree
12
SubjectID - the subject of this query
13
SpecificationID or Specification XML Name "installedsoftware" etc - only used for queries with a set SpecificationID
14
Editmode - for future use
15
Transform id to run before running the query - not currently supported
16
Tree Options
17
Additional Tree Nodes. Use for HTMLTree function options
18
TreeFilter - the stored procedure to use when filtering records on tree click
19
QueryVariantIndex - specify which query variant to run
20
QueryFilterType
21
QueryFilterName
22
QueryFilterText
23
Filter xml
24
DisplayContext
25
DrillDownMode - 0 (default) - return the whole tree, 1 - return just the children of the level below the key given, 2 - return all children
26
DrillDownKey - 0 return all nodes at the level specified. 1 - return just the children of this key
27
Presentation - TABLE, GROUPEDTABLE, PIE, SOLIDPIE, RING, BAR, BARHORIZONTAL or MAP
28
IncludeFlags - Include the a and b xml tags used by version 6. Default is true

Returns

Query data in XML format

Syntax and Examples

Restful syntax with Microsoft Visual Basic

Example 1 - To run the All Assets query


    Imports System.Text
    Imports Newtonsoft.Json.Linq
    Public Module Module1

        Public Sub Main()

            Try

                '   Enter your API key and company database name in these variables

                Dim _db As String = "mycompany"
                Dim apikey As String = "YOURAPIKEY"

                '   Open a web client to login

                Dim web As New System.Net.WebClient()

                Dim urlroot as String = "https://" & _db & ".hosted.xassets.net/api"
                Dim json As String = web.DownloadString(urlroot & "/api.ashx?apikey=" & apikey & "&database=" & _db & "&command=apilogon")

                '   Check the login for errors

                Dim o As JObject = JObject.Parse(json)
                Dim e As String = GetResultFromJson(o, "error")
                If e <> "" Then
                    Throw New Exception(e)
                End If

                '   Store the login hash, nonce and noncedate

                Dim hash As String = GetResultFromJson(o, "hash")
                Dim nonce As String = GetResultFromJson(o, "nonce")
                Dim noncedate As Date = CDate(GetResultFromJson(o, "noncetime"))

                If hash = "" Then
                    Throw New Exception("Unexpected error - a hash was not returned from the API logon process")
                End If

                Console.WriteLine("Logged on OK")

                '   Open a new web client to perform the API call

                web = New System.Net.WebClient()

                '   Add the authorization header

                web.Headers.Add("Authorization", "Bearer " & hash)
                web.Headers.Add("Sec", _db & "|" & nonce & "|" & Format(noncedate, "dd-MMM-yyyy HH:mm:ss") & "|" & Format(noncedate, "fff"))

                '   Perform the actual API call

                Dim url as String = urlroot & "/api.ashx?command=AssetXML&arg0=10269
                Dim data As String = web.DownloadString(url.ToString)

                '   Parse and output the data

                Dim ob As JObject = JObject.Parse(data)
                Dim err As String = GetResultFromJson(ob, "error")
                If err <> "" Then
                    Throw New Exception(err)
                End If
            
                Dim xml As String = GetResultFromJson(ob, "returncode")

                Console.WriteLine(xml)
                Console.WriteLine("Finished - Press enter to close")
            
                Catch ex As Exception
                Console.WriteLine("Error:" & ex.Message & " - Press enter to close")
            End Try

            Console.ReadLine()

        End Sub

        Private Function GetResultFromJson(o As JObject, sFind As String) As String

            For Each res As JObject In o.SelectTokens("data[*]")
                If res("type").Value(Of String) = sFind Then
                    Return res("value").ToString
                End If
            Next

            Return ""

        End Function
    End Module
                

Example 2 - To edit Asset number 1


    Imports System.Text
    Imports Newtonsoft.Json.Linq
    Public Module Module1

        Public Sub Main()

            Try

                '   Enter your API key and company database name in these variables

                Dim _db As String = "mycompany"
                Dim apikey As String = "YOURAPIKEY"

                '   Open a web client to login

                Dim web As New System.Net.WebClient()

                Dim urlroot as String = "https://" & _db & ".hosted.xassets.net/api"
                Dim json As String = web.DownloadString(urlroot & "/api.ashx?apikey=" & apikey & "&database=" & _db & "&command=apilogon")

                '   Check the login for errors

                Dim o As JObject = JObject.Parse(json)
                Dim e As String = GetResultFromJson(o, "error")
                If e <> "" Then
                    Throw New Exception(e)
                End If

                '   Store the login hash, nonce and noncedate

                Dim hash As String = GetResultFromJson(o, "hash")
                Dim nonce As String = GetResultFromJson(o, "nonce")
                Dim noncedate As Date = CDate(GetResultFromJson(o, "noncetime"))

                If hash = "" Then
                    Throw New Exception("Unexpected error - a hash was not returned from the API logon process")
                End If

                Console.WriteLine("Logged on OK")

                '   Open a new web client to perform the API call

                web = New System.Net.WebClient()

                '   Add the authorization header

                web.Headers.Add("Authorization", "Bearer " & hash)
                web.Headers.Add("Sec", _db & "|" & nonce & "|" & Format(noncedate, "dd-MMM-yyyy HH:mm:ss") & "|" & Format(noncedate, "fff"))

                '   Perform the actual API call

                Dim url as String = urlroot & "/api.ashx?command=AssetXML&arg0=EDIT&arg1=1
                Dim data As String = web.DownloadString(url.ToString)

                '   Parse and output the data

                Dim ob As JObject = JObject.Parse(data)
                Dim err As String = GetResultFromJson(ob, "error")
                If err <> "" Then
                    Throw New Exception(err)
                End If
            
                Dim xml As String = GetResultFromJson(ob, "returncode")

                Console.WriteLine(xml)
                Console.WriteLine("Finished - Press enter to close")
            
                Catch ex As Exception
                Console.WriteLine("Error:" & ex.Message & " - Press enter to close")
            End Try

            Console.ReadLine()

        End Sub

        Private Function GetResultFromJson(o As JObject, sFind As String) As String

            For Each res As JObject In o.SelectTokens("data[*]")
                If res("type").Value(Of String) = sFind Then
                    Return res("value").ToString
                End If
            Next

            Return ""

        End Function
    End Module
                

SOAP Syntax with Microsoft Visual Basic

Example 1 - To run the All Assets query



    Try

        ErrorMessage = ""

        Return w.WebCommandProcessorArray(_hash, _username, _db, _ip, "AssetXML", {"10269"}, _dns, _port, _scheme, _nonce, _noncedate)

    Catch ex As Exception
        ErrorMessage = ex.Message
        Return ""
    End Try
                        

Example 2 - To edit Asset number 1



    Try

        ErrorMessage = ""

        Return w.WebCommandProcessorArray(_hash, _username, _db, _ip, "AssetXML", {"EDIT", "1"}, _dns, _port, _scheme, _nonce, _noncedate)

    Catch ex As Exception
        ErrorMessage = ex.Message
        Return ""
    End Try
                        

AMSX Syntax

Example 1 - To run the All Assets query


    Set xml = CommandProcessor "AssetXML", "10269"
                        

Example 2 - To edit Asset number 1


    Set xml = CommandProcessor "AssetXML", "EDIT", "1"
                        

XCS Syntax

Example 1 - To run the All Assets query


    Dim xml As String = Server.API("AssetXML", "10269")
                        

Example 2 - To edit Asset number 1


    Dim xml As String = Server.API("AssetXML", "EDIT", "1")
                        

Download the Visual Studio API Samples Project

Return to the API Index Page