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 Virtana Service Observability 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 Virtana Service Observability 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

Request elements

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.

Response elements

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 Virtana-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

Code	Description
200	Success. The request was processed. Check the response body for per-item results when processing multiple objects.
400	Bad request. The request body is missing, malformed, or contains invalid values.
401	Unauthorized. The API key is missing or invalid.
409	Conflict. The request conflicts with the current state of the resource.

Example

Request example

 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"
  ]
}'

Response example

 {
  "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

Request body

None.

Response elements

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 Virtana-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

Code	Description
200	Success. The request was processed. Check the response body for per-item results when processing multiple objects.
401	Unauthorized. The API key is missing or invalid.
404	Not found. The specified resource does not exist.

Examples

Default entry

Request example

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

Response example

 {
  "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

Request example

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

Response example

 {
  "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

Request example

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

Response example

 {
  "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

Request body

None.

Response elements

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 Virtana-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

Code	Description
200	Success. The request was processed. Check the response body for per-item results when processing multiple objects.
401	Unauthorized. The API key is missing or invalid.

Example

Request example

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

Response example

 {
  "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
    },
    .
    .
    .
  ]
}

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

Request body

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

Response elements

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 Virtana-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

Code	Description
200	Success. The request was processed. Check the response body for per-item results when processing multiple objects.
401	Unauthorized. The API key is missing or invalid.
404	Not found. The specified resource does not exist.

Example

Request example

 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."
}'

Response example

 {
  "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

Code	Description
200	Success. The request was processed. Check the response body for per-item results when processing multiple objects.
400	Bad request. The request body is missing, malformed, or contains invalid values.
401	Unauthorized. The API key is missing or invalid.

Example

Request example

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

Response example

{}

In this section:

Entity fields resources

Resources

Authentication

Create an entry

Request template

Request body and response elements

Status codes

Example

Get an entry

Request body and response elements

Status codes

Examples

Default entry

Overridden entry

Custom entry

Get all entries

Request body and response elements

Status codes

Example

Update an entry

Request body and response elements

Status codes

Example

Delete an entry

Status codes

Example

Search results