temporalio__skill-temporal-developer/references/ruby/data-handling.md

Ruby SDK Data Handling

Overview

Data converters serialize and deserialize workflow/activity inputs and outputs. The Temporalio::Converters module provides the conversion pipeline.

Default Data Converter

The default converter handles types in this order:

1. nil - null payload
2. Bytes - String with ASCII_8BIT encoding
3. Protobuf - objects implementing Google::Protobuf::MessageExts
4. JSON - everything else, via Ruby's JSON module

Note: symbol keys become strings on deserialization. create_additions: true by default.

ActiveModel Integration

Use the ActiveModelJSONSupport mixin to make ActiveModel objects work with Temporal's JSON serialization:

module ActiveModelJSONSupport
  extend ActiveSupport::Concern
  include ActiveModel::Serializers::JSON

  included do
    def as_json(*)
      super.merge(::JSON.create_id => self.class.name)
    end

    def to_json(*args)
      as_json.to_json(*args)
    end

    def self.json_create(object)
      object = object.dup
      object.delete(::JSON.create_id)
      new(**object.symbolize_keys)
    end
  end
end

Include it in any ActiveModel class to make it serializable by Temporal:

class OrderInput
  include ActiveModel::Model
  include ActiveModelJSONSupport

  attr_accessor :order_id, :items, :total
end

Custom Data Conversion

converter = Temporalio::Converters::DataConverter.new(
  payload_converter: my_payload_converter,
  payload_codec: my_payload_codec,
  failure_converter: my_failure_converter
)

client = Temporalio::Client.connect(
  'localhost:7233',
  'default',
  data_converter: converter
)

Converter Hints

Ruby-specific feature for guiding deserialization to the correct type:

class MyWorkflow
  workflow_arg_hint MyClass
  workflow_result_hint MyClass

  workflow_update :my_update, arg_hints: [MyClass]

  def execute(input)
    # input is deserialized as MyClass
  end
end

Custom converters use these hints to know the target deserialization type.

Payload Encryption

Implement a PayloadCodec with encode and decode:

class EncryptionCodec
  def encode(payloads)
    payloads.map { |p| encrypt(p) }
  end

  def decode(payloads)
    payloads.map { |p| decrypt(p) }
  end

  private

  def encrypt(payload)
    # encryption logic
  end

  def decrypt(payload)
    # decryption logic
  end
end

converter = Temporalio::Converters::DataConverter.new(
  payload_codec: EncryptionCodec.new
)

Search Attributes

Define a search attribute key:

key = Temporalio::SearchAttributes::Key.new(
  'CustomerId',
  Temporalio::SearchAttributes::IndexedValueType::KEYWORD
)

Set at workflow start:

client.start_workflow(
  MyWorkflow,
  'arg',
  id: 'wf-1',
  task_queue: 'my-queue',
  search_attributes: Temporalio::SearchAttributes.new({ key => 'customer-123' })
)

Upsert from a workflow:

Temporalio::Workflow.upsert_search_attributes({ key => 'new-value' })

Querying Workflows by Search Attributes

client.list_workflows("CustomerId = 'customer-123'")

Workflow Memo

Set at workflow start:

client.start_workflow(
  MyWorkflow,
  'arg',
  id: 'wf-1',
  task_queue: 'my-queue',
  memo: { 'region' => 'us-east', 'priority' => 'high' }
)

Read from within a workflow:

region = Temporalio::Workflow.memo['region']

Deterministic APIs for Values

Use these instead of standard Ruby equivalents inside workflows:

Temporalio::Workflow.uuid       # deterministic UUID
Temporalio::Workflow.random     # deterministic random number
Temporalio::Workflow.now        # deterministic current time

Best Practices

• Use dedicated model classes for Temporal data, not ActiveRecord models.
• Keep payloads small; store large data externally and pass references.
• Encrypt sensitive data with a PayloadCodec.
• Use Temporalio::Workflow.uuid, .random, and .now inside workflows for determinism.