Zum Inhalt

cmdb.external#

Die Einbindung externer Datenquellen in die Configuration Management Database (CMDB) kann durch verschiedene Maßnahmen vereinfacht werden. Zunächst ist es wichtig, dass die Daten in einem standardisierten, leicht zu verarbeitenden Format vorliegen, um das Auslesen und Übernehmen in die CMDB zu erleichtern. Darüber hinaus sollten Funktionen implementiert werden, die eine vollständige, einmalige Datenübernahme sowie regelmäßige, automatisierte Synchronisationen ermöglichen. Dabei ist es entscheidend, dass jedes Datenelement in der CMDB mit seiner Herkunft verknüpft wird, um die Identifizierbarkeit der Datenquellen sicherzustellen. Gleichzeitig müssen klare Regeln und Richtlinien definiert werden, um den Geltungsbereich der Daten aus den einzelnen Quellen abzugrenzen. Die simultane Integration mehrerer Datenquellen sollte ebenfalls unterstützt werden, wobei Konflikte und Inkonsistenzen erkannt und aufgelöst werden müssen. Schließlich sollten Single-Request Operationen implementiert werden, die es Anwendern ermöglichen, Datenimporte, -synchronisationen und -abfragen über eine einzige Schnittstelle durchzuführen, um die Benutzerfreundlichkeit und Effizienz zu erhöhen.

cmdb.external#

Was sind External Identifier?#

  • Benutzerdefinierte String-basierte stabile und eindeutige IDs
  • Zusammengesetzt aus einem "type" und einer "id"

Zum Beispiel my_vendor_id / my_object_id.

Warum brauchen wir External Identifier?#

  • Klare Identifizierung von Objekt- und Kategorie-Datensätzen
  • Scoping: Abgeschlossene Datenbereiche
  • Caller muss interne Datensatz-IDs nicht kennen

Wie funktionieren External Identifier?#

  • Hierarchischer Ansatz
  • User definiert einen External Identifier für das Objekt
    • extType: Identifikator für die Datenquelle/Vendor
    • extId: Identifikator für das Objekt
  • User definiert zudem einen Identifier (ohne extType) für jeden Kategorieeintrag
  • API erstellt ein Mapping zwischen Identifier und internen IDs

Beispiele dazu wären:

  • External Identifier für ein Objekt
    • datenquelle-1 / windows-server100
  • External Identifier für jeden Kategorieeintrag
    • datenquelle-1 / windows-server100 / C__CATG__CPU / intel-1

Auf der ersten Ebene befindet sich das Objekt. Hierbei definieren wir zum einen den extType und zum anderen die extId. Beides im Verbund bildet den vollständigen Identifier und identifiziert das erstellte Objekt eindeutig.

Auf der nächsten Ebene hingegen haben wir unsere Kategorie Ebene. Dabei startet jede Kategorie mit der zugehörigen Konstante und erhält auf der darunterliegenden eine eindeutige Id.

Aus dieser Struktur ermittelt i-doit dann automatisch den finalen Identifier hier am Beispiel von intel-1 und intel-2 verdeutlicht.

Hier ein beispielhafter Push-Request zur Erstellung eines Objektes über den neuen Endpunkt.

 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
28
29
30
31
32
33
34
35
36
37
{
    "jsonrpc": "2.0",
    "id": 1,
    "params": {
        ...
        "apikey": "xxx",
        <--- Objekt Ebene
        "extType": "datenquelle-1",
        "extId": "windows-server100",
        "title": "Server 100",
        "class": "C__OBJTYPE__SERVER",
        Objekt Ebene --->
        "data": {
            <--- Kategorie Ebene
            "C__CATG__CPU": {
                "strategy": "overwrite",
                "data": {
                    "intel-1": {
                        "title": "Intel Core i9 3.5GHz #1",
                        "manufacturer": "Intel",
                        "type": "Core i9",
                        "frequency": "3.5",
                        "frequency_unit": "GHz"
                    },
                    "intel-2":{
                        "title": "Intel Core i9 3.5GHz #2",
                        "manufacturer": "Intel",
                        "type": "Core i9",
                        "frequency": "3.5",
                        "frequency_unit": "GHz"
                    }
                },...
            }
            Kategorie Ebene --->
        }
    }
}

und erfasst das ganze in einer internen Mapping Tabelle.

Mapping Tabelle

Scoping#

Das Scoping soll sicherstellen, dass sich zwei Datenquellen nicht in die Quere kommen, da wir folgendes annehmen:

Wenn unterschiedliche Datenquellen zugleich ihre Daten in i-doit einspeisen, so nehmen wir an, dass jede Datenquelle für sich genommen führend ist und als Single-Source-of-Truth betrachtet werden kann. Das heisst im Umkehrschluss, dass ein Objekt niemals zugleich in mehreren Datenquellen auftauchen kann.

Scoping

Basierend auf dieser Annahme implementiert i-doit daher folgendes Sicherheitsnetz:

  • Es gibt eine klare Zuweisung von Objekten zu Datenquellen
    • Ein Objekt kann lediglich einer Datenquelle zugewiesen sein
      • Ein Datenquelle-Objekt kann nicht von mehreren Datenquellen verwaltet werden
    • Eine weitere Feinheit: Bestehende Objekte können einer Datenquelle nicht manuell zugewiesen werden

Auf der Kategorie Ebene haben wir ein ähnliches Handling:

  • Klare Zuweisung von Kategorieeinträgen zu Datenquellen
  • Eine Besonderheit bei MV: MV-Einträge können manuell bearbeitet werden auch wenn sie aus einer Datenquelle kommen
  • Der umgekehrte Weg jedoch, also manuell erstellte multi-value Kategorieeinträge bleiben vor dem Zugriff der Datenquelle geschützt
  • Aber auch hier gibt es eine Ausnahme, nämlich bei single-value Kategorien: Manuell erstellte single-value Kategorieeinträge können durch Datenquellen manipuliert werden
  • Rechts unten gibt es zudem noch einen unerlaubten und nicht abbildbaren Case: Die Datenquelle "datenquelle-2" kann keinen CPU-Eintrag in einem Objekt besitzen, was durch die "datenquelle-1" verwaltet wird

cmdb.external.push.v2#

Erstellung und Aktualisierung von Objekten und Kategorieeinträgen durch einen einzelnen Request. Zudem erlauben uns verschiedene "strategies" die Abbildung verschiedener Use-Cases, wobei aber erwähnt werden sollte, dass diese lediglich auf der Kategorieschicht angesiedelt sind.

Außerdem verfügt auch die Push-API über Prozeduren, um Human-Readable Werte in ihre technische Repräsentation zu überführen, beispielsweise Dialog+, Objekt-Referenzen oder Kategoriereferenzen. Und ganz wichtig:

Durch die Verwendung der Push-API muss man nicht auf generelle CMDB-Strukturen verzichten, wie zum Beispiel das Rechtesystem, Validierungsregel oder das Logbuch. Alles greift wie bisher!

Strategy Eintrag existiert single-value Eintrag existiert multi-value Eintrag existiert nicht single-value Eintrag existiert nicht multi-value
create wird übersprungen wird übersprungen wird erstellt wird erstellt
update wird aktualisiert wird aktualisiert wird erstellt wird erstellt
overwrite wird aktualisiert wird aktualisiert wird erstellt wird erstellt

overwrite löscht alle multi-value Einträge aus i-doit, die nicht im Request enthalten sind. Bestehende werden aktualisiert oder erstellt.

Request parameters#

Key JSON data type Required Description
extType String Ja Datenquelle, zum Beispiel: datenquelle-1
extId String Ja Objekt, zum Beispiel: windows-server100
class String Ja Objekttyp, zum Beispiel: C__OBJTYPE__SERVER
title String Ja Objekt Bezeichnung, zum Beispiel: Server 100
data Object Ja Kategoriedaten, je Kategorie-Konstante (siehe Beispiele unten)

Example#

 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
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "cmdb.external.push.v2",
    "params": {
        "apikey": "xxx",
        "extType": "datenquelle-1",
        "extId": "windows-server100",
        "class": "C__OBJTYPE__SERVER",
        "title": "Server 100",
        "data": {
            "C__CATG__CPU": {
                "strategy": "create",
                "data": {
                    "intel-1": {
                        "title": "5th Generation Intel® Xeon® Scalable Processors #1",
                        "manufacturer": "Intel",
                        "cores": 52,
                        "type": "8571N",
                        "frequency": "2.4",
                        "frequency_unit": "GHz"
                    },
                    "intel-2":{
                        "title": "5th Generation Intel® Xeon® Scalable Processors #2",
                        "manufacturer": "Intel",
                        "cores": 52,
                        "type": "8571N",
                        "frequency": "2.4",
                        "frequency_unit": "GHz"
                    }
                }
            },
                "C__CATG__GLOBAL": {
                    "strategy": "update",
                    "data": {
                        "windows-server1001_TAGS": {
                            "tag": [
                                "server",
                                "monitoring",
                                "api2.0"
                            ],
                            "purpose": "Doku",
                            "type": "C__OBJTYPE__SERVER"
                        }
                    }
                },
                "C__CATG__LOCATION": {
                    "strategy": "create",
                    "data": {
                        "CITY_OBJECT_DUESSELDORF": {
                            "parent": {
                                "title": "Düsseldorf",
                                "class": "C__OBJTYPE__CITY",
                                "extType": "datenquelle-1",
                                "extId": "CITY_OBJECT_DUESSELDORF"
                        }
                    }
                }
            }
        }
    }
}

  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
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "messages": [
            {
                "message": "External id datenquelle-1/windows-server100 not found. Object with id 770 created.",
                "level": 200,
                "datetime": "2024-04-09T15:53:56.134886+02:00"
            },
            {
                "message": "Preparing data for category 'CPU' using strategy create.",
                "level": 200,
                "datetime": "2024-04-09T15:53:56.135378+02:00"
            },
            {
                "message": "Handling multi value category.",
                "level": 100,
                "datetime": "2024-04-09T15:53:56.135431+02:00"
            },
            {
                "message": "New category entry 104 created for custom id intel-1.",
                "level": 200,
                "datetime": "2024-04-09T15:53:56.138370+02:00"
            },
            {
                "message":"Original: {\"title\":\"5th Generation Intel\® Xeon\® Scalable Processors #1\",\"manufacturer\":\"Intel\",\"cores\":52,\"type\":\"8571N\",\"frequency\":\"2.4\",\"frequency_unit\":\"GHz\"}",
                "level": 100,
                "datetime": "2024-04-09T15:53:56.139098+02:00"
            },
            {
                "message":"Normalized: {\"title\":\"5th Generation Intel\® Xeon\® Scalable Processors #1\",\"manufacturer\":2,\"type\":33,\"frequency\":\"2.4\",\"frequency_unit\":3,\"cores\":52}",
                "level": 100,
                "datetime": "2024-04-09T15:53:56.144378+02:00"
            },
            {
                "message":"Final: {\"data_id\":104,\"properties\":{\"title\":{\"value\":\"5th Generation Intel\® Xeon\® Scalable Processors #1\"},\"manufacturer\":{\"value\":2},\"type\":{\"value\":33},\"frequency\":{\"value\":\"2.4\"},\"frequency_unit\":{\"value\":3},\"cores\":{\"value\":52},\"description\":{\"value\":null}}}",
                "level": 100,
                "datetime": "2024-04-09T15:53:56.145200+02:00"
            },
            {
                "message": "New category entry 105 created for custom id intel-2.",
                "level": 200,
                "datetime": "2024-04-09T15:53:56.146411+02:00"
            },
            {
                "message":"Original: {\"title\":\"5th Generation Intel\® Xeon\® Scalable Processors #2\",\"manufacturer\":\"Intel\",\"cores\":52,\"type\":\"8571N\",\"frequency\":\"2.4\",\"frequency_unit\":\"GHz\"}",
                "level": 100,
                "datetime": "2024-04-09T15:53:56.147024+02:00"
            },
            {
                "message":"Normalized: {\"title\":\"5th Generation Intel\® Xeon\® Scalable Processors #2\",\"manufacturer\":2,\"type\":33,\"frequency\":\"2.4\",\"frequency_unit\":3,\"cores\":52}",
                "level": 100,
                "datetime": "2024-04-09T15:53:56.147884+02:00"
            },
            {
                "message":"Final: {\"data_id\":105,\"properties\":{\"title\":{\"value\":\"5th Generation Intel\® Xeon\® Scalable Processors #2\"},\"manufacturer\":{\"value\":2},\"type\":{\"value\":33},\"frequency\":{\"value\":\"2.4\"},\"frequency_unit\":{\"value\":3},\"cores\":{\"value\":52},\"description\":{\"value\":null}}}",
                "level": 100,
                "datetime": "2024-04-09T15:53:56.148551+02:00"
            },
            {
                "message": "Preparing data for category 'General' using strategy update.",
                "level": 200,
                "datetime": "2024-04-09T15:53:56.148807+02:00"
            },
            {
                "message": "Handling single value category.",
                "level": 100,
                "datetime": "2024-04-09T15:53:56.148844+02:00"
            },
            {
                "message": "New external id windows-server1001_TAGS reference created for category entry id 768.",
                "level": 200,
                "datetime": "2024-04-09T15:53:56.150471+02:00"
            },
            {
                "message": "Original: {\"tag\":[\"server\",\"monitoring\",\"api2.0\"],\"purpose\":\"Doku\",\"type\":\"C__OBJTYPE__SERVER\"}",
                "level": 100,
                "datetime": "2024-04-09T15:53:56.150502+02:00"
            },
            {
                "message": "Normalized: {\"purpose\":5,\"type\":\"C__OBJTYPE__SERVER\",\"tag\":[1,4,8]}",
                "level": 100,
                "datetime": "2024-04-09T15:53:56.153905+02:00"
            },
            {
                "message": "Final: {\"data_id\":768,\"properties\":{\"purpose\":{\"value\":5},\"type\":{\"value\":\"C__OBJTYPE__SERVER\"},\"tag\":{\"value\":[1,4,8]},\"title\":{\"value\":\"Server 100\"},\"status\":{\"value\":\"2\"},\"created\":{\"value\":\"2024-04-09 15:53:56\"},\"created_by\":{\"value\":\"admin\"},\"changed_by\":{\"value\":\"admin\"},\"category\":{\"value\":null},\"sysid\":{\"value\":\"SYSID_1712671606\"},\"cmdb_status\":{\"value\":\"6\"},\"description\":{\"value\":null}}}",
                "level": 100,
                "datetime": "2024-04-09T15:53:56.156163+02:00"
            },
            {
                "message": "Preparing data for category 'Location' using strategy create.",
                "level": 200,
                "datetime": "2024-04-09T15:53:56.156514+02:00"
            },
            {
                "message": "Handling single value category.",
                "level": 100,
                "datetime": "2024-04-09T15:53:56.156542+02:00"
            },
            {
                "message": "New category entry 167 created for custom id CITY_OBJECT_DUESSELDORF.",
                "level": 200,
                "datetime": "2024-04-09T15:53:56.159102+02:00"
            },
            {
                "message":"Original: {\"parent\":{\"title\":\"D\üsseldorf\",\"class\":\"C__OBJTYPE__CITY\",\"extType\":\"datenquelle-1\",\"extId\":\"CITY_OBJECT_DUESSELDORF\"}}",
                "level": 100,
                "datetime": "2024-04-09T15:53:56.159744+02:00"
            },
            {
                "message": "Normalized: {\"parent\":771}",
                "level": 100,
                "datetime": "2024-04-09T15:53:56.169216+02:00"
            },
            {
                "message": "Final: {\"data_id\":167,\"properties\":{\"parent\":{\"value\":771},\"option\":{\"value\":null},\"insertion\":{\"value\":null},\"pos\":{\"value\":null},\"snmp_syslocation\":{\"value\":null},\"description\":{\"value\":null}}}",
                "level": 100,
                "datetime": "2024-04-09T15:53:56.174171+02:00"
            },
            {
                "message": "Sync C__CATG__CPU in object 770 with import status 2.",
                "level": 200,
                "datetime": "2024-04-09T15:53:56.175085+02:00"
            },
            {
                "message": "Sync C__CATG__CPU in object 770 with import status 2.",
                "level": 200,
                "datetime": "2024-04-09T15:53:56.176118+02:00"
            },
            {
                "message": "Sync C__CATG__GLOBAL in object 770 with import status 2.",
                "level": 200,
                "datetime": "2024-04-09T15:53:56.176866+02:00"
            },
            {
                "message": "Sync C__CATG__LOCATION in object 770 with import status 2.",
                "level": 200,
                "datetime": "2024-04-09T15:53:56.185615+02:00"
            }
        ],
        "success": true
    }
}

cmdb.external.pull.v2#

Lesen von CMDB-Daten basierend auf dem "External Identifier". Beim Pull bestimmt der External Identifier die abgefragten Daten zum Beispiel:

extType extId Aktion
datenquelle-1 null Liest alle Objekte und jegliche Kategoriedaten
datenquelle-1 windows-server100 Liest windows100 und jegliche Kategoriedaten
datenquelle-1 / windows-server100 / C__CATG__CPU null Liest windows100 und alle CPU-Einträge
datenquelle-1 / windows-server100 / C__CATG__CPU intel-1 Liest windows100 und nur den CPU-Eintrag intel-1

Request parameters#

Key JSON data type Required Description
extType String Ja Datenquelle, zum Beispiel: datenquelle-1
extId String Nein Objekt, zum Beispiel: windows-server100. Ohne Angabe werden alle Objekte der Datenquelle gelesen

Example#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "cmdb.external.pull.v2",
    "params": {
        "apikey": "xxx",
        "extType": "datenquelle-1",
        "extId": "windows-server100"
    }
}

  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
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "extId": "windows-server100",
            "extType": "datenquelle-1",
            "id": 770,
            "title": "Server 100",
            "sysid": "SYSID_1712671606",
            "objecttype": 5,
            "type_title": "Server",
            "type_icon": "images/axialis/hardware-network/server-single.svg",
            "status": 0,
            "cmdb_status": 0,
            "data": {
                "C__CATG__CPU": [
                    {
                        "extId": "intel-1",
                        "extType": "datenquelle-1/windows-server100/C__CATG__CPU",
                        "id": "104",
                        "objID": "770",
                        "title": "5th Generation Intel® Xeon® Scalable Processors #1",
                        "manufacturer": {
                            "id": "2",
                            "title": "Intel",
                            "const": null,
                            "title_lang": "Intel"
                        },
                        "type": {
                            "id": "33",
                            "title": "8571N",
                            "const": null,
                            "title_lang": "8571N"
                        },
                        "frequency": {
                            "title": 2.4
                        },
                        "frequency_unit": {
                            "id": "3",
                            "title": "GHz",
                            "const": "C__FREQUENCY_UNIT__GHZ",
                            "title_lang": "GHz"
                        },
                        "cores": "52",
                        "description": ""
                    },
                    {
                        "extId": "intel-2",
                        "extType": "datenquelle-1/windows-server100/C__CATG__CPU",
                        "id": "104",
                        "objID": "770",
                        "title": "5th Generation Intel® Xeon® Scalable Processors #1",
                        "manufacturer": {
                            "id": "2",
                            "title": "Intel",
                            "const": null,
                            "title_lang": "Intel"
                        },
                        "type": {
                            "id": "33",
                            "title": "8571N",
                            "const": null,
                            "title_lang": "8571N"
                        },
                        "frequency": {
                            "title": 2.4
                        },
                        "frequency_unit": {
                            "id": "3",
                            "title": "GHz",
                            "const": "C__FREQUENCY_UNIT__GHZ",
                            "title_lang": "GHz"
                        },
                        "cores": "52",
                        "description": ""
                    }
                ],
                "C__CATG__GLOBAL": [
                    {
                        "extId": "windows-server1001_TAGS",
                        "extType": "datenquelle-1/windows-server100/C__CATG__GLOBAL",
                        "id": "770",
                        "objID": "770",
                        "title": "Server 100",
                        "status": {
                            "id": "2",
                            "title": "Normal",
                            "const": "",
                            "title_lang": "LC__CMDB__RECORD_STATUS__NORMAL"
                        },
                        "created": "2024-04-09 15:53:56",
                        "created_by": "admin",
                        "changed": "2024-04-09 15:53:56",
                        "changed_by": "admin",
                        "purpose": {
                            "id": "5",
                            "title": "Doku",
                            "const": null,
                            "title_lang": "Doku"
                        },
                        "category": null,
                        "sysid": "SYSID_1712671606",
                        "cmdb_status": {
                            "id": "6",
                            "title": "in operation",
                            "const": "C__CMDB_STATUS__IN_OPERATION",
                            "title_lang": "LC__CMDB_STATUS__IN_OPERATION"
                        },
                        "type": {
                            "id": "5",
                            "title": "Server",
                            "const": "C__OBJTYPE__SERVER",
                            "title_lang": "LC__CMDB__OBJTYPE__SERVER"
                        },
                        "tag": [
                            {
                                "id": "1",
                                "title": "server"
                            },
                            {
                                "id": "4",
                                "title": "monitoring"
                            },
                            {
                                "id": "8",
                                "title": "api2.0"
                            }
                        ],
                        "description": ""
                    }
                ],
                "C__CATG__LOCATION": [
                    {
                        "extId": "CITY_OBJECT_DUESSELDORF",
                        "extType": "datenquelle-1/windows-server100/C__CATG__LOCATION",
                        "id": "167",
                        "objID": "770",
                        "location_path": "771",
                        "parent": {
                            "id": "771",
                            "title": "Düsseldorf",
                            "sysid": "SYSID_1712671607",
                            "type": "C__OBJTYPE__CITY",
                            "type_title": "City",
                            "location_path": "Düsseldorf"
                        },
                        "option": null,
                        "insertion": null,
                        "pos": null,
                        "gps": {
                            "0": null,
                            "1": null,
                            "latitude": null,
                            "longitude": null
                        },
                        "latitude": null,
                        "longitude": null,
                        "snmp_syslocation": "",
                        "description": ""
                    }
                ]
            }
        }
    ]
}

Anwendungsfälle#

Die folgenden Beispiele folgen einem typischen Ablauf: Ein externes System (hier datenquelle-1) führt eigene IDs und spiegelt Daten nach i-doit. Beachten Sie, dass objectId eine Zahl ohne Anführungszeichen ist und das JSON-RPC-Feld id auf die oberste Ebene der Anfrage gehört, nicht in params.

Ein vorhandenes Objekt mit einer externen Kennung verbinden#

Das Objekt liegt schon in i-doit, und Sie möchten es mit der ID aus Ihrem externen System verbinden, um es später anzureichern. Das erledigt cmdb.external.link.v2.

Key JSON data type Required Description
extType String Ja Datenquelle, zum Beispiel: datenquelle-1
extId String Ja Externe Kennung für das Objekt, zum Beispiel: windows-server100
objectId Number Ja Interne ID des vorhandenen i-doit-Objekts, zum Beispiel: 770
cmdb.external.link.v2

Request 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "cmdb.external.link.v2",
    "params": {
        "apikey": "xxx",
        "extType": "datenquelle-1",
        "extId": "windows-server100",
        "objectId": 770
    }
}
Response 
1
2
3
4
5
6
7
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "success": true
    }
}

Ist das Objekt bereits mit dieser Kennung verbunden, erhalten Sie success: true zusammen mit der Meldung External identifier is already linked to given object.. Diese Antwort bestätigt die Zuordnung bereits, ein separater Pull zur Prüfung ist dafür nicht nötig.

Ein verbundenes Objekt anreichern#

Das Objekt ist verbunden, jetzt schreiben Sie Daten aus Ihrem externen System in eine seiner Kategorien. Unter data steht je Kategorie eine Kennung pro Eintrag, und erst darunter stehen die eigentlichen Felder.

cmdb.external.push.v2 (eine Kategorie)

Request 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "cmdb.external.push.v2",
    "params": {
        "apikey": "xxx",
        "extType": "datenquelle-1",
        "extId": "windows-server100",
        "class": "C__OBJTYPE__SERVER",
        "title": "Server 100",
        "data": {
            "C__CATG__MODEL": {
                "strategy": "create",
                "data": {
                    "model-1": {
                        "manufacturer": "Dell",
                        "title": "PowerEdge R760"
                    }
                }
            }
        }
    }
}
Response 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "messages": [
            {
                "message": "Object for external id datenquelle-1/windows-server100 found: 770",
                "level": 200,
                "datetime": "2024-04-09T15:53:56.134886+02:00"
            },
            {
                "message": "Preparing data for category 'Model' using strategy create.",
                "level": 200,
                "datetime": "2024-04-09T15:53:56.135378+02:00"
            }
        ],
        "success": true
    }
}

Ein Objekt anlegen und gleich anreichern#

Das Objekt gibt es noch nicht, also legen Sie es an und füllen es mit einem einzigen cmdb.external.push.v2-Aufruf. Die Objekt-Ebene (extType, extId, title, class) und die Kategorie-Ebene (data) werden zusammen gesendet.

cmdb.external.push.v2 (Objekt anlegen)

Request 

 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
{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "cmdb.external.push.v2",
    "params": {
        "apikey": "xxx",
        "extType": "datenquelle-1",
        "extId": "windows-server200",
        "class": "C__OBJTYPE__SERVER",
        "title": "Server 200",
        "data": {
            "C__CATG__CPU": {
                "strategy": "create",
                "data": {
                    "intel-1": {
                        "title": "Intel Core i9 3.5GHz #1",
                        "manufacturer": "Intel",
                        "type": "Core i9",
                        "frequency": "3.5",
                        "frequency_unit": "GHz"
                    }
                }
            }
        }
    }
}
Response 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "messages": [
            {
                "message": "External id datenquelle-1/windows-server200 not found. Object with id 771 created.",
                "level": 200,
                "datetime": "2024-04-09T15:53:56.134886+02:00"
            },
            {
                "message": "New category entry 106 created for custom id intel-1.",
                "level": 200,
                "datetime": "2024-04-09T15:53:56.138370+02:00"
            }
        ],
        "success": true
    }
}

Nachsehen, was mit einer Kennung verbunden ist#

Sie möchten sehen, was hinter einer Kennung steckt und wie deren Daten aussehen. cmdb.external.pull.v2 liest anhand der Kennung, und wie viel Sie zurückbekommen, hängt davon ab, welchen Teil der Kennung Sie senden:

extType extId Liest
datenquelle-1 null alle Objekte und alle Kategoriedaten
datenquelle-1 windows-server100 dieses Objekt und alle seine Kategoriedaten
datenquelle-1 / windows-server100 / C__CATG__CPU null dieses Objekt und alle CPU-Einträge
datenquelle-1 / windows-server100 / C__CATG__CPU intel-1 dieses Objekt und nur den CPU-Eintrag intel-1
cmdb.external.pull.v2

Request 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "cmdb.external.pull.v2",
    "params": {
        "apikey": "xxx",
        "extType": "datenquelle-1",
        "extId": "windows-server100"
    }
}
Response 
 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
28
29
30
31
32
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "extId": "windows-server100",
            "extType": "datenquelle-1",
            "id": 770,
            "title": "Server 100",
            "sysid": "SYSID_1712671606",
            "objecttype": 5,
            "type_title": "Server",
            "status": 2,
            "cmdb_status": 6,
            "data": {
                "C__CATG__MODEL": [
                    {
                        "extId": "model-1",
                        "extType": "datenquelle-1/windows-server100/C__CATG__MODEL",
                        "id": "104",
                        "objID": "770",
                        "manufacturer": {
                            "id": "2",
                            "title": "Dell"
                        },
                        "title": "PowerEdge R760"
                    }
                ]
            }
        }
    ]
}