Overview
Common types are fundamental structures used throughout the Cadence API. These types are protocol-agnostic and shared across all services.
Source Location: common/types/shared.go
Data Encoding Types
DataBlob
Container for encoded data with encoding type information.
type DataBlob struct {
EncodingType *EncodingType
Data []byte
}
Type of encoding used for the data
- Workflow/activity input and output
- Event payloads
- Query results
- Memos and search attributes
EncodingType
Supported data encoding formats.
type EncodingType int32
const (
EncodingTypeThriftRW EncodingType = iota
EncodingTypeJSON
)
Thrift encoding (deprecated)
JSON encoding (recommended)
History Types
History
Sequence of workflow execution events.
type History struct {
Events []*HistoryEvent
}
Ordered list of history events
HistoryEvent
Single event in workflow execution history.
type HistoryEvent struct {
EventID int64
Timestamp *int64
EventType *EventType
Version int64
TaskID int64
// Event-specific attributes (one will be set based on EventType)
WorkflowExecutionStartedEventAttributes *WorkflowExecutionStartedEventAttributes
WorkflowExecutionCompletedEventAttributes *WorkflowExecutionCompletedEventAttributes
WorkflowExecutionFailedEventAttributes *WorkflowExecutionFailedEventAttributes
WorkflowExecutionTimedOutEventAttributes *WorkflowExecutionTimedOutEventAttributes
DecisionTaskScheduledEventAttributes *DecisionTaskScheduledEventAttributes
DecisionTaskStartedEventAttributes *DecisionTaskStartedEventAttributes
DecisionTaskCompletedEventAttributes *DecisionTaskCompletedEventAttributes
DecisionTaskTimedOutEventAttributes *DecisionTaskTimedOutEventAttributes
DecisionTaskFailedEventAttributes *DecisionTaskFailedEventAttributes
ActivityTaskScheduledEventAttributes *ActivityTaskScheduledEventAttributes
ActivityTaskStartedEventAttributes *ActivityTaskStartedEventAttributes
ActivityTaskCompletedEventAttributes *ActivityTaskCompletedEventAttributes
ActivityTaskFailedEventAttributes *ActivityTaskFailedEventAttributes
ActivityTaskTimedOutEventAttributes *ActivityTaskTimedOutEventAttributes
ActivityTaskCancelRequestedEventAttributes *ActivityTaskCancelRequestedEventAttributes
ActivityTaskCanceledEventAttributes *ActivityTaskCanceledEventAttributes
TimerStartedEventAttributes *TimerStartedEventAttributes
TimerFiredEventAttributes *TimerFiredEventAttributes
TimerCanceledEventAttributes *TimerCanceledEventAttributes
WorkflowExecutionCancelRequestedEventAttributes *WorkflowExecutionCancelRequestedEventAttributes
WorkflowExecutionCanceledEventAttributes *WorkflowExecutionCanceledEventAttributes
RequestCancelExternalWorkflowExecutionInitiatedEventAttributes *RequestCancelExternalWorkflowExecutionInitiatedEventAttributes
RequestCancelExternalWorkflowExecutionFailedEventAttributes *RequestCancelExternalWorkflowExecutionFailedEventAttributes
ExternalWorkflowExecutionCancelRequestedEventAttributes *ExternalWorkflowExecutionCancelRequestedEventAttributes
WorkflowExecutionContinuedAsNewEventAttributes *WorkflowExecutionContinuedAsNewEventAttributes
StartChildWorkflowExecutionInitiatedEventAttributes *StartChildWorkflowExecutionInitiatedEventAttributes
StartChildWorkflowExecutionFailedEventAttributes *StartChildWorkflowExecutionFailedEventAttributes
ChildWorkflowExecutionStartedEventAttributes *ChildWorkflowExecutionStartedEventAttributes
ChildWorkflowExecutionCompletedEventAttributes *ChildWorkflowExecutionCompletedEventAttributes
ChildWorkflowExecutionFailedEventAttributes *ChildWorkflowExecutionFailedEventAttributes
ChildWorkflowExecutionCanceledEventAttributes *ChildWorkflowExecutionCanceledEventAttributes
ChildWorkflowExecutionTimedOutEventAttributes *ChildWorkflowExecutionTimedOutEventAttributes
ChildWorkflowExecutionTerminatedEventAttributes *ChildWorkflowExecutionTerminatedEventAttributes
SignalExternalWorkflowExecutionInitiatedEventAttributes *SignalExternalWorkflowExecutionInitiatedEventAttributes
SignalExternalWorkflowExecutionFailedEventAttributes *SignalExternalWorkflowExecutionFailedEventAttributes
ExternalWorkflowExecutionSignaledEventAttributes *ExternalWorkflowExecutionSignaledEventAttributes
UpsertWorkflowSearchAttributesEventAttributes *UpsertWorkflowSearchAttributesEventAttributes
WorkflowExecutionSignaledEventAttributes *WorkflowExecutionSignaledEventAttributes
WorkflowExecutionTerminatedEventAttributes *WorkflowExecutionTerminatedEventAttributes
MarkerRecordedEventAttributes *MarkerRecordedEventAttributes
}
Unique identifier for this event (sequential starting from 1)
Unix timestamp in nanoseconds when event occurred
Event version for multi-cluster replication
Task ID that generated this event
EventType
Enumeration of all possible event types.
type EventType int32
const (
EventTypeWorkflowExecutionStarted EventType = iota
EventTypeWorkflowExecutionCompleted
EventTypeWorkflowExecutionFailed
EventTypeWorkflowExecutionTimedOut
EventTypeDecisionTaskScheduled
EventTypeDecisionTaskStarted
EventTypeDecisionTaskCompleted
EventTypeDecisionTaskTimedOut
EventTypeDecisionTaskFailed
EventTypeActivityTaskScheduled
EventTypeActivityTaskStarted
EventTypeActivityTaskCompleted
EventTypeActivityTaskFailed
EventTypeActivityTaskTimedOut
EventTypeActivityTaskCancelRequested
EventTypeActivityTaskCanceled
EventTypeTimerStarted
EventTypeTimerFired
EventTypeTimerCanceled
EventTypeCancelTimerFailed
EventTypeStartChildWorkflowExecutionInitiated
EventTypeStartChildWorkflowExecutionFailed
EventTypeChildWorkflowExecutionStarted
EventTypeChildWorkflowExecutionCompleted
EventTypeChildWorkflowExecutionFailed
EventTypeChildWorkflowExecutionCanceled
EventTypeChildWorkflowExecutionTimedOut
EventTypeChildWorkflowExecutionTerminated
EventTypeSignalExternalWorkflowExecutionInitiated
EventTypeSignalExternalWorkflowExecutionFailed
EventTypeExternalWorkflowExecutionSignaled
EventTypeWorkflowExecutionSignaled
EventTypeWorkflowExecutionCancelRequested
EventTypeWorkflowExecutionCanceled
EventTypeRequestCancelExternalWorkflowExecutionInitiated
EventTypeRequestCancelExternalWorkflowExecutionFailed
EventTypeExternalWorkflowExecutionCancelRequested
EventTypeMarkerRecorded
EventTypeWorkflowExecutionTerminated
EventTypeWorkflowExecutionContinuedAsNew
EventTypeUpsertWorkflowSearchAttributes
)
Timeout Types
TimeoutType
Type of timeout that occurred.
type TimeoutType int32
const (
TimeoutTypeStartToClose TimeoutType = iota
TimeoutTypeScheduleToStart
TimeoutTypeScheduleToClose
TimeoutTypeHeartbeat
)
Timeout from task start to completion
Timeout from task schedule to start
Timeout from task schedule to completion
Heartbeat timeout (activity only)
Query Types
WorkflowQuery
Query definition for querying workflow state.
type WorkflowQuery struct {
QueryType string
QueryArgs []byte
}
Type of query to execute (registered query handler name)
Serialized query arguments
WorkflowQueryResult
Result of a workflow query.
type WorkflowQueryResult struct {
ResultType *QueryResultType
Answer []byte
ErrorMessage string
}
Type of result (Answered or Failed)
Serialized query answer if successful
Error message if query failed
QueryResultType
Type of query result.
type QueryResultType int32
const (
QueryResultTypeAnswered QueryResultType = iota
QueryResultTypeFailed
)
QueryRejectCondition
Condition for rejecting a query.
type QueryRejectCondition int32
const (
QueryRejectConditionNotOpen QueryRejectCondition = iota
QueryRejectConditionNotCompletedCleanly
)
Reject query if workflow is not open
Reject if workflow completed with failure/timeout/termination
QueryConsistencyLevel
Consistency level for query execution.
type QueryConsistencyLevel int32
const (
QueryConsistencyLevelEventual QueryConsistencyLevel = iota
QueryConsistencyLevelStrong
)
Eventual consistency (may use cached state)
Strong consistency (reads latest state)
QueryRejected
Information about a rejected query.
type QueryRejected struct {
CloseStatus *WorkflowExecutionCloseStatus
}
CloseStatus
WorkflowExecutionCloseStatus
Close status if workflow is closed
Version History Types
VersionHistories
Collection of version histories for multi-cluster support.
type VersionHistories struct {
CurrentVersionHistoryIndex int32
Histories []*VersionHistory
}
CurrentVersionHistoryIndex
Index of the current active version history
List of version histories (branches)
VersionHistory
Sequence of version history items representing a branch.
type VersionHistory struct {
BranchToken []byte
Items []*VersionHistoryItem
}
Opaque token identifying this history branch
Ordered version history items
VersionHistoryItem
Single item in version history.
type VersionHistoryItem struct {
EventID int64
Version int64
}
Event ID at this version point
Version number (failover version)
Health Status Types
HealthStatus
Health status of a service.
type HealthStatus struct {
Ok bool
Msg string
}
Whether the service is healthy
Supported Client Versions
SupportedClientVersions
Client version compatibility information.
type SupportedClientVersions struct {
GoSdk string
JavaSdk string
}
Supported Go SDK version range
Supported Java SDK version range
ClusterInfo
Cluster information.
type ClusterInfo struct {
SupportedClientVersions *SupportedClientVersions
}
Supported client version information
Indexed Value Types
IndexedValueType
Type of indexed search attribute.
type IndexedValueType int32
const (
IndexedValueTypeString IndexedValueType = iota
IndexedValueTypeKeyword
IndexedValueTypeInt
IndexedValueTypeDouble
IndexedValueTypeBool
IndexedValueTypeDatetime
)
Text string (full-text searchable)
Keyword string (exact match only)
Decision Task Failed Cause
DecisionTaskFailedCause
Reason why a decision task failed.
type DecisionTaskFailedCause int32
const (
DecisionTaskFailedCauseUnhandledDecision DecisionTaskFailedCause = iota
DecisionTaskFailedCauseBadScheduleActivityAttributes
DecisionTaskFailedCauseBadRequestCancelActivityAttributes
DecisionTaskFailedCauseBadStartTimerAttributes
DecisionTaskFailedCauseBadCancelTimerAttributes
DecisionTaskFailedCauseBadRecordMarkerAttributes
DecisionTaskFailedCauseBadCompleteWorkflowExecutionAttributes
DecisionTaskFailedCauseBadFailWorkflowExecutionAttributes
DecisionTaskFailedCauseBadCancelWorkflowExecutionAttributes
DecisionTaskFailedCauseBadRequestCancelExternalWorkflowExecutionAttributes
DecisionTaskFailedCauseBadContinueAsNewAttributes
DecisionTaskFailedCauseStartTimerDuplicateID
DecisionTaskFailedCauseResetStickyTasklist
DecisionTaskFailedCauseWorkflowWorkerUnhandledFailure
DecisionTaskFailedCauseBadSignalWorkflowExecutionAttributes
DecisionTaskFailedCauseBadStartChildExecutionAttributes
DecisionTaskFailedCauseForceCloseDecision
DecisionTaskFailedCauseFailoverCloseDecision
DecisionTaskFailedCauseBadSignalInputSize
DecisionTaskFailedCauseResetWorkflow
DecisionTaskFailedCauseBadBinary
DecisionTaskFailedCauseScheduleActivityDuplicateID
DecisionTaskFailedCauseBadSearchAttributes
)
Pending State Types
PendingActivityState
State of a pending activity.
type PendingActivityState int32
const (
PendingActivityStateScheduled PendingActivityState = iota
PendingActivityStateStarted
PendingActivityStateCancelRequested
)
PendingDecisionState
State of a pending decision task.
type PendingDecisionState int32
const (
PendingDecisionStateScheduled PendingDecisionState = iota
PendingDecisionStateStarted
)
Failover Marker Types
FailoverMarkerAttributes
Attributes for a domain failover marker.
type FailoverMarkerAttributes struct {
DomainID string
FailoverVersion int64
CreationTime *int64
}
UUID of the domain being failed over
New failover version after failover
When failover marker was created
- Returned in responses with
NextPageToken
- Pass back in subsequent requests
- Empty/nil token indicates no more results
- Tokens expire after ~10 minutes
Common Patterns
Optional Fields
Many fields are pointers to distinguish between:
- nil: Field not set
- zero value: Field explicitly set to zero
ExecutionStartToCloseTimeoutSeconds *int32
Enumerations
Enums are represented as int32 with constants:
type MyEnum int32
const (
MyEnumValue1 MyEnum = iota
MyEnumValue2
)
Timestamps
All timestamps are Unix nanoseconds (int64):
StartTime *int64 // nanoseconds since Unix epoch
t := time.Unix(0, *startTime)
Binary Data
Binary payloads use byte slices:
Input []byte // Serialized workflow/activity input
Best Practices
Type Safety
-
Use Type-Safe Enums
- Don’t use raw integers
- Use provided constants
- Validate enum values
-
Check Nil Pointers
- Always check optional fields for nil
- Use getter methods when available
- Provide defaults for missing values
Data Encoding
-
Prefer JSON
- More readable and debuggable
- Better cross-language support
- Easier schema evolution
-
Keep Payloads Small
- Limit to less than 2MB per payload
- Use external storage for large data
- Compress when appropriate
History Events
-
Event Ordering
- Events are strictly ordered by EventID
- EventID is sequential starting from 1
- Never skip event IDs
-
Event Attributes
- Only one attribute field is set per event
- Attribute type matches EventType
- Contains all data for that event
Version History
-
Conflict Detection
- Use version histories for consistency
- Check versions before updates
- Handle conflicts gracefully
-
Multi-Cluster
- Version tracks failover version
- Different branches for different clusters
- Merge on conflict resolution
See Also
