The xAssets API

Introduction

There are three ways to execute API calls in xAssets Applications

  • Build a program to embed restful readonly API calls
  • Embed the API accesses within a transformation, and use either a program, a schedule or a menu item within xAssets to invoke the transformation

The option to embed API functionality within transformations requires no programming expertise and does not need to be hosted on a computer, since the programs will exist within your xAssets database, and xAssets Engineers will write the scripts for you. These scripts can still be triggered from an external program.

When using restful calls, all methods automatically route through to one of three interfaces:

  • Command Processor - to "get" data
  • Save - to "save" standard formatted data to tables
  • SaveSpecial - to execute specialized/complex save operations such as asset disposals, asset splits, and to run transformations

One restful call is needed to get an authorization token, and this is then used in subsequent restful calls to get data and run queries from the database. API get commands are listed below.

Using restful calls, you explicitly call the web services interface as follows:

  • Logon - to establish a session and obtain a bearer token
  • CommandProcessor - to get data, settings or XML
  • Save - to save data back to the database - see the save function in the api interface section below
  • SaveSpecial - for specialized save operations such as asset disposal, bulk update and bulk transfer

These methods are described in detail in the API Interface section.

Commonly Used API Methods

This section links to methods which are most commonly used.

Get data from a query or an asset record for editing or creation
Save changed XML data for any record
To run a transformation. Transformations can themselves run any server-side task
To execute a month end depreciation batch and create budgetary depreciation for future periods
To dispose of or transfer a list of assets

Most tasks can be achieved within transformations, which can run on a schedule, a trigger, or be manually launched from any menu item. This includes notifications, emailing reports, imports, exports, data manipulation and integration to other local and cloud applications.

Index of API Get Operations

Get operations are called using the API Interface Function named "CommandProcessor".

AccountingPeriodSetXML
Generate XML for table AccountingPeriodSet
AccountingPeriodXML
Generate XML for table AccountingPeriod
AssetAuditXML
Generate a table of Asset History information for an asset or a list of assets xAssets stores each instance of an asset record every time it is saved, so a full audit trail exists for the asset in a history table Use this function to query the asset history. You can query for a specific field or for all fields, and over all time or over a specific time frame Any number of Asset table fields can be added to the data
AssetCheckOutXML
Generate the checkout records needed for checking out an asset or a list of assets
AssetDefaultXML
Generate XML for table AssetDefault
AssetDependencyXML
Generate the records needed to display inter-asset dependencies. Note that asset-dependency is also a supported type of query, so this API method is mainly of use to the system for editing AssetDependency records directly.
AssetDepreciationProfileSectXML
Generate XML for table AssetDepreciationProfileSect
AssetDepreciationProfileXML
Generate records for the depreciation profile of an asset. This data determines how the asset will be depreciated in each accounting book.
AssetInsurancePolicyXML
Generate XML for table AssetInsurancePolicy
AssetServiceHistoryDepXML
Generate XML for table AssetServiceHistoryDep
AssetServiceHistoryXML
Generate XML for table AssetServiceHistory
AssetServicePlanXML
Generate XML for table AssetServicePlan
AssetTransactionXML
Generate XML for table AssetTransaction
AssetViewFieldXML
Generate XML for table AssetViewField
AssetViewXML
Generate XML for table AssetView
AssetXML
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
BookXML
Generate XML for table Book
BudgetXML
Generate XML for table Budget
CategoryBookXML
Generate XML for table CategoryBook
CategoryGroupXML
Generate XML for table CategoryGroup
CategoryXML
Generate XML for table Category
CheckOutStatusXML
Generate XML for table CheckOutStatus
ClaimXML
Generate XML for table Claim
CollectionServerXML
Generate XML for table CollectionServer
CompanyXML
Generate XML for table Company
CostCentreTypeXML
Generate XML for table CostCentreType
CostCentreXML
Generate XML for table CostCentre
CredentialPackXML
Generate XML for table CredentialPack
CurrencyCodeXML
Generate XML for table CurrencyCode
CustodianXML
Generate XML for table Custodian
DataMappingTypeXML
Generate XML for table DataMappingType
DataMappingXML
Generate XML for table DataMapping
DBTransformScheduleXML
Generate XML for table DBTransformSchedule
DBTransformXML
Generate XML for table DBTransform
DepartmentTypeXML
Generate XML for table DepartmentType
DepartmentXML
Generate XML for table Department
DependencyTypeXML
Generate XML for table DependencyType
DepreciationTableXML
Generate XML for table DepreciationTable
DepreciationTypeXML
Generate XML for table DepreciationType
DocumentObjectUsageXML
Generate XML for table DocumentObjectUsage
DocumentObjectXML
Generate XML for table DocumentObject
ErrorCodeXML
Generate XML for table ErrorCode
ExchangeRateXML
Generate XML for table ExchangeRate
FinancialYearXML
Generate XML for table FinancialYear
GetAssetValueOnTransactionDate
Get the value of an asset on the date of a specified asset transaction record
GetAssetViewFormID
Find the best fit Form (Asset View) to edit a record given a form name match, Asset ID, CategoryID, ServiceTypeID or Subject, or any combination of these
GetCategoryFromAsset
Get the Category of a given asset record
GetFieldLookupAll
Get the default display type and lookup name for the field specified
GetFormattedDate
Format a date according to the logged-in-user's date format
GetHomeCurrencyValue
Get a converted value at a specified date for the currency provided
GetLastAssetID
Get the Asset ID of the Asset that this user account last inspected or edited
GetParameters
Get a list of parameters expected in order to run a query or a transformation
GetQueryVariantCount
Get the number of query variants that the specified query has
GetQueryVariantIndex
Get the index of a query variant. Note that passing through "Base Query" will always return zero since by convention the base query of each query in the database is the 0th query variant
GetSpecialOption
Get the value of a special option
GetSpecificationID
Get the specification ID of a specification field
GetSpecificationTypeID
Get the specification type of a specification field
ImportanceRatingXML
Generate XML for table ImportanceRating
IndexationXML
Generate XML for table Indexation
InsurancePolicyXML
Generate XML for table InsurancePolicy
LeaseXML
Generate XML for table Lease
LicenseCodeXML
Generate XML for table LicenseCode
LocationTypeXML
Generate XML for table LocationType
LocationXML
Generate XML for table Location
LogonGUID
get the current logged in user's logon guid
LookupAccountingPeriod
Returns a list of accounting periods for use in dropdowns and searches
LookupAccountingPeriodSet
Returns a list of accounting period sets for use in dropdowns
LookupAssetFromCustodian
Returns a list of assets (ID and Asset Description) for a given custodian
LookupAssetHierarchy
Build an XML tree structure of the asset hierarchy determined by parent-child relationships
LookupAssetViewField
Get a lookup list of fields in an Asset View (Form)
LookupAttribute
Lookup any attribute of a table using its ID field
LookupAttributes
Lookup returns multiple attributes separated by a caret character, or otherwise the character specified in the third argument This function should not be used for retrieving queryvariant data
LookupDataMapping
Generate a lookup list of values for a datamapping entity
LookupDescription
Returns the value of a description field for a given ID in any lookup table
LookupID
Returns the value of an ID field for a given description or name in any lookup table
LookupQueryCSV
Execute a query and return its data as a CSV string. In general this is used for queries that return a single field. The values of the first field on each record are concatenated into a CSV string
LookupQueryXML
Execute a query and return its data as a XML string. The values of each field on each record are concatenated into a XML string, each XML node under the document represents a record, and each XML node under each record represents a field
MainMenuCategoryXML
Generate XML for table MainMenuCategory
MainMenuGroupXML
Generate XML for table MainMenuGroup
MainMenuXML
Generate XML for table MainMenu
NominalCodeXML
Generate XML for table NominalCode
NominalGroupXML
Generate XML for table NominalGroup
ObjectPermissionsXML
Generate XML for table ObjectPermissions
PeriodicityXML
Generate XML for table Periodicity
ProblemXML
Generate XML for table Problem
ProductClassXML
Generate XML for table ProductClass
ProductFamilyXML
Generate XML for table ProductFamily
ProductMigrationXML
Generate XML for table ProductMigration
ProductSuiteXML
Generate XML for table ProductSuite
ProductTypeXML
Generate XML for table ProductType
PurchaseOrderStatusXML
Generate XML for table PurchaseOrderStatus
PurchaseOrderXML
Generate XML for table PurchaseOrder
SavedSelectFieldXML
Generate XML for table SavedSelectField
SavedSelectXML
Generate XML for table SavedSelect
ServiceIntervalUnitsXML
Generate XML for table ServiceIntervalUnits
ServicePriorityXML
Generate XML for table ServicePriority
ServiceStatusXML
Generate XML for table ServiceStatus
ServiceTypeXML
Generate XML for table ServiceType
SetOfCompaniesXML
Generate XML for table SetOfCompanies
SpecialOptionXML
Generate XML for table SpecialOption
SpecificationTypeXML
Generate XML for table SpecificationType
SpecificationXML
Generate XML for table Specification
StatusXML
Generate XML for table Status
SupplierXML
Generate XML for table Supplier
TransactionTypePostRuleXML
Generate XML for table TransactionTypePostRule
TransactionTypeXML
Generate XML for table TransactionType
UserGroupXML
Generate XML for table UserGroup
UserOptionsXML
Generate XML for table UserOptions
UserSettingsXML
Generate XML for table UserSettings
VerificationTypeXML
Generate XML for table VerificationType
VerificationXML
Generate XML for table Verification
WorkCentreTypeXML
Generate XML for table WorkCentreType
WorkCentreXML
Generate XML for table WorkCentre

Index of Save Special Operations

SaveSpecial operations are specialized save methods called using the Restful API Interface Function named "SaveSpecial". SaveSpecial and Save operations are only available through the restful API from version 7.3.43 or later.

In order to save XML, which was retrieved from a table or API method, and then modified, use the WebSaveXML function.

SpecialAccountingProcess
Run a period end depreciation calculation, create journals and close a financial accounting period
SpecialAssetClone
Clone an Asset. This makes a "deep" copy of an asset record, such that all child information (specification data, devices, software, transactions, service plans, maintenance) is copied.
SpecialAssetMerge
Merge a list of assets into a single asset. A single asset is selected as the merge target, and the remaining assets in the list are merged onto it
SpecialAssetPOAdd
Add a list of asset records as line items to an existing purchase order
SpecialAssetPOApprove
Approve a list of purchase orders
SpecialAssetPOSetStatus
Set the status of multiple purchase orders in a single call
SpecialAssetSplit
Split one asset into many assets. sXML is ignored
SpecialAssetUpdate
Update any single-ID-keyed table in the data model, including the Asset table, with full support for coded business rules in the API layer
SpecialBarcodeAssign
Assign barcodes to a list of assets
SpecialBuildPCADeployment
Create the self extracting DiscoverMyPC and InstallDiscoverMyPC downloads
SpecialBulkDisposal
Dispose of or Transfer a list of assets
SpecialBulkUndispose
Undispose a list of Assets
SpecialBulkUpdate
Bulk update a list of assets with a single piece of Asset XML. This will update only fields with a value specified in the XML, if a field is blank in the XML or absent, it will not be updated in each Asset record.
SpecialDBTransformRun
Run a transformation. Transformations can perform any tasks including imports, exports, email notifications, data recognition and cleansing, integration to local systems and web services. Transformations can be run on a trigger, on a scheduled batch job or can be started by an application user from a menu item.
SpecialDeleteRecords
Delete a list of records from a xAssets table, with full respect for coded API business rules
SpecialFixAssetDependencies
For each asset which has dependencies in the system, this will self heal such that moves with parent fields are copied to each child asset
SpecialLogoffUser
Forcibly log one or more users off, thus freeing connections when the concurrent user licensing model is deployed
SpecialRecogniseSoftware
Recognise a table containing a block of software for recognition
SpecialReportCreate
Run any report into a PDF file, and return the path of the PDF file to the caller
SpecialResetUser
Reset a users permissions. This will execute all sql grant commands needed for the user to have operational access to the sql server database. Although rarely needed, there are situations where the users grants are lost by sql server, this restores the users account where a permission denied error message was raised.
SpecialRestartBatchProcessor
Restart the batch processor.
SpecialSaveSpecialOption
Save an option to the SpecialOption table
SpecialSetMenuGroup
Set the main menu group (profile) for the current user
SpecialTaskPOAdd
Add a list of task records as service cost items to an existing purchase order
SpecialUnlockUser
Unlock one or more locked-out users account

Index of API Interface Functions

The example programs provided include the most commonly used interface methods.

HelloWorld
A helper function to test that API connectivity is established
WebCommandProcessorArray
Execute an API command with arguments. Most commands either return a single value, or return a data table in the form of XML
WebLogon
Connect to an xAssets Instance with a Username and Password
WebLogonCollectionServer
Connect a discovery service to an xAssets Instance with a Username and Password
WebSaveSpecial
Execute a SaveSpecial method, optionally with XML data, into the xAssets database for your instance
WebSaveXML
Save XML data into the database Typically an API caller would retrieve data from a get function such as AssetXML, then load the xml string into an XML document object, then edit the data, and finally save the data using this method

Download the Visual Studio API Samples Project

© xAssets 2024 All rights reserved.