About this task

In this article, we explain how you can connect you BVQ to a third party (ITSM) application and send Alert Results via notifications

Applies to

all BVQ Versions

Procedure

Starting with version 2022.H2.3 we reworked the way how notifications are formatted in BVQ°.

You are now able to chose between YAML and JSON formatting.
This allows us to process the results of an alert even more effectively.

In this article, we have chosen to hand over the results to a PowerShell script.
So please select "Executable" as the type of your new notification configuration.

Now give your notification configuration a suitable NAME.

In short, the EXECUTABLE COMMAND has to be in the form of [<environment>] <script> <parameter>.

In the example we are running PowerShell in a Linux environment, so the complete command for us looks like

/usr/bin/pwsh /server-data/notification-data/notificationHandler.ps1 ${text}

Please make sure to use ${text} and not ${attachment} here to get the content of the alert results as shown in the preview section.

Since PowerShell comes with proper built-in JSON handling functionality, we go with "JSON" as NOTIFICATION FORMAT:

Feel free to use the fields SUBJECT PREFIX, ENVIRONMENT DESCRIPTION, CONTACT INFORMATION, COMMENT and NOTIFICATION TYPE as needed in your use case.

Please note that the script is called once per alert calculation run an not per alert result.

Now you can simply select the configured notification in the desired alert configuration(s):

Let's have a look at the processing ...
In the transferred content, we have an array[ ] of matching objects:

...
"affectedObjects" : [ {
    "object" : {
      "name" : "4865f1ce-546c-11ed-bdc3-0242ac120002",
...

Our PowerShell script looks as follows.

## notification handler for BVQ alert notifications (of type "executable")

## with the ${attachment} flag the linked file ist empty
## you have to use ${text}
$str = Get-Content $args[0] -Raw

## make sure it starts as valid JSON
$index = $str.IndexOf("{")
$str = $str.Substring($index)

if ($str | Test-Json) {
    $myJson = $str | ConvertFrom-Json
} else {
    "<<<NO JSON>>>"  | Out-File /server-data/notification-data/run.log -Append
    exit 1
}

$comment = ''
if ( $myJson.bvqNotification.Comment ) {
    $comment = $myJson.bvqNotification.Comment
}

foreach( $affectedObject in $myJson.affectedObjects ) {
    $change = ''
    $name = ''

    if ( $affectedObject.alertLevel.change ) {
        $change = $affectedObject.alertLevel.change
    }
    if ( $affectedObject.object.name ) {
        $name = $affectedObject.object.name
    }

    $postData = '{"name":"[' + $change + '] ' + $name `
        + '", "desc":"\n\n**Comment:**\n' + $comment + '"}'

    $param = @{
        Uri         = "<https://api.my-application.com/>"
        Method      = "Post"
        ContentType = "application/json"
        Body        = $postData
    }
    Invoke-RestMethod @param
}

At first, we load the content from the given filename (provided by ${text}).

The substring trimming is just to make sure that the content starts with the opening curly bracket.
Afterwards we convert the file content to a corresponding object.
Now we're able to access all necessary attributes from the object.

As already said, the matching BVQ objects are presented in an array we can iterate on:

foreach( $affectedObject in $myJson.affectedObjects ) { ...

Collect what you need for your purpose from the object, create the payload for your API request and invoke it via "Invoke-RestMethod".

In our case we limited that to the Alert Level Change, the object name and the global BVQ notification comment we entered in the notification configuration.

In our demo we created a simple Trello board and pushed only errors (this is configurable in the Alert configuration) as incidents via API to the board: