README.md
1# i-doit DokuWiki Syntax Plugin
2
3This plugin provides a basic integration of the [i-doit JSON-RPC API client in PHP](https://bitbucket.org/dstuecken/i-doit-api-clients/wiki/PHP) with DokuWiki.
4
5## Installation
6
7### Manually
8
9Simply clone the repo to `lib/plugins` of your Dokuwiki installation root within a directory named `idoit`. The naming is important, otherwise the plugin will not be loaded.
10
11 git clone https://github.com/oliverguenther/dokuwiki-idoit-syntax <path to dokuwiki>/lib/plugins/idoit/
12
13The PHP client API must be initialized for your i-doit installation. Run the following command ([More Information](https://bitbucket.org/dstuecken/i-doit-api-clients/wiki/PHP)).
14
15 cd <path to dokuwiki>/lib/plugins/idoit/php && make initialize
16
17## Usage
18
19The plugin adds a protected syntax block `<idoitAPI></idoitAPI>` which contains a JSON request passed to the API.
20
21 <idoitAPI>
22 {
23 "method": "cmdb.object.read",
24 "params": { "id": 1234 },
25 "filter": [
26 { "desc": "SYS-ID", "path": [ "sysid" ] },
27 { "desc": "Foo", "path": [ "foo", "bar" ] }
28 ]
29 }
30 </idoitAPI>
31
32The JSON request must contain the following attributes:
33
34 * **method**: The method string as defined in `CMDB/Methods.class.php` of the PHP API
35 * **request** The actual JSON request as sent to the API.
36
37 And may contain an optional `filter` attribute for filtering the result object as an array of the following objects:
38
39 * **path**: An array that denotes the accessor hierarchy in the response object.
40
41 A filter `{ "desc": "My Hostname", "path": [0, "hostaddress", "ref_title"] }`
42 would return the line `'My Hostname myhostname'` for the following API response:
43
44 [{
45 "hostaddress": {
46 id: 128,
47 type: "C__OBJTYPE__LAYER3_NET",
48 title: "Management",
49 ref_title: "myhostname"
50 }
51 },
52 ...
53 ]
54
55
56 * **desc**: The name to be used for printing the retrieved value
57
58
59For available methods and categories as strings, see the constant definitions in [https://bitbucket.org/dstuecken/i-doit-api-clients](https://bitbucket.org/dstuecken/i-doit-api-clients).
60
61
62## Examples
63
64
65### Retrieving objects by IDs
66
67 <idoitAPI>
68 {
69 "method": "cmdb.object.read",
70 "params": { "id": 578 }
71 }
72 </idoitAPI>
73
74**Output**
75
76 id 578
77 title NOS
78 sysid SYSID_1404992452
79 objecttype 5
80 type_title Server
81 ....
82 updated 2014-10-17 11:53:54
83
84
85#### Retrieve single attribute pairs
86
87
88 <idoitAPI>
89 {
90 "method": "cmdb.object.read",
91 "params": { "id": 578 },
92 "filter": [
93 { "desc": "SYS-ID", "path": [ "sysid" ] },
94 { "desc": "Foo", "path": [ "foo", "bar" ] }
95 ]
96 }
97 </idoitAPI>
98
99If a filter does not match the response, a warning is instead printed:
100
101 SYS-ID SYSID_1404992452
102 Foo Filter 'Foo' (path foo/bar) does not match response
103
104#### Retrieve, Filter values from categories
105
106 <idoitAPI>
107 {
108 "method": "cmdb.category.read",
109 "params": { "objID": 578, "catgID": "C__CATG__IP" },
110 "filter": [
111 { "desc": "Hostname", "path": [ "1", "hostname" ] },
112 { "desc": "IPv4", "path": [ "1", "hostaddress", "ref_title" ] }
113 ]
114 }
115 </idoitAPI>
116
117 Hostname myhostname.example.com
118 IPv4 123.456.789.0
119
120
121
122## Copyrights & License
123The i-doit DokuWiki syntax plugin is completely free and open source and released under the [MIT License](https://github.com/oliverguenther/dokuwiki-idoit-syntax/blob/master/LICENSE).
124
125Copyright (c) 2014 Oliver Günther (mail@oliverguenther.de)
126
127This plugin makes use of the [i-doit JSON-RPC API client in PHP](https://bitbucket.org/dstuecken/i-doit-api-clients/wiki/PHP), Copyright (c) 2014 Dennis Stücken
128