Ops Manager Search API
  • 06 Jun 2023
  • Dark
    Light
  • PDF

Ops Manager Search API

  • Dark
    Light
  • PDF

Article summary

Operations Manager Search APIs

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

Search API
GET /operations-manager/jobs
GET /operations-manager/tasks
Note:

The information presented herein applies only to the /jobs and /tasks APIs.

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.

Property Description
message This property contains a human readable message, and will always be populated with a string.
data This property contains any data that is directly related to the request. This key will always be present; if it is not applicable to the request (as with error responses), it will be set to null.
metadata This property contains any extra details on the response. When no metadata is available, this will be an empty object. This field is used in several places, including pagination information in search responses, as well as detailed reports on failed imports and input validation failures.


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.

Note:

Specifically for the /jobs API, the description property has special behavior when queried with contains. When filtering over the description field on jobs, MongoDB text search syntax is supported. This allows efficient searching for complex expressions in the description field even when the jobs collection grows very large. Please refer to Text Search in the MongoDB Manual for details on supported behavior.


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.

Note:

When specifying an inclusive list, the _id field is implicitly included, even if it is not specified. To exclude it from the list, use &exclude=_id alongside the include expression to remove it.


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.


Was this article helpful?

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.