Activity Queries

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: Have a completion status of “Incomplete” Have any held status Use an employee job transfer set and primary job
Direct	Activities that satisfy all of the following criteria: Are classified as “Direct” Have a completion status of “Not Started” or “Incomplete” Have any held status
Indirect	Activities that satisfy all of the following criteria: Are classified as “Indirect” Have a completion status of “Not Started” or “Incomplete” Have any held status

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.