REST Extractor Plug-in User Guide

Overview

The REST Extractor plug-in enables you to parse and extract fields from JSON content and turn these into dataviews in Geneos.

The plug-in supports JSON responses coming from a web server or URL.

Dataviews are configured through the use of jq queries. The REST Extractor plug-in uses the jq for Jackson library. For more information, see Application and plug-in specific information in 5.x Compatibility Matrix.

Intended audience

This guide is directed towards Geneos users who want to set up a plug-in to display JSON content in a dataview.

As a user, you should be familiar with REST API. Knowledge of jq is required in order to create specific dataviews.

Prerequisites

Create the REST Extractor sampler

1. In the Gateway Setup Editor, create a new sampler by right-clicking the Samplers folder and selecting New Sampler.
2. Enter a name for this sampler. For example, enter "rest-extractor" in the Name field.
3. Under the Plugin field, click the drop-down list and select rest-extractor.
4. Under Dataviews, enter the information in the fields that appear:
   • In the Name field, enter the name you want for your dataview.
   • In the Url field, enter the source URL from which the REST Extractor plug-in expects a JSON response.
   • In the Query field, enter the jq query you want to use to transform the JSON response into your desired dataview.

   Note: For guidance in using jq for Jackson in queries, see Example queries, responses, and dataviews in REST Extractor Plug-in Technical Reference.

   • In the Row limit field, enter the number of rows you would like the dataview to display.

   Note: You can toggle between data and var for the Row limit field. This toggle option allows you to define either a text or numerical value (data) or variable (var) for this field.

5. If you want the fields from the JSON response to appear in a certain order on the dataview, click the Columns button. Then, click Add new to add the fields in the order you want on the dataview.

Note: The REST Extractor plug-in does not require you to define the columns for the sampler to run. However, we recommend that you establish an order for the columns. For guidance on how to use the columns feature, see Column order in REST Extractor Plug-in Technical Reference

6. If you want to add more dataviews to the sampler, click Add new under the Query box. Then, enter the information in the fields that appear, similar to the previous step.
7. If you want to include any HTTP header in the HTTP request, click the Headers button. Then, click Add new to provide the headers in key-value pairs.
8. If authentication is needed to access the source URL, click the Authentication button.

Note: The REST Extractor plug-in supports basic and bearer authentication, as well as no authentication. The authentication setting depends on the authentication setup in the system that you are monitoring, if any. For guidance in setting up basic or bearer authentication, see Plug-in configuration in REST Extractor Plug-in Technical Reference.

9. Click Save current document to apply your changes.

Success: The sampler can now be associated with a managed entity. This sampler provides the dataviews you have defined.

Associate the REST Extractor sampler with a managed entity

1. In the Gateway Setup Editor, create a new managed entity by right-clicking the Managed entities folder and selecting New Managed entity.
2. Enter a name for this managed entity. For example, enter "rest-extractor" in the Name field.
3. In the Options field, select the probe on which you want the sampler to run.
4. Under the Sampler field, click Add new.
5. In the text field under Ref, select the sampler you just created from the drop-down list.
6. Click Save current document to apply your changes.

Success: The REST Extractor dataviews appear under the managed entity on the Active Console state tree.

Further reading

For more information on the REST Extractor sampler fields, as well as examples of well-formed queries and responses, see the REST Extractor Plug-in Technical Reference.