searchJobs

Search for jobs in the system

Search the jobs in the system using keywords matching the fields in the jobs. Information about the fields that can be searched can be found in /{orgId}/{itemId}/jobs/{jobId} endpoint about getting a job. Arcade expressions will also be evaluated at run time. For details, see Arcade expression evaluator

Search syntax details

• q - the query for the search you are performing
• search - the match criteria for a simple search
• fields - an array of fields whose value you want to return in the search result. If no fields are defined in the search query, jobName, priority, dueDate and currentStep fields are returned
• displayNames - an array of display names for the fields, stored as part of saved searches
• sortFields - the field based on which you want to sort the results and whether you want to sort the results in ascending or descending order
• start - The index of the results from which you want to start the list of results
• num - The number of results to return in the page
• spatialExtent - Optional. Spatial extent string to filter jobs by their locations
• hasLocation - Optional. Whether or not jobs with defined location in jobLocation are returned

Search can be performed by defining the match criteria with or without field names in the search terms. For example, "search": "High priority" will search for strings High and priority in the jobId, jobName, description, parentName, notes, ownedBy, createdBy, jobPriority, jobStatus, diagramId, jobTemplateId, activeVersions, jobTemplateName, currentStepID, currentStep, assignedType and assignedTo fields. Whereas "q": "priority='High'" will search for string High in the priority field. These can be combined using logical operators like so: "search":"edits","q":"AND priority='High'". To conduct a simple search on multiple terms as one match criteria without field names, enclose them in single quotes such as 'High Priority'. When searching based on names in the assignedTo, createdBy and ownedBy the search criteria is based on the username while the value returned in the fields and sorting is based on the Full Name of the user. Searches by assignment, with currentStep or currentStepId field names in the search terms will filter current steps to ones that match the search criteria, both for users and group. For example, "q": "assignedTo='wmxuser'", "fields":["jobId","currentStep","currentStepId"] will return all jobs with current steps assigned to the wmxuser, and only include those steps. Any steps assigned to other users will be excluded from the results.

Search Operators

The results for the same search string can vary based on the operator used, the operator like will return the results that should match the string whereas, the operator = will return results that must match the search criteria. For example, "q": "currentStep like '%Edit%' or currentStep like '%Data%'" will return all jobs whose currentStep has either string Edit and Data. However, "q": "currentStep='Edit Data'" will return all jobs whose currentStep has exact string Edit Data, in this case any job which has only Edit or Data will not be returned. To get all the jobs in the system use "q": "1=1"

Searching Dates

When searching based on dates, the search criteria must include the time zone to get correct results. For example, to get results based on Pacific Standard Time (UTC - 7 hrs) the criteria would be similar to "q": "dueDate>='2017-05-05T00:00:00-7:00'" All operators for greater than, smaller than, equal are supported for searching dates.

Searching Extended Job Properties

When searching extended job properties, the search criteria must include the table name and property name. For example, to get results based on the value of the field employeeid in the table employees the criteria would be similar to "q": "employees.employeeid = '101'".

Searching Groups

When searching jobs based on assigned groups, the search criteria must use groupID. The returned job assignment will be group name.

Results pagination

The query results can be paginated by pre-defining the number of records to be returned in one page. For example, "num": 10 will return 10 results on the page and "start": 5 will start at the index 6 of the results.

Result syntax details

• q - the query for the search performed
• fields - the fields whose value is returned in the search result along with their field type. If returning extended job properties, it will follow the same format as the search criteria.
• results - an array of results, with value of fields defined in the search criteria returned for each result
• start - The index of the results from which the list of results start on this page
• nextStart - The index of the results from which the list of results will start on next page. If there are no more results, it returns -1.
• num - The number of results returned in the page

Body parameter

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "q": "string",
  "search": "string",
  "fields": [
    "string"
  ],
  "displayNames": [
    "string"
  ],
  "sortFields": [
    {
      "field": "string",
      "sortOrder": "Asc"
    }
  ],
  "spatialExtent": "string",
  "hasLocation": true,
  "start": 0,
  "num": 0
}

Query parameters

Path parameters

Examples

Request

1
2
3
4
5
# You can also use wget
curl -X POST /{orgId}/{itemId}/jobs/search \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Response

200 Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "q": "string",
  "fields": [
    {
      "name": "string",
      "fieldType": "String"
    }
  ],
  "results": [
    [
      {}
    ]
  ],
  "start": 0,
  "nextStart": 0,
  "num": 0
}