Operations Manager search APIs

Operations Manager 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. To get all documents where a field equals a particular value, use:

1
equals[field]=value

This syntax allows the search API to accept multiple field conditions in a single request. For example, to get all jobs with the name Job name 1 and description Job description 1:

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

The API supports querying on nested properties using dotted path notation. For example, to get all tasks started after 2021-11-18:

1
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 using the getJobs and getTasks workflow tasks, respectively. Query parameters are provided to these tasks in JSON object format using the queryParameters variable. To get all documents with a field equal to a particular value:

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

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

1
{
2
  "equals": {
3
    "name": "Job name 1",
4
    "description": "Job description 1"
5
  }
6
}

Response format

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

Example response

1
{
2
  "message": "Human readable message",
3
  "data": {
4
    "some": "data"
5
  },
6
  "metadata": {
7
    "some": "metadata"
8
  }
9
}

Basic examples

To get all jobs with a name starting with Job name prefix:

API format

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

Workflow task format

1
{
2
  "starts-with": {
3
    "name": "Job name prefix"
4
  }
5
}

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

API format

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

Workflow task format

1
{
2
  "include": "_id,name",
3
  "gt": {
4
    "metrics.start_time": "1637279999"
5
  }
6
}

Search operators

equals

The equals operator returns documents with a field exactly matching the specified value. Operations Manager knows the field type, so you do not need to specify whether fields should be interpreted as dates, ObjectIds, booleans, etc.

API format

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

Workflow task format

1
{
2
  "equals": {
3
    "name": "JobName"
4
  }
5
}

starts-with, ends-with, contains

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

API format

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

Workflow task format

1
{
2
    "starts-with": {
3
        "name": "NamePrefix"
4
    }
5
}

1
{
2
    "ends-with": {
3
        "name": "Suffix"
4
    }
5
}

1
{
2
    "contains": {
3
        "description": "InternalString"
4
    }
5
}

in, not-in

The in operator accepts a comma-separated list of options and returns documents with a field exactly equal to one of the specified options. For example, to get jobs with a name of Name 1, Name 2, or Name 3:

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

The not-in operator accepts the same format and returns documents with a field not equal to any of the specified options.

If the search value contains a comma, percent-encode it as %2C to prevent Operations Manager from treating it as a delimiter. For example, to search for jobs named Name,1 or Name,2:

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

API format

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

Workflow task format

1
{
2
    "in": {
3
        "name": "EitherThis,OrThis,OrMaybeThis"
4
    }
5
}

1
{
2
    "not-in": {
3
        "description": "NotThis,NorThis"
4
    }
5
}

gt, lt, gte, lte

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

API format

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

Workflow task format

1
{
2
    "gt": {
3
        "metrics.progress": 0.5
4
    }
5
}

1
{
2
    "lte": {
3
        "metrics.start_time": "1669675620370"
4
    }
5
}

?q=

The ?q= query parameter supports more complex searches than the top-level query parameters, including logical combinations with and, or, and not.

1
{
2
  "equals": { "name": "my name" },
3
  "starts-with": { "description": "Some desc prefix" }
4
}

%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

1
?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 limit the fields returned in the API response using either an inclusive list with include or an exclusive list with exclude.

include

The include parameter accepts a comma-delineated list of property names to include in the response.

API format

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

Workflow task format

1
{
2
  "include": "name,description"
3
}

Response

1
{
2
  "message": "Successfully retrieved items",
3
  "data": [
4
    {
5
      "_id": "000000000000000000000000",
6
      "name": "Job 1",
7
      "description": "Job description 1"
8
    },
9
    {
10
      "_id": "111111111111111111111111",
11
      "name": "Job 2",
12
      "description": "Job description 2"
13
    }
14
  ],
15
  "metadata": {
16
    "skip": 0,
17
    "limit": 100,
18
    "nextPageSkip": null,
19
    "previousPageSkip": null,
20
    "total": 2,
21
    "currentPageSize": 2
22
  }
23
}

exclude

The exclude parameter specifies the set of properties to exclude from the response.

API format

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

Workflow task format

1
{
2
  "include": "name,description",
3
  "exclude": "_id"
4
}

Response

1
{
2
  "message": "Successfully retrieved items",
3
  "data": [
4
    {
5
      "name": "Job 1",
6
      "description": "Job description 1"
7
    },
8
    {
9
      "name": "Job 2",
10
      "description": "Job description 2"
11
    }
12
  ],
13
  "metadata": {
14
    "skip": 0,
15
    "limit": 100,
16
    "nextPageSkip": null,
17
    "previousPageSkip": null,
18
    "total": 2,
19
    "currentPageSize": 2
20
  }
21
}

Sort parameters

Sort parameters arrange query results in a specified order using ?sort=<field> and ?order=<-1|1>. Both parameters must be used together.

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

When querying /jobs, you can use:

1
?sort=metrics.start_time

The sort field must not be excluded from the response via projection parameters.

Pagination parameters

Use ?skip=<number> and ?limit=<number> to control the paging of results:

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

Further reading

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