Search API

Operations Manager Search APIs

Operations Manager (OM) includes two search APIs that support advanced functionality through query parameters.

Query Parameter Syntax

Operations Manager uses an object syntax to express operators and their relationship to the fields they operate on. For example, to get all documents that have a field equal to a particular value, use the following syntax:

equals[field]=value

This syntax allows the search API to accept multiple field conditions in a single request. Likewise, to get all the jobs with the name Job name 1 and description Job description 1, the following request could be made:

GET /operations-manager/jobs?equals[name]=Job name 1&equals[description]=Job description 1

The API supports querying on nested properties within a document using dotted path notation. For example, to get all tasks which were started after 2021-11-18, the following request could be made:

GET /operations-manager/tasks?gt[metrics.start_time]=2021-11-18T23:59:59

Workflow Task Query Parameter Syntax

The /operations-manager/jobs and /operations-manager/tasks APIs can be invoked in workflows by using the getJobs and getTasks workflow tasks, respectively. Query parameters are provided to these tasks in JSON object format using the queryParameters variable. For example, to get all documents that have a field equal to a particular value, use the following syntax:

{ "equals": { "field": "value" } }

To get all jobs with the name Job name 1 and description Job description 1:

{
  "equals": {
    "name": "Job name 1",
    "description": "Job description 1"
  }
}

Response Format

Operations Manager standardizes the top-level structure of all responses, both success and error, with the following fields.

Example Response

{
  "message": "Human readable message",
  "data": {
    "some": "data"
  },
  "metadata": {
    "some": "metadata"
  }
}

Basic Examples

To get all jobs that have a name starting with the string 'Job name prefix':

Example API Format

GET /operations-manager/jobs?starts-with[name]=Job name prefix

Example Workflow Task Format

{
  "starts-with": {
    "name": "Job name prefix"
  }
}

To get the IDs and names of all jobs started after November 18, 2021, use Unix epoch time format (1637279999):

Example API Format

GET /operations-manager/jobs?include=_id,name&gt[metrics.start_time]=1637279999

Example Workflow Task Format

{
  "include": "_id,name",
  "gt": {
    "metrics.start_time": "1637279999"
  }
}

Search Operators

This section outlines the available search operators used to narrow the focus of a search query.

equals

The equals operator returns documents with a field exactly matching the specified value. The field type is known to Operations Manager, meaning there is no need for an API consumer to specify which fields should be interpreted as Dates, ObjectIds, booleans, etc. Operations Manager will interpret the value according to the structure of the document being queried.

Example Requests

API Format

GET /operations-manager/jobs?equals[name]=JobName

Workflow Task Format

{
  "equals": {
    "name": "JobName"
  }
}

starts-with, ends-with, contains

These three related search operators return documents with a field that either starts-with, ends-with, or contains the specified string.

Example Requests

API Format

GET /operations-manager/jobs?starts-with[name]=NamePrefix
GET /operations-manager/tasks?ends-with[name]=Suffix
GET /operations-manager/jobs?contains[description]=InternalString

Workflow Task Format

{
    "starts-with": {
        "name": "NamePrefix"
    }
}

{
    "ends-with": {
        "name": "Suffix"
    }
}

{
    "contains": {
        "description": "InternalString"
    }
}

in, not-in

The in operator accepts a comma-separated list of options and returns documents with a field that is exactly equal to one of the specified options.

For example, to get jobs with a name of either Name 1, Name 2, or Name 3, the following request could be used:

GET /operations-manager/jobs?in[name]=Name 1,Name 2,Name 3

The not-in operator also accepts a comma-separated list of options and returns documents with a field that is not equal to any of the specified options.

If the search value contains a comma, it is important to explicitly percent encode that comma (a comma is percent encoded as %2C), otherwise Operations Manager will interpret it as multiple options rather than a single option with comma characters inside. For example, to search for jobs with a name of either Name,1 or Name,2, use the following request:

GET /operations-manager/jobs?in[name]=Name%2C1,Name%2C2

The in and not-in operators interpret the items in the option list according to the type of the specified field, as with the equals operator.

Example Requests

API Format

GET /operations-manager/jobs?in[name]=EitherThis,OrThis,OrMaybeThis
GET /operations-manager/tasks?not-in[description]=NotThis,NorThis

Workflow Task Format

{
    "in": {
        "name": "EitherThis,OrThis,OrMaybeThis"
    }
}

{
    "not-in": {
        "description": "NotThis,NorThis"
    }
}

gt, lt, gte, lte

These operators provide support for comparison operators in searches. Use gt for greater than comparisons, lt for less than, gte for greater than or equal to, and lte for less than or equal to.

The values provided to these operators are interpreted based on the type of the specified field, as with the equals, in, and not-in operators.

Example Requests

API Format

GET /operations-manager/jobs?gt[metrics.progress]=0.5
GET /operations-manager/jobs?lte[metrics.start_time]=1637279999

Workflow Task Format

{
    "gt": {
        "metrics.progress": 0.5
    }
}

{
    "lte": {
        "metrics.start_time": "1669675620370"
    }
}

?q=

The ?q= query parameter exposes a way of doing more complex searches than are possible with other top-level query parameters. The advantage of this parameter is that it not only supports all top-level query parameters as described above, but also logical combinations of those parameters with and, or, and not.

To use the ?q= query parameter:

1. Create a query string in JSON object format:

   {
     "equals": { "name": "my name" },
     "starts-with": { "description": "Some desc prefix" }
   }
   

   
   

2. URL encode the JSON object using encodeURLComponent.

   %7B%22equals%22%3A%7B%22name%22%3A%22my%20name%22%7D%2C%22starts-with%22%3A%7B%22description%22%3A%22Some%20desc%20prefix%22%7D%7D
   

   
   

3. Construct a new query string in which the encoded JSON object is passed to the ?q= query parameter:

   ?q=%7B%22equals%22%3A%7B%22name%22%3A%22my%20name%22%7D%2C%22starts-with%22%3A%7B%22description%22%3A%22Some%20desc%20prefix%22%7D%7D
   

   
   

Projection Parameters

Projection parameters are used to limit the fields returned in the API response. The fields returned may be specified either using an inclusive list with include, or an exclusive list with exclude.

include

The include parameter accepts a comma-delineated list of property names. This specifies the set of properties to include in the API response.

Example Request and Response

API Format

GET /operations-manager/jobs?include=name,description

Workflow Task Format

{
  "include": "name,description"
}

Response

Note the properties included in the data array.

{
  "message": "Successfully retrieved items",
  "data": [
    {
      "_id": "000000000000000000000000",
      "name": "Job 1",
      "description": "Job description 1"
    },
    {
      "_id": "111111111111111111111111",
      "name": "Job 2",
      "description": "Job description 2"
    }
  ],
  "metadata": {
    "skip": 0,
    "limit": 100,
    "nextPageSkip": null,
    "previousPageSkip": null,
    "total": 2,
    "currentPageSize": 2
  }
}

exclude

The exclude parameter specifies the set of properties to exclude in the API response.

Example Request and Response

Note the addition of &exclude=_id.

API Format

GET /operations-manager/jobs?include=name,description&exclude=_id

Workflow Task Format

{
  "include": "name,description",
  "exclude": "_id"
}

Response

{
  "message": "Successfully retrieved items",
  "data": [
    {
      "name": "Job 1",
      "description": "Job description 1"
    },
    {
      "name": "Job 2",
      "description": "Job description 2"
    }
  ],
  "metadata": {
    "skip": 0,
    "limit": 100,
    "nextPageSkip": null,
    "previousPageSkip": null,
    "total": 2,
    "currentPageSize": 2
  }
}

Sort Parameters

Sort parameters arrange query results in a specified sequence (order) for any extracted data or list elements. Sorting is activated by ?sort=< field > and ?order=< -1 | 1 >.

Use both parameters to specify the sort order; in other words, they must be used together (cannot skip one).

• order must be -1 or 1
• sort must be a valid field path within the queried document type

When querying /jobs, you can provide:

?sort=metrics.start_time

But do not use:

?sort=metrics.some_other_field

The sort parameter must not be excluded from the resulting document with projection parameters.

Pagination Parameters

Most API endpoints that return a list of entities have some sort of pagination. Use the ?skip=< number > and ?limit=< number > parameters to limit the results returned by the query and control the paging of all documents returned in a result set.

• skip and limit must be numbers
• limit defaults to 100 and skip defaults to 0

Further Reading

For more information about Operations Manager APIs, refer to the app-operations_manager section of the Itential API References.