See www.zabbix.com for the official Zabbix site.

Docs/specs/ZBXNEXT-1424

From Zabbix.org
Jump to: navigation, search

Zabbix API for Value Mappings

ZBXNEXT-1424

Status: v1.0

Owner: Ivo

Summary

Currently value mapping is handled only in frontend with plain functions and SQL queries. Zabbix should support value mapping via API methods.

Specification

Front-end changes

No frontend changes.

API changes

New API methods will be introduced:

  • valuemap.get
  • valuemap.create
  • valuemap.update
  • valuemap.delete

Methods create, update and delete should add an audit log record.

valuemap.get

Description

integer/array valuemap.get(object parameters)

The method allows to retrieve value maps according to the given parameters.

Parameters

(object) Parameters defining the desired output.

Parameter Type Description
valuemapids string/array Return only value maps with the given IDs.
selectMappings query Return the value mappings for current value map in the mappings property.
sortfield string/array Sort the result by the given properties.

Possible values are: valuemapid, name.

countOutput flag These parameters being common for all get methods are described in detail in the reference commentary page.
editable boolean
excludeSearch flag
filter object
limit integer
output query
preservekeys flag
search object
searchByAny boolean
searchWildcardsEnabled boolean
sortorder string/array
startSearch flag

Return values

  • (integer/array) Returns either:
    • an array of objects;
    • the count of retrieved objects, if the countOutput parameter has been used.
  • By default value map returns only ID and name (for example in item edit form Show value dropdown). In order to retrieve value mappings, selectMappings is used.
    • selectMappings returns an array of value and newvalue properties. Other invalid fields in selectMappings and fields that are not visible to user like "mappingid", "valuemapid" are removed from the result. In case there are no fields requested in selectMappings empty records are returned for each mapping;
    • selectMappings will also support "count" option and it will return mapping count for each value map.

Validation

  • valuemapids property should be validated and in case wrong IDs are passed and no such value maps exist, user should receive an error "No permissions to referred object or it does not exist!".
  • If the user is not super admin and editable property is present in the request, he will get an empty response.

Example 1

Get one value map with ID and name.

Request:

{
    "valuemapids": "2",
    "output": [
        "valuemapid",
        "name"
    ]
}

Output:

[
    {
        "valuemapid": "2",
        "name": "Host status"
    }
]

Example 2

Get two value maps with ID, name and mappings for each value map.

Request:

{
    "valuemapids": ["1", "2"],
    "output": [
        "valuemapid",
        "name"
    ],
    "selectMappings":[
        "value",
        "newvalue"
    ]
}

Output:

[
    {
        "valuemapid": "1",
        "name": "Service state",
        "mappings": [
            {
                "value": "0"
                "newvalue": "Down"
            },
            {
                "value": "1"
                "newvalue": "Up"
            }
        ]
    },
    {
        "valuemapid": "2",
        "name": "Host status",
        "mappings": [
            {
                "value": "0"
                "newvalue": "Up"
            },
            {
                "value": "2"
                "newvalue": "Unreachable"
            }
        ]
    }
]

valuemap.create

Description

object valuemap.create(object/array valuemaps)

This method allows to create new value mappings.

Parameters

(object/array) Value maps to create.

The method accepts value maps with following properties:

Parameter Type Description
name

(required)

string Name of the value map.
mappings

(required)

array Value mappings for current value map.

Each value mapping contains two properties:

  • value - original value
  • newvalue - value to which the original value is mapped to

Return values

  • (object) Returns an object containing the IDs of the created value maps under the valuemapids property. The order of the returned IDs matches the order of the passed value maps.
  • If the user is not super admin, he will get an error message: "Only super admins can create value mappings."

Validation

  • At least one value mapping should be present. This means that mappings property should be present and should have value and newvalue properties.
  • Properties, name and newvalue cannot be empty. value is allowed to be empty, since empty string can be mapped to something.
  • The fields name, value and newvalue have a limit of 64 characters (defined by DB).
  • Value map name must be unique. Each mapping inside one value map must have a unique value field.

Example 1

Create one value map with one mapping.

Request:

{
    "name": "My new value map",
    "mappings": [
        {
            "value": "0",
            "newvalue": "offline"
        }
    ]
}

Output:

{
    "valuemapids": [
        "4"
    ]
}

Example 2

Create two value maps. The first value map has two mappings and the second has one mapping.

Request:

[
    {
        "name": "Some status",
        "mappings": [
            {
                "value": "1",
                "newvalue": "Up"
            },
            {
                "value": "0",
                "newvalue": "Down"
            }
        ]
    },
    {
        "name": "Another status",
        "mappings": [
            {
                "value": "2",
                "newvalue": "Testing"
            }
        ]
    }
]

Output:

{
    "valuemapids": [
        "5",
        "6"
    ]
}

valuemap.update

Description

object valuemap.update(object/array valuemaps)

This method allows to update existing value maps.

Parameters

(object/array) value map properties to be updated.

The valuemapid property must be defined for each value map, all other properties are optional. Only the passed properties will be updated, all others will remain unchanged.

The method accepts value maps with following properties:

Parameter Type Description
valuemapid

(required)

integer ID of the value map.
name string Name of the value map.
mappings array Value mappings for current value map.

Each value mapping contains two properties:

  • value - value that will be mapped from
  • newvalue - new value to which old value is mapped to

Return values

  • (object) Returns an object containing the IDs of the updated value maps under the valuemapids property.
  • If the user is not super admin, he will get an error message: "Only super admins can update value mappings."

Validation

  • valuemapid property should be validated and in case wrong ID is passed and no such value map exists, user should receive an error "No permissions to referred object or it does not exist!".
  • If name property is set, it should be validated, it cannot be empty and it is limited to 64 characters (defined by DB). If name property is not set, it is unchanged.
  • If mappings property is set, it cannot be empty and each mapping should have value and newvalue properties. Property newvalue cannot be empty. value is allowed to be empty, since empty string can be mapped to something. If mappings property is not set, mappings stay unchanged.
  • The fields name, value and newvalue have a limit of 64 characters (defined by DB).
  • Value map name must be unique. Each mapping inside one value map must have a unique value field.

Example 1

Change the name of one value map.

Request:

{
    "valuemapid": "2",
    "name": "new name"
}

Output:

{
    "valuemapids": [
        "2"
    ]
}

Example 2

Change mappings for two value maps.

Request:

[
    {
        "valuemapid": "4",
        "mappings": [
            {
                "value": "3",
                "newvalue": "On"
            }
        ]
    },
    {
        "valuemapid": "5",
        "mappings": [
            {
                "value": "4",
                "newvalue": "Off"
            }
        ]
    }
]

Output:

{
    "valuemapids": [
        "4",
        "5"
    ]
}

valuemap.delete

Description

object valuemap.delete(array valuemapids)

This method allows to delete value maps.

Parameters

(array) IDs of the value maps to delete.

Return values

  • (object) Returns an object containing the IDs of the deleted value maps under the valuemapids property.
  • If the user is not super admin, he will get an error message: "Only super admins can delete value mappings."

Validation

IDs should be validated and in case wrong ID is passed and no such value map exists, user should receive an error "No permissions to referred object or it does not exist!".

Example

Delete two value maps.

Request:

[
    "2",
    "4"
}

Output:

{
    "valuemapids": [
        "2",
        "4"
    ]
}

Translation strings

Remove translation strings

  • Value map with valuemapid "%1$s" does not exist.

(it will be replaced by standart API message: No permissions to referred object or it does not exist!

Add new translation strings

  • Only super admins can create value mappings.
  • Only super admins can update value mappings.
  • Only super admins can delete value mappings.

Database changes

No database changes.

Documentation

Also discussed

  • Create and update methods have no limitations on the amount of mappings. The limit is only for get method.
  • get method should validate input and API should respond with error in case unsupported fields are requested - out of scope.

ChangeLog

N/A