Saved Search Notification Webhook Feature

Overview

Prior to this release, users have been able to create a Saved Search in Navigo and subscribe to it through their email. When changes occur such as new items being indexed that fall under a Saved Search and its parameters, it will trigger a notification to the user's email of the indexed changes and will send a web hook in the form of a new link of the updated Saved Search.

To support this important feature and meet the needs and requirements of our customers, we added a new way for users to create and subscribe to saved searches. A notification channel type has been created that allows for users to subscribe to the Saved Search and run a POST request that provides an updated endpoint URL and the JSON payload for the body, including the credentials. This added capability allows users to automatically copy newly indexed data to a user-defined directory. Building on the Saved Search Notification framework, the webhook task allows the software to call a web service with parameters to process data in addition to sending a notification email.

Step-by-Step Guide

The user will define a Saved Search and create a webhook task. Using the File Manager, the user will then edit triggers.json linking the Saved Search to the task. When newly indexed data meets the parameters of a Saved Search, the webhook task will then make an HTTP call to the copy data service to process the data. The following steps will walk through how to utilize this new saved search notification feature:

In Navigo, enter search parameters and click the Save Search button
In the Save Search dialog box, enter a name, Share parameter, a Frequency parameter, and click Save

NOTE: Email notifications need to be enabled in HQ if not done so already for a user to be able to enter an email address. Entering an email address is required even though it may not be used.

Log into HQ

(IMPORTANT: This step requires admin access)

On the left panel, go to Indexing > Tasks

In the upper right corner, click “CREATE TASK”
In the Create Task dialog, select “Webhook” at the bottom

In the Create Task dialog, enter a name for the new task
Specify the URL of the service for which the task will be using. In this case, it’s http://loaclhost:10010/copydata. This is a custom Python service that supports the direct copying of data files indexed by Voyager.

NOTE: This endpoint is based on the local HQ configuration. Double check the url in HQ by going to Python > Services.

This service has one required input called “dest” and it’s a folder where the files will be landing when this process is triggered. These are the “Key” and “Value” parameters in the Properties section.

Click “SAVE” once the parameters have been entered
Open the HQ File Manager (%HQ URL%/app/system/file-manager)
Click on tasks.json
In tasks.json, locate the new task “id” and copy it

Click on triggers.json
Locate the Saved Search which needs to run the task

NOTE: The subscribers email address that was provided in the Saved Search will be shown on line 8 for “subscribers”

Replace the “newContentEmail” string in the tasks key with the id copied from tasks.json

NOTE: If email notifications are also required, simply add the Webhook task ID to the task input. For example, [“newContentEmail”, “t195ba3074bb”]. This sends an email and copies the data.

Click “Save” in the upper right corner of the File Manager
Index new data

Disabling the Saved Search Notification Feature

There are three options to disable this functionality:

In Manage UI > My Displays > Saved Searches, turn off the notifications for the saved search
Optionally, delete the Saved Search
Delete the task from HQ > Indexing > Tasks

NOTE: If the task is deleted and the trigger is still running, this error below will be in the logs.

Alternative Guide for Setting Up the Saved Search Notification Feature

Alternatively, follow these steps to set up the notification feature for a Saved Search:

Setup 'Service Task' in your Voyager HQ

Create a Saved Search in Navigo and add a notification
Open the HQ File Manager (%HQ URL%/app/system/file-manager)
Manually edit in the trigger.json and change the task ID to the newly added task. The example below shows how HQ will make the request to the specified endpoint with this payload:

{
   "trigger":{
      "created":1739875844475,
      "diffLink":"http://192.168.0.137:8888/navigo/search?sort=score desc&basemap=ESRI Street Map&ssearch=test&disp=ace4bb77&fq=indexed:[2025-02-19T15:30:04Z TO 2025-02-19T16:11:00Z]",
      "frequency":"MINUTELY",
      "lastExecution":1739979004034,
      "numFound":23,
      "query":"fl=id,title,name:[name],format,abstract,fullpath:[absolute],absolute_path:[absolute],thumb:[thumbURL],path_to_thumb,subject,download:[downloadURL],format_type,bytes,modified,shard:[shard],bbox,geo:[geo],format_category,component_files,ags_fused_cache,linkcount__children,contains_name,wms_layer_name,tag_flags,hasMissingData,layerURL:[lyrURL],hasLayerFile,likes,dislikes,description,keywords,name,name_alias,format_app&start=0&rows=48&sort=score desc",
      "quietPeriod":0,
      "resultLink":"http://192.168.0.137:8888/navigo/search?sort=score desc&basemap=ESRI Street Map&ssearch=test&disp=ace4bb77",
      "subscribers":[
         "[*insert subscibers email address*]"
      ],
      "tasks":[
         "t195194331c2"
      ],
      "unsubscribeLink":"http://192.168.0.137:8888/api/rest/display/ssearch/S19518955494/unsubscribe?token=EdbRs58MS6%2FojP9T1yqlFyh%2F1bnyJAeB",
      "id":"i1951893097f",
      "name":"test"
   },
   "payload":{
      "result":{
         "responseHeader":{
            "indexVersion":3051,
            "status":0,
            "QTime":2,
            "params":{
               "fq":"indexed:[2025-02-19T15:30:04Z TO 2025-02-19T16:11:00Z]",
               "rows":"0",
               "_vgp":"eyJhbGciOiJIUzUxMiIsImNhbGciOiJERUYifQ.eNoUzMsKwjAQheF3OesKGW2JyU7opov6AiIh0VQDkl6mWYnv7mQ383P4vuASYPFe0YDTs55k2qDbENUjSkzMElPe45b9pwa_w5I-GTKdMl2D1zaXRUY3uEs_DlfchYpriVkAe6D6Mac5iyP2pCiQn8iRdudjj98fAAD__w.GjXEBl1PHdMbObqRThiJZu1B2wY80FoKDmnpGooVKObGwdSkyJXvyrD_qI5M5ycvXdE305KnmmjBtRgOAFTiLw",
               "wt":"javabin",
               "version":"2"
            }
         },
         "response":[
            
         ]
      },
      "server":{
         "baseUrl":"http://192.168.0.137:8888/",
         "name":"localhost",
         "server":true,
         "url":"http://192.168.0.137:8888"
      },
      "resultLabel":"results"
   }
}

Additional Examples of Saved Search Notification Configuration

Code for the configuring an email notification channel:

{
  "count": 1,
  "channels": [
    {
      "auth": true,
      "authMethod": "TLS",
      "host": "smtp.gmail.com",
      "password": "bf:oyBv9GDhPfQ-ezqIlTQ365bVRd3WXvffR3qmLyvKNqw",
      "port": 587,
      "sender": "[*insert subscribers email address*]",
      "user": "[*insert subscribers email address*]",
      "id": "n193e5c8c384",
      "type": "email"
    }
  ]
}

A Saved Search notification payload would need to include the Saved Search link similar to how it’s sent to the subscribers email, involving the need for a JSON template.

The API will be used to create the following channel with no user interface needed to configure the POST request of the payload:

{
  "count": 1,
  "channels": [
    {
      "auth": true,
      "post_request_url": "http://localhost:10000/copydata",

      "payload": “{'query': saved search diff link, 'dest': output_folder}
      "password": "bf:oyBv9GDhPfQ-ezqIlTQ365bVRd3WXvffR3qmLyvKNqw",
      "user": "john",
      "id": "n0000000001",
      "type": "request"
    }
  ]
}