Zum Inhalt

Namespace cmdb.category#

Zum lesen oder editieren einer Kategorie.

cmdb.category.create#

This method is deprecated and will be removed in a feature release. Use cmdb.category.save instead.

Create a new category entry

Request parameters#

Key JSON data type Required Description
objID Integer Yes Object identifier, for example: 42
category String Yes Category constant, for example: C__CATG__MODEL
data Object Yes Attributes with their values, for example:
{ "manufacturer": "Name of manufacturer", "title": "Name of model" }

Response parameters#

JSON key result contains a JSON object.

Key JSON data type Description
id String Entry identifier (as numeric string)
message String Some information
success Boolean Should always be true

Example#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
"version": "2.0",
"method": "cmdb.category.create",
"params": {
    "objID": 42,
    "data": {
        "manufacturer": "Name of manufacturer",
        "title": "Name of model"
    },
    "category": "C__CATG__MODEL",
    "apikey": "xxx",
    "language": "en"
},
"id": 1
}

1
2
3
4
5
6
7
8
9
{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "id": "123",
    "message": "Category entry successfully created. [This method is deprecated and will be removed in a feature release. Use 'cmdb.category.save' instead.]",
    "success": true
  }
}

cmdb.category.read#

Read one or more category entries for an object

Request parameters#

Key JSON data type Required Description
objID Integer Yes Object identifier, for example: 42
category String Yes Category constant, for example: "C__CATG__MODEL"
status Integer Yes ID of the status, for example 2 for normal
If the status parameter is not specified, the status must be set to 2 (normal). This corresponds to the previous behavior.

Response parameters#

JSON key result contains an array of JSON objects. Each object contains all available attributes for the requested category.

Even if it is a single-value category or a multi-value category with only 1 entry, the JSON key result contains always an array of JSON objects.

Key JSON data type Description
id String Entry identifier (as numeric string)
objID String Object identifier (as numeric string)
… Mixed Optional attributes with values depending on requested category

Example#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
"version": "2.0",
"method": "cmdb.category.read",
"params": {
    "objID": 1000,
    "category": "C__CATG__MODEL",
    "apikey": "xxx",
    "language": "en"
},
"id": 1
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
  "id": 1,
  "jsonrpc": "2.0",
  "result": [
    {
      "id": "74",
      "objID": "1000",
      "manufacturer": {
        "id": "19",
        "title": "Lenovo",
        "const": null,
        "title_lang": "Lenovo"
      },
      "title": {
        "id": "38",
        "title": "ThinkPad R61",
        "const": null,
        "title_lang": "ThinkPad R61"
      },
      "productid": "",
      "service_tag": "WRT231",
      "serial": "123000999888",
      "firmware": "",
      "description": ""
    }
  ]
}

cmdb.category.update#

This method is deprecated and will be removed in a feature release. Use cmdb.category.save instead.

Request parameters#

Key JSON data type Required Description
objID Integer Yes Object identifier, for example: 42
category String Yes Category constants, for example: "C__CATG__MODEL"
data Object Yes Attributes which will be updated
data.category_id Integer No Entry identifier (only required for multi-value categories)

Response parameters#

JSON key result contains a JSON object.

Key JSON data type Description
success Boolean Should be true
message String Should be "Category entry successfuly saved"

Example#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
"version": "2.0",
"method": "cmdb.category.update",
"params": {
    "objID": 42,
    "category": "C__CATG__MODEL",
    "data": {
        "serial": "123abc"
    },
    "apikey": "xxx",
    "language": "en"
},
"id": 1
}

1
2
3
4
5
6
7
8
{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "success": true,
    "message": "Category entry successfuly saved. [This method is deprecated and will be removed in a feature release. Use 'cmdb.category.save' instead.]"
  }
}

cmdb.category.delete#

Archive a category entry for an object, mark it as deleted or purge it from database. See also Dokumentationszyklus

Limitations:

  • This only works with multi-value categories at the moment.
  • You can only archive category entries which have a normal status.
  • You can only mark category entries as deleted which are archived.
  • You can only purge category entries from the database which are marked as deleted.

Request parameters#

Key JSON data type Required Description
objID Integer Yes Object identifier, for example: 42
category String Yes Category constant, for example: "C__CATG__IP"
cateID or id Integer Yes Entry identifier, for example: 3

Response#

JSON key result contains a JSON object.

Key JSON data type Description
success Boolean Should be true
message String Some information

Example#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  "version": "2.0",
  "method": "cmdb.category.delete",
  "params": {
    "objID": 42,
    "category": "C__CATG__IP",
    "cateID": 3,
    "apikey": "xxx",
    "language": "en"
  },
  "id": 1
}

1
2
3
4
5
6
7
8
{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "success": true,
    "message": "Category entry '3' successfuly deleted"
  }
}

cmdb.category.save#

Create or Update a category entry of an object.
It works for multi-value categories and single-value category.

Request parameters#

Key JSON data type Required Description
object Integer Yes Object identifier, for example: 456
category String Yes Category constant, for example: "C__CATG__ACCESS"
data Object Yes { "title":"Name of the access", "description": "description of the access" }

Response body#

JSON key result contains a JSON object.

Key JSON data type Description
success Boolean Should be true
message String Some information
entry Integer Entry identifier, for example: 35

Example#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
    "version": "2.0",
    "method": "cmdb.category.save",
    "params": {
        "object": 456,
        "data": {
            "title":"Name of the access",
            "description":"description of the access"
        },
        "category": "C__CATG__ACCESS",
        "apikey": "xxx",
        "language": "en"
    },
    "id": 1
}

1
2
3
4
5
6
7
8
9
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "success": true,
        "message": "Category entry successfuly saved",
        "entry": 35
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{
"version": "2.0",
"method": "cmdb.category.save",
"params": {
    "object": 456,
    "data": {
        "manufacturer": "Name of manufacturer",
        "title": "Name of model"
    },
    "category": "C__CATG__MODEL",
    "entry": 24,
    "apikey": "xxx",
    "language": "en"
},
"id": 1
}

Special case: connecting a network port (assigned_connector)#

The property assigned_connector of the category C__CATG__NETWORK_PORT does not take an object identifier. It expects the entry identifier of the connector on the other end of the cable, which you find in the category Cabling → Connectors (C__CATG__CONNECTOR) of the target object:

  1. Read C__CATG__CONNECTOR of the object you want to connect to. For a patch panel this returns its connectors. For a switch or another device with network ports it also returns one connector per port; the right entry has "assigned_category": {"const": "C__CATG__NETWORK_PORT"} and the title of the port.
  2. Save the network port with "assigned_connector": <id of that entry>. i-doit creates the cable object automatically. To use an existing cable object instead, pass its object identifier in cable.

Any other value, for example the object identifier of the patch panel, is rejected with the error -32099: (assigned_connector) The given connector does not exist, please check "Cabling > Connector" category!

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
    "version": "2.0",
    "method": "cmdb.category.read",
    "params": {
        "objID": 42884,
        "category": "C__CATG__CONNECTOR",
        "apikey": "xxx",
        "language": "en"
    },
    "id": 1
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "id": "1365",
            "objID": "42884",
            "title": "Port 1",
            "type": { "id": "2", "title": "Output" },
            "assigned_connector": null,
            "assigned_category": { "value": "50", "const": "C__CATG__CONNECTOR", "title": "Connectors" },
            "cable_connection": null
        }
    ]
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
    "version": "2.0",
    "method": "cmdb.category.save",
    "params": {
        "object": 42883,
        "category": "C__CATG__NETWORK_PORT",
        "entry": 1364,
        "data": {
            "assigned_connector": 1365
        },
        "apikey": "xxx",
        "language": "en"
    },
    "id": 1
}

1
2
3
4
5
6
7
8
9
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "success": true,
        "message": "Category entry successfully saved",
        "entry": 1364
    }
}

Reading the network port afterwards shows the connected connector and the cable that was created:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
"assigned_connector": {
    "id": "42884",
    "title": "KB-1189 Patch panel",
    "type": "C__OBJTYPE__PATCH_PANEL",
    "assigned_category": "C__CATG__CONNECTOR",
    "ref_id": "1365",
    "ref_title": "Port 1"
},
"cable": {
    "id": "42886",
    "title": "KABEL_DEFAULT_259",
    "type": "C__OBJTYPE__CABLE"
}

cmdb.category.quickpurge#

If Quickpurge is enabled, purge a category entry of an object directly from the database.

Request parameters#

Key JSON data type Required Description
objID Integer Yes Object identifier, for example: 42
category String Yes Category constant, for example: "C__CATG__IP"
cateID or id Integer Yes Entry identifier, for example: 3

Response body#

JSON key result contains a JSON object.

Key JSON data type Description
success Boolean Should be true
message String Some information

Example#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
    "version": "2.0",
    "method": "cmdb.category.quickpurge",
    "params": {
        "objID": 42,
        "category": "C__CATG__IP",
        "cateID": 3,
        "apikey": "xxx",
        "language": "en"
    },
    "id": 1
}

1
2
3
4
5
6
7
8
{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "success": true,
    "message": "Category entry '3' successfuly purged"
  }
}

cmdb.category.purge#

Purge a category entry of an object.It works for multi-value categories and single-value category.

Request parameters#

Key JSON data type Required Description
object Integer Yes Object identifier, for example: 456
category String Yes Category constant, for example: "C__CATG__ACCESS"
entry Integer Yes Entry identifier, for example: 33

Response body#

JSON key result contains a JSON object.

Key JSON data type Description
success Boolean Should be true
message String Some information

Example#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
    "version": "2.0",
    "method": "cmdb.category.purge",
    "params": {
        "object": 456,
        "category": "C__CATG__ACCESS",
        "entry": 33,
        "apikey": "xxx",
        "language": "en"
    },
    "id": 1
}

1
2
3
4
5
6
7
8
{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "success": true,
    "message": "Entry 33 has been successfuly purged from 2 to 5."
  }
}

cmdb.category.recycle#

Limitations:

  • This only works with multi-value categories.
  • You can recycle category entries which have archived or deleted status.

Request parameters#

Key JSON data type Required Description
object Integer Yes Object identifier, for example: 456
category String Yes Category constant, for example: "C__CATG__ACCESS"
entry Integer Yes Entry identifier, for example: 32

Response body#

JSON key result contains a JSON object.

Key JSON data type Description
success Boolean Should be true
message String Some information

Example#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
    "version": "2.0",
    "method": "cmdb.category.recycle",
    "params": {
        "object": 456,
        "category": "C__CATG__ACCESS",
        "entry": 32,
        "apikey": "xxx",
        "language": "en"
    },
    "id": 1
}

1
2
3
4
5
6
7
8
{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "success": true,
    "message": "Entry 32 has been successfuly recycled from 3 to 2."
  }
}

cmdb.category.archive#

Limitations

  • This only works with multi-value categories at the moment.
  • You can only archive category entries which have a normal status.

Request parameters#

Key JSON data type Required Description
object Integer Yes Object identifier, for example: 456
category String Yes Category constant, for example: "C__CATG__ACCESS"
entry Integer Yes Entry identifier, for example: 32

Response body#

JSON key result contains a JSON object.

Key JSON data type Description
success Boolean Should be true
message String Some information

Example#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
    "version": "2.0",
    "method": "cmdb.category.archive",
    "params": {
        "object": 456,
        "category": "C__CATG__ACCESS",
        "entry": 32,
        "apikey": "xxx",
        "language": "en"
    },
    "id": 1
}

1
2
3
4
5
6
7
8
{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "success": true,
    "message": "Entry 32 has been successfuly archived from 2 to 3."
  }
}