Fields
A field is one attribute an asset can carry: a hostname, an owner, an operating system, a recovery time objective. Each tenant has its own field dictionary, listed under Settings → Fields. The dictionary is shared by all asset types; the type decides which fields its layouts, columns and CSV template use, not which fields exist.
Every field has:
| Property | Meaning |
|---|---|
| Name | The display name used in lists, forms and the asset page |
| Key | The identifier used in searches (os:Ubuntu), the CSV template and the API. Derived from the name when the field is created, and fixed after that |
| Type | What kind of value it holds; see Field types. Fixed after creation |
| Status | Where the field comes from; see Field origins |
| Mandatory | An asset cannot be saved without a value |
| Multi value | The field holds a list rather than a single value |
| Placeholder | Ghost text in the empty input when someone edits an asset |
| Description | Shown as the field's tooltip on the asset page |
| Integration | The integration that contributed the field, if any |
Permissions
Reading the dictionary needs Fields Read. Creating, editing and deleting custom fields needs Fields Write. Editing a field's value on an asset is an asset change and needs Assets Write. See Roles and permissions.
The Fields screen
Settings → Fields lists every field the tenant has: the platform's own, those contributed by integrations, and the ones you add. The table shows Name, Type, Key, Status, Mandatory, Multi value, Description and Integration; Aggregation key, Placeholder and Id can be added from Columns.
Search by name, key or description, and filter by Field type and by Integration (choose No integration for the platform's and your own fields). The search, filters and page are kept in the page address, so a view can be linked.
Field origins
The Status column says where a field comes from, and that decides what you can do with it.
| Status | What it is | Value editable by hand | Definition editable or deletable |
|---|---|---|---|
| System | Core bookkeeping kept by the platform: Created, Updated, First Seen, Last Seen, Created by, Updated by, Detected By, Alive and similar | No | No |
| Standard | The platform's shared asset model: Names, OS, Private IP, Asset Owner, Criticality, the application register and licence fields, and so on | Yes | No |
| Integration | Contributed by an integration, usually with its own prefix (cs_*, nessus_*) | No | No |
| Custom | Created by your tenant on this screen | Yes | Yes |
| Scripted | Calculated when read, for example Private Ip Subnet, Subnet Assets Count, Owned Assets, Hosted Applications, Used By | No | No |
| Cached | Calculated from other fields and stored, for example Subnet Capacity, Subnet Min IP, Subnet Max Ip | No | No |
Only Custom fields can be edited or deleted. For any other field the console disables the controls and explains that the field is part of the platform's asset model.
"Value editable by hand" means on the asset page, in the create form, by bulk edit and in a CSV import. File fields are the exception: their values are files uploaded on the asset page, never typed.
Field types
| Type | Stores | Options (Arguments) |
|---|---|---|
| Text | A line of text | None |
| Integer | A whole number | None |
| Decimal | A number with a fractional part | None |
| Date | A calendar date, picked in your local time | None |
| Date & time | A date and time, picked in your local time | None |
| Text block | Multi-line text | None |
| Dropdown | One value from a fixed list | {"options": ["One", "Two"], "defaultValue": null}; a value outside the list is refused |
| Multi-select | Several values from a fixed list, always a list | {"options": ["One", "Two"], "defaultValue": null} |
| IP address | An IP address; anything else is refused | None |
| Team | People from the tenant's Users list, picked by name | None |
| File | Files uploaded on the asset page | {"allowedExtensions": ["pdf", "png"], "maxFileSizeBytes": 1048576}; with no extension list any extension is accepted; the size defaults to 1 MB and cannot exceed 10 MB |
| Boolean | Yes or no | None |
| Integration | One or more of the tenant's integration instances | None |
| Tags | A line of tags, always a list | {"minCount": 0, "maxCount": 100, "allowedTags": null}; with allowedTags set, only those tags can be used, otherwise any tag can be typed and tags already in use are suggested |
| Asset reference | Links to other assets | Chosen with Points at instead of JSON: Any asset or one asset type. A multi-value reference holds up to 100 assets, and every referenced asset must exist |
A single-value field holds one value. With Multi value ticked it holds a list, and the asset page shows one input per value with Add value. Multi-select and Tags are lists whatever Multi value says.
Team and Asset reference values link to the assets they name; a value whose asset has since been deleted is marked as such.
Creating a custom field
- Go to Settings → Fields and choose Add field.
- In Create new field, enter a Name (2 to 64 characters: letters,
digits, spaces,
_,-and.) and pick a Type. These are the only required choices. - Optionally add a Description and a Placeholder (each up to 500 characters), and tick Mandatory or Multi value.
- For an Asset reference, choose what it Points at. For other types
that take options, enter them as JSON in Arguments; the hint under the
box shows the keys the chosen type reads. Leave
{}when there are none. - Choose Create field. The console opens the new field's page.
The key is made from the name: lower case, with spaces turned into
underscores (Business owner becomes business_owner). A name whose key
already exists in the tenant is refused.
A tenant can hold up to 500 fields by default, counting the platform's, integrations' and your own; a deployment can change the limit per tenant. Only fields you add are refused at the limit. Fields the platform and integrations provision are always added.
A new field is empty on every asset. To use it, add it to a layout (so it appears on the asset page and in the create form) and fill it by hand, by bulk edit or by CSV import. The CSV template of every asset type includes all custom fields.
Editing and deleting a custom field
Open the field from the list. Under Details you can change the Name, Placeholder, Description, Mandatory, Multi value and Arguments, then Save changes. Properties shows what cannot change: Type, Status, Key, Integration, Version and Field id.
Changing the name does not change the key, so searches and layouts that use the field keep working. An Asset reference field can be widened from one asset type to Any asset, but not narrowed, since that would leave assets it already points at out of bounds.
To delete a custom field, choose Delete field on its page, or the delete action on its row in the Fields list, and confirm.
The field and the value every asset holds for it are removed, and the field is taken out of every layout that uses it. This cannot be undone.
How integrations fill fields
When an integration instance is added to a tenant, the integration's own fields are added to the dictionary (as Integration fields) if the tenant does not have them yet. Some integrations also add a tab to an asset type's detail layout; see Layouts.
Integrations then write values when they run as part of a scan. They write two kinds of field: their own prefixed fields, and the shared Standard fields (Names, OS, Private IP, MAC and so on) that correlation uses to recognise one machine across sources. Values arrive as change entries, and the scan template's action settings decide whether they are applied automatically or wait for approval. A scan template's mutator rules can also rewrite or drop field values before they reach the inventory.
A scan never changes a File field.
For the fields each integration writes, see its page in Integrations. For scan templates and mutator rules, see Scan templates.
See also
- Assets: searching on fields, columns, bulk edit and import
- Asset types: the fields each type uses
- Layouts: placing fields on the asset page and create form