After you installed ZbxWizz, to get a feeling about how it works follow this short tutorial where I will:
If you will follow this tutorial step by step, it is safe enough to be executed against any Zabbix installations, including production. Basically we will retrieve some data, modify it and push back to Zabbix updates of a field with no operational impact (host description).
There is also a video version of this tutorial which you can follow here:
In your Zabbix instance obtain an API token. Showing how to obtain one is out of the scope of this article, but I don't know how to do it, you can check this nice tutorial from the guys at Serverspace.io: (https://serverspace.io/support/help/creating-a-zabbix-api-tokens/)
Once you have the token, click on the red Z icon on the top right corner and fill in the form with the following details:
API URL: it usually looks like this: https://example.com/zabbix/api_jsonrpc.php
API token
API query mode - When pulling or pushing data to the API, ZbxWizz will perform an individual request for each of the rows in the selected set. The way these request are being performed depends on this setting:
paralel: all requests are started at the same time. It's fast, but it might lead to problems when pushing data in Zabbix if there are too many.
sequential: requests are performed one by one. It's pretty slow, but safe for write operations
hybrid: requests are split into batches of 10. Inside a batch the requests are performed in parallel, while the batches are executed sequentially
First create a new empty worksheet by clicking on the + button on the bottom bar.
Click on the Data -> Import from Zabbix menu and fill in the form:
{
"limit":2,
"output":["host","name","description"]
}With this request you will retrieve the first 2 hosts from Zabbix (in the order in which they have been added). I do assume that you have at least 2 hosts defined in your Zabbix
Now click on execute. You will see that the worksheet has been populated with (hopefully) 2 rows, and it should look like this
| hostid | host | name | description | col4 | col5 | col6 |
|---|---|---|---|---|---|---|
| 123 | host1 | ... | ... | |||
| 234 | host2 | ... | ... |
Let's now add some more data into the view. Let's retrieve also the hosts interfaces.
To do this I will use the Pull request, which you can access by clicking on Zabbix Ops -> Pull
In the newly opened window, fill the form with the following details:
{
"output":["ip"],
"hostids":["${$0}"]
}Notice the ${$0} part. The request template is interpreted as a JavaScript template literal. This allows us to inject JavaScript code right into the text. By placing the JavaScript code inside this block ${....}, the code will be executed on parse time and its output will be interpolated in the resulting text. $0 refers to the cell at the first position in the row, because row and column numbering starts at 0.
At this point you will notice the text No rows selected inside the preview box, under the editor,The requests are always performed only against selected rows. So, do select now the 2 rows and back in the editor type a space at the end of the text, to force a reevaluation of the template. Now you will be able to see in the preview box the template interpolated with the data of the first selected row. It should look something like this
{
"output":["ip"],
"hostids":["12257"]
}
Notice how the ${$0} part has been replaced by the actual host ID of the first selected row.
Now you can click on execute. Once the requests are completed you will notice that the selected rows have turned pale blue. That's a good sign! It means that the request was successful. The newly retrieved data is now attached to each row. If you want to see it, click on row menu button and select Row info. In the newly opened window you will see all the data attached to the row. Scroll down the window (or click in the window and search with Ctrl+F for zbx) until you reach the zbx property. There you will see it contains the retrieved IP, something like this
.... "zbx": {
"interfaceid": "1634",
"ip": "10.10.0.2"
}
...As you've noticed pulling the data did not changed the contents of the table. This is because the newly pulled data is attached to the row as a data object, but not displayed.
We can now pull this hidden data into the actual table by using Transformations. To do this, click on the column menu of the 5th column (col4) and select Transform.
In the newly opened window fill in the expression editor the following code: data.zbx.ip. You will notice that you can see the host IP of the first record in the preview box. Now click on Apply and all visible cells in col5 will be populated with the IP address of the host in each row.
In this example I have assumed that you have a single interface defined for each host. In the case when there are multiple interfaces define per host, the expression to use to extract the IP of the first interface would be data.zbx[0].ip
This worksheet can be now exported into CSV format by clicking Data -> Export to CSV
As a last phase, we will modify the description of the host and push this back into Zabbix.
Click on the column menu of column 6 (col5) and select Transform. In the transformation window fill in the expression editor the following code: _description + " Modified by ZbxWizz" and click on Apply. What we did now was to create a new, slightly modified, description. Notice that this time, instead of the column index variabile ($3) I have used the column name preceded by the underscore character. Use whichever way you feel more comfortable.
To update the data in Zabbix, go to Zabbix Ops -> Push and fill in the following details:
{
"hostid":"${_hostid}",
"description": "${$5}"
}Note: if you will follow the video version of this tutorial you will notice that I'm running into troubles at this step. The reason is that when I generated the new description I have inserted a new line. Because of this, the final output looks like this:
{
"hostid":"${_hostid}",
"description": "
Modified by ZbxWizz"
}This is not a valid JSON, so it will throw an error. Unfortunately there is nothing I can do to automatically cleanup the template. So always make sure to check for special characters.
Now, make sure all the rows are selected, check again that the request is valid by makins sure the preview block is green. If you forget this, don't worry. ZbxWizz will complain about it if you try to execute an invalid request (from the JSON format perspective) or if there are no selected rows.
Now you can hit the Execute button. If the request was successful, you will see the rows turn pale blue. It there was an error, open the Row info window (see above how it's done) and scroll down to the bottom, there you will find a property named lastError with a message inside.
Go now to you Zabbix interface, search for the hosts which we edits, click on them and verify that the description has been updated.
And that's it. Congratulations! You've just completed a complete workflow in ZbxWizz.