Documentation
What's NewUKG.comMarketplaceUKG Pro status

Data Query Nodes

Person and ITM query nodes for retrieving workflow context and business data.

Data Query Nodes

Note: Compose is only available for Beta testing. See Welcome to UKG Compose > Beta Disclosure for more information.

Data query nodes retrieve UKG-related information so workflows can identify records, enrich requests, find identifiers, branch based on values, or prepare later steps. This page uses the same terminology you see in the editor (node, workflow, execution, query result, empty result, etc.).

UKG Compose provides two query nodes: Person for person-related information and ITM for ITM business records.

Data query nodes in UKG Compose

  • Person - Retrieve person-related information including identity, supervisor, and RBAC details; used for recipient lookup and approver resolution
  • ITM - Retrieve ITM business records including assignments, applications, and growth-goal context; used for enriching ITM-oriented workflows

Use data query nodes when a workflow must:

  • Look up a person, supervisor, or RBAC-related identity
  • Find an ITM assignment, application, or related record
  • Retrieve data before sending a notification
  • Retrieve identifiers before running an approval or update node
  • Validate whether the workflow should continue down one path or another

These nodes are often paired with IF or Switch to branch based on results, notification nodes that need recipients (see Notification Nodes), approval nodes that need approvers or identifiers (see Approval and Workflow Nodes), API integration nodes that need employee IDs (see API Integration Nodes), and triggers that start the workflow (see Webhook Triggers).

When to use Person

Use Person when the workflow needs to retrieve person-related information.

This node is the best fit when:

  • The workflow needs to look up a person by an identifier
  • The workflow needs supervisor or manager context
  • The workflow needs RBAC- or identity-related person details
  • A later step depends on the correct person record or person identifier

Typical scenarios include:

  • Resolving a recipient before sending a notification
  • Finding the supervisor for an approval or escalation
  • Looking up a person from an employee or identity value supplied by the trigger
  • Retrieving person context before an HR update or workflow action

When to use ITM

Use ITM when the workflow needs to retrieve ITM-related business records.

This node is the best fit when:

  • The workflow needs to find an assignment, application, or related ITM record
  • The workflow must enrich a process with ITM context before taking action
  • A later node depends on an ITM identifier or returned business object
  • The process is centered on a growth, assignment, or job-match workflow

Typical scenarios include:

  • Retrieving an assignment before approval or rejection
  • Finding an assignment application before acting on it
  • Retrieving ITM data before notifying a user or approver
  • Enriching a workflow with growth-goal or job-match context

Choosing between the two nodes

Use this simplified decision model:

Choose Person when:

  • The workflow needs person identity, supervisor, or RBAC-related context
  • The next step depends on the right person record or person identifier
  • The workflow must determine who should receive a message or take action

Choose ITM when:

  • The workflow needs assignment, application, growth-goal, or other ITM business context
  • The next step depends on an ITM record
  • The business process is centered on ITM data rather than person identity alone

Common lookup patterns

Trigger to person lookup to notification

Pattern:

  1. Trigger starts the workflow (see Webhook Triggers).
  2. Person looks up the target person or supervisor.
  3. Workflow extracts the identifier or recipient detail needed.
  4. Notification sends the message (see Notification Nodes).

Use this pattern when the workflow starts with a business event or submitted request but still needs to determine the right recipient.

Trigger to person lookup to approval action

Pattern:

  1. The request or event starts the workflow.
  2. Person retrieves approver or actor identity.
  3. IF or Switch confirms the correct path.
  4. Approval or workflow action node uses the returned identifier.

Use this pattern when the workflow cannot proceed until the correct acting person is resolved.

Trigger to ITM lookup to approval

Pattern:

  1. Trigger starts the workflow
  2. ITM retrieves the assignment, application, or related record
  3. Workflow evaluates the returned business object
  4. ItmApproval or another downstream node acts on the record

Use this pattern when the action depends on first retrieving the correct ITM record.

Query to branch logic

Pattern:

  1. Trigger starts the workflow.
  2. Query node returns data.
  3. IF or Switch evaluates whether a record was found or which values were returned.
  4. The workflow continues down the appropriate path.

Use this pattern when the workflow must handle:

  • Found vs not found
  • Manager vs non-manager
  • Active vs inactive
  • Assignment type differences
  • Other data-based routing decisions

Inputs that matter

Public documentation should focus on the practical inputs that matter to builders.

Person inputs

A Person lookup may depend on identifiers such as:

  • Person ID
  • Pro HR person ID
  • SSO-related identity
  • RBAC person identifier
  • Other supported lookup values

Builders should know which identifier they actually have at the point where the query node runs.

ITM inputs

An ITM lookup may depend on:

  • Assignment identifier
  • Application identifier
  • Activity or related business object identifier
  • Resource type or record type context
  • Other supported ITM lookup inputs

Builders should confirm which business record the workflow is actually trying to retrieve.

Outputs that matter

Later nodes may depend on:

  • Whether a record was found
  • The returned person or ITM identifier
  • Supervisor or relationship data
  • Assignment or application metadata
  • Values used for routing, notification, approval, or update steps

Builders do not need every low-level response field in the public guide, but they do need to understand how query results shape the next step in the workflow.

Data freshness and query expectations

Query nodes can introduce an important design consideration: the returned data may reflect a query layer rather than an immediate transaction response.

Builders should understand:

  • Query results may not always feel fully real-time in every scenario
  • Workflows should be designed to handle empty, missing, or older-than-expected data gracefully
  • Query results should be validated before being used in downstream action nodes

This is especially important when a later step writes data, sends an approval request, or assumes the returned record is ready for action.

Handling empty or partial results

A query that returns no result is not always a workflow failure. It may be a valid business outcome that the workflow needs to handle explicitly.

Design for:

  • No matching person found
  • No supervisor returned
  • No matching ITM record found
  • Partial data returned
  • Record found, but missing a value needed by the next step

A good pattern is:

  1. Query the record.
  2. Use IF or Switch to evaluate whether the required result exists.
  3. Route the workflow to a normal path or exception path.

Tips for working with data query nodes

  • Use query nodes early enough in the flow to prepare later steps with the identifiers they need.
  • Always validate whether the query returned the expected record before continuing to a notification, approval, or update node.
  • Use IF or Switch to separate found and not-found paths.
  • Be explicit about which identifier the workflow is using before the query runs.
  • Use returned person or ITM values to enrich downstream nodes rather than hard-coding assumptions.
  • Review Execution History to inspect the query inputs and outputs when troubleshooting.
  • Design workflows to handle empty results, not just successful lookups.
  • Be cautious when treating query results as fully immediate if the workflow depends on very recent upstream changes.

Common pitfalls to avoid

  • Using the wrong identifier type for the query
  • Assuming the query returned a record without checking the actual output
  • Passing an empty result into a later action node
  • Confusing person identity lookup with ITM business record lookup
  • Assuming query data is always current enough for a sensitive downstream action without validation
  • Not adding an exception path for missing or partial results

Troubleshooting query issues

When a query-based workflow does not behave as expected, start with:

  • Whether the query node executed successfully
  • Whether the workflow passed the correct identifier to the query
  • Whether the query returned a record, an empty result, or partial data
  • Whether the workflow used the returned values correctly in later nodes
  • Whether the IF or Switch logic handled empty and found results correctly
  • Whether the next node failed because the expected identifier was not available

For operational troubleshooting patterns, use the Administration and Operations page together with this one.

Related nodes and workflow patterns

Data query nodes are commonly used with:

  • IF and Switch for result-based routing
  • Notification to send communication to resolved recipients
  • Approval and workflow nodes that require a person or business record identifier
  • API integration nodes that need employee context before a system-of-record update
  • Webhook, form, schedule, or event triggers that start the process
  • Error Trigger and exception branches for not-found or invalid-result handling

Related pages

Other node types:

Conceptual pages:

Updated 8 days ago