Search API

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

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.

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.

Result Group

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

Individual Search Result Value

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

Currently Supported Itential Applications

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

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.