In this article we explain the i-doit JSON-RPC API in depth. If you want to know what parameters must/can be set for each method and what a typical response looks like, this will be the right resource.

Contents

Namespace idoit

This namespace is reserved for common methods.

idoit.search

Search in i-doit

Request parameters

KeyJSON data typRequiredDescription
qStringYesQuery, for example: "My little server"

Response

JSON key result contains an array of JSON objects. Each object contains a search result.

KeyJSON data typeDescription
documentIDStringIdentifier
keyStringAttribute which relates to query
valueStringValue which relates to query
typeStringAdd-on or core feature
linkStringRelative URL which directly links to search result
scoreIntegerScoring (deprecated)

Example

RequestResponse

Body:

{
    "version": "2.0",
    "method": "idoit.search",
    "params": {
        "q": "My little server",
        "apikey": "xxx",
        "language": "en"
    },
    "id": 1
}

 Body:

{
    "jsonrpc": "2.0",
    "result": [
        {
            "documentId": "1000",
            "key": "Virtual Host > Global > Title",
            "value": "My little server",
            "type": "cmdb",
            "link": "/?objID=1000&catgID=1&cateID=1029&highlight=My%20little%20server",
            "score": 0
        },
        […]
    ],
    "id": 1
}

idoit.version

Fetch information about i-doit and the current user

Request parameters

None

Response

JSON key result contains an JSON object with various information about i-doit itself and the current user.

KeyJSON data typeDescription
loginArrayInformation about the user who has performed the request; see below for details
login.useridStringObject identifier (as numeric string)
login.nameStringObject title
login.mailStringE-mail address (see category Persons → Master Data)
login.usernameStringUser name (see category Persons → Login)
login.mandatorStringTenant name
login.languageStringLanguage: "en" or "de"
versionStringVersion of installed i-doit
stepStringDev, alpha or beta release
typeStringRelease variant: "OPEN" or "PRO"

Example

RequestResponse

Body:

{
    "version": "2.0",
    "method": "idoit.version",
    "params": {
        "apikey": "xxx",
        "language": "en"
    },
    "id": 1
}

Body:

{
    "jsonrpc": "2.0",
    "result": {
        "login": {
            "userid": "9",
            "name": "i-doit Systemadministrator ",
            "mail": "i-doit@acme-it.example",
            "username": "admin",
            "mandator": "ACME IT Solutions",
            "language": "en"
        },
        "version": "1.10.2",
        "step": "",
        "type": "PRO"
    },
    "id": 1
}

idoit.constants

Fetch defined constants from i-doit

Request parameters

None

Response

JSON key result contains a JSON object.

KeyJSON data typeDescription
objectTypesObject

List of object types

Keys: object type constants

Values: translated object type titles

categoriesObject

List of global and specific categories

categories.gObject

List of global categories

Keys: category constants

Values: translated category titles

categories.sObject

List of specific categories

Keys: category constants

Values: translated category titles

Example

RequestReponse

Body:

{
    "version": "2.0",
    "method": "idoit.constants",
    "params": {
        "apikey": "xxx",
        "language": "en"
    },
    "id": 1
}

Body:

{
    "jsonrpc": "2.0",
    "result": {
        "objectTypes": {
            "C__OBJTYPE__SERVER": "Server",
            […]
        },
        "categories": {
            "g": {
                "C__CATG__GLOBAL": "General",
                "C__CATG__MODEL": "Model",
                […]
            },
            "s": {
                "C__CATS__MONITOR": "Monitor",
                […]
            }
        }
    },
    "id": 1
}

idoit.login

Create new session

Request parameters

None

Response

JSON key result contains a JSON object.

KeyJSON data typeDescription
resultBooleanShould be true
useridStringObject identifier of logged-in user (as numeric string)
nameStringObject title of logged-in user
mailStringAttribute E-mail address in category Persons → Master Data
usernameStringAttribute User name in category Persons → Login
session-idStringGenerated session identifier
client-idStringTenant identifier (as numeric string)
client-nameStringTenant name

Example

RequestResponse

Header:

X-RPC-Auth-Username: admin
X-RPC-Auth-Password: admin

Body:

{
    "version": "2.0",
    "method": "idoit.login",
    "params": {
        "apikey": "xxx",
        "language": "en"
    },
    "id": 1
}

Header:

X-RPC-Auth-Session: d1obs9m3d2pd8651grptjhdjg3

Body:

{
    "jsonrpc": "2.0",
    "result": {
        "result": true,
        "userid": "9",
        "name": "i-doit Systemadministrator ",
        "mail": "i-doit@acme-it.example",
        "username": "admin",
        "session-id": "d1obs9m3d2pd8651grptjhdjg3",
        "client-id": "1",
        "client-name": "ACME IT Solutions"
    },
    "id": 1
}
RequestResponse

Header:

X-RPC-Auth-Session: d1obs9m3d2pd8651grptjhdjg3

Body:

{
    "version": "2.0",
    "method": "idoit.version",
    "params": {
        "apikey": "xxx",
        "language": "en"
    },
    "id": 2
}

Header:

X-RPC-Auth-Session: d1obs9m3d2pd8651grptjhdjg3

Body:

{
    "jsonrpc": "2.0",
    "result": {
        "login": {
            "userid": "9",
            "name": "i-doit Systemadministrator ",
            "mail": "i-doit@acme-it.example",
            "username": "admin",
            "mandator": "ACME IT Solutions",
            "language": "de"
        },
        "version": "1.9",
        "step": "",
        "type": "PRO"
    },
    "id": 2
}
RequestResponse

Header:

X-RPC-Auth-Session: d1obs9m3d2pd8651grptjhdjg3

Body:

{
    "version": "2.0",
    "method": "idoit.logout",
    "params": {
        "apikey": "xxx",
        "language": "en"
    },
    "id": 3
}

Header:

X-RPC-Auth-Session: d1obs9m3d2pd8651grptjhdjg3

Body:

{
    "jsonrpc": "2.0",
    "result": {
        "message": "Logout successfull",
        "result": true
    },
    "id": 3
}

idoit.logout

Close current session

Request parameters

None

Response

JSON key result contains a JSON object.

KeyJSON data typeDescription
messageStringShould be "Logout successfull"
resultBooleanShould be true

Example

See method idoit.login

Namespace cmdb

This namespace is related to all CMDB-specific methods like handling objects and categories.

cmdb.object.create

Create new object with some optional information

Request parameters

KeyJSON data typeRequiredDescription
typeString|IntegerYes

Object type constant as string, for example: "C__OBJTYPE__SERVER"

Alternatively, object type identifier as integer, for example: 5

titleStringYesObject title, for example: "My little server"
categoryStringNoAttribute Category in category Global
purposeStringNoAttribute Purpose in category Global, for example: "In production"
cmdb_statusString|IntegerNo

Attribute CMDB status in category Global by its constant (string), for example: "C__CMDB_STATUS__IN_OPERATION"

Alternatively, by its identifier (integer), for example: 6

descriptionStringNoAttribute Description in category Global

Response

JSON key result contains a JSON object.

KeyJSON data typeDescription
idStringObject identifier (as numeric string)
messageStringSome information
successBooleanShould always be true

Example

RequestResponse

Body:

{
    "version": "2.0",
    "method": "cmdb.object.create",
    "params": {
        "type": "C__OBJTYPE__SERVER",
        "title": "My little server",
        "apikey": "xxx",
        "language": "en"
    },
    "id": 1
}

Body:

 {
    "jsonrpc": "2.0",
    "result": {
        "id": "42",
        "message": "Object was successfully created",
        "success": true
    },
    "id": 1
}

cmdb.object.read

Read common information about an object

Request parameters

KeyJSON data typeRequiredDescription
idIntegerYesObject identifier; for example: 42

Response

JSON key result contains a JSON object.

KeyJSON data typeDescription
idStringObject identifier (as numeric string)
titleStringObject title
sysidStringSYSID (see category Global)
objecttypeStringObject type identifier (as numeric string)
createdStringDate of creation; format: Y-m-d H:i:s
updatedString

Date of last update; format: Y-m-d H:i:s

Note: This key is optional because not every object has been updated before.

type_titleStringTranslated name of object type
type_iconStringRelative URL to object type icon
statusString

Object status (as numeric string):

  • "1": Unfinished
  • "2": Normal
  • "3": Archived
  • "4": Deleted
  • "6": Template
  • "7": Mass change template
cmdb_statusStringCMDB status (see category Global; as numeric string)
cmdb_status_titleStringTranslated CMDB status (see category Global)
imageStringURL to object picture

Example

RequestResponse

Body:

{
    "version": "2.0",
    "method": "cmdb.object.read",
    "params": {
        "id": 1000,
        "apikey": "xxx",
        "language": "en"
    },
    "id": 1
}

Body:

 {
    "jsonrpc": "2.0",
    "result": {
        "id": "1000",
        "title": "ESXi1",
        "sysid": "VHOST_1426338622",
        "objecttype": "58",
        "type_title": "Virtual host",
        "type_icon": "images/icons/silk/server_database.png",
        "status": "2",
        "cmdb_status": "6",
        "cmdb_status_title": "in operation",
        "created": "2015-03-14 14:10:22",
        "updated": "2017-04-26 10:22:20",
        "image": "http://demo.synetics.int/pro/images/objecttypes/server.png"
    },
    "id": 1
}

cmdb.object.update

Change object title

Request parameters

KeyJSON data typeRequiredDescription
idIntegerYesObject identifier, for example: 42
titleStringYesNew object title, for example: "Your little server"

Response

JSON key result contains a JSON object.

KeyJSON data typeDescription
messageStringShould be
successBooleanShould be true

Example

RequestResponse

Body:

{
    "version": "2.0",
    "method": "cmdb.object.update",
    "params": {
        "id": 42,
        "title": "Your little server",
        "apikey": "xxx",
        "language": "en"
    },
    "id": 1
}

Body:

{
    "jsonrpc": "2.0",
    "result": {
        "message": "Object title was successfully updated",
        "success": true
    },
    "id": 1
}

cmdb.object.delete

Archive object, mark it as deleted or purge it from database

Request paramters

KeyJSON data typeRequiredDescription
idIntegerYesObject identifier, for example: 42
statusStringYes

Status constant:

  • "C__RECORD_STATUS__ARCHIVED": Archive object
  • "C__RECORD_STATUS__DELETED": Mark object as deleted
  • "C__RECORD_STATUS__PURGE": Purge object from database

Response

JSON key result contains a JSON object.

Example

RequestResponse

Body:

{
    "version": "2.0",
    "method": "cmdb.object.delete",
    "params": {
        "id": 42,
        "status": "C__RECORD_STATUS__ARCHIVED",
        "apikey": "xxx",
        "language": "en"
    },
    "id": 1
}

Body:

{
    "jsonrpc": "2.0",
    "result": {
        "message": "Object(s) successfully archived!",
        "success": true
    },
    "id": 1
}

cmdb.objects.read

Fetch a list of objects

Request parameters

KeyJSON data typeRequiredDescription
filterArrayNoFilter list of objects; see below for a full list of options
limitMixedNo

Maximum amount of objects (as integer), for example, fetch the first thousand of objects: 1000

Combine this limit with an offset (as string), for example, fetch the next thousand of objects: "1000,1000"

order_byStringNo

Order result set by (see filter for more details what each value means):

  • "isys_obj_type__id",
  • "isys_obj__isys_obj_type__id",
  • "type",
  • "isys_obj__title",
  • "title",
  • "isys_obj_type__title",
  • "type_title",
  • "isys_obj__sysid",
  • "sysid",
  • "isys_cats_person_list__first_name",
  • "first_name",
  • "isys_cats_person_list__last_name",
  • "last_name",
  • "isys_cats_person_list__mail_address",
  • "email",
  • "isys_obj__id", or
  • "id"
sortStringNoOnly useful in combination with key order_by; allowed values are either "ASC" (ascending) or "DESC" (descending)

Filter

KeyJSON data typeRequiredDescription
idsArrayNoList of object identifiers (as integers), for example: [1, 2, 3]
typeInteger|StringNo

Object type identifier (as integer), for example: 5

Alternatively, object type constant (as string), for example: "C__OBJTYPE__SERVER"

titleStringNoObject title (see attribute Title in category Global), for example: "My little server"
type_titleStringNo

Translated name of object type, for example: "Server"

Note: Set a proper language in your request.

sysidStringNoSYSID (see category Global), for example: "SRV_101010"
first_nameStringNoFirst name of an object of type Persons (see attribute First name in category Persons → Master Data), for example: "John"
last_nameStringNoLast name of an object of type Persons (see attribute Last name in category Persons → Master Data), for example: "Doe"
emailStringNo

Primary e-mail address of an object of type Persons, Person groups or Organization (see attribute E-mail address in categories Persons/Person groups/Organization → Master Data), for example: "john.doe@example.com"

You can use any combination of filters. Filters are logically associated with AND. A valid combination could be: "Give me all servers which have the same hostname."

Response

JSON key result contains an array of JSON objects. Each object contains a bunch of information about an i-doit object.

KeyJSON data typeDescription
idStringObject identifier (as numeric string)
titleStringObject title
sysidStringSYSID (see category Global)
typeStringObject type identifier (as numeric string)
createdStringDate of creation; format: Y-m-d H:i:s
updatedString

Date of last update; format: Y-m-d H:i:s

Note: This key is optional because not every object has been updated before.

type_titleStringTranslated name of object type
type_group_titleStringTranslated name of object type group
statusString

Object status (as numeric string):

  • "1": Unfinished
  • "2": Normal
  • "3": Archived
  • "4": Deleted
  • "6": Template
  • "7": Mass change template
cmdb_statusStringCMDB status (see category Global; as numeric string)
cmdb_status_titleStringTranslated CMDB status (see category Global)
imageStringURL to object picture

Example

RequestResponse

Body:

 {
    "version": "2.0",
    "method": "cmdb.objects.read",
    "params": {
        "filter": {
            "type": "C__OBJTYPE__SERVER"
        },
        "limit": "0,10",
        "order_by": "title",
        "sort": "ASC",
        "apikey": "xxx",
        "language": "en"
    },
    "id": 1
}

Body:

{
    "jsonrpc": "2.0",
    "result": [
        {
            "id": "123",
            "title": "My little server",
            "sysid": "SRV_101010",
            "type": "5",
            "created": "2017-03-07 15:57:48",
            "updated": "2017-05-10 15:40:27",
            "type_title": "Server",
            "type_group_title": "Hardware",
            "status": "2",
            "cmdb_status": "6",
            "cmdb_status_title": "in operation",
            "image": "https://demo.i-doit.com/images/objecttypes/empty.png"
        },
        […]
    ]
}

cmdb.category.create

Create a new category entry

Request parameters

KeyJSON data typeRequiredDescription
objIDIntegerYesObject identifier, for example: 42
categoryStringYesCategory constant, for example: C__CATG__MODEL
dataObjectYes

Attributes with their values, for example:

{
    "manufacturer": "Name of manufacturer",
    "title": "Name of model"
}

Response

JSON key result contains a JSON object.

KeyJSON data typeDescription
idStringEntry identifier (as numeric string)
messageStringSome information
successBooleanShould always be true

Example

RequestResponse

Body:

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

Body:

 {
    "jsonrpc": "2.0",
    "result": {
        "id": "123",
        "message": "Category entry successfully created.",
        "success": true
    },
    "id": 1
}

cmdb.category.read

Read one or more category entries for an object

Request parameters

KeyJSON data typeRequiredDescription
objIDIntegerYesObject identifier, for example: 42
categoryStringYesCategory constant, for example: "C__CATG__MODEL"

Response

JSON key result contains an array of JSON objects. Each object contains all available attributes for the requested category. Note: 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.

KeyJSON data typeDescription
idStringEntry identifier (as numeric string)
objIDStringObject identifier (as numeric string)
MixedOptional attributes with values depending on requested category

Example

RequestResponse

Body:

{
    "version": "2.0",
    "method": "cmdb.category.read",
    "params": {
        "objID": 1000,
        "category": "C__CATG__MODEL",
        "apikey": "xxx",
        "language": "en"
    },
    "id": 1
}

 Body:

 {
    "jsonrpc": "2.0",
    "result": [
        {
            "id": "74",
            "objID": "1000",
            "manufacturer": {
                "id": "2",
                "title": "Lenovo",
                "const": null,
                "title_lang": "Lenovo"
            },
            "title": {
                "id": "1",
                "title": "ThinkServer RD350",
                "const": null,
                "title_lang": "ThinkServer RD350"
            },
            "productid": "",
            "service_tag": "",
            "serial": "123000999888",
            "firmware": "",
            "description": ""
        }
    ],
    "id": 1
}

cmdb.category.update

Update category entry of an object

Request parameters

KeyJSON data typeRequiredDescription
objIDIntegerYesObject identifier, for example: 42
categoryStringYesCategory constant, for example: "C__CATG__MODEL"
dataObjectYes

Attributes which will be updated

data.category_idIntegerNoEntry identifier (only required for multi-value categories)

Response

JSON key result contains a JSON object.

KeyJSON data typeDescription
successBooleanShould be true
messageStringShould be "Category entry successfully saved"

Example

RequestResponse

Body:

 {
    "version": "2.0",
    "method": "cmdb.category.update",
    "params": {
        "objID": 42,
        "category": "C__CATG__MODEL",
        "data": {
            "serial": "123abc"
        },
        "apikey": "xxx",
        "language": "en"
    },
    "id": 1
}

Body:

{
    "jsonrpc": "2.0",
    "result": {
        "success": true,
        "message": "Category entry successfully saved"
    },
    "id": 1
}

cmdb.category.delete

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

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

KeyJSON data typeRequiredDescription
objIDIntegerYesObject identifier, for example: 42
categoryStringYesCategory constant, for example: "C__CATG__IP"
cateIDIntegerYesEntry identifier, for example: 3

Response

JSON key result contains a JSON object.

KeyJSON data typeDescription
successBooleanShould be true
messageStringSome information

Example

RequestResponse

Body:

{
    "version": "2.0",
    "method": "cmdb.category.delete",
    "params": {
        "objID": 42,
        "category": "C__CATG__IP",
        "cateID": 3,
        "apikey": "xxx",
        "language": "en"
    },
    "id": 1
}

Body:

{
    "jsonrpc": "2.0",
    "result": {
        "success": true,
        "message": "Category entry '3' successfully deleted"
    },
    "id": 1
}

cmdb.category.quickpurge

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

Request parameters

KeyJSON data typeRequiredDescription
objIDIntegerYesObject identifier, for example: 42
categoryStringYesCategory constant, for example: "C__CATG__IP"
cateIDIntegerYesEntry identifier, for example: 3

Response

JSON key result contains a JSON object.

KeyJSON data typeDescription
successBooleanShould be true
messageStringSome information

Example

RequestResponse

Body:

 {
    "version": "2.0",
    "method": "cmdb.category.quickpurge",
    "params": {
        "objID": 42,
        "category": "C__CATG__IP",
        "cateID": 3,
        "apikey": "xxx",
        "language": "en"
    },
    "id": 1
}

Body:

 {
    "jsonrpc": "2.0",
    "result": {
        "success": true,
        "message": "Category entry '3' successfully purged"
    },
    "id": 1
}