Entity fields resources

Use the entity fields resources of the dictionary service to override the default dictionary entries with your own definitions, create new entries for entity fields that are not included in the default dictionary, and manage custom entries.

Resources

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

Authentication

All Zenoss API endpoints require HTTPS, expect JSON in the request body when a body is required, and return a JSON response. You must have an authentication key to send requests to a Zenoss API endpoint. The key is sent in the zenoss-api-key header of each request.

All of the following API examples use curl to send a JSON request from a Bash shell to an endpoint. All examples use YOUR-API-ENDPOINT and YOUR-API-KEY as placeholders for endpoints and authentication keys.

Create an entry

POST /v1/dictionary/entity_fields

You can create a custom entity field entry in the Dictionary service. If the default dictionary includes an entry for the entity field name specified in a create request, the custom entry becomes the effective entry. Later, if you delete this custom entry, then the default entry becomes the effective entry.

Request template

A model of a JSON request to create one custom entity field entry.

{
  "name": "<name>",
  "label": "<label>",
  "description": "<description>",
  "tags": [ "<tag1>", "<tag2>" ]
}

Request body and response elements

RequestResponse

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

Name	Description
`layer`	`DEFAULT` for Zenoss-defined entries or `TENANT` for entries defined by a user in your organization.
`default`	If a custom entry overrides the default entry, then this value is the default value that was overridden. For the default entry or for a custom entry that doesn't override a default value, the value is `null`.

Status codes

200400401409

Custom entry was created.

No name provided.

Invalid request. Check that both your base URL and API Key are correct.

A custom entry with the same name already exists.

Example

RequestResponse

curl https://<YOUR-API-ENDPOINT>/v1/dictionary/entity_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 an entry

GET /v1/dictionary/entity_fields/{name}

Returns a single entity field entry. Enter the name of the entity field as part of the parameter query.

Request body and response elements

RequestResponse

None

Name	Type	Description
`name`	string	The entity field name.
`label`	string	A short name for an entity field.
`description`	string	A longer, free-form statement about an entity field.
`tags`	array	A list of arbitrary terms to associate with an entity field. The tags namespace is shared among all dictionary types. By convention, this field is used to record the source of an entry.
`layer`	-	`DEFAULT` for Zenoss-defined entries or `TENANT` for entries defined by a user in your organization.
`default`	-	If a custom entry overrides the default entry, then this value is the default value that was overridden. For the default entry or for a custom entry that doesn't override a default value, the value is `null`.

Status Codes

200401404

Entry exists for requested name.

Invalid request. Check that both your base URL and API Key are correct.

No entry exists for the requested name.

Examples

Default entry

RequestResponse

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

{
  "name": "source",
  "label": "Source",
  "description": "The system or process that created the entity. \n\nTypically this will be a fully-qualified hostname, or something that follows the same conventions. For example, mycollector1.example.com. If you expect multiple distinct processes on the same system to be sending events, the source could be additionally qualified by the process.",
  "tags": [
    "common"
  ],
  "layer": "DEFAULT",
  "default": null
}

Overridden entry

RequestResponse

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

{
  "name": "source",
  "label": "My Source",
  "description": "I changed this description from the default.",
  "tags": [
    "myorg"
  ],
  "layer": "TENANT",
  "default": {
    "name": "source",
    "label": "Source",
    "description": "The system or process that created the event.\n\nTypically this will be a fully-qualified hostname, or something that follows the same conventions. For example, mycollector1.example.com. If you expect multiple distinct processes on the same system to be sending events, the source could be additionally qualified by the process.",
    "tags": [
      "common"
    ],
    "layer": "DEFAULT",
    "default": null
  }
}

Custom entry

RequestResponse

curl https://<YOUR-API-ENDPOINT>/v1/dictionary/entity_fields/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 all entries

GET /v1/dictionary/entity_fields

Get all entity field entries, including all default entries, all overridden entries, and all custom entries.

Request body and response elements

RequestResponse

None

Name	Type	Description
`name`	string	The entity field name.
`label`	string	A short name for an entity field.
`description`	string	A longer, free-form statement about an entity field.
`tags`	array	A list of arbitrary terms to associate with an entity field. The tags namespace is shared among all dictionary types. By convention, this field is used to record the source of an entry.
`layer`	-	`DEFAULT` for Zenoss-defined entries or `TENANT` for entries defined by a user in your organization.
`default`	-	If a custom entry overrides the default entry, then this value is the default value that was overridden. For the default entry or for a custom entry that doesn't override a default value, the value is `null`.

Status Codes

200401

Entries exist.

Invalid request. Check that both your base URL and API Key are correct.

Example

RequestResponse (truncated)

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

{
  "entityFields": [
    {
      "name": "Source",
      "label": "Source",
      "description": "The system or process that created the entity.Typically this will be a fully-qualified hostname, or something that follows the same conventions. For example, mycollector1.example.com. If you expect multiple distinct processes on the same system to be sending entities, the source could be additionally qualified by the process.",
      "tags": [
        "cz",
        "common"
      ],
      "layer": "DEFAULT",
      "default": null
    },
    {
      "name": "Source-type",
      "label": "Source type",
      "description": "The type of system or process that created the entity. Entity ingest policy works based on the source-type field. If you want to be able to apply a specific policy to entities, you must be able to identify them by source-type.",
      "tags": [
        "cz",
        "common"
      ],
      "layer": "DEFAULT",
      "default": null
    },
    .
    .
    .
  ],
  "nextPageToken": "",
  "totalCount": "68"
}

Update an entry

PATCH /v1/dictionary/entity_fields/{name}

Update an existing custom entity field entry. For example, you might want to update a description. Enter the name of the entity field as part of the parameter query.

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

Request body and response elements

RequestResponse

Update requests use the same fields as create requests. The name field is required and can't be changed.

Name	Type	Description
`name`	string	The entity field name.
`label`	string	A short name for an entity field.
`description`	string	A longer, free-form statement about an entity field.
`tags`	array	A list of arbitrary terms to associate with an entity field. The tags namespace is shared among all dictionary types. By convention, this field is used to record the source of an entry.
`layer`	-	`DEFAULT` for Zenoss-defined entries or `TENANT` for entries defined by a user in your organization.
`default`	-	If a custom entry overrides the default entry, then this value is the default value that was overridden. For the default entry or for a custom entry that doesn't override a default value, the value is `null`.

Status Codes

200401404

Custom entry was updated.

Invalid request. Check that both your base URL and API Key are correct.

No custom entry exists with the requested name.

Example

RequestResponse

curl https://<YOUR-API-ENDPOINT>/v1/dictionary/entity_fields/psblusmk \
  -H "zenoss-api-key: <YOUR-API-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 an entry

DELETE /v1/dictionary/entity_fields/{name}

Delete a custom entity field entry. Enter the name of the entity field as part of the parameter query.

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

Status Codes

200400401

Custom entry was deleted.

No custom entry exists with the requested name.

Invalid request. Check that both your base URL and API Key are correct.

Example

RequestResponse

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

{}