Using Custom Attributes

This section describes how to use custom attributes.

Use the following menu options to navigate the SL1 user interface:

To view a pop-out list of menu options, click the menu icon ().
To view a page containing all the menu options, click the Advanced menu icon ().

This section includes the following topics:

Custom Attributes

Custom Attributes are name-value pairs. You can use custom attributes to add custom descriptive fields to assets, devices, interfaces, services, themes, and vendors. In SL1, you can create and update custom attributes via the API, in configuration Dynamic Applications, and in the Custom Attribute Manager page. Custom attributes can be used to dynamically define device groups and can be viewed with the custom table widget.

There are two categories of custom attributes:

Base Custom Attributes. These custom attributes are applied to each member of an element type. For example, a base attribute for devices would be applied to all devices.
Extended Custom Attributes. These custom attributes are applied individually to one or more members of an element type. For example, you could apply the custom attribute cisco_ios_version only to those asset records for Cisco devices; you would not want to assign this custom attribute to all asset records.

Viewing the List of Custom Attributes

The Custom Attribute Manager page (Manage > Custom Attributes) displays a list of all the existing custom attributes created through the user interface:.

If you are looking for a very specific set of custom attributes, click the gear icon () to the right of the Search field and select Advanced. In this mode you can create an advanced search using "AND" or "OR" for multiple search criteria. For more information, see Performing an Advanced Search.

The same information is available on the classic Custom Attribute Manager page (System > Manage > Custom Attributes):

For each custom attribute, the Custom Attribute Manager page displays the following information:

Display Name. Name for the custom attribute. This value appears in the user interface.
Internal Field Name (classic only). Name for the custom attribute that complies with XML naming rules. If the value in the Display Name field does not comply with XML rules, SL1 will convert the value to a name that complies with XML rules. The Internal Field Name is the unique ID of each Custom Attribute, and you cannot change it after the custom attribute has been created.

Names for custom attributes must conform to XML naming standards. The attribute name can contain any combination of alphanumeric characters, a period, a dash, a combining character, or an extending character. If a value in the Display Name column does not conform to XML standards, SL1 will replace non-valid characters with an underscore plus the hexadecimal value of the illegal character plus an underscore. So "serial number" would be replaced with "serial_X20_number".

Value Type. Specifies the type of value that will be saved in the custom attribute. Choice are:

String. Non-numeric value
Integer. Numeric value

Attribute Type. Specifies the behavior of the custom attribute. Choices are:

Base. A base custom attribute is automatically aligned to all members of the specified Resource Type. For example, a base custom attribute for devices would be aligned with each and every device in your SL1 System.

Extended. An extended custom attribute is manually assigned only to some members of the Resource Type and should not be assigned to all members of the Resource Type. For example, you could apply the custom attribute cisco_ios_version only to those asset records for Cisco devices; you would not want to assign this custom attribute to all asset records.

Resource Type. Specifies the ScienceLogic element that will use the custom attribute. Choices are:

Asset. Custom attribute will be associated with one or more asset records.

Device. Custom attribute will be associated with one or more devices.
Interface. Custom attribute will be associated with one or more network interfaces.
Service. Custom attribute will be associated with one or more services.
Theme. Custom attribute will be associated with one or more user-interface themes.
Vendor. Custom attribute will be associated with one or more vendor records.

Database Index. Specifies how the custom attribute is stored in the ScienceLogic database. Choices are:

None. Custom attribute is not indexed.

Extended custom attributes allow only the value None in this field.

Unique. For base custom attributes, ensures that the value of each base custom attribute is unique within its Resource Type.
Index. For base custom attributes, allows SL1 to efficiently search for custom attributes in the ScienceLogic database.

Subscribers (classic user interface only). Specifies the Resource Type and number of subscribers. Possible values in this field include:

For base custom attributes, the value in the Subscribers column is always "- - " (dash dash).

(Asset). Custom attribute is associated with one or more asset records. Clicking on the icon displays the Custom Attribute Subscribers page, where you can view details about each subscriber of type Asset.

(Device). Custom attribute is associated with one or more devices. Clicking on the icon displays the Custom Attribute Subscribers page, where you can view details about each subscriber of type Device.
(Interface). Custom attribute is associated with one or more network interfaces. Clicking on the icon displays the Custom Attribute Subscribers page, where you can view details about each subscriber of type Interface.
(Theme). Custom attribute is associated with one or more user-interface themes. Clicking on the icon displays the Custom Attribute Subscribers page, where you can view details about each subscriber of type Theme.
(Vendor). Custom attribute is associated with one or more vendor records. Clicking on the icon displays the Custom Attribute Subscribers page, where you can view details about each subscriber of type Vendor.

Subscriber Count (SL1 user interface only). Lists the number of subscribers to this custom attribute.

Filtering the List of Custom Attributes

You can filter the list on the Custom Attribute Manager page by one or more parameters. Only attributes that meet all the filter criteria will be displayed in the Custom Attribute Manager page.

To filter by parameter, enter text into the desired filter-while-you-type field. The Custom Attribute Manager page searches for attributes that match the text, including partial matches. By default, the cursor is placed in the left-most filter-while-you-type field. You can use the <Tab> key or your mouse to move your cursor through the fields. The list is dynamically updated as you type. Text matches are not case-sensitive.

You can also use special characters to filter each parameter.

Filter by one or more of the following parameters:

Display Name. You can enter text to match, including special characters, and the Custom Attribute Manager page will display only custom attributes that have a matching display name.
Internal Field Name. You can enter text to match, including special characters, and the Custom Attribute Manager page will display only custom attributes that have a matching internal field name.
Value Type. You can enter text to match, including special characters, and the Custom Attribute Manager page will display only custom attributes that have a matching value type.
Resource Type. You can enter text to match, including special characters, and the Custom Attribute Manager page will display only custom attributes that have a matching resource type.
Attribute Type. You can enter text to match, including special characters, and the Custom Attribute Manager page will display only custom attributes that have a matching attribute type
Database Index. You can enter text to match, including special characters, and the Custom Attribute Manager page will display only custom attributes that have a matching database index.
Subscribers. You can enter text to match, including special characters, and the Custom Attribute Manager page will display only custom attributes that have a matching number of subscribers.

Viewing the List of Subscribers for a Custom Attribute

To view a list of subscribers for a custom attribute:

Go to the Custom Attribute Manager page (System > Manage > Custom Attributes) .
Click the icon in the Subscribers column.
The Custom Attribute Subscribers modal page appears.

For (Asset), the Custom Attribute Subscribers modal page displays the following for each subscriber:

Make. Make of the asset.

Model. Model of the asset.
Device. If applicable, name of the device associated with the asset record.
Asset Tag. Asset tag associated with the asset.
Name of the custom attribute. The value assigned to the custom attribute for this subscriber.

For (Device), the Custom Attribute Subscribers modal page displays the following for each subscriber:

DID. Device ID for the device. SL1 automatically assigns this value to the device.

Device Name. Name of the device.
IP Address. If applicable, the IP address associated with the device.
Name of the custom attribute. The value assigned to the custom attribute for this subscriber.

For (Interface), the Custom Attribute Subscribers modal page displays the following for each subscriber:

Device Name. Name of the device associated with the interface.

IF Name. Name of the interface.
IF Port. Port number associated with the interface.
Alias. Alias associated with the interface.
Name of the custom attribute. The value assigned to the custom attribute for this subscriber.

For (Theme), the Custom Attribute Subscribers modal page displays the following for each subscriber:

ID. Unique ID associated with the theme. SL1 automatically assigns this value to the theme.

Theme Name. Name of the theme.
HTML Header/Title. HTML header associated with the theme.
Name of the custom attribute. The value assigned to the custom attribute for this subscriber.

For (Vendor), the Custom Attribute Subscribers modal page displays the following for each subscriber:

ID. Unique ID associated with the vendor. SL1 automatically assigns this value to the vendor.

Vendor Name. Name of the vendor.
Name of the custom attribute. The value assigned to the custom attribute for this subscriber.

Creating Custom Attributes

You can create custom attributes on the Custom Attributes page (or on the Custom Attribute Manager page in the classic SL1 user interface), via the ScienceLogic API, or by using a configuration Dynamic Application. The following rules apply to the creation of custom attributes:

If you define a base custom attribute for devices on the Custom Attributes page (or on the Custom Attribute Manager page in the classic SL1 user interface), that base custom attribute is aligned with each device in your system. The value of the base custom attribute will be null until you assign a value for each device.
If you define an extended custom attribute for devices on the Custom Attributes page (or on the Custom Attribute Manager page in the classic SL1 user interface), that extended custom attribute is not aligned with any devices.
You can use the Attributes page in the Device Administration panel to assign a value or edit the value for each custom attribute aligned with a device. For more information, see the section on Managing a Single Device with the Device Administration Panel.
You can use Dynamic Applications of type "configuration" to create custom attributes and/or assign values to custom attributes for devices. For details, see the section on Using a Dynamic Application to Create and/or Populate Custom Attributes.
If you create a base custom attribute for asset records, network interfaces, themes, and vendor records, those custom attributes will appear in the ScienceLogic API for the specified entity. Initially, the value of the base attribute will be null. You cannot use the SL1 user interface to assign a value to these base custom attribute. You must use the ScienceLogic API to assign values to these base custom attribute. For details, see the section on Custom Attributes in the ScienceLogic API.
If you create an extended custom attribute for asset records, network interfaces, themes, and vendor records, those custom attributes can be aligned and populated using the ScienceLogic API. You cannot use the SL1 user interface to assign a value to these extended custom attributes. You must use the ScienceLogic API to assign values to these extended custom attributes. For details, see the section on Custom Attributes in the ScienceLogic API.
You can use an API call to “unsubscribe” interfaces from the extended custom attribute. For example:

curl -k -v -H 'X-em7-beautify-response:1' http://em7admin:em7admin@10.2.15.81/api/device/1/interface/1 -H 'content-type:application/json' -d '{"c-apple_ext_test":null}'

In this example the custom attribute is called apple_ext_test, and you need add c- at the start of the name in the API call to match how it is stored in the database. In the example above, the Device ID is 1, the Interface ID is also 1, and the Custom Attribute unique name or ID is c-apple_ext_test. This call sets the custom attribute to null, which unsubscribes the interface.

To create a custom attribute from the Custom Attribute Manager page:

Go to the Custom Attribute Manager page (System > Manage > Custom Attributes).

In the bottom-most row, enter a value in each field.
Click the Save icon ().

Deleting One or More Custom Attributes

From the Custom Attribute Manager page, you can delete custom attributes from SL1. To do this:

Go to the Custom Attribute Manager page (System > Manage > Custom Attributes).
Select the checkbox () for each custom attribute you want to delete.
Click the Select Action field in the lower-right and select DELETE Custom Attributes.
Click the Go button.

SL1 will not allow you to delete an extended custom attribute that is aligned with one or more subscribers. If you try to delete an extended custom attribute that is aligned with one or more subscribers, SL1 will display the error message: "Error: Some attributes have entities aligned. Unalign entity from attribute before deleting." This message appears to the right of the page title.

Adding Custom Attributes for a Device

You can view detailed data about a specific device by clicking the device name on the Devices page () to open the Device Investigator page for that device.

On the Attributes tab of the Device Investigator, you can view a list of list of custom attributes that are already aligned with that device, and you can also add and remove extended custom attributes for the device:

Before you can add a custom attribute to a device, you might need to create that custom attribute on the Custom Attribute Manager page (Manage > Custom Attributes) or on the classic Custom Attribute Manager page (System > Manage > Custom Attributes).

To add and edit custom attributes for a device on the Attributes tab:

On the Attributes tab for the device, click Edit and then click Align Attribute. The Align Extended Attribute window appears.
Complete the following fields:

Attributes. Select the name of the custom attribute.
Attribute value. Specify a text or numeric value for the attribute, based on its value type.

Click Align Attribute. The custom attribute is added to the list on the Attributes tab.
To edit an attribute in the list, click the Actions button () for that attribute and select Edit Attribute.
To unalign an attribute, click the Actions button () for that attribute and select Unalign Attribute.
When you are done adding, editing, or unaligning attributes, click Save.

Upon saving, your attribute changes will be reflected in the More Attributes section of the Info drop-down.

Adding Custom Attributes for a Device in the Classic SL1 User Interface

For information about how to add custom attributes for a device in the classic SL1 user interface, see the section on Aligning Custom Attributes with a Device.

Custom Attributes in the ScienceLogic API

The ScienceLogic API includes resources for adding custom attributes to the following resources:

/asset
/device
The /interface sub-resource under /device resources
/theme
/vendor

When you define a custom attribute for a resource:

For any instance of that resource (e.g., a specific device), you can perform a POST operation specifying a value for that attribute for that instance.
If you configure the attribute as a base attribute, the attribute will appear in the list of fields for all instances of that resource. For example, if you define a custom attribute as a base attribute for the /device resource, the response to a GET request for any /device/device_id resource includes the custom attribute in the list of fields.
If you configure the attribute as an extended attribute, the attribute will appear in the list of fields for instances of that resource only if a value has been specified for the attribute for that instance. For example, suppose you define a custom attribute as an extended attribute for the /device resource. The response to a GET request on the /device resource index with the extended_fetch option enabled will include the custom attribute only for devices that have a value for that custom attribute.
GET requests for the resource index can include filter and sort criteria that use that custom attribute.

When you define a value for a custom attribute by performing a POST request to a resource, the value is available through the API and can be used in dynamic rules for device groups and viewed in the custom table widget.

Using the ScienceLogic API to View, Create, and Edit Custom Attributes

You can use the ScienceLogic API to view, edit, and create custom attributes. For details on viewing, creating, and editing custom attributes, see the section on Using the ScienceLogic API.

Using a Dynamic Application to Create and/or Populate Custom Attributes

For details on creating aDynamic Application or creating collection objects, see the section on Dynamic Applications.

One of the ways you can create and/or populate a custom attribute for devices is through a Dynamic Application of type configuration.

In Dynamic Applications of archetype configuration, you can:

Use a collection object to populate the value of an existing custom attribute.
Use a pair of collection objects to create a custom attribute and provide a value for that custom attribute. You must define a collection object to define the name of the custom attribute; this causes the SL1 system to create a custom attribute with the name from the collection object. You must also define a second collection object to populate the value of the custom attribute.

For details on creating and managing custom attributes, see the section on custom attributes.

The following fields in the Collection Objects page allow you to use one or more collection objects to define and/or populate a custom attribute:

Align to Custom Attribute. Specify the custom attribute to associate with this collection object. The custom attribute will be populated with a value from a collection object. Choices are:

None. This collection object is not associated with a custom attribute.

Static. This collection object is associated with a specific custom attribute.

Static Name. If you selected Static in the Custom Attribute field, the Static Name field appears. In this field, specify the name of the custom attribute that you want to populate with the value of the collection object. You can select from a list of existing custom attributes.

If the list does not include the custom attribute you want to align with the collection, select the plus-sign icon (). The icon clears the field and allows you to manually enter a value.

If you manually specify a custom attribute, SL1 will search for a custom attribute with a matching name and populate the custom attribute with the value of this collection object. If SL1 does not find a custom attribute with a matching name and therefore creates the custom attribute, the new custom attribute will be an extended custom attribute, for devices. The data type will be integer (for numeric values) or string (for all other value types).

Dynamic Name. You can use a pair of collection objects to populate the name and value of a custom attribute. You must define each collection object separately. When you select Dynamic Name in the Custom Attribute field, the name of the custom attribute is populated with the value of the collection object. If SL1 does not find a custom attribute with a matching name, SL1 will create the custom attribute. If SL1 does not find a custom attribute with a matching name and therefore creates the custom attribute, the new custom attribute will be an extended custom attribute, for devices. The data type will be integer (for numeric values) or string (for all other value types).

If you select Dynamic Name in the Custom Attribute field, you must create a second collection object that will populate the value of the custom attribute.

Names for custom attributes must conform to XML naming standards. The attribute name can contain any combination of alphanumeric characters, a period, a dash, a combining character or an extending character. If a collected value for an attribute name does not conform to XML standards, SL1 will replace non-valid characters with an underscore + the hexadecimal value of the illegal character + an underscore. So "serial number" would be replaced with "serial_X20_number". The attribute label will use the original, non-converted value ("serial number").

Dynamic Value. The value of the custom attribute selected in the Dynamic Name field is populated with the value of the collection object.
Dynamic Name. If you selected Dynamic Value in the Custom Attribute field, the Dynamic Name field appears. Select from the list of collection objects that have a Custom Attribute value of Dynamic Name.

The collection object assigned to the Dynamic Value is added to the same Group as the collection object assigned to the associated Dynamic Name. If the collection object for Dynamic Name is not assigned to a Group, you will be prompted to select a Group for the both the collection object for Dynamic Name and the collection object for Dynamic Value.

Each group can contain only one collection object that is assigned to a Dynamic Value and only one collection object that is assigned to a Dynamic Name. The group can contain other collection objects, but should not contain more than one collection object assigned to a Dynamic Value and not more than one collection object assigned to a Dynamic Name.

Using Custom Attributes to Define Device Groups

A device group is a group of multiple devices, grouped together for ease of management. You can use custom attributes to define membership in a device group. Only devices that have a specific value for a custom attribute will be included in the device group.

You can add devices to a device group either explicitly or dynamically.

You can create static device groups, where you explicitly assign one or more devices to a device group.

You can create dynamic device groups, where you define rules for the device group. Each device that meets the criteria in the rule is automatically included in the device group. For example, suppose that you define a rule that specifies "include all devices in the System organization, with an IP address that starts with '10.100.100' ". SL1 would automatically assign all devices from the System organization with an IP of "10.100.100.*" to the new device group. When a new device is added to the System organization with an IP that begins with "10.100.100.*", that device will also be included in the device group. If a device with an IP that starts with "10.100.100" is removed from the System organization, that device will also be removed from the device group.

You can create a device group that includes both explicitly assigned devices and also includes a dynamic rule. This device group will include both the explicitly assigned devices and all devices that meet the criteria in the dynamic rule.

In the Device Group Rule Editor page, the Active Selectors field includes an entry for each custom attribute you have defined with the API or with a Dynamic Application. When you select a custom attribute, the Selector Definitions pane displays a field in which you can enter a string. SL1 will use the string to search for devices that have a matching value for this custom attribute.

In the example above, we selected the custom attribute Device:Color and specified the value red. Our device group will include only devices that ihave the value red assigned to the Device:Color custom attribute.

For additional details on defining device groups and defining device group rules, see the section on creating a device group.

Viewing Custom Attributes in the Custom Table Widget

A dashboard is a page that displays one or more graphical reports, called widgets. SL1 includes pre-defined widgets that can be customized and displayed in the Classic Dashboards page. These widgets are displayed in their own pane, and display graphs, tables, and/or text.

To define an instance of a widget, you first select from a list of pre-defined widget definitions, and then customize what will be displayed by the selected widget by supplying values in the option fields provided by that widget.

The Custom Table widget displays multiple instances of an entity in a table. The Custom Table widget can be configured to display a list of devices, device classes, or device groups (and also other entities).

The generated table displays information about each entity in the list. You can configure which information is included in the table in the Layout Editor pane during configuration.

The Layout Editor panel displays the columns that will be displayed in the widget.

In the example above, Color and Device Location are custom attributes for devices.

If you selected Device,or Asset, or Interface in the Entity Type field of the Custom Table Widget, the Layout Editor will include columns for the custom attributes defined in your system for that entity type.

By default, the columns for the custom attributes are excluded from the configuration.
If an extended custom attribute is defined in your system but has not been assigned a value for any asset, device, or interface, it will not appear in the list of columns.

You can add or remove custom attributes from the layout of the widget using the following buttons:

<|> You can move columns from left to right by clicking on the arrow characters at the top of each column and dragging the column left or right. Double-clicking on the arrow moves the column out of the display past a black bar to the right. All disabled columns can be seen to the right of the black bar. Double-clicking on the arrow again moves the column back into the display.

For additional details on configuring the Custom Table Widget, see the section on Dashboards.