Custom Attributes

Download this manual as a PDF file

This section describes how to view, add, and edit custom attributes for API resources.

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 of the menu options, click the Advanced menu icon ().

Custom Attributes for API Resources

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.

Viewing and Adding Custom Attributes

You can view information about the custom attributes for a resource by performing a GET request to one of the following resource indexes:

  • /custom_attribute/asset
  • /custom_attribute/device
  • /custom_attribute/interface
  • /custom_attribute/theme
  • /custom_attribute/vendor
  • /custom_attribute/_lookup. Allows for searching across all custom attributes for all entity types.

The "limit" option is required for all resource indexes for custom attributes.

Each resource custom attribute resource index returns a list of custom attributes including the URI for each custom attribute. URIs for custom attributes are in the following format:

/custom_attribute/<resource type>/<attribute name>

 

By default, no custom attributes are defined for any of the resources that support custom attributes.

To add a custom attribute for a resource, perform a POST request to either of the following URIs:

  • The corresponding /custom_attribute/resource resource index.
  • The URI of the custom attribute itself, i.e. /custom_attribute/resource/name.

The body of a POST request to an /custom_attribute/resource resource index must have the following JSON structure:

{

"name":"attribute name",

"label":"attribute label",

"type":"attribute type",

"index":"attribute index type",

"extended":"attribute extended option"

}

Or the following XML structure:

<custom_attribute>

<name>attribute name</name>

<label>attribute label</label>

<type>attribute type</type>

<index>attribute index type</index>

<extended>attribute extended option</extended>

</custom_attribute>

The body of a POST request to an /custom_attribute/resource/name resource must have the following JSON structure:

{

"label":"attribute label",

"type":"attribute type",

"index":"attribute index type",

"extended":"attribute extended option"

}

Or the following XML structure:

<custom_attribute>

<label>attribute label</label>

<type>attribute type</type>

<index>attribute index type</index>

<extended>attribute extended option</extended>

</custom_attribute>

You can request example JSON or XML content that must be posted to a /custom_attribute/resource/name resource by performing a GET request to the following URI: /custom_attribute/resource/_example.

Where attribute name, attribute label, attribute type, attribute index type, and attribute extended option are properties of the custom attribute you want to add. Attributes have the following properties:

  • name. The name 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 you attempt to create a custom attribute with a non-compliant name, the API will respond with a HTTP 400 Bad Request status.
  • label. A human-readable description of the attribute, up to 128 characters in length.

  • type. The data type of the custom attribute. You must specify one of the following two values in the type field:
    • integer. The custom attribute will be used to store signed 64-bit integer values.
    • string. The custom attribute will be used to store string values up to 512 characters in length.

  • index. You must specify one of the following three values in the index field:
    • index. When SL1 creates the database table that stores this custom attribute, the column that stores this value will be set as an index for the table. Setting index values can speed up queries performed on the database table, but does not affect which filter or search options will be available for this custom attribute.
    • unique. When SL1 creates the database table that stores this custom attribute, the column that stores this value will be set as a unique index for the table. The values defined for this custom attribute must be unique for all resources. For example, if you add a custom attribute called "c-external-id" to the /custom_attribute/device resource and define the index as unique, the value of "c-external-id" for a /device/device_id resource cannot be re-used for another /device/device_id resource. Setting index values can speed up queries performed on the database table, but does not affect which filter or search options will be available for this custom attribute.
    • none. When SL1 creates the database table that stores this custom attribute, the column that stores this value will not be set as an index or unique index.
  • extended. A boolean value. You must specify 0 or 1 in this field:
    • 0. The attribute is a "base" attribute. The attribute is displayed in the list of fields for all instances of the specified resource regardless of whether a value has been specified for the attribute.
    • 1. The attribute is an "extended" attribute. The attribute is displayed in the list of fields for an instance of the specified resource only if a value has been specified for the attribute.

When you add a custom attribute, the default value for all resources where that attribute is now defined is NULL.

Example of How to Add Custom Attributes

Suppose you are integrating SL1 with an external provisioning system and you want to include information from the external provisioning system in each device record to make searching for devices and generating reports easier. You could define the following two custom attributes:

  • An ID value from the external provisioning system
  • A name field from the external provisioning system

To add these custom attributes, you would perform two POST requests with the following JSON structures to the /custom_attribute/device resource to create the two custom attributes:

Request 1:

{

"name":"external-id",

"label":"ID from external provisioning system",

"type":"integer",

"index":"unique",

"extended":"0"

}

Request 2:

{

"name":"external-name",

"label":"Name from external provisioning system",

"type":"string",

"index":"none",

"extended":"0"

}

Each request specifies a custom attributes:

  • external_id. An integer value that will contain the ID value from the external provisioning system. The index field is set to unique because all ID values from the external provisioning system will be unique.
  • external_name. A string value that will contain the name from the external provisioning system.

The structures look like this in XML format:

Request 1:

<custom_attribute>

<name>external-id</name>

<label>ID from external provisioning system</label>

<type>integer</type>

<index>unique</index>

<extended>0</extended>

</custom_attribute>

Request 2:

<custom_attribute>

<name>external-name</name>

<label>Name from external provisioning system</label>

<type>string</type>

<index>none</index>

<extended>0</extended>

</custom_attribute>

Editing Custom Attributes

To edit a custom attribute, perform a POST request to the URI for that attribute. URIs for custom attributes are in the following format:

/custom_attribute/<resource type>/<attribute name>

The body of a POST request to a /custom_attribute/<resource type>/<attribute name> resource must have the following JSON structure:

{

"label":"attribute label",

"type":"attribute type",

"index":"attribute index type"

}

Or the following XML structure:

<custom_attribute>

<label>attribute label</label>

<type>attribute type</type>

<index>attribute index type</index>

</custom_attribute>

You cannot update the name or the extended option of a custom attribute.

Requests to Resources with Custom Attributes

When you define a custom attribute for a resource:

  • If the attribute is a "base" attribute, the attribute is displayed in the list of fields for all instances of the specified resource regardless of whether a value has been specified for the attribute.
  • If the attribute is an "extended" attribute, the attribute is displayed in the list of fields for an instance of the specified resource only if a value has been specified for the attribute.

To view or define custom attributes, you must prefix the attribute key with c-.

For example, if you created the "external_id" and "external_name" attributes described in the Example of How to Add Custom Attributes section, both of which are base attributes, the response to a GET request for a /device/device_id resource would look like this:

{

"name":"em7_ap",

"ip":"10.0.9.50",

"snmp_cred_id":"\/credential\/snmp\/1",

"snmp_w_cred_id":null,

"class_type":"\/device_class\/20036",

"organization":"\/organization\/0",

"auto_update":"1",

"event_suppress_mask":"00:10:00",

"auto_clear":"1",

"log_all":"1",

"daily_port_scan":"1",

"critical_ping":"0",

"scan_all_ips":"0",

"preserve_hostname":"1",

"disable_asset_update":"0",

"date_added":"1320183224",

"c-external-id":"",

"c-external-name":"",

"parent_device":null,

"child_devices":{

},

"state":0,

"notes":{

"URI":"\/device\/2\/note\/?hide_filterinfo=1&limit=1000",

"description":"Notes"

},

.

.

"app_credentials":{

"URI":"\/device\/2\/device_app_credentials",

"description":"Read-only lookup for aligned credentials and the device-aligned apps that are using them"

}

}

To define a value for a custom attribute for a specific instance of a resource, you can include the custom attribute when performing a POST request to that resource. For example, to define a value for the "external-id" attribute for the device with ID "3", you would POST to following JSON to the /device/3 resource:

{

"ip":"10.0.9.50",

"c-external-id":"4"

}

When you perform a GET request on a resource index, you can use custom attributes in filter and sort criteria. For example, if you want to perform a GET request on the /device resource index and want to sort the response by the external-id field, you would request the following URI:

/device?limit=100&order.c-external-id=ASC

If you want to perform a GET request on the /device resource index and want to filter the response to include only devices that contain the string "server" in the "external-name" field, you would request the following URI:

/device?limit=100&filter.c-external-name.contains=server

Removing Custom Attributes

To remove a custom attribute, perform a DELETE request to the URI for that attribute. URIs for custom attributes are in the following format:

/custom_attribute/<resource type>/<attribute name>

If you want to unalign a custom attribute for an interface, you can perform a PUT action and set the value to null(lowercase without quotes).