Activity Queries
Activity queries allow employees and managers to search for activities that are relevant to them. Queries are helpful if there are many activities that need to be available to employees. Activity queries can be configured to filter out activities based on:
- Query user’s home labor account
- Query user’s labor transfer set
- labor category profile sets
- job transfer sets
- Activity completion and held status
- Activity type (direct or indirect)
- Time period within which activity start or end dates fall
- Activity name
Prerequisites
You must create activities before creating activity queries.
Pre-defined activity queries
Pre-configured activity queries are also known as system queries. They were designed with business needs in mind and to help reduce the number of queries you need to create for your needs.
Note: You cannot edit or delete system queries. To create a query that is based on a system query, duplicate the query, and then edit it.
You can assign system queries to activity query profiles.
The following table lists the pre-configured activity queries. The term “held status” refers to any of the following activity statuses: “Hold,” “Released,” “Never Held or Released.”
| Pre-defined activity query | Description |
|---|---|
| All Activities | Returns all activities within the applicable employee job transfer set and primary job. This query is available to include in query profiles. The query is also the default activity search query for users who do not have an Activities license. |
| Incomplete | Direct and indirect activities that:
|
| Direct | Activities that satisfy all of the following criteria:
|
| Indirect | Activities that satisfy all of the following criteria:
|
Example
In this example, we create, verify, update, and delete an activity query.
Create an activity query
The create request:
- creates a new activity query named: Direct and Not Started
- the query contains a detailed description
- the query contains direct activities that have a Not Started completion status and any held status and that use an employee job transfer set and an employee labor category profile set
Example request
Call the Create Activity Query POST /v1/work/queries operation with the following request payload.
{
"name": "Direct and Not Started",
"description": "This query contains direct activities that have a Not Started completion status and any held status and that use an employee job transfer set and an employee labor category profile set.",
"useEmployeeJobTransferSet": true,
"useEmployeeLaborCategoryProfileSet": true,
"activityTypes": [
{
"id": 1,
"qualifier": "Direct"
}
],
"completionStatuses": [
{
"id": 0,
"qualifier": "Not Started"
}
],
"heldStatuses": [
{
"id": 0,
"qualifier": "Never Held or Released"
},
{
"id": 1,
"qualifier": "On Hold"
},
{
"id": 2,
"qualifier": "Released"
}
],
"queryDateRanges": [],
"version": 1,
"excludeDefaultActivity": true,
"excludeIdleTimeActivity": true,
"excludeUnpaidMealActivity": true,
"excludePaidMealActivity": true,
"default": false
}
Example response
A success response returns HTTP status code 200 and a response body similar to the following example.
{
"id": 501,
"name": "Direct and Not Started",
"description": "This query contains direct activities that have a Not Started completion status and any held status and that use an employee job transfer set and an employee labor category profile set.",
"useEmployeeJobTransferSet": true,
"useEmployeeLaborCategoryProfileSet": true,
"activityTypes": [
{
"id": 1,
"qualifier": "Direct"
}
],
"completionStatuses": [
{
"id": 0,
"qualifier": "Not Started"
}
],
"heldStatuses": [
{
"id": 0,
"qualifier": "Never Held or Released"
},
{
"id": 1,
"qualifier": "On Hold"
},
{
"id": 2,
"qualifier": "Released"
}
],
"queryDateRanges": [],
"version": 1,
"excludeDefaultActivity": true,
"excludeIdleTimeActivity": true,
"excludeUnpaidMealActivity": true,
"excludePaidMealActivity": true,
"default": false
}
Verify
To verify, call the Retrieve Activity Query by ID GET /v1/work/queries/{id} or the Retrieve All Activity Queries or by Name GET /v1/work/queries?name={name} operation.
Calling GET /v1/work/queries/501 or GET /v1/work/queries?name=Direct and Not Started returns:
{
"id": 501,
"name": "Direct and Not Started",
"description": "This query contains direct activities that have a Not Started completion status and any held status and that use an employee job transfer set and an employee labor category profile set.",
"useEmployeeJobTransferSet": true,
"useEmployeeLaborCategoryProfileSet": true,
"activityTypes": [
{
"id": 1,
"qualifier": "Direct"
}
],
"completionStatuses": [
{
"id": 0,
"qualifier": "Not Started"
}
],
"heldStatuses": [
{
"id": 0,
"qualifier": "Never Held or Released"
},
{
"id": 1,
"qualifier": "On Hold"
},
{
"id": 2,
"qualifier": "Released"
}
],
"queryDateRanges": [],
"version": 1,
"excludeDefaultActivity": true,
"excludeIdleTimeActivity": true,
"excludeUnpaidMealActivity": true,
"excludePaidMealActivity": true,
"default": false
}
Note: The Retrieve All Activity Queries or by Name GET /v1/work/queries?name=Direct and Not Started operation returns the object above enclosed in an array, since omitting the name query parameter returns all activity queries in the system.
Update the query
To update the activity query to disallow the use of an employee labor category profile set and to update the description, call the Update Activity Query by ID PUT /v1/work/queries/501 operation with the following request payload.
Example request
{
"id": 501,
"name": "Direct and Not Started",
"description": "This query contains direct activities that have a Not Started completion status and any held status and that use an employee job transfer set and a primary job.",
"useEmployeeJobTransferSet": true,
"useEmployeeLaborCategoryProfileSet": false,
"activityTypes": [
{
"id": 1,
"qualifier": "Direct"
}
],
"completionStatuses": [
{
"id": 0,
"qualifier": "Not Started"
}
],
"heldStatuses": [
{
"id": 0,
"qualifier": "Never Held or Released"
},
{
"id": 1,
"qualifier": "On Hold"
},
{
"id": 2,
"qualifier": "Released"
}
],
"queryDateRanges": [],
"version": 1,
"excludeDefaultActivity": true,
"excludeIdleTimeActivity": true,
"excludeUnpaidMealActivity": true,
"excludePaidMealActivity": true,
"default": false
}
Example response
{
"id": 501,
"name": "Direct and Not Started",
"description": "This query contains direct activities that have a Not Started completion status and any held status and that use an employee job transfer set and a primary job.",
"useEmployeeJobTransferSet": true,
"useEmployeeLaborCategoryProfileSet": false,
"activityTypes": [
{
"id": 1,
"qualifier": "Direct"
}
],
"completionStatuses": [
{
"id": 0,
"qualifier": "Not Started"
}
],
"heldStatuses": [
{
"id": 0,
"qualifier": "Never Held or Released"
},
{
"id": 1,
"qualifier": "On Hold"
},
{
"id": 2,
"qualifier": "Released"
}
],
"queryDateRanges": [],
"version": 2,
"excludeDefaultActivity": true,
"excludeIdleTimeActivity": true,
"excludeUnpaidMealActivity": true,
"excludePaidMealActivity": true,
"default": false
}
Note that the version is automatically incremented to 2. To successfully update this query again, you must pass version 2 in the request body.
Delete the query
To delete this activity query, call the Delete Activity Query by ID DELETE /v1/work/queries/501 operation.
The system returns HTTP status 204 with an empty response body.
Updated over 1 year ago