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