workato-connector-sdk-advanced

Workato SDK Advanced Patterns

Guide for advanced connector development patterns, architecture planning, and best practices.

Overview

Building production-quality connectors requires:

• Thoughtful planning and API analysis
• Reusable code patterns
• Proper schema design
• Robust error handling
• Performance optimization

Connector Planning

API Analysis Checklist

Before building a connector, analyze:

1. Authentication

   • What auth method does the API use?
   • Are there multiple auth options?
   • How are tokens refreshed?

2. Data Model

   • What are the primary objects/resources?
   • How do objects relate to each other?
   • What fields are required vs optional?

3. Operations

   • What CRUD operations are available?
   • Are there batch operations?
   • What search/filter capabilities exist?

4. Webhooks/Events

   • Does the API support webhooks?
   • What events are available?
   • How is webhook security handled?

5. Rate Limits

   • What are the rate limits?
   • How should the connector handle throttling?

Connector Structure

Organize connector code logically:

{
  title: 'My Connector',

  # 1. Connection & Auth
  connection: { ... },

  # 2. Reusable Methods
  methods: { ... },

  # 3. Object Definitions (Schemas)
  object_definitions: { ... },

  # 4. Pick Lists
  pick_lists: { ... },

  # 5. Actions
  actions: { ... },

  # 6. Triggers
  triggers: { ... },

  # 7. Streams (if needed)
  streams: { ... }
}

Code Patterns

Reusable Methods

Extract common logic into methods:

methods: {
  # Pagination helper
  paginate: lambda do |endpoint, params = {}|
    results = []
    page = 1

    loop do
      response = get(endpoint).params(params.merge(page: page, per_page: 100))
      results.concat(response['items'])
      break unless response['has_more']
      page += 1
    end

    results
  end,

  # Error handling wrapper
  safe_request: lambda do |&block|
    block.call
      .after_error_response(/4\d{2}/) do |code, body, headers, message|
        error("API Error (#{code}): #{body['error'] || message}")
      end
      .after_error_response(/5\d{2}/) do |code, body, headers, message|
        error("Server Error (#{code}): Please try again later")
      end
  end,

  # Field mapping
  map_fields: lambda do |record, field_map|
    field_map.each_with_object({}) do |(api_field, workato_field), result|
      result[workato_field] = record[api_field] if record[api_field]
    end
  end
}

Using Methods

execute: lambda do |connection, input|
  records = call('paginate', '/api/records', { status: 'active' })
  records.map { |r| call('map_fields', r, { 'id' => 'record_id', 'name' => 'title' }) }
end

Schema Design

Object Definitions

Define reusable schemas:

object_definitions: {
  # Base record schema
  record: {
    fields: lambda do |connection, config_fields|
      [
        { name: 'id', label: 'Record ID' },
        { name: 'name', label: 'Name' },
        { name: 'created_at', label: 'Created At', type: 'date_time' },
        { name: 'updated_at', label: 'Updated At', type: 'date_time' }
      ]
    end
  },

  # Input-specific schema (writable fields only)
  record_input: {
    fields: lambda do |connection, config_fields|
      [
        { name: 'name', label: 'Name', optional: false },
        { name: 'email', label: 'Email', control_type: 'email' },
        { name: 'status', control_type: 'select', pick_list: 'statuses' }
      ]
    end
  },

  # Dynamic schema based on config
  dynamic_record: {
    fields: lambda do |connection, config_fields|
      object_type = config_fields['object_type']
      get("/api/schemas/#{object_type}")['fields'].map do |field|
        {
          name: field['name'],
          label: field['label'],
          type: field['type'],
          optional: !field['required']
        }
      end
    end
  }
}

Schema Composition

Combine schemas:

input_fields: lambda do |object_definitions|
  [
    { name: 'id', optional: false }
  ].concat(object_definitions['record_input'])
end

Error Handling

Comprehensive Error Handling

execute: lambda do |connection, input|
  post('/api/records')
    .payload(input)
    .after_error_response(400) do |code, body, headers, message|
      # Validation errors
      errors = body['errors']&.map { |e| e['message'] }&.join(', ')
      error("Validation failed: #{errors || body['message']}")
    end
    .after_error_response(401) do |code, body, headers, message|
      error("Authentication failed. Please reconnect.")
    end
    .after_error_response(403) do |code, body, headers, message|
      error("Permission denied: #{body['message']}")
    end
    .after_error_response(404) do |code, body, headers, message|
      error("Resource not found")
    end
    .after_error_response(429) do |code, body, headers, message|
      retry_after = headers['Retry-After']
      error("Rate limited. Retry after #{retry_after} seconds")
    end
    .after_error_response(/5\d{2}/) do |code, body, headers, message|
      error("Server error (#{code}). Please try again later.")
    end
end

Retry Logic

actions: {
  create_with_retry: {
    execute: lambda do |connection, input|
      post('/api/records').payload(input)
    end,

    retry_on_response: [429, 503],
    max_retries: 3
  }
}

Best Practices

Naming Conventions

• Actions: Verb + noun (create_record, search_contacts)
• Triggers: new_ prefix (new_record, new_event)
• Fields: snake_case matching API where possible

Performance

1. Minimize API calls - Batch requests when possible
2. Use pagination - Don't fetch all records at once
3. Cache static data - Store picklist values
4. Optimize webhooks - Use webhooks over polling when available

Security

1. Never log credentials - Use control_type: 'password'
2. Validate webhooks - Always verify signatures
3. Sanitize inputs - Escape user data in URLs
4. Use HTTPS - Never allow HTTP connections

User Experience

1. Clear labels - Use descriptive field names
2. Helpful hints - Explain what fields do
3. Smart defaults - Pre-populate common values
4. Validation - Catch errors before API calls

Debugging

Local Testing

# Add debug output
execute: lambda do |connection, input|
  workato.log("Input: #{input.inspect}")

  response = get('/api/records')
  workato.log("Response: #{response.inspect}")

  response
end

Common Issues

Issue	Cause	Solution
"undefined method"	Method not defined	Check method name spelling
Empty response	Wrong endpoint/params	Log request, check API docs
Auth fails	Token expired	Implement token refresh
Missing fields	Schema mismatch	Update object_definitions

Reference Files

For detailed documentation:

Connector Guide

• references/guides__advanced-connector-guide__introduction.md - Guide overview
• references/guides__advanced-connector-guide__connector-planning.md - Planning checklist
• references/guides__advanced-connector-guide__connector-building-defining-schema.md - Schema design
• references/guides__advanced-connector-guide__connector-building-building-actions.md - Action patterns
• references/guides__advanced-connector-guide__connector-building-building-triggers.md - Trigger patterns
• references/guides__advanced-connector-guide__connector-building-code-patterns.md - Code patterns

Best Practices

• references/guides__best-practices.md - General best practices
• references/guides__error-handling.md - Error handling patterns
• references/guides__debugging.md - Debugging techniques