Event fields resources

The event fields resources of the dictionary service enable overriding default dictionary entries with your own definitions, creating new entries for event fields not included in the default dictionary, and managing custom entries.

Resource list

• Create an entry (POST /v1/dictionary/event_fields)
• Get one entry (GET /v1/dictionary/event_fields/{name})
• Get all entries (GET /v1/dictionary/event_fields)
• Update an entry (PATCH /v1/dictionary/event_fields/{name})
• Delete an entry (DELETE /v1/dictionary/event_fields/{name})

POST /v1/dictionary/event_fields

Creates a custom entry.

If the default dictionary includes an entry for the event field name specified in a create request, the custom entry becomes the effective entry. Subsequently, if the custom entry is deleted, the default entry becomes the effective entry.

Fields

The name field is required; all other fields are optional.

Field	Description
name	The event field name (required).
label	A display name for an event field.
description	A longer, free-form statement about an event field.
tags	A list of arbitrary terms to associate with an event field. The tags namespace is shared among all dictionary types. By convention, this field is used to record the source of an entry.

Status Codes

• 200 (custom entry was created)
• 400 (no name provided)
• 409 (a custom entry by the same name already exists)

Example

RequestResponse

curl https://YOUR-API-ENDPOINT/v1/dictionary/event_fields \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X POST -s \
  -d '{
  "name": "psblusmk",
  "label": "Power Supply Blue Smoke",
  "description": "The power supply has released its last gasp of blue smoke.",
  "tags": [
    "hardware",
    "failure"
  ]
}'

{
  "name": "psblusmk",
  "label": "Power Supply Blue Smoke",
  "description": "The power supply has released its last gasp of blue smoke.",
  "tags": [
    "hardware",
    "failure"
  ],
  "layer": "TENANT",
  "default": null
}

GET /v1/dictionary/event_fields/{name}

Get one entry.

Fields

Responses include the fields in the following table.

Field	Description
layer	DEFAULT for Zenoss-defined entries or TENANT for entries defined by a user in your organization.
default	null for Zenoss-defined entries or an object containing the default value of a Zenoss-defined entry that has been overridden by a user in your organization.

Status Codes

• 200 (entry exists for requested name)
• 404 (no entry exists for requested name)

Examples

Default entry

RequestResponse

curl https://YOUR-API-ENDPOINT/v1/dictionary/metrics/CZ_EVENT_DETAIL-zenoss.device.groups \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X GET -s

{
  "name": "CZ_EVENT_DETAIL-zenoss.device.groups",
  "label": "Device Groups",
  "description": "Device groups of the event's device.",
  "tags": [
    "cz"
  ],
  "layer": "DEFAULT",
  "default": null
}

Overridden entry

RequestResponse

curl https://YOUR-API-ENDPOINT/v1/dictionary/metrics/CZ_EVENT_DETAIL-zenoss.device.groups \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X GET -s

{
  "name": "CZ_EVENT_DETAIL-zenoss.device.groups",
  "label": "CZ Device Groups",
  "description": "Device groups of the event's device.",
  "tags": [
    "cz"
  ],
  "layer": "TENANT",
  "default": {
    "name": "CZ_EVENT_DETAIL-zenoss.device.groups",
    "label": "Device Groups",
    "description": "Device groups of the event's device.",
    "tags": [
      "cz"
    ],
    "layer": "DEFAULT",
    "default": null
  }
}

Custom entry

RequestResponse

curl https://YOUR-API-ENDPOINT/v1/dictionary/metrics/psblusmk \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X GET -s

{
  "name": "psblusmk",
  "label": "Power Supply Blue Smoke",
  "description": "The power supply has released its last gasp of blue smoke.",
  "tags": [
    "hardware",
    "failure"
  ],
  "layer": "TENANT",
  "default": null
}

GET /v1/dictionary/event_fields

Gets all entries. This includes all default entries, all overridden entries, and all custom entries.

Fields

Responses include the fields in the following table.

Field	Description
layer	DEFAULT for Zenoss-defined entries or TENANT for entries defined by a user in your organization.
default	null for Zenoss-defined entries or an object containing the default value of a Zenoss-defined entry that has been overridden by a user in your organization.

Status Codes

• 200 (entries exist)

Example

RequestResponse (truncated)

curl https://YOUR-API-ENDPOINT/v1/dictionary/event_fields \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X GET -s

{
  "eventFields": [
    {
      "name": "CZ_EVENT_DETAIL-capacity.breach",
      "label": "Capacity Breach Type",
      "description": "The type of capacity breach being reported by the event.\n\nPossible values include current or projected. Current indicates that the defined capacity threshold is currently breached, and projected indicates that it is projected to be breached. When the type is projected you can use the Capacity Breach Timestamp, Capacity Breach At, or Capacity Breach In fields to know when breach is projected to occur.",
      "tags": [
        "cz",
        "capacity"
      ],
      "layer": "DEFAULT",
      "default": null
    },
    {
      "name": "CZ_EVENT_DETAIL-capacity.breach_at",
      "label": "Capacity Breach At",
      "description": "Formatted timestamp for when the capacity threshold is projected to be breached.",
      "tags": [
        "cz",
        "capacity"
      ],
      "layer": "DEFAULT",
      "default": null
    },
    .
    .
    .
  ],
  "nextPageToken": "",
  "totalCount": "68"
}

PATCH /v1/dictionary/event_fields/{name}

Updates fields of an existing custom entry.

To override a default entry, create a new custom entry.

Fields

The name field is required but cannot be changed. The fields you specify replace the existing fields.

Field	Description
name	The event field name (required).
label	A display name for an event field.
description	A longer, free-form statement about an event field.
tags	A list of arbitrary terms to associate with an event field. The tags namespace is shared among all dictionary types. By convention, this field is used to record the source of an entry.

Status Codes

• 200 (custom entry was updated)
• 404 (no custom entry exists with the requested name)

Example

RequestResponse

curl https://api-zing-preview.zenoss.io/v1/dictionary/event_fields/psblusmk \
  -H "zenoss-api-key:  $(cat $HOME/.qapreview-key)" \
  -X PATCH -s -d '{
  "name": "psblusmk",
  "description": "The power supply has released its last gasp of blue smoke. RIP good buddy."
}'

{
  "name": "psblusmk",
  "label": "Power Supply Blue Smoke",
  "description": "The power supply has released its last gasp of blue smoke. RIP good buddy.",
  "tags": [
    "hardware",
    "failure"
  ],
  "layer": "TENANT",
  "default": null
}

DELETE /v1/dictionary/event_fields/{name}

Deletes a custom entry.

If a default entry exists for the specified name, the default entry becomes the effective entry.

Status Codes

• 200 (custom entry was deleted)
• 404 (no custom entry exists with the requested name)

Example

RequestResponse

curl https://YOUR-API-ENDPOINT/v1/dictionary/metrics/psblusmk \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X DELETE -s

{}