TDX Asset Integration¶

This class contains all the methods that work with the TDX Asset API endpoints.

This class inherits the base TDX integration class.

Searching for Assets¶

Special Characters¶

Using the method search_assets() exposes a few undocumented features in TDX’s Web API. The primary one is some limited support for Regular Expressions in the SearchText parameter. This can be confusing because you may occasionally specify a Regex special character without realizing it.

For instance, you may use the following:

my_asset_integration_object.search_assets('K-')

This would be a pretty broad search anyway, but because of the way the TDX API interprets it, it actually includes all assets that have a “K” in their name or Serial number, or a number of other fields.

If to search for assets whose names or serial numbers begin with “K-”, use the following:

my_asset_integration_object.search_assets('^K-')

This search returns more what you would expect.

Normal searches with only alphanumerical characters work as expected.

Searching with Attributes¶

The following may be useful if you need to filter by a specific product type:

prodmod = my_asset_integration_object.get_all_product_models()

Then, set up a list for the models you actually want:

models = []

Then run a quick loop, appending to the list:

for mod in prodmod:
    if mod['ProductTypeName'] == "Desktop" or mod['ProductTypeName'] == "Laptop":
        models.append(mod['ID'])

Then use this info in a filter in search_assets()

criteria = {'ProductModelIDs': models}
assets = my_asset_integration_object.search_assets(criteria, max_results=1000)

Searching with Custom Attributes¶

If you’d like to search for assets that have a specific value for a custom attribute, you’ll need to do something similar:

ca = t.build_asset_custom_attribute_value("My CA Name", "My Value Name")
criteria = {'CustomAttributes': [ca]}
assets = my_asset_integration_object.search_assets(criteria, max_results=1000)

This will find all assets with the value “My Value Name” for the Custom Attribute “My CA Name”.

For more information check out the documentation on the AssetSearch object in TDX’s API docs

Custom Attributes¶

Custom Attributes are so useful in TeamDynamix and so difficult to understand in the API that it’s worth a section in the documentation dealing directly with them.

The simplest use case is to set a custom attribute to a certain value on an asset.

Set up your TDX Integration:

import tdxlib
t = tdxlib.tdxassetintegration.TdxAssetIntegration()

Set up your dict of updated values with CA and value that you would like to set. This command retrieves the CA ID and the ID of the choice you selected (if a choice variable) and formats it correctly for ingestion by TDX. If it is a non-choice field, it will simply include the second attribute as the value of the CA.

update = {'Attributes': [t.build_asset_custom_attribute_value("My CA Name", "My Value Name")]}

To add more attributes:

update['Attributes'].append(t.build_asset_custom_attribute_value("My Other CA Name", "My Other Value Name"))

Get the assets you want to update:

assets = t.search_assets("KIOSK")

Update the assets:

updated_assets = t.update_assets(assets, update)

Class & Methods¶

class tdxlib.tdx_asset_integration.TDXAssetIntegration(filename: str = None)¶

add_asset_user(asset_id: str, user_uid: str) → dict¶

Adds a users to an asset

Parameters:	asset_id – the ID of the asset to get users user_uid – the UID of the person to add
Returns:	the API response (success/failure only)

build_asset(asset_name: str, serial_number: str, status_name: str, location_name: str = None, room_name: str = None, asset_tag: str = None, acquisition_date: datetime.datetime = None, asset_lifespan_years: int = None, requester: str = None, requesting_dept: str = None, owner: str = None, owning_dept: str = None, parent: Union[int, str] = None, external_id: str = None, product_model: str = None, form: str = None, asset_custom_attributes: Union[list, dict] = None, supplier: str = None, replacement_date: datetime.datetime = None) → dict¶

Makes a correctly-formatted dict of asset attributes for inputting into create_asset() function

Parameters:	asset_name – a string containing the name for the asset serial_number – String with serial number of new asset status_name – String with name of status of new asset location_name – String with name of location for new asset (optional) room_name – String with name of room for new asset (optional, requires location_name) asset_tag – String with asset tag value for new asset (optional) acquisition_date – Datetime for Acquisition date (Default: date of execution) asset_lifespan_years – Number of years you expect this device to be in service (Default: None) requester – String with email of requester for new asset (Default: integration username) requesting_dept – Account Name of requesting department for new asset owner – String with Email of owner of new asset owning_dept – String with Account name of owning department parent – Int with ID or String with serial number of a parent asset. Parent Asset must already exist. external_id – String with external id for new asset (Default: serial Number) product_model – String with name of product model form – Name of the Asset form to use asset_custom_attributes – a dictionary of asset custom attribute values (or list from asset[‘Attributes’]) supplier – name of a TDX vendor to set as supplier (Default: manufacturer from product model) replacement_date – datetime object for expected replacement of asset (Default: set by asset_lifespan)
Returns:	dict usable in create_asset()
Return type:	dict

build_asset_custom_attribute_value(custom_attribute: Union[dict, str, int], value: Union[datetime.datetime, str, int]) → dict¶

Builds a custom attribute for an asset from the name of the attribute and value.

Parameters:	custom_attribute – name of custom attribute (or dict of info) value – name of value to set, or value to set to
Returns:	list of updated assets in dict format (for use in change_custom_attribute_value())

change_asset_custom_attribute_value(asset: Union[dict, str, int, list], custom_attributes: list) → list¶

Takes a correctly formatted list of CA’s (from build_asset_custom_attribute_value, for instance) and updates one or more assets with the new values.

Parameters:	asset – asset to update (doesn’t have to be full record), or list of same custom_attributes – List of ID/Value dicts (from build_asset_custom_attribute_value())
Returns:	list of updated assets in dict format

change_asset_location(asset: Union[dict, str, int, list], new_location, new_room=None)¶

Updates Location data in a list of assets

Parameters:	asset – asset to update (doesn’t have to be full record), or list of same new_location – name of new location, or dict of location data new_room – name of new room, or dict of room data
Returns:	list of the updated assets

change_asset_owner(asset: Union[dict, str, int, list], new_owner, new_dept=None) → list¶

Updates owner data in a list of assets

Parameters:	asset – asset to update (doesn’t have to be full record), or list of same new_owner – email or name of new owner, or dict of their information new_dept – name of new department, or dict of information
Returns:	list of the updated assets

change_asset_requesting_dept(asset: Union[dict, str, int, list], new_dept) → list¶

Updates Requesting Department data in a list of assets

Parameters:	asset – asset to update (doesn’t have to be full record), or list of same new_dept – name of new department
Returns:	list of the updated assets

clean_cache() → None¶: Internal method to refresh the cache in a tdxlib object.

clear_asset_custom_attributes(asset: Union[dict, str, int], attributes_to_clear: Union[str, list]) → dict¶

Takes a list of CA names and removes those custom attributes from the provided asset

Parameters:	asset – asset to update (doesn’t have to be full record) attributes_to_clear – List of names of custom attributes to remove
Returns:	the updated asset in dict format

copy_asset_attributes(source_asset: dict, target_asset: dict, copy_name: bool = False, exclude: list = None, new_status: str = None, new_name: str = None, is_full_source: bool = False)¶

Copies asset attributes from one asset to another. Does not include attributes like Serial Number, Asset Tag,: and other hardware-specific fields.

Parameters:

source_asset – asset to copy attributes from (doesn’t have to be full record)
target_asset – asset to copy attributes to (doesn’t have to full record) This asset will be OVERWRITTEN!
copy_name – Set to true to copy the name of the source asset to the target asset
exclude – List of attributes to be excluded, in addition to defaults
new_status – Name or ID of new status for source asset
new_name – New name for source asset (usually used with copy_name=True). Default: False
is_full_source – Boolean indicating whether source_asset is a full asset record or not. Default: False

Returns:

list of the target and source asset data

create_asset(asset: dict, check_duplicate: bool = True) → dict¶

Creates an asset

Parameters:	asset – a dict of asset info (maybe from make_asset_json()) to use in creation check_duplicate – boolean of whether we should check to see if this is a duplicate asset
Returns:	dict of created asset details

create_product_model(name: str, product_type: Union[str, dict], source: str, description: str = None, part_number: str = None, active: bool = True, attributes: dict = None) → dict¶

Creates a new Product Model with the information provided.

Parameters:

name – The name of the new product model
product_type – A Type (dict) or Type ID to set as the product type of this model
source – The manufacturer or vendor the model is sourced from
description – A description of the model (optional)
part_number – Part number for this model (optional)
active – Boolean indicating whether the new model should be active (optional, default True)
attributes – Dict of custom attributes to set on the new model (no validation yet – build this by hand)

Returns:

dict of created product type

create_product_type(name: str, description: str = None, parent=None, order: int = 1, active: bool = True) → dict¶

Creates a new Product Type with the information provided.

Parameters:	name – The name of the new product type description – A description of the type (optional) parent – A Type (dict) or Type ID to set as the parent type of this type (creates a subtype)(optional) order – Sort order for this type (optional, defaults to 1) active – Boolean indicating whether the new type should be active (optional, default True)
Returns:	dict of created product type

create_vendor(name: str, email: str = None, description: str = None, account_number: str = None, additional_info: dict = None, active=True) → dict¶

Creates a new Vendor with the information provided.

Parameters:

name – The name of the new product model
email – An email contact for the new vendor (optional)
description – A description of the model (optional)
account_number – An account number with the vendor (optional)
active – Boolean indicating whether the new vendor should be active (optional, default True)
additional_info – Dict of other info for the vendor (including CAs, no validation yet – build by hand)

Returns:

dict of created product type

delete_asset_users(asset_id: str, users: list)¶

Deletes specified users of an asset

Parameters:	asset_id – the ID of the asset to delete users from users – a list of the users (maybe from get_asset_users()) or user UIDs to delete
Returns:	list of this asset’s users, each represented by a dict

find_asset_by_sn(sn: str, full_record: bool = False, all_statuses: bool = True) → dict¶

Gets an asset based on its serial number

Parameters:	sn – serial number as a string full_record – boolean indicating whether to fetch the full Asset record, or just summary info all_statuses – gets assets, regardless of what their status is (default: True)
Returns:	the single asset with the corresponding serial number

find_asset_by_tag(tag: str, full_record: bool = False, all_statuses: bool = True) → dict¶

Gets an asset based on its asset tag

Parameters:	tag – asset tag as a string full_record – boolean indicating whether to fetch the full Asset record, or just summary info all_statuses – gets assets, regardless of what their status is (default: True)
Returns:	the single asset with the corresponding tag

get_all_asset_forms() → list¶

Gets a list asset forms

Returns:	list of form data

get_all_asset_statuses() → list¶

Gets a list asset statuses

Returns:	list of status data

get_all_product_models() → list¶

Gets a list asset models

Returns:	list of model data

get_all_product_models_of_type(product_type: Union[str, dict]) → list¶

Get all product models of a specific type

Parameters:	product_type – dict, name, or ID of a product type
Returns:	list of product models of that type

get_all_product_types() → list¶

Gets a list of all product types

Returns:	list of product type data

get_all_vendors() → list¶

Gets a list vendors

Returns:	list of vendor data

get_asset_by_id(asset_id: Union[str, int]) → dict¶

Gets a specfic asset object, including the full list of attributes.

Parameters:	asset_id – asset ID from TDX
Returns:	dict of asset data

get_asset_custom_attribute_by_name_id(key: str) → dict¶

Gets a specific Asset Custom Attribute object

Parameters:	key – name or id of the Custom Attribute. This must be the exact name, no partial searching.
Returns:	dict of custom attribute data

get_asset_custom_attribute_value_by_name(asset: Union[dict, str, int], key: str, id_only: bool = False) → str¶

Returns the current value of a specific CA in the specified asset

Parameters:	asset – asset to get CA value for, in dict or ID form key – Name or ID of CA to find in the asset id_only – (Default: False) Return the ID of the value, instead of ValueText (only for choice-based CA’s)
Returns:	a string representation of the value or ID

get_asset_form_by_name_id(key: str) → dict¶

Gets a specific asset form object

Parameters:	key – name of AssetForm to search for
Returns:	list of form data

get_asset_status_by_name_id(key: str) → dict¶

Gets a specific asset status object

Parameters:	key – name of an asset status to search for
Returns:	dict of status data

get_asset_users(asset_id: str) → list¶

Gets users of an asset

Parameters:	asset_id – the ID of the asset to get users
Returns:	list of this asset’s users, each represented by a dict

get_assets_by_location(location: Union[str, dict, list], max_results: int = 5000, full_record: bool = False, retired: bool = False, disposed: bool = False, all_statuses: bool = False) → list¶

Gets all assets in a location

Parameters:

location – a single location (from get_location_by_name()) or list of same
max_results – an integer indicating the maximum number of results that should be returned (default: 25)
full_record – boolean indicating whether to fetch the full Asset record, or just summary info
retired – include retired assets in search if true
disposed – include disposed assets in search if true
all_statuses – gets assets, regardless of what their status is (default: False)

Returns:

a list of assets in the location(s)

get_assets_by_owner(person: str, max_results: int = 25, full_record: bool = False, retired: bool = False, disposed: bool = False, all_statuses: bool = False) → list¶

Gets all assets owned by a particular person in TDX

Parameters:

person – the name or email of a person in TDX, or a dict containing their information
max_results – an integer indicating the maximum number of results that should be returned (default: 25)
full_record – boolean indicating whether to fetch the full Asset record, or just summary info
retired – include retired assets in search if true
disposed – include disposed assets in search if true
all_statuses – gets assets, regardless of what their status is (default: False)

Returns:

a list of assets owned by that person

get_assets_by_product_model(model: Union[dict, str, int], max_results: int = 25, full_record: bool = False, retired: bool = False, disposed: bool = False, all_statuses: bool = False) → list¶

Gets all assets of a certain product model

Parameters:

model – the name or ID of a product model, or a dict of same
max_results – an integer indicating the maximum number of results that should be returned (default: 25)
full_record – boolean indicating whether to fetch the full Asset record, or just summary info
retired – include retired assets in search if true
disposed – include disposed assets in search if true
all_statuses – gets assets, regardless of what their status is (default: False)

Returns:

a list of assets of the specified model

get_assets_by_product_type(product_type: Union[dict, str, int], max_results: int = 25, full_record: bool = False, retired: bool = False, disposed: bool = False, all_statuses: bool = False) → list¶

Gets all assets of a certain product type

Parameters:

product_type – the name or ID of a product type, or a dict of same
max_results – an integer indicating the maximum number of results that should be returned (default: 25)
full_record – boolean indicating whether to fetch the full Asset record, or just summary info
retired – include retired assets in search if true
disposed – include disposed assets in search if true
all_statuses – gets assets, regardless of what their status is (default: False)

Returns:

a list of assets of the specified type

get_assets_by_requesting_department(dept: Union[dict, str], max_results: int = 25, full_record: bool = False, retired: bool = False, disposed: bool = False, all_statuses: bool = False) → list¶

Gets all assets requested by a particular account/department in TDX

Parameters:

dept – the name or email of an account/department, or a dict containing its information
max_results – an integer indicating the maximum number of results that should be returned (default: 25)
full_record – boolean indicating whether to fetch the full Asset record, or just summary info
retired – include retired assets in search if true
disposed – include disposed assets in search if true
all_statuses – gets assets, regardless of what their status is (default: False)

Returns:

a list of assets requested by that department

get_assets_by_room(room: dict, max_results: int = 25, full_record: bool = False, retired: bool = False, disposed: bool = False, all_statuses: bool = False) → list¶

Gets all assets in a specific room in a location

Parameters:

room – a single room (from get_room_by_name())
max_results – an integer indicating the maximum number of results that should be returned (default: 25)
full_record – boolean indicating whether to fetch the full Asset record, or just summary info
retired – include retired assets in search if true
disposed – include disposed assets in search if true
all_statuses – gets assets, regardless of what their status is (default: False)

Returns:

a list of assets in the room

get_product_model_by_name_id(key: Union[str, int]) → dict¶

Gets a specific product model object

Parameters:	key – name of product model to search for
Returns:	dict of model data

get_product_type_by_name_id(key: str) → dict¶

Gets a specific product type object

Parameters:	key – name of product type to search for
Returns:	dict of product type data

get_vendor_by_name_id(key: str) → dict¶

Gets a specific vendor object

Parameters:	key – name or ID of vendor to search for
Returns:	dict of vendor data

make_call(url: str, action: str, post_body: dict = None) → Union[list, dict]¶

Makes an HTTP call using the Assets API information.

Parameters:	url – The URL (everything after assets/) to call action – The HTTP action (get, put, post, delete, patch) to perform. post_body – A python dict of the information to post, put, or patch. Not used for get/delete.
Returns:	the API response as a python dict or list

move_child_assets(source_asset: Union[dict, str, int], target_asset: Union[dict, str, int]) → list¶

Moves child assets from one parent asset to another

Parameters:	source_asset – asset (or asset ID) to move children from (doesn’t have to be full record) target_asset – asset (or asset ID) to move children to
Returns:	list of the updated assets

search_assets(criteria: Union[str, dict], max_results=25, retired=False, disposed=False, full_record=False, all_statuses: bool = False) → list¶

Searches for assets, based on criteria

Common criteria to put in dict: {‘SerialLike’: [List of Int], ‘SearchText’: [String], ‘StatusIDs’: [List of Int], ‘CustomAttributes’: [Dict of CA], ‘ParentIDs’: [List of Int]} (https://api.teamdynamix.com/TDWebApi/Home/type/TeamDynamix.Api.Assets.AssetSearch)

Parameters:

max_results – maximum number of results to return
criteria – a string or dict to search for tickets with. If a string, use as ‘SearchString’
retired – include retired assets in search if true (overridden if “StatusIDs” in criteria or all_statuses is set)
disposed – include disposed assets in search if true (overridden if “StatusIDs” in criteria or all_statuses is set)
full_record – get full asset record (Default: False). Takes more time, but returns full asset record(s)
all_statuses – gets assets, regardless of what their status is (default: False) (overridden if “StatusIDs” in criteria)

Returns:

list of asset info, or None if no assets found matching criteria. (by default, NOT FULL ASSET RECORDS, pass full_record=True to get full record)

search_product_types(search_string: str = '*', active: bool = True, root_only: bool = False, parent=None) → list¶

Searches product types by parent, text, or parent.

Parameters:	search_string – String to search by name/description active – Boolean, when true, searches only active product types root_only – Boolean, when true, limits search to only top-level product types parent – Name or ID of parent type. Limits search to children of that parent
Returns:	list of product types as dicts

update_assets(assets: Union[dict, str, int, list], changed_attributes: dict, clear_custom_attributes: bool = False) → list¶

Updates data in a list of assets

Parameters:	assets – a list of assets (maybe from search_assets()) or a single asset (only ID required) changed_attributes – a dict of attributes in the ticket to be changed clear_custom_attributes – (default: False) Indicates whether custom attributes not specified in the changed_attributes argument should be cleared
Returns:	list of updated assets

update_product_type(product_type: Union[str, dict], updated_values: dict) → dict¶

Updates an existing product type

Parameters:	product_type – Type (dict) or Type ID to edit updated_values – dict of values that should be changed
Returns:	dict of edited product type