This documentation includes content for releases that might not be available on-premises. For the latest on-premises Asset documentation, see the PDF version of Tanium™ Asset User Guide version 1.26.184.
Reference: Import API source field mappings
When you create an Import API source in Asset, you must map the fields from the source data to the corresponding field in the Asset database using JSON format. For more information about creating an Import API source, see Create an Import API source.
The Import API source provides an example field mapping, but you must replace this mapping with a mapping that corresponds to the fields in your source.
In the field mappings, the keys specify one or more values that determine a unique asset, which is system_uuid in the example mapping. When you specify the keys, use the attribute name in the Asset database as the value. Click the View Asset destination fields link in the Field Mappings section of the Create Custom Source page to see a list of the available fields. In the fieldMaps, the source field is the name of the field in the source API. The destination field is the column name in the Asset database. For Import API sources, refer to the documentation for the source API.
Use the Convert conversion library if you need to transform the source value into another value before it is inserted into the Asset database. For more information about these functions, see Convert functions.
Map source fields to Asset destination fields
Each field mapping must specify how to map attributes in the source (using the API for the configured source) to attributes in the Asset database (the destination). You must also specify the keys for assets, which are one or more attributes that uniquely define each asset.
Consider the data type when you map fields. In most cases, data is converted automatically to the appropriate data type before adding it to the Asset database. However, unexpected results can occur if the source data cannot be converted. For example, if you attempt to map a string field in the source with a value of Hello World to an integer field in the Asset database, results might not be as expected.
Keys
This definition sets the keys to use the computer_id value as the unique identifier for assets in this source.
"keys": [
"computer_id"
],
If you want to use more than one value as the key, separate them with a comma:
"keys": [
"computer_id", "os_platform"
],
Make sure that you specify a field mapping for each key.
Field mappings with no conversions or formatting
In the fieldMaps section, map the fields in the source to the corresponding fields in the Asset database using the source and destination name/value pairs.
Consider this example mapping:
{
"keys": [
"system_uuid"
],
"fieldMaps": [
{
"destination": "system_uuid",
"source": "deviceId"
},
{
"destination": "serial_number",
"source": "serialNumber"
},
{
"destination": "computer_name",
"source": "computerName"
},
]
In this example, the keys entry specifies system_uuid as the value that is unique to each asset. It then maps the deviceID field in the source to the system_uuid field in the Asset database. After defining the keys and associated field, it then maps these fields:
Attribute name in the source (source) | Attribute name in the Asset database (destination) |
---|---|
serialNumber | serial_number |
computerName | computer_name |
Convert functions
You can use the Convert functions to transform the data returned by the source API into another value before it is inserted into the Asset database when you customize the field mappings for custom sources. Each function contains the following name/value pairs:
Category
Every convert function must include the category with a value of Tanium: "category": "Tanium",
Name
Include a name/value pair that specifies the name of the function that you want to run: "name": "name of function",
Options
You must specify options for some functions, either as a string or Boolean. In the name/value pair, the name is the name of the option and the value is either a Boolean or a string: "option name": "boolean or string",
The following convert functions are available:
Integer
Function name: Integer
Options: none
Converts the value to a PostgreSQL Integer data type and ensures that the value is within the bounds of a valid PostgreSQL Integer (-2147483647 and 2147483647). In the following example, the value for the numProcessors field in the source to a PostgreSQL Integer data type before storing it in the number_of_logical_processor field in the Asset database.
{
"destination": "number_of_logical_processor",
"source": "numProcessors",
"convert": {
"category": "Tanium",
"name": "Integer"
},
}
Literal
Function name: Literal
Options: value, which specifies the value
Inserts a literal value into a field. The following example creates a new text field named custom_attribute, with the display name Custom Attribute, and the Literal conversion function to insert the value Sample Value into the custom_attribute field. For details on creating a new field in the Asset database, see Create a new field in the Asset database.
{
"source": "",
"destination": {
"fieldName": "custom_attribute",
"displayName": "Custom Attribute",
"type": "text"
},
"convert": {
"category": "Tanium",
"name": "Literal",
"value": "Sample Value"
}
}
Property
Function name: Property
Options: path, which specifies the array position or dot-notation path for the property to return from the provided object value.
Specify the array position or dot-notation path for a property to return from the specified object.
This example retrieves the first IP address from the list of lastKnownNetwork in the source and stores it in the ip_address field in the Asset database.
{
"destination": "ip_address",
"source": "lastKnownNetwork",
"convert": {
"category": "Tanium",
"name": "Property",
"path": "lastKnownNetwork[0].ipAddress"
},
}
This example retrieves the value using dot notation to the path in the recentUsers object in the source and stores it in the user_name field in the Asset database.
{
"destination": "user_name",
"source": "recentUsers",
"convert": {
"category": "Tanium",
"name": "Property",
"path": "login.email"
},
}
ObjectArray
Function name: ObjectArray
Options:
- keyField, which specifies the name of the key field for the object to return from the array.
- key, which specifies the key field value.
Specify the key and key field for the object to return from the array. The following example stores the value 4 in the cpu_processor
column:
Source data:
{
"properties": [
{
"name": "cpu_id",
"value": 1234567
},
{
"name": "number_of_cpus",
"value": 4
}
]
}
Field mapping:
{
"destination": "cpu_processor",
"source": "properties",
"convert" [
{
"category": "Tanium",
"name": "ObjectArray",
"keyField": "name",
"key": "number_of_cpus"
},
{
"category": "Tanium",
"name": "Property",
"path": "value",
}
]
}
Size
Function name: Size
Options: none
The size function returns the size of the provided value converted into bytes to normalize values across fields if the unit for the value is not known by Asset. For example, the string 3 is converted into the number 3072. The following example converts the value of the diskSpace field in the source into bytes before storing the value in the disk_total_space field in the Asset database.
{
"destination": "disk_total_space",
"source": "diskSpace",
"convert": {
"category": "Tanium",
"name": "Size"
},
}
Speed
Function name: Speed
Options: none
The Speed function returns the speed of the provided value converted into hertz to normalize values across fields if the unit is not known by Asset. For example, the string 3 is converted into the number 3000. The following example converts the value of the cpuInfo field in the source into hertz before storing the value in the cpu_speed field in the Asset database.
{
"destination": "cpu_speed",
"source": "cpuInfo",
"convert": {
"category": "Tanium",
"name": "Speed"
},
}
Text
The Text function provides several options to transform text from the source:
Function name: Text
Options: match, replace, append, prefix, lowercase, humanize
match and replace
The match and replace options must be used together. Matches a value based on a regular expression or string and replaces it with the specified value (either a regular expression or literal string).
The following example finds any string that matches the regular expression ([^\\s]+).* (anything other than a space character at the start of a string) in the value for model in the source and replaces the characters matched by the regular expression $1 (the matched text defined by the regex within the parenthesis) before inserting the value into the manufacturer field in the Asset database. For example, if the source provides the string value HP Envy, the value HP is stored in the manufacturer field in the Asset database.
{
"destination": "manufacturer",
"source": "model",
"convert":
{
"category": "Tanium",
"name": "Text",
"match": "([^\\s]+).*",
"replace": "$1"
},
}
The following example finds any string that matches , Corp. in the value for manufacturer in the source, clears the characters, and appends the characters , Inc. before inserting the value into the manufacturer field in the Asset database.
{
"destination": "company",
"source": "manufacturer",
"convert": {
"category": "MyCompany",
"name": "Text",
"match": ", Corp.",
"replace": "",
"append": ", Inc.",
},
},
append
Specify a string to append to the value. The following example appends " GB" to the value of ramInfo before inserting it into the ram field in the Asset database.
{
"destination": "ram",
"source": "ramInfo",
"convert":
{
"category": "Tanium",
"name": "Text",
"append": " GB"
},
}
prefix
Specify a string to prefix to the value. The following example prefixes "SN_" to the value of serialNumber before inserting it into the serial_number field in the Asset database.
{
"destination": "serial_number",
"source": "serialNumber",
"convert":
{
"category": "Tanium",
"name": "Text",
"prefix": "SN_"
},
}
lowerCase
Convert the value to lowercase. The following example converts the value for domainName to lowercase before inserting it into the domain_name field in the Asset database. Note the case for the function: lowerCase.
The Generate Preview panel does not render the preview in lowercase when this function is used.
{
"destination": "domain_name",
"source": "domainName",
"convert":
{
"category": "Tanium",
"name": "Text",
"lowerCase": true
},
}
Humanize
Convert the value to a human-readable format. For example, ComputerName is converted to Computer Name.
{
"destination": "serial_number",
"source": "serialNumber",
"convert":
{
"category": "Tanium",
"name": "Text",
"humanize": true
},
}
Using multiple conversion functions
Use an array to chain together more than one conversion function on a name/value pair, as shown in the following example:
{
"destination": "cpu_speed",
"source": "cpuInfo",
"convert": [
{
"category": "Tanium",
"name": "Property",
"path": "[0].maxClockSpeedKhz"
},
{
"category": "Tanium",
"name": "Text",
"append": "khz"
},
{
"category": "Tanium",
"name": "Speed"
}
]
},
This function gets the maxClockSpeedKhz property from the cpuInfo array in the source, adds a text string khz to that value, and then uses the Speed conversion function to normalize the data before it is inserted into the Asset database.
Create a new field in the Asset database
If you want to create a new field and insert a value in the Asset table, but there is no corresponding name/value pair in the source, leave the source entry empty. This scenario is the only time when the source should be left empty.
The following example creates a new text field in the Asset database named custom_attribute with the display name Custom Attribute and inserts the literal value Sample Value into that field.
{
"source": "",
"destination": {
"fieldName": "custom_attribute",
"displayName": "Custom Attribute",
"type": "text"
},
"convert": {
"category": "Tanium",
"name": "Literal"
"value": "Sample Value"
}
}
The following example maps the value of orgUnitPath in the source to a new text field in the Asset database named org_unit_path with the display name Org Unit Path.
{
"destination": {
"fieldName": "org_unit_path",
"displayName": "Org Unit Path",
"type": "text"
},
"source": "orgUnitPath"
},
Test field mappings
Click Test Mappings to validate the JSON in your field mappings.
Provide sample data to simulate input from the source in the Sample Data editor and then click Generate Preview to see the resulting data after the fields map and conversion functions are evaluated.
Asset data types
Fields in the Asset database must be one of the following data types:
Data type | Acceptable formats | Notes |
---|---|---|
bigint | Valid from -9223372036854775000 to 9223372036854775000 | |
boolean | 0/1, true/false, "true"/"false", and "yes"/"no" | |
datetime |
|
Datetime values are converted to UTC via the MomentJS library.
|
decimal | Float, Integer, String | |
duration | BigInt | Stored in total milliseconds as a BigInt (valid from -9223372036854775000 to 9223372036854775000) |
integer | Integer, String |
|
ipAddress | String | |
size | Acceptable unit values include the following, grouped by unit and preceded by an integer value (for example, 500gb):
|
Stored In total bytes as a BigInt (valid from -9223372036854775000 to 9223372036854775000) |
speed | Acceptable unit values include the following, grouped by unit and preceded by an integer value (for example, 100ghz):
|
Stored In total hertz as a BigInt (valid from -9223372036854775000 to 9223372036854775000) |
text | String |
Last updated: 9/22/2023 9:48 AM | Feedback