# HowTo: Create Annotations in Grafana via rules

**URL:** <https://community.openhab.org/t/howto-create-annotations-in-grafana-via-rules/48929>\
**Category:** Solutions\
**Tags:** rules, grafana\
**Created:** [August 5, 2018, 8:07pm UTC](https://community.openhab.org/t/howto-create-annotations-in-grafana-via-rules/48929 "2018-08-05T20:07:52Z")\
**Posts on this page:** 4\
**Page:** 1

<div class="post-metadata">

**Author:** ![christoph\_wempe](https://community.openhab.org/user_avatar/community.openhab.org/christoph_wempe/32/70848_2.png) [@christoph\_wempe](https://community.openhab.org/u/christoph_wempe)\
**Post date:** [August 5, 2018, 8:07pm UTC](https://community.openhab.org/t/howto-create-annotations-in-grafana-via-rules/48929/1 "2018-08-05T20:07:52Z")

</div>

Here is a short HowTo about creating Annotations in Grafana via Rules in openHAB.

# What are Annotations?

Annotations are “markers” that can be displayed inside your Grafana graphs to provide more information about your data.

see: [Annotate visualizations | Grafana documentation](http://docs.grafana.org/reference/annotations/)

# How to create Annotations via openHAB

Annotations can be created via the HTTP-API.  
So it is possible to create them via the [HTTP Actions](https://www.openhab.org/docs/configuration/actions.html#core-actions).

To create a single Annotation at this moment you simply need to execute this commands via a rule.

```auto
sendHttpPostRequest("http://admin:mySecretPassword@myGrafanaServer:3000/api/annotations", "application/json", '{"tags":["tag1"],"text":"your description"}')

```

For better readability you can use some variables:

```php
var String url = "http://admin:mySecretPassword@myGrafanaServer:3000/api/annotations"
var String json = '{
    "tags":["test"],
    "text":"your description"
}'
sendHttpPostRequest(url, "application/json", json)

```

You can find more information about the API here: [Annotations HTTP API | Grafana documentation](http://docs.grafana.org/http_api/annotations/)

# Display Annotations in your Dashboard

To display Annotations you did not created by hand in the Grafana Webinterface you need to go to `Settings`of your Dashboard (gears symbol in the right top) and select `Annotations`on the left menu.  
Then you click `New` to create a new Query.  
Define a name and select `Tags`as the filter.

 ![image](https://community-openhab-org.s3.dualstack.eu-central-1.amazonaws.com/original/3X/9/f/9fbcf1b6fe688e5bfb97031c5dd915800892e14d.png)

# Delete the last Annotation an create a new one with `region`

In this example I will create a normal annotation when an event happens (`Test == ON`).  
Once `Test`goes back to `OFF` the previous Annotation will be deleted and a new Annotation will created that will range from the time the item changed to `ON` to the current time is changed to `OFF`.

```php
var long last_Test_On = now.millis
var long last_Test_Off = now.millis
var long last_AnnotationId_On = 0

rule "Test"
    when
        Item Test changed
    then
        logInfo("Test", "Test")
        var String json
        var String url = "http://admin:mySecretPassword@myGrafanaServer:3000/api/annotations"

        if ( Test.state == ON) {
            last_Test_On = now.millis
            json = '{
                "time":' + Long::toString(last_Test_On) + ',
                "tags":["test"],
                "text":"start"
            }'
            logInfo("Test", "url: " + url)
            logInfo("Test", "json: " + json)

            var output = sendHttpPostRequest(url, "application/json", json)

            logInfo("Test", "output: " + output)

			// Save Annotation-ID to use it later
            last_AnnotationId_On = Long.parseLong(transform("JSONPATH","$.id", output))
            logInfo("Test", "last_AnnotationId_On: " + last_AnnotationId_On)
        } else {
            last_Test_Off = now.millis
            json = '{
                "time":' + Long::toString(last_Test_On) + ',
                "isRegion":true,
                "timeEnd":' + Long::toString(last_Test_Off) + ',
                "tags":["test"],
                "text":"start to stop"
            }'
            logInfo("Test", "url: " + url)
            logInfo("Test", "json: " + json)

            var output = sendHttpPostRequest(url, "application/json", json)

            logInfo("Test", "output: " + output)

            // Delete old Annotation
			var String delete_url = url + "/" + last_AnnotationId_On
            var delete_output = sendHttpDeleteRequest(delete_url)
            logInfo("Test", "delete_url: " + delete_url)
            logInfo("Test", "delete_output: " + delete_output)
        }
end

```

(You might want to delete some of the `LogInfo` commands.)

 ![image](https://community-openhab-org.s3.dualstack.eu-central-1.amazonaws.com/original/3X/2/9/29d1ff059d3d7713b9e45696cd890ef4848125d4.png)

# ToDo

I am not sure, but it might be possible and more secure to create an `API key`in Grafana instead of using the `admin` user with the clrear text password.  
But I don’t know how to pass the key via `sendHttpPostRequest`.

This method saves the Annotations in Grafana.  
It is possible to do that in InfluxDB.  
But I don’t know if that is better and how to do so.

---

<div class="post-metadata">

**Author:** ![CDriver](https://community.openhab.org/letter_avatar_proxy/v4/letter/c/a3d4f5/32.png) [@CDriver](https://community.openhab.org/u/CDriver)\
**Post date:** [August 5, 2018, 11:06pm UTC](https://community.openhab.org/t/howto-create-annotations-in-grafana-via-rules/48929/2 "2018-08-05T23:06:03Z")

</div>

Thank you. I can see a number of cases where i can use this.

---

<div class="post-metadata">

**Author:** ![christoph\_wempe](https://community.openhab.org/user_avatar/community.openhab.org/christoph_wempe/32/70848_2.png) [@christoph\_wempe](https://community.openhab.org/u/christoph_wempe)\
**Post date:** [September 20, 2018, 5:03pm UTC](https://community.openhab.org/t/howto-create-annotations-in-grafana-via-rules/48929/3 "2018-09-20T17:03:39Z")

</div>

I edited the first post a little.

I am now using VScode and openHAB 2.4-milestone3.

VScode showed this error.

```auto
Type mismatch: cannot convert from String to long

```

So I added `Long.parseLong()` to

```auto
last_AnnotationId_On = Long.parseLong(transform("JSONPATH","$.id", output))

```

VScode does not show the error anymore.  
But I did not test if everything works now.

---

<div class="post-metadata">

**Author:** ![Bredmich](https://community.openhab.org/user_avatar/community.openhab.org/bredmich/32/30457_2.png) [@Bredmich](https://community.openhab.org/u/Bredmich)\
**Post date:** [June 16, 2020, 5:19pm UTC](https://community.openhab.org/t/howto-create-annotations-in-grafana-via-rules/48929/4 "2020-06-16T17:19:11Z")

</div>

Hi Christoph,

thanks for your HowTo 🙂  
I used your rule and added the API key authentication.

```auto
val String GrafanaAPIKey = "<YourAPIkey>"
val String GrafanaAPIUser = "api_key"

var String url = "http://" + GrafanaAPIUser + ":" + GrafanaAPIKey + "@<yourGrafanaServer>:3000/api/annotations"

```

kind regards  
Michael