Config - Hashtag/Keyword

Object type: keyword

Note

Even though they are called hashtags in the UI and documentation, they are still referenced as keywords in the REST API.

Request URL: /rest/config/keyword

Permissions: Requires CONFIGUREKEYWORDS

Methods:

• GET — List hashtags.
• POST — Create hashtag.
• PUT — Update hashtag.
• DELETE — Unimplemented.

Example GET Copied

    {
       "object" : {
          "all_hosts" : "0",
          "all_servicechecks" : "0",
          "calculate_hard_states" : "0",
          "description" : "cisco devices",
          "enabled" : "1",
          "exclude_handled" : "0",
          "hosts" : [
             {
                "ref" : "/rest/config/host/7",
                "name" : "cisco"
             },
             {
                "ref" : "/rest/config/host/8",
                "name" : "cisco1"
             }
          ],
          "id" : "2",
          "individual_objects" : [
             {
                "attribute_value" : null,
                "host_id" : "7",
                "host_name" : "cisco",
                "id" : "13",
                "servicecheck_id" : "44",
                "servicecheck_name" : "Check Memory"
             },
             {
                "attribute_value" : null,
                "host_id" : "8",
                "host_name" : "cisco1",
                "id" : "16",
                "servicecheck_id" : "79",
                "servicecheck_name" : "Coldstart"
             },
             {
                "attribute_value" : null,
                "host_id" : "11",
                "host_name" : "cisco4",
                "id" : "17",
                "servicecheck_id" : "44",
                "servicecheck_name" : "Check Memory"
             },
             {
                "attribute_value" : "Ethernet0-12",
                "host_id" : "11",
                "host_name" : "cisco4",
                "id" : "22",
                "servicecheck_id" : "95",
                "servicecheck_name" : "Interface"
             }
          ],
          "interfaces": [
             {
                "add_to_keyword": "0",
                "use_discards": "1",
                "use_throughput": "1",
                "host_id": "7",
                "use_errors": "1",
                "interface_id": "16",
                "id": "13",
                "host_name": "cisco",
                "interface_name": "shouldnotbecreated"
             },
             {
                "host_name": "cisco4",
                "interface_name": "Ethernet0-01",
                "interface_id": "8",
                "use_errors": "1",
                "host_id": "11",
                "id": "1",
                "use_throughput": "1",
                "use_discards": "1",
                "add_to_keyword": "1"
             },
             {
                "use_discards": "1",
                "use_throughput": "1",
                "add_to_keyword": "1",
                "host_name": "cisco4",
                "interface_name": "Ethernet0-12",
                "host_id": "11",
                "use_errors": "1",
                "interface_id": "10",
                "id": "2"
             },
             {
                "use_discards": "1",
                "use_throughput": "1",
                "add_to_keyword": "1",
                "host_name": "cisco4",
                "interface_name": "Ethernet0-20",
                "interface_id": "12",
                "use_errors": "1",
                "host_id": "11",
                "id": "3"
             },
             {
                "interface_name": "EthernetWithAVeryLongAndSillyNameForPeopleToDiscussAboutUntilARipeOldAgeOf75AndAHalf0-06",
                "host_name": "cisco4",
                "interface_id": "15",
                "use_errors": "1",
                "host_id": "11",
                "id": "4",
                "use_discards": "1",
                "use_throughput": "1",
                "add_to_keyword": "1"
             }
          ],
          "name" : "cisco",
          "public" : "1",
          "roles" : [
             {
                "ref" : "/rest/config/role/14",
                "name" : "View some, change none"
             },
             {
                "ref" : "/rest/config/role/15",
                "name" : "View some, change none, no notify"
             }
          ],
          "servicechecks" : [
             {
                "ref" : "/rest/config/servicecheck/82",
                "name" : "Another exception"
             },
             {
                "ref" : "/rest/config/servicecheck/81",
                "name" : "Test exceptions"
             }
          ],
          "show_contextual_menus" : "0",
          "style" : "group_by_host",
          "uncommitted" : "1"
       }
    }

Fields:

• id — ID number for this hashtag.
• name — name of the hashtag.
• all_hosts — if set, then all hosts with the specified service checks will be included in the bulk tagging selection.
• all_servicechecks — if set, then all service checks on the specified hosts will be included in the bulk tagging selection.
• calculate_hard_states — if set, the hashtag summary status will be based on the hard states of the services, not the current state. It is possible that the hashtag will have a calculated state of OK but in an unhandled state.
• description — text to display in the hashtag detail view.
• enabled — if set, this hashtag will be included in the Hashtags Summary view.
• exclude_handled — if set, Opsview will exclude handled services from the calculation of the overall hashtag status. For example, with this setting enabled, a service in a handled CRITICAL state will be ignored. If this setting is disabled, the hashtag state will become CRITICAL.
• hosts — list of hosts specified in this hashtag for bulk tagging.
• individual_objects — returns an array of individually selected objects that will be associated with this hashtag. This column is not retrieved in a GET by default - add cols=+individual_objects in a GET request to include this column (with the + symbol URL encoded if required). The fields within each individual object:
  • id — unique ID for this individual object in this table.
  • host_id — ID of the host from the configuration database.
  • host_name — current host name for that host_id (from the configuration database, before an Apply Changes).
  • servicecheck_id — ID of the service check from the configuration database.
  • servicecheck_name — current name of the service check (from the configuration database, before an Apply Changes).
  • attribute_value — if the service check is a multi-servicecheck, this is the host variable value for that host service. Note that this value might not yet exist in the database or at runtime. It can be NULL, but it cannot be an empty string.
• interfaces — returns an array of host interfaces that can be associated with this hashtag. This column is not included in default GET requests. To retrieve it, add cols=+interfaces to your GET request (with the + symbol URL-encoded if required). Each interface object contains the following fields:
  • id — unique ID for this interface in this table.
  • host_id — ID of the host from the configuration database.
  • host_name — current host name for that host_id (from the configuration database, before an Apply Changes).
  • interface_id — ID of the host interface from the configuration database.
  • interface_name — host interface name for that interface_id (from the configuration database, before an Apply Changes).
  • add_to_keyword — if set, assigns the host interface and its selected service checks to the hashtag.
  • use_throughput — if set, assigns the host interface’s Interface service check to the hashtag.
  • use_errors — if set, assigns the host interface’s Errors service check to the hashtag.
  • use_discards — if set, assigns the host interface’s Discards service check to the hashtag.
• public — if set, this hashtag is visible to users in the Hashtags Summary View even if their permission does not include this hashtag.
• roles — list of roles that have permission to see this hashtag.
• servicechecks — list of service checks specified in this hashtag for bulk tagging.
• show_contextual_menus — deprecated.
• style — deprecated.
• uncommitted — if set, you need to run Apply Changes to make any changes live.

Example POST/PUT Copied

    {
       "all_hosts" : "0",
       "all_servicechecks" : "0",
       "calculate_hard_states" : "0",
       "description" : "cisco devices",
       "enabled" : "1",
       "exclude_handled" : "0",
       "hosts" : [ 7, 8 ],
       "id" : "2",
       "individual_objects" : [
          {
             "attribute_value" : null,
             "host_name" : "cisco",
             "id" : "13",
             "servicecheck_name" : "Check Memory"
          },
          {
             "attribute_value" : "/",
             "host_name" : "opsview",
             "id" : "0",
             "servicecheck_name" : "Disk"
          },
          {
             "attribute_value" : "Ethernet0-12",
             "host_name" : "cisco4",
             "id" : "22",
             "servicecheck_name" : "Interface"
          }
       ],
       "interfaces": [
             {
                "id": "13",
                "host_name": "cisco",
                "interface_name": "eth0"
                "add_to_keyword": "1",
                "use_throughput": "1",
                "use_errors": "1",
                "use_discards": "1",
             },
             {
                "id": "0",
                "host_name": "cisco2",
                "interface_name": "lo"
                "add_to_keyword": "1",
                "use_throughput": "1",
                "use_errors": "1",
                "use_discards": "1",
             },
          ],
       "name" : "cisco",
       "public" : "1",
       "roles" : [ 14, 15 ],
       "servicechecks" : [ 82, 81 ],
       "show_contextual_menus" : "0",
       "style" : "group_by_host",
       "uncommitted" : "1"
    }

individual_objects Copied

The input for this field is expected to be an array of objects. The logic for creating is:

• For each individual object:
  • If an ID is specified and already exists for this hashtag, all other fields are assumed to have the same values as those in the database, and the rest of the object is ignored.
  • If an ID is not specified, or is 0, it is considered a new individual object. The system searches for host_id and servicecheck_id in the current configuration database based on the input host_name and servicecheck_name. If either is not found, then the individual object is ignored. This means there is a potential race condition if a host name is changed while editing this object or if a host has been renamed in the configuration database but Apply Changes has not been run yet.
  • If an attribute_value is specified and it is either null or an empty string, it will be saved as null.
• Any objects currently associated with this hashtag that are not listed in this call will be removed.

interfaces Copied

The expected input for this field is an array of objects. The logic for creating is:

• Interfaces must exist in their corresponding hosts and be selected for monitoring (active = 1) in the configuration database before making a POST or PUT request with interfaces included.
• For each interface:
  • If an interface ID is specified and already exists for the hashtag, all other fields are assumed to be the same as the current database values, and the rest of the object is ignored. However, a PUT request with new values for add_to_keyword, use_throughput, use_errors, and use_discards will update those fields for the specified ID.
  • If an ID is not specified, or is 0, it is considered a new hashtag interface. The system searches for host_id and interface_id in the current configuration database based on the input host_name and interface_name. If either is not found, then the interface is ignored.
  • The add_to_keyword, use_throughput, use_errors, and use_discards fields are binary integers (either 0 or 1). If not specified, they default to 1.
• Any interfaces currently associated with the hashtag that are not listed in this request will be removed.