The xAssets API - Method : SpecialBulkDisposal

Summary

Dispose of or Transfer a list of assets

Parameters

Parameter : sXML

A bulk disposal structure in the following form:

<BulkDisposal_T><BulkDisposal_R><a>1</a><b>0</b><D39>DateDisposedOf</D39><FixedList>AssetIDList</FixedList><SID>StatusID</SID><AID>0</AID><BID>1</BID><B1ID></B1ID><ValueToDispose>0</ValueToDispose><WriteDownCurrencyCode>USD</WriteDownCurrencyCode><WriteDown>100%</WriteDown><SaleProceedsCurrencyCode>USD</SaleProceedsCurrencyCode><SaleProceeds>0</SaleProceeds><SaleExpensesCurrencyCode>TransferExpensesCurrencyCode</SaleExpensesCurrencyCode><SaleExpenses>TransferExpenses</SaleExpenses><SBID>7</SBID><PurgeFlag>0</PurgeFlag><Transfer>Transfer</Transfer><DIDList>4,5</DIDList></BulkDisposal_R></BulkDisposal_T>

Where:

DateDisposedOf is the date the disposal occurred in real life. This could be backdated or a future date. If disposals are backdated into a closed period, the disposal transactions and therefore journal entries will be posted on the first day of the next open period.

AssetIDLIst - a comma separated list of AssetIDs that are being disposed or transferred

StatusID - the disposal status ID. Check the status table for the disposed status that is the best match to the operation being performed. Status codes by default include Sold, Stolen, Written off or Scrapped, Lost, Disassembled, Upgraded and Out of Service, Consumed and Expired.

AID - when disposing of a single asset, the ID can be passed directly here, and this has no material difference to passing the value in the AssetIDList parameter

Bid - the budget ID to dispose to. This should normally be 1.

B1ID - to dispose only in a single book and leave other books undisposed, specify the BookID in here. Note this may produce confusing results to end users, since the asset may appear undisposed when it is disposed, and vice versa.

ValueToDispose - specify zero (0) to dispose of the entire asset value, or specify an amount to partially dispose of the asset

WriteDownCurrencyCode - when specifying a write down amount, this determines the currency of the value provided

WriteDown - for partial disposals, a percentage can be implied here. Normally assets are 100% disposed of.

SaleProceedsCurrencyCode - when specifying a sales proceeds amount, this determines the currency of the value provided

SaleProceeds - when an asset is sold, enter the sale value in this field. Transactions will be posted reflecting this sale value in a specific transaction type

SaleExpensesCurrencyCode - when specifying a cost of selling this asset, this determines the currency of the value provided

SaleExpenses - specifies the cost of selling the asset. Transactions will be posted reflecting this expense value in a specific transaction type

SBID - this value has to be 0

PurgeFlag - Specify zero to dispose of the asset, specify 1 to delete the asset and all it's child records and history. This cannot be undone.

Transfer - Specify "transfer" if this is a Transfer operation, or an empty string if this is a Disposal operation.

DIDList - a list of DocumentIDs for Documents already uploaded that should be linked to the Transfer Out and Transfer In transactions, or the Disposal Transaction.

Parameter : sArguments

For transfers, a comma separated list of transfer fields.

Returns

An empty string is returned if the operation was successful. If an error occured then an error message is returned

Syntax and Examples

Restful syntax with Microsoft Visual Basic

Example 1 - Dispose of Assets 2,3 and 4 to status Sold(6)


	
    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 & ".yourxassetsplatform.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=SpecialBulkDisposal&xml=<BulkDisposal_T><BulkDisposal_R><a>1</a><b>0</b><D39>12-Apr-2022</D39><FixedList>2,3,4</FixedList><SID>6</SID><AID>0</AID><BID>1</BID><B1ID></B1ID><ValueToDispose>0</ValueToDispose><WriteDownCurrencyCode>USD</WriteDownCurrencyCode><WriteDown>100%</WriteDown><SaleProceedsCurrencyCode>USD</SaleProceedsCurrencyCode><SaleProceeds>0</SaleProceeds><SaleExpensesCurrencyCode>USD</SaleExpensesCurrencyCode><SaleExpenses>0</SaleExpenses><SBID>7</SBID><PurgeFlag>0</PurgeFlag><Transfer></Transfer></BulkDisposal_R></BulkDisposal_T>
                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 - Transfer Assets 2,3 and 4 to LocationID 7


	
    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 & ".yourxassetsplatform.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=SpecialBulkDisposal&xml=<BulkDisposal_T><BulkDisposal_R><a>1</a><b>0</b><D39>12-Apr-2022</D39><FixedList>2,3,4</FixedList><SID>6</SID><AID>0</AID><BID>1</BID><B1ID></B1ID><ValueToDispose>0</ValueToDispose><WriteDownCurrencyCode>USD</WriteDownCurrencyCode><WriteDown>100%</WriteDown><SaleProceedsCurrencyCode>USD</SaleProceedsCurrencyCode><SaleProceeds>0</SaleProceeds><SaleExpensesCurrencyCode>USD</SaleExpensesCurrencyCode><SaleExpenses>0</SaleExpenses><SBID>7</SBID><PurgeFlag>0</PurgeFlag><Transfer>transfer</Transfer></BulkDisposal_R></BulkDisposal_T>&arg0=LocationID&arg1=7
                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 - Dispose of Assets 2,3 and 4 to status Sold(6)



    Try

        ErrorMessage = ""

        Return w.WebSaveSpecial(_hash, _username, _db, _ip, "<BulkDisposal_T><BulkDisposal_R><a>1</a><b>0</b><D39>12-Apr-2022</D39><FixedList>2,3,4</FixedList><SID>6</SID><AID>0</AID><BID>1</BID><B1ID></B1ID><ValueToDispose>0</ValueToDispose><WriteDownCurrencyCode>USD</WriteDownCurrencyCode><WriteDown>100%</WriteDown><SaleProceedsCurrencyCode>USD</SaleProceedsCurrencyCode><SaleProceeds>0</SaleProceeds><SaleExpensesCurrencyCode>USD</SaleExpensesCurrencyCode><SaleExpenses>0</SaleExpenses><SBID>7</SBID><PurgeFlag>0</PurgeFlag><Transfer></Transfer></BulkDisposal_R></BulkDisposal_T>", "SpecialBulkDisposal", {"<BulkDisposal_T><BulkDisposal_R><a>1</a><b>0</b><D39>12-Apr-2022</D39><FixedList>2,3,4</FixedList><SID>6</SID><AID>0</AID><BID>1</BID><B1ID></B1ID><ValueToDispose>0</ValueToDispose><WriteDownCurrencyCode>USD</WriteDownCurrencyCode><WriteDown>100%</WriteDown><SaleProceedsCurrencyCode>USD</SaleProceedsCurrencyCode><SaleProceeds>0</SaleProceeds><SaleExpensesCurrencyCode>USD</SaleExpensesCurrencyCode><SaleExpenses>0</SaleExpenses><SBID>7</SBID><PurgeFlag>0</PurgeFlag><Transfer></Transfer></BulkDisposal_R></BulkDisposal_T>"}, False, _dns, _port, _scheme, _nonce, _noncedate)

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

Example 2 - Transfer Assets 2,3 and 4 to LocationID 7



    Try

        ErrorMessage = ""

        Return w.WebSaveSpecial(_hash, _username, _db, _ip, "<BulkDisposal_T><BulkDisposal_R><a>1</a><b>0</b><D39>12-Apr-2022</D39><FixedList>2,3,4</FixedList><SID>6</SID><AID>0</AID><BID>1</BID><B1ID></B1ID><ValueToDispose>0</ValueToDispose><WriteDownCurrencyCode>USD</WriteDownCurrencyCode><WriteDown>100%</WriteDown><SaleProceedsCurrencyCode>USD</SaleProceedsCurrencyCode><SaleProceeds>0</SaleProceeds><SaleExpensesCurrencyCode>USD</SaleExpensesCurrencyCode><SaleExpenses>0</SaleExpenses><SBID>7</SBID><PurgeFlag>0</PurgeFlag><Transfer>transfer</Transfer></BulkDisposal_R></BulkDisposal_T>", "SpecialBulkDisposal", {"<BulkDisposal_T><BulkDisposal_R><a>1</a><b>0</b><D39>12-Apr-2022</D39><FixedList>2,3,4</FixedList><SID>6</SID><AID>0</AID><BID>1</BID><B1ID></B1ID><ValueToDispose>0</ValueToDispose><WriteDownCurrencyCode>USD</WriteDownCurrencyCode><WriteDown>100%</WriteDown><SaleProceedsCurrencyCode>USD</SaleProceedsCurrencyCode><SaleProceeds>0</SaleProceeds><SaleExpensesCurrencyCode>USD</SaleExpensesCurrencyCode><SaleExpenses>0</SaleExpenses><SBID>7</SBID><PurgeFlag>0</PurgeFlag><Transfer>transfer</Transfer></BulkDisposal_R></BulkDisposal_T>", "LocationID", "7"}, False, _dns, _port, _scheme, _nonce, _noncedate)

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

AMSX Syntax

Example 1 - Dispose of Assets 2,3 and 4 to status Sold(6)



    SaveSpecial "SpecialBulkDisposal","<BulkDisposal_T><BulkDisposal_R><a>1</a><b>0</b><D39>12-Apr-2022</D39><FixedList>2,3,4</FixedList><SID>6</SID><AID>0</AID><BID>1</BID><B1ID></B1ID><ValueToDispose>0</ValueToDispose><WriteDownCurrencyCode>USD</WriteDownCurrencyCode><WriteDown>100%</WriteDown><SaleProceedsCurrencyCode>USD</SaleProceedsCurrencyCode><SaleProceeds>0</SaleProceeds><SaleExpensesCurrencyCode>USD</SaleExpensesCurrencyCode><SaleExpenses>0</SaleExpenses><SBID>7</SBID><PurgeFlag>0</PurgeFlag><Transfer></Transfer></BulkDisposal_R></BulkDisposal_T>"

Example 2 - Transfer Assets 2,3 and 4 to LocationID 7



    SaveSpecial "SpecialBulkDisposal","<BulkDisposal_T><BulkDisposal_R><a>1</a><b>0</b><D39>12-Apr-2022</D39><FixedList>2,3,4</FixedList><SID>6</SID><AID>0</AID><BID>1</BID><B1ID></B1ID><ValueToDispose>0</ValueToDispose><WriteDownCurrencyCode>USD</WriteDownCurrencyCode><WriteDown>100%</WriteDown><SaleProceedsCurrencyCode>USD</SaleProceedsCurrencyCode><SaleProceeds>0</SaleProceeds><SaleExpensesCurrencyCode>USD</SaleExpensesCurrencyCode><SaleExpenses>0</SaleExpenses><SBID>7</SBID><PurgeFlag>0</PurgeFlag><Transfer>transfer</Transfer></BulkDisposal_R></BulkDisposal_T>", "LocationID", "7"

XCS Syntax

Example 1 - Dispose of Assets 2,3 and 4 to status Sold(6)



    Dim ret as String = Server.SaveSpecial("SpecialBulkDisposal","<BulkDisposal_T><BulkDisposal_R><a>1</a><b>0</b><D39>12-Apr-2022</D39><FixedList>2,3,4</FixedList><SID>6</SID><AID>0</AID><BID>1</BID><B1ID></B1ID><ValueToDispose>0</ValueToDispose><WriteDownCurrencyCode>USD</WriteDownCurrencyCode><WriteDown>100%</WriteDown><SaleProceedsCurrencyCode>USD</SaleProceedsCurrencyCode><SaleProceeds>0</SaleProceeds><SaleExpensesCurrencyCode>USD</SaleExpensesCurrencyCode><SaleExpenses>0</SaleExpenses><SBID>7</SBID><PurgeFlag>0</PurgeFlag><Transfer></Transfer></BulkDisposal_R></BulkDisposal_T>")
    If ret = " Or ret.Substring(0, 8) = "special=" Then
        MsgBox("Save operation completed.", vbInformation, "Save Data")
    Else
        MsgBox("Save operation failed:" & ret, vbExclamation, "Save Data")
    End If

Example 2 - Transfer Assets 2,3 and 4 to LocationID 7



    Dim ret as String = Server.SaveSpecial("SpecialBulkDisposal","<BulkDisposal_T><BulkDisposal_R><a>1</a><b>0</b><D39>12-Apr-2022</D39><FixedList>2,3,4</FixedList><SID>6</SID><AID>0</AID><BID>1</BID><B1ID></B1ID><ValueToDispose>0</ValueToDispose><WriteDownCurrencyCode>USD</WriteDownCurrencyCode><WriteDown>100%</WriteDown><SaleProceedsCurrencyCode>USD</SaleProceedsCurrencyCode><SaleProceeds>0</SaleProceeds><SaleExpensesCurrencyCode>USD</SaleExpensesCurrencyCode><SaleExpenses>0</SaleExpenses><SBID>7</SBID><PurgeFlag>0</PurgeFlag><Transfer>transfer</Transfer></BulkDisposal_R></BulkDisposal_T>", "LocationID", "7")
    If ret = " Or ret.Substring(0, 8) = "special=" Then
        MsgBox("Save operation completed.", vbInformation, "Save Data")
    Else
        MsgBox("Save operation failed:" & ret, vbExclamation, "Save Data")
    End If

Download the Visual Studio API Samples Project

Return to the API Index Page