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.

1
2
3
4
5

"keys": [
  "computer_id"
 ],

If you want to use more than one value as the key, separate them with a comma:

1
2
3
4
5

"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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
"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:

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.

1
2
3
4
5
6
7
8
{
 "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.

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "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.

1
2
3
4
5
6
7
8
9
{
  "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.

1
2
3
4
5
6
7
8
9
{
  "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:

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "properties": [
     {
        "name": "cpu_id",
        "value": 1234567
     },
     {
        "name": "number_of_cpus",
        "value": 4
     }
  ]
}
        

Field mapping:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "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.

1
2
3
4
5
6
7
8
{
  "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.

1
2
3
4
5
6
7
8
{
  "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.

1
2
3
4
5
6
7
8
9
10
11
{
  "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.

1
2
3
4
5
6
7
8
9
10
11
{
  "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.

1
2
3
4
5
6
7
8
9
10
{
 "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.

1
2
3
4
5
6
7
8
9
10
{
 "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.

1
2
3
4
5
6
7
8
9
10
{
  "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.

1
2
3
4
5
6
7
8
9
10
{
  "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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
 "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.

1
2
3
4
5
6
7
8
9
10
11
12
13
{
 "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.

1
2
3
4
5
6
7
8
{
  "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: