GetJobList API

Endpoint

POST - /Jobs/GetJobList

Overview

The GetJobList API is used to query jobs and return a list of jobs that match the filter that is provided. This is useful for verifying the existence of a job, or simply returning data to be used for another purpose.

Filtering is based around building up a collection of filters that combine to form a logical “AND” expression. “OR” expressions are currently not supported.

Each filter set is made from the following parameters which are used to specify the search/filter criteria.

• field
• filterType
• stringValue
• integerValue
• dateValue

Input Parameters

excludeClosedJobs

Use this parameter to exclude closed jobs. This boolean field can be set to True, or False.

field

The job field parameter is the field that is being filtered on. The following table displays the fields that are available for filtering, and the data type that they support.

* Note! Only the Summary and Details fields can be used with the FullTextSearch filter type.

Data types

Stringvalue: A text string. eg. “Reset password”

IntegerValue: A number. eg. 58

DateValue: A date string in ISO8601 format. eg. “2020-08-27T04:47:15.352Z”.

Note that the “T” appears literally in the string, to indicate the beginning of the time element, as specified in ISO 8601.

Year: YYYY (eg 1997)
Year and month: YYYY-MM (eg 1997-07)
Complete date: YYYY-MM-DD (eg 1997-07-16)
Complete date plus hours and minutes: YYYY-MM-DDThh:mmTZD (eg 1997-07-16T19:20+01:00)
Complete date plus hours, minutes and seconds: YYYY-MM-DDThh:mm:ssTZD (eg 1997-07-16T19:20:30+01:00)
Complete date plus hours, minutes, seconds and a decimal fraction of a second YYYY-MM-DDThh:mm:ss.sTZD (eg 1997-07-16T19:20:30.45+01:00)

where:

 YYYY = four-digit year
 MM   = two-digit month (01=January, etc.)
 DD   = two-digit day of month (01 through 31)
 hh   = two digits of hour (00 through 23) (am/pm NOT allowed)
 mm   = two digits of minute (00 through 59)
 ss   = two digits of second (00 through 59)
 s    = one or more digits representing a decimal fraction of a second
 TZD  = time zone designator (Z or +hh:mm or -hh:mm)

• Hour is 24 hour format
• Z at end means date is in UTC. (No Z means local time)

filterType

FilterType is the type of filter used against the field. Options include:

• Contains
• StartsWith
• Equals
• NotEqualTo
• GreaterThan
• LessThan
• EndsWith
• FullTextSearch (only valid if SQL Server Full Text Searching is installed and configured)

StringValue

The StringValue is the text value used to filter a field. This value is case insensitive. For some fields, you can use the “IntegerValue” instead of the actual string value - see below.

Example of a single expression that filters on Priority and uses a text value of “Critical”

{
  "excludeClosedJobs": false,
  "filters": [
    {
      "field": "Priority",
      "filterType": "Equals",
      "stringValue": "Critical",
      "integerValue": null,
      "dateValue": null
    }
  ]
}

StringValue with FullTextSearch

Using the FullTextSearch filter may require additional formatting of the JSON string parameter in order to be syntactically correct.

Full Text Searching supports keywords such as “and”, “or”, “not”, and other logical operators. Groups of words can also be groups together to create more complex searches. See Full Text Searching Examples

When groups of words (more than 1 word) are to be treated as a search term, they need to be enclosed in quotes. For example, you may wish to search job details for…

"printer malfunction" OR "paper jam"

In order to pass this search criteria to the WebAPI via JSON, you first need to “escape” the quote marks with a backslash character like this…

{
  "excludeClosedJobs": false,
  "filters": [
    {
      "field": "details",
      "filterType": "FullTextSearch",
      "stringValue": "\"printer malfunction\" OR \"paper jam\"",
      "integerValue": null,
      "dateValue": null
    }
  ]
}

IntegerValue

The IntegerValue is the internal/PKID/“under the hood” value of a field, that can be used instead of the actual text value. This is useful when you wish to filter by the internal number rather than the text-value of a field. The text value of a system code may change over time, however its internal number will always remain the same. See System Codes PKID for more information.

eg. The Priority code “Critical” has an internal “PKID” of 139.

Instead of using the “stringValue” parameter and using “Critical” as the value, the same list of jobs can be found by using the “IntegerValue”, and using the PKID value that corresponds to the text value of “Critical”.

{
  "excludeClosedJobs": false,
  "filters": [
    {
      "field": "Priority",
      "filterType": "Equals",
      "stringValue": null,
      "integerValue": 139,
      "dateValue": null
    }
  ]
}

DateValue

DateValue is a valid JSON date expression.

{
  "excludeClosedJobs": false,
  "filters": [
    {
      "field": "dateLogged",
      "filterType": "GreaterThan",
      "stringValue": null,
      "integerValue": null,
      "dateValue": "2021-06-01T08:00:00"
    }
  ]
}

Combining Filters

Filter can be combined to form a logical “AND” filtering operation. Additional filter blocks are separated with a comma. Add multiple filter blocks to achieve the desired filtering.

The following example combines a “Job type” search with a “Priority” search.

{
  "excludeClosedJobs": false,
  "filters": 
  [
    {
      "field": "JobType",
      "filterType": "Equals",
      "stringValue": "Incident",
      "integerValue": null,
      "dateValue": null
    },
    {
      "field": "Priority",
      "filterType": "Equals",
      "stringValue": "High",
      "integerValue": null,
      "dateValue": null
    }
  ]
}

See also

Jobs Overview

SQL Server Full Text Searching