Overview
The Matching Service is responsible for:- Managing task queues for workflows and activities
- Distributing tasks to available workers
- Task queue partitioning and load balancing
- Worker versioning and build ID compatibility
- Task queue user data and configuration
- Nexus endpoint management
- Worker heartbeat and health tracking
Service Methods
Task Polling
PollWorkflowTaskQueue
Polls for a workflow task from a task queue.UUID of the namespace
Unique identifier for the worker polling
Poll parameters including task queue name and worker identity
Source partition if forwarded from another partition
Opaque token identifying the task
Workflow execution information
Type of the workflow
Event ID when task started
Workflow history events for the task
PollActivityTaskQueue
Polls for an activity task from a task queue.Namespace UUID
Unique poller identifier
Poll parameters
Source partition if forwarded
Task token
Parent workflow execution
Activity identifier
Type of activity
Activity input parameters
When the activity was scheduled
When current attempt was scheduled
PollNexusTaskQueue
Polls for a Nexus task from a task queue.Namespace UUID
Poll request with task queue and worker identity
Token for the Nexus task
Nexus request details
Task Addition
AddWorkflowTask
Adds a workflow task to a task queue.Namespace UUID
Workflow execution identifier
Target task queue
Event ID when task was scheduled
Source of the task (history, backlog)
Source if forwarded from another partition
Empty response on success
AddActivityTask
Adds an activity task to a task queue.Namespace UUID
Parent workflow execution
Target task queue
Event ID when activity was scheduled
Task source
Forwarding source partition
Empty response on success
Query Management
QueryWorkflow
Forwards a workflow query to a worker.Namespace UUID
Task queue where workflow is processing
Query parameters
Source partition
Result of the query
Rejection details if query was rejected
RespondQueryTaskCompleted
Records completion of a query task.Namespace UUID
Task queue
Query task identifier
Completion details
Nexus Operations
DispatchNexusTask
Dispatches a Nexus task to a worker.Namespace UUID
Target task queue
Nexus request to dispatch
Nexus response from worker
RespondNexusTaskCompleted
Records successful completion of a Nexus task.Namespace UUID
Nexus task token
Task response
RespondNexusTaskFailed
Records failure of a Nexus task.Namespace UUID
Nexus task token
Failure error details
Nexus Endpoint Management
CreateNexusEndpoint
Creates a new Nexus endpoint.Endpoint specification including name, target
Created endpoint with assigned ID
UpdateNexusEndpoint
Updates an existing Nexus endpoint.Endpoint ID
Current version for optimistic concurrency
Updated endpoint specification
Updated endpoint
DeleteNexusEndpoint
Deletes a Nexus endpoint.Endpoint ID to delete
Current version
Empty response on success
ListNexusEndpoints
Lists all Nexus endpoints.Maximum endpoints per page
Pagination token
List of endpoints
Token for next page
Task Queue Description
DescribeTaskQueue
Retrieves information about a task queue.Namespace UUID
Description request with task queue name and type
List of active pollers
Task queue status including backlog
Version information for versioned task queues
DescribeTaskQueuePartition
Retrieves information about a specific task queue partition.Namespace UUID
Task queue identifier
Partition ID
Pollers on this partition
Partition configuration
DescribeVersionedTaskQueues
Describes task queues with versioning information.Namespace UUID
Task queue name
Version selection criteria
Information for each versioned queue
ListTaskQueuePartitions
Lists all partitions for a task queue.Namespace name
Task queue identifier
Activity task queue partitions
Workflow task queue partitions
Worker Versioning
UpdateWorkerBuildIdCompatibility
Updates build ID compatibility rules for a task queue.Namespace UUID
Task queue name
Build ID operation (add, promote, mark_default)
Empty response on success
GetWorkerBuildIdCompatibility
Retrieves build ID compatibility rules.Namespace UUID
Task queue name
Maximum compatibility sets to return
Compatible version sets
UpdateWorkerVersioningRules
Updates versioning rules for workers.Namespace UUID
Task queue name
Versioning rules update
Updated rules
GetWorkerVersioningRules
Retrieves current versioning rules.Namespace UUID
Task queue name
Assignment rules
Redirect rules
Task Queue User Data
GetTaskQueueUserData
Retrieves user data for a task queue.Namespace UUID
Task queue name
User data including versioning info
UpdateTaskQueueUserData
Updates user data for a task queue.Namespace UUID
Task queue name
Updated user data
Associated build IDs
Empty response on success
ReplicateTaskQueueUserData
Replicates task queue user data across clusters.Namespace UUID
Task queue name
User data to replicate
Worker Management
RecordWorkerHeartbeat
Records a heartbeat from a worker.Namespace UUID
Worker identity
Task queue the worker is polling
Empty response on success
ListWorkers
Lists workers polling a task queue.Namespace UUID
Task queue name
Maximum workers per page
List of worker information
DescribeWorker
Retrieves detailed information about a worker.Namespace UUID
Worker identity
Detailed worker information
Partition Management
ForceLoadTaskQueuePartition
Forces loading of a task queue partition.Namespace UUID
Task queue name
Partition to load
Empty response on success
ForceUnloadTaskQueue
Forces unloading of a task queue.Namespace UUID
Task queue to unload
Empty response on success
ForceUnloadTaskQueuePartition
Forces unloading of a specific partition.Namespace UUID
Task queue name
Partition to unload
Additional Operations
CancelOutstandingPoll
Cancels an outstanding poll request.Namespace UUID
Type of task queue
Task queue identifier
Poller to cancel
GetBuildIdTaskQueueMapping
Retrieves mapping between build IDs and task queues.Namespace UUID
Build ID to query
Task queues associated with the build ID
UpdateTaskQueueConfig
Updates configuration for a task queue.Namespace UUID
Task queue name
Configuration to apply
Empty response on success
Usage Notes
- Long polling is used for task distribution with configurable timeouts
- Task queue partitioning enables horizontal scaling
- Worker versioning supports gradual rollouts and compatibility management
- Sticky task queues improve workflow task performance
- The service handles automatic task forwarding between partitions