Itential getJobs API Call

The getJobs API endpoint/canvas task allows us to retrieve detailed job data for one or multiple jobs. It returns a staggering amount of data, and I strongly advise to use the filter options to limit both the number of results and the returned fields. Consider also using pagination (limit and skip options) when retrieving many jobs.
The official API documentation for this endpoint was not really clear to me and I couldn’t figure out how to set the queryParameters to get this API call to work. Luckily, the Itential Service Desk was able to get me on the right track. And I am sharing my lessons learned here.

The getJobs task #

You can use the getJobs task, which is part of the OperationsManager tasks group in IAP Automation Builder, to retrieve data for one or multiple jobs.

Example #

The following screenshot shows an example of how to use the getJobs task.

queryParameters #

The queryParameters determine what and how much data is returned by the getJobs API call.

In this example I want to retrieve ten jobs that are either in a running or paused state. I also only want four data points returned: name, last_updated, status, and created_by.

Here is an example template you can use to send as the queryParameters object in the getJobs task:

{
    "limit": 10,
    "order": 1,
    "sort": "last_updated",
    "include": "name,last_updated,status,created_by",
    "in": {
        "status": "running,paused"
    }
}

Check out the schema definition for more options.

As mentioned at the beginning, you will want to limit the amount of data returned by this API call. Make good use of the in, not-in, and equals filters and limit the returned fields using the include parameter.

Example Input/Output #

Input

{
    "limit": 10,
    "order": 1,
    "sort": "last_updated",
    "include": "name,last_updated,status,created_by",
    "in": {
        "status": "error"
    }
}

Output (truncated)

{
  "result": {
    "message": "Successfully retrieved items",
    "data": [
      {
        "_id": "218ca51de2ee46db804708fa",
        "created_by": "616736faae58e11d5875293e",
        "last_updated": "2023-07-10T13:35:30.069Z",
        "name": "child-updateUserDatetimeTimeZone",
        "encodingVersion": 1,
        "status": "error"
      }
    ]
}

Parent vs. Child Jobs #

Some job entries in the API output will have a property called parent, while others don’t. This allows us to easily distinguish child jobs from parent jobs.
If the job has a parent property, it’s a child job. Otherwise, it’s either a parent job or simply one with no child jobs.

Lookup data using the Dereference option #

The dereference option allows us to join data from another Mongo document using foreign keys.

In the previous example we could see that the created_by value returned by the getJobs API is just a foreign key value by default.

“created_by”: “616736faae58e11d5875293e”

Let’s get some user data using this foreign key. You will need to know in which Mongo collection the data behind the foreign key lives in. The created_by value corresponds to the id in accounts.

Prefix the foreign key value with the proper collection name and add it as a string to the dereference option.
In our example we are joining the accounts data using the created_by key like this:

“dereference”: “accounts.created_by”

You can look up multiple values by chaining them as a comma-separated string.

By default, this will return the all the user’s information. To limit the amount of data we join, we can specify which field(s) we want to be returned by using the include option.

Let’s assume we only want the get the firstname value for our user from the accounts collection. So, we update our include filter as follows:

“include”: “name,last_updated,status,created_by.firstname”

Input

{
    "limit": 10,
    "order": 1,
    "sort": "last_updated",
    "include": "name,last_updated,status,created_by.firstname",
    "in": {
        "status": "error"
    },
    "dereference": "accounts.created_by"
}

Output

{
  "result": {
    "message": "Successfully retrieved items",
    "data": [
      {
        "_id": "218ca51de2ee46db804708fa",
        "created_by": {
          "firstname": "Spongebob"
        },
        "last_updated": "2023-07-10T13:35:30.069Z",
        "name": "child-updateUserDatetimeTimeZone",
        "encodingVersion": 1,
        "status": "error"
      }
    ]
}

The created_by field in the API response now shows a user object containing the first name of the user instead of a foreign key value.