Search API
  • 01 Sep 2022
  • Dark
    Light
  • PDF

Search API

  • Dark
    Light
  • PDF

Article Summary

The Search API provides a simple way to search the MongoDB databases long as your data is properly exposed to the Itential Automation Platform (IAP) search engine. This guide explains how to set indexes and expose your data collections with search objects.

Note: Only use this guide to modify custom applications. Do not modify or update the Pronghorn (Itential) applications.

Exposing an Application for Searching

A database collection may be searched if the collection is exposed with a search object. This search object is added to the pronghorn.json file and consists of an object, or an array of objects, that follow the schema below.

Search Object Attributes

Attribute Description
Label The name of the application that is used when displaying search results. For example: "Mop Template" or "Workflow".
Collection The name of the collection to search.
Fields An array of objects containing fields to search. Name: The field name to search. Type: The type of data. Only type "string" is supported.
Map An object that will format the returned data in a specific way. Name: A field name reference. For example, if the title field is exposed to being searched, set the value to "title" to return the title value as the name for each result.

Description: A field name reference. Can be null, as many database results will not have a description. URL: The absolute path used for users to access the content they have found. Uses a mustache template system; therefore, field values are available as variables using the mustache syntax {{variable}}. In addition to your exposed field values, you also have access to the mongo_id field .


Examples

Use the following examples to set the search template and search exposure object.

Empty Search Template

    // Place this in pronghorn.json.
    "search": {
      "label": "YOUR APP NAME",
      "collection": "DATABASE COLLECTION NAME",
      "fields": [
        {
          "name": "FIELD TITLE",
          "type": "FIELD TYPE (only "string" supported currently)"
        }
      ],
      "map": {
        "name": "FIELD REFERENCE NAME",
        "description": "FIELD REFERENCE NAME (can be null or empty)",
        "url": "/myapp/{{EXAMPLE_VAR}}?myvar={{EXAMPLE_VAR}}"
      }
    },

Search Exposure Object

    "search": {
      "label": "Mop",
      "collection": "mop_templates",
      "fields": [
        {
          "name": "name",
          "type": "string"
        }
      ],
      "map": {
        "name": "name",
        "description": null,
        "url": "/mop/template?name={{name}}"
      }
    },

Text Only - Currently, you can only search on text-based fields ("type": "string"). Other types may be supported in the future.

Create Index for Exposed Collections

You will need to create the proper indexes for your fields to be search enabled. For MongoDB, simple compound indexes are used. You list each field name followed by the number 1 as the field value. For more detailed information on creating indexes, refer to: MongoDB Method Reference db.collection.createIndex().

Index Must Match Fields - The compound index must match the fields in the search template. For example, if you want to search on name and type, you must have a compound index on name and type.

To create an index against a local instance for testing:

  1. Run the following command in a MongoDB collection browser. This example creates an index on the MOP templates collection for name. This index will persist to the local database, but if it is dropped it will need to be recreated.

    db.getCollection('mop_templates').createIndex({ "name": 1 }, { background: true });
    

Note: Be careful when setting indexes and exposing items to search. If done incorrectly, it can have a profound negative impact. To avoid potential issues, adhere to the following guidelines.

  • Be careful not to create too many indexes! Too many indexes will slow down inserts into the database, which is not good.
  • Always verify background is set to true when creating indexes. This supports performance at scale.
  • Test the addition of search objects in a lab environment to monitor performance before they are released into production.

Making a Search Request

The following attributes are used to make a search request.

Search API Endpoint POST /search/find
POST Body The post object consists of a data object with a text property that contains the value to search on.

Examples

Use the following examples to set your search object.

Empty Request

Here is an empty request example.

{
    "data": {
        "text": "TEXT TO SEARCH ON"
    }
}

Search Object

Here is an example search object, searching on the word workflow.

 {
    "data": {
        "text": "workflow"
    }
}

Search Results

The results that are returned follow the map object that was configured above, with the addition of the _id and tags fields. You can now display these results to the user, allowing them to find and navigate to content throughout the system.

{
    "results": [
        {
            "label": "Mop",
            "type": "mop_templates",
            "results": [
                {
                    "_id": "workflow helper",
                    "name": "workflow helper",
                    "description": "",
                    "url": "/mop/template?name=workflow%20helper",
                    "tags": [
                        {
                            "_id": "5c37ada0788ede01a2b62b47",
                            "name": "Awesome",
                            "description": "Sauce"
                        }
                    ]
                },
                {
                    "_id": "workflow helper two",
                    "name": "workflow helper two",
                    "description": "",
                    "url": "/mop/template?name=workflow%20helper%20two",
                    "tags": []
                }
            ],
            "count": 2
        },
        {
            "label": "Workflows",
            "type": "workflows",
            "results": [
                {
                    "_id": "51fdc757-076a-41d6-9e51-bf7856aabb28",
                    "name": "Delay Workflow",
                    "description": "",
                    "url": "/workflow_builder/edit?name=Delay%20Workflow",
                    "tags": []
                },
                {
                    "_id": "b087eecc-15ab-490c-b592-42194c24584f",
                    "name": "Workflow Form",
                    "description": "",
                    "url": "/workflow_builder/edit?name=Workflow%20Form",
                    "tags": [
                        {
                            "_id": "5c35161afc3301a3d4c9505e",
                            "name": "Stage One",
                            "description": "Stage one related details"
                        },
                        {
                            "_id": "5c351628fc3301a3d4c9505f",
                            "name": "Stage Two",
                            "description": "Stage two related details"
                        }
                    ]
                }
            ],
            "count": 2
        }
    ],
    "totalCount": 4
}

Top Level Result

Below are attributes for the top level fields of the example search result.

Field Type Value
results Array An array of search results grouped by collection type.
totalCount Number Total count of all results.

Result Group

The attributes of the result group are outlined in the table below.

Field Type Value
Label String Display name.
Type String Collection name.
Results Array Array of results.
Count Number Total results count for this group.

Individual Search Result Value

The field values for the individual results in the example are presented in the table below.

Field Type Value
_id String The id of the search result.
Name String Name of the result.
Description String Description of the result.
URL String URL path to access content.
Tags Array List of tags for each result.

Currently Supported Itential Applications

The following Itential applications already have search objects and indexes on the following fields.

Application Search Enabled Fields
Workflow Name
Mop Templates Name
Forms Name
Golden Config Name

Additional Information

Currently, the Search REST API is only used by the site-wide search box that is available in the top navigation bar. You can, however, use the results in your own application, if needed.


Was this article helpful?

What's Next
Changing your password will log you out immediately. Use the new password to log back in.
First name must have atleast 2 characters. Numbers and special characters are not allowed.
Last name must have atleast 1 characters. Numbers and special characters are not allowed.
Enter a valid email
Enter a valid password
Your profile has been successfully updated.