forest_admin_datasource_zendesk 1.28.1

data/lib/forest_admin_datasource_zendesk/collections/ticket/schema_definition.rb

@@ -0,0 +1,72 @@
+module ForestAdminDatasourceZendesk
+  module Collections
+    class Ticket < BaseCollection
+      module SchemaDefinition
+        ColumnSchema = BaseCollection::ColumnSchema
+        Operators    = BaseCollection::Operators
+        STRING_OPS   = BaseCollection::STRING_OPS
+        NUMBER_OPS   = BaseCollection::NUMBER_OPS
+        DATE_OPS     = BaseCollection::DATE_OPS
+
+        private
+
+        def define_schema
+          add_field('id', ColumnSchema.new(column_type: 'Number', filter_operators: NUMBER_OPS,
+                                           is_primary_key: true, is_read_only: true, is_sortable: true))
+          add_field('subject', ColumnSchema.new(column_type: 'String', filter_operators: STRING_OPS,
+                                                is_read_only: false, is_sortable: false))
+          add_field('description', ColumnSchema.new(column_type: 'String', filter_operators: [],
+                                                    is_read_only: false, is_sortable: false))
+          add_field('status', ColumnSchema.new(column_type: 'Enum', filter_operators: STRING_OPS,
+                                               enum_values: ENUM_STATUS, is_read_only: false, is_sortable: true))
+          add_field('priority', ColumnSchema.new(column_type: 'Enum', filter_operators: STRING_OPS,
+                                                 enum_values: ENUM_PRIORITY, is_read_only: false, is_sortable: true))
+          add_field('ticket_type', ColumnSchema.new(column_type: 'Enum', filter_operators: STRING_OPS,
+                                                    enum_values: ENUM_TYPE, is_read_only: false, is_sortable: true))
+          add_field('requester_id', ColumnSchema.new(column_type: 'Number', filter_operators: NUMBER_OPS,
+                                                     is_read_only: false, is_sortable: true))
+          add_field('assignee_id', ColumnSchema.new(column_type: 'Number', filter_operators: NUMBER_OPS,
+                                                    is_read_only: false, is_sortable: true))
+          add_field('group_id', ColumnSchema.new(column_type: 'Number', filter_operators: NUMBER_OPS,
+                                                 is_read_only: false, is_sortable: true))
+          add_field('organization_id', ColumnSchema.new(column_type: 'Number', filter_operators: NUMBER_OPS,
+                                                        is_read_only: false, is_sortable: true))
+          add_field('external_id', ColumnSchema.new(column_type: 'String', filter_operators: STRING_OPS,
+                                                    is_read_only: false, is_sortable: false))
+          add_field('requester_email', ColumnSchema.new(column_type: 'String', filter_operators: [Operators::EQUAL],
+                                                        is_read_only: true, is_sortable: false))
+          add_field('tags', ColumnSchema.new(column_type: 'Json', filter_operators: [],
+                                             is_read_only: false, is_sortable: false))
+          add_field('url', ColumnSchema.new(column_type: 'String', filter_operators: [],
+                                            is_read_only: true, is_sortable: false))
+          add_field('created_at', ColumnSchema.new(column_type: 'Date', filter_operators: DATE_OPS,
+                                                   is_read_only: true, is_sortable: true))
+          add_field('updated_at', ColumnSchema.new(column_type: 'Date', filter_operators: DATE_OPS,
+                                                   is_read_only: true, is_sortable: true))
+
+          @custom_fields.each { |cf| add_field(cf[:column_name], cf[:schema]) }
+        end
+
+        def define_relations
+          add_field('requester', ManyToOneSchema.new(
+                                   foreign_collection: 'ZendeskUser',
+                                   foreign_key: 'requester_id',
+                                   foreign_key_target: 'id'
+                                 ))
+          add_field('assignee', ManyToOneSchema.new(
+                                  foreign_collection: 'ZendeskUser',
+                                  foreign_key: 'assignee_id',
+                                  foreign_key_target: 'id'
+                                ))
+          add_field('organization', ManyToOneSchema.new(
+                                      foreign_collection: 'ZendeskOrganization',
+                                      foreign_key: 'organization_id',
+                                      foreign_key_target: 'id'
+                                    ))
+          add_field('comments', ColumnSchema.new(column_type: [Ticket::COMMENT_THREAD_SCHEMA],
+                                                 filter_operators: [], is_read_only: true))
+        end
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_zendesk/collections/ticket/serializer.rb

@@ -0,0 +1,31 @@
+module ForestAdminDatasourceZendesk
+  module Collections
+    class Ticket < BaseCollection
+      module Serializer
+        private
+
+        def serialize(ticket, emails = {})
+          attrs = attrs_of(ticket)
+          result = base_attributes(attrs, emails)
+          cf_values = Array(attrs['custom_fields']).to_h { |f| [f['id'], f['value']] }
+          @custom_fields.each { |cf| result[cf[:column_name]] = cf_values[cf[:zendesk_id]] }
+          result
+        end
+
+        def base_attributes(attrs, emails)
+          {
+            'id' => attrs['id'], 'subject' => attrs['subject'],
+            'description' => attrs['description'], 'status' => attrs['status'],
+            'priority' => attrs['priority'], 'ticket_type' => attrs['type'],
+            'requester_id' => attrs['requester_id'], 'assignee_id' => attrs['assignee_id'],
+            'group_id' => attrs['group_id'], 'organization_id' => attrs['organization_id'],
+            'external_id' => attrs['external_id'],
+            'requester_email' => emails[attrs['requester_id']],
+            'tags' => attrs['tags'], 'url' => attrs['url'],
+            'created_at' => attrs['created_at'], 'updated_at' => attrs['updated_at']
+          }
+        end
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_zendesk/collections/ticket.rb

@@ -0,0 +1,128 @@
+module ForestAdminDatasourceZendesk
+  module Collections
+    class Ticket < BaseCollection
+      include SchemaDefinition
+      include RelationEmbedder
+      include CommentsEmbedder
+      include Serializer
+
+      ManyToOneSchema = ForestAdminDatasourceToolkit::Schema::Relations::ManyToOneSchema
+
+      ENUM_STATUS   = %w[new open pending hold solved closed].freeze
+      ENUM_PRIORITY = %w[low normal high urgent].freeze
+      ENUM_TYPE     = %w[problem incident question task].freeze
+
+      ZENDESK_SORTABLE = {
+        'updated_at' => 'updated_at',
+        'created_at' => 'created_at',
+        'priority' => 'priority',
+        'status' => 'status',
+        'ticket_type' => 'ticket_type'
+      }.freeze
+
+      COMMENT_THREAD_SCHEMA = {
+        'id' => 'Number',
+        'body' => 'String',
+        'html_body' => 'String',
+        'public' => 'Boolean',
+        'author_email' => 'String',
+        'author_name' => 'String',
+        'created_at' => 'Date'
+      }.freeze
+
+      def initialize(datasource, custom_fields: [])
+        super(datasource, 'ZendeskTicket')
+        @custom_fields = custom_fields
+        define_schema
+        define_relations
+        enable_search
+        enable_count
+      end
+
+      def list(caller, filter, projection)
+        records = fetch_records(caller, filter)
+        emails  = needs_requester_email?(projection) ? bulk_fetch_emails(records) : {}
+        rows    = records.map { |t| project(serialize(t, emails), projection) }
+        embed_relations(records, rows, projection)
+        embed_comments(records, rows) if want_comments?(projection)
+        rows
+      end
+
+      def create(_caller, data)
+        payload = build_payload(data, on_create: true)
+        created = datasource.client.create_ticket(payload)
+        serialize(created)
+      end
+
+      def update(caller, filter, patch)
+        ids = ids_for(caller, filter)
+        payload = build_payload(patch, on_create: false)
+        ids.each { |id| datasource.client.update_ticket(id, payload) }
+      end
+
+      def delete(caller, filter)
+        ids_for(caller, filter).each { |id| datasource.client.delete_ticket(id) }
+      end
+
+      protected
+
+      def aggregate_count(caller, filter)
+        datasource.client.count('ticket', query: build_zendesk_query(caller, filter))
+      end
+
+      private
+
+      # `description` only writes the initial comment at creation time; Zendesk
+      # has no update path for it, so it's dropped on patch.
+      def build_payload(data, on_create:)
+        attrs = data.transform_keys(&:to_s)
+        custom_fields, base = split_custom_fields(attrs)
+        %w[id requester_email url created_at updated_at].each { |k| base.delete(k) }
+        base['type'] = base.delete('ticket_type') if base.key?('ticket_type')
+
+        description = base.delete('description')
+        base['comment'] = { 'body' => description } if on_create && description && !description.empty?
+
+        base['custom_fields'] = custom_fields unless custom_fields.empty?
+        base
+      end
+
+      def split_custom_fields(attrs)
+        cf_by_column = @custom_fields.to_h { |cf| [cf[:column_name], cf[:zendesk_id]] }
+        custom = []
+        rest = attrs.each_with_object({}) do |(k, v), h|
+          if (zendesk_id = cf_by_column[k])
+            custom << { 'id' => zendesk_id, 'value' => v }
+          else
+            h[k] = v
+          end
+        end
+        [custom, rest]
+      end
+
+      def fetch_records(caller, filter)
+        ids = extract_id_lookup(filter.condition_tree)
+        if ids
+          by_id = datasource.client.fetch_tickets_by_ids(ids)
+          return ids.filter_map { |id| by_id[id] }
+        end
+
+        sort_by, sort_order = translate_sort(filter.sort, ZENDESK_SORTABLE)
+        page, per_page      = translate_page(filter.page)
+
+        datasource.client.search('ticket', query: build_zendesk_query(caller, filter),
+                                           sort_by: sort_by, sort_order: sort_order,
+                                           page: page, per_page: per_page)
+      end
+
+      def needs_requester_email?(projection)
+        projection.nil? || Array(projection).map(&:to_s).include?('requester_email')
+      end
+
+      def bulk_fetch_emails(records)
+        ids = records.map { |t| attrs_of(t)['requester_id'] }
+        datasource.client.fetch_user_emails(ids)
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_zendesk/collections/user.rb

@@ -0,0 +1,121 @@
+module ForestAdminDatasourceZendesk
+  module Collections
+    class User < BaseCollection
+      include Searchable
+
+      ManyToOneSchema = ForestAdminDatasourceToolkit::Schema::Relations::ManyToOneSchema
+      OneToManySchema = ForestAdminDatasourceToolkit::Schema::Relations::OneToManySchema
+      ENUM_ROLE       = %w[end-user agent admin].freeze
+
+      ZENDESK_SORTABLE = {
+        'created_at' => 'created_at',
+        'updated_at' => 'updated_at',
+        'name' => 'name'
+      }.freeze
+
+      def initialize(datasource, custom_fields: [])
+        super(datasource, 'ZendeskUser')
+        @custom_fields = custom_fields
+        define_schema
+        define_relations
+        enable_search
+        enable_count
+      end
+
+      def create(_caller, data)
+        payload = build_payload(data)
+        created = datasource.client.create_user(payload)
+        serialize(created)
+      end
+
+      def update(caller, filter, patch)
+        ids = ids_for(caller, filter)
+        payload = build_payload(patch)
+        ids.each { |id| datasource.client.update_user(id, payload) }
+      end
+
+      def delete(caller, filter)
+        ids_for(caller, filter).each { |id| datasource.client.delete_user(id) }
+      end
+
+      protected
+
+      def zendesk_resource = 'user'
+      def sortable_fields  = ZENDESK_SORTABLE
+      def find_one(id)     = datasource.client.find_user(id)
+
+      private
+
+      def build_payload(data)
+        attrs = data.transform_keys(&:to_s)
+        cf_keys = @custom_fields.to_h { |cf| [cf[:column_name], cf[:zendesk_key]] }
+        user_fields = {}
+        base = attrs.each_with_object({}) do |(k, v), h|
+          if (key = cf_keys[k])
+            user_fields[key] = v
+          else
+            h[k] = v
+          end
+        end
+        %w[id created_at updated_at].each { |k| base.delete(k) }
+        base['user_fields'] = user_fields unless user_fields.empty?
+        base
+      end
+
+      def define_schema
+        add_field('id', ColumnSchema.new(column_type: 'Number', filter_operators: NUMBER_OPS,
+                                         is_primary_key: true, is_read_only: true, is_sortable: true))
+        add_field('email', ColumnSchema.new(column_type: 'String', filter_operators: STRING_OPS,
+                                            is_read_only: false, is_sortable: false))
+        add_field('name', ColumnSchema.new(column_type: 'String', filter_operators: STRING_OPS,
+                                           is_read_only: false, is_sortable: true))
+        add_field('role', ColumnSchema.new(column_type: 'Enum', filter_operators: STRING_OPS,
+                                           enum_values: ENUM_ROLE, is_read_only: false, is_sortable: false))
+        add_field('phone', ColumnSchema.new(column_type: 'String', filter_operators: STRING_OPS,
+                                            is_read_only: false, is_sortable: false))
+        add_field('organization_id', ColumnSchema.new(column_type: 'Number', filter_operators: NUMBER_OPS,
+                                                      is_read_only: false, is_sortable: false))
+        add_field('time_zone', ColumnSchema.new(column_type: 'String', filter_operators: [],
+                                                is_read_only: false, is_sortable: false))
+        add_field('locale', ColumnSchema.new(column_type: 'String', filter_operators: [],
+                                             is_read_only: false, is_sortable: false))
+        add_field('verified', ColumnSchema.new(column_type: 'Boolean', filter_operators: STRING_OPS,
+                                               is_read_only: false, is_sortable: false))
+        add_field('suspended', ColumnSchema.new(column_type: 'Boolean', filter_operators: STRING_OPS,
+                                                is_read_only: false, is_sortable: false))
+        add_field('created_at', ColumnSchema.new(column_type: 'Date', filter_operators: DATE_OPS,
+                                                 is_read_only: true, is_sortable: true))
+        add_field('updated_at', ColumnSchema.new(column_type: 'Date', filter_operators: DATE_OPS,
+                                                 is_read_only: true, is_sortable: true))
+
+        @custom_fields.each { |cf| add_field(cf[:column_name], cf[:schema]) }
+      end
+
+      def define_relations
+        add_field('organization', ManyToOneSchema.new(foreign_collection: 'ZendeskOrganization',
+                                                      foreign_key: 'organization_id', foreign_key_target: 'id'))
+        add_field('requested_tickets', OneToManySchema.new(foreign_collection: 'ZendeskTicket',
+                                                           origin_key: 'requester_id', origin_key_target: 'id'))
+      end
+
+      def serialize(user)
+        attrs = attrs_of(user)
+        result = base_attributes(attrs)
+        user_fields = attrs['user_fields'] || {}
+        @custom_fields.each { |cf| result[cf[:column_name]] = user_fields[cf[:zendesk_key]] }
+        result
+      end
+
+      def base_attributes(attrs)
+        {
+          'id' => attrs['id'], 'email' => attrs['email'], 'name' => attrs['name'],
+          'role' => attrs['role'], 'phone' => attrs['phone'],
+          'organization_id' => attrs['organization_id'],
+          'time_zone' => attrs['time_zone'], 'locale' => attrs['locale'],
+          'verified' => attrs['verified'], 'suspended' => attrs['suspended'],
+          'created_at' => attrs['created_at'], 'updated_at' => attrs['updated_at']
+        }
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_zendesk/configuration.rb

@@ -0,0 +1,33 @@
+module ForestAdminDatasourceZendesk
+  class Configuration
+    attr_reader :subdomain, :username, :token
+
+    def initialize(subdomain:, username:, token:)
+      @subdomain = subdomain
+      @username  = username
+      @token     = token
+      validate!
+    end
+
+    def url
+      "https://#{@subdomain}.zendesk.com/api/v2"
+    end
+
+    private
+
+    def validate!
+      missing = []
+      missing << 'subdomain' if blank?(@subdomain)
+      missing << 'username'  if blank?(@username)
+      missing << 'token'     if blank?(@token)
+      return if missing.empty?
+
+      raise ConfigurationError,
+            "ForestAdminDatasourceZendesk missing required config: #{missing.join(", ")}"
+    end
+
+    def blank?(value)
+      value.nil? || value.to_s.strip.empty?
+    end
+  end
+end

data/lib/forest_admin_datasource_zendesk/datasource.rb

@@ -0,0 +1,44 @@
+module ForestAdminDatasourceZendesk
+  class Datasource < ForestAdminDatasourceToolkit::Datasource
+    attr_reader :client, :configuration, :custom_field_mapping
+
+    def initialize(subdomain:, username:, token:)
+      super()
+      @configuration = Configuration.new(subdomain: subdomain, username: username, token: token)
+      @client = Client.new(@configuration)
+      @custom_field_mapping = {}
+
+      register_collections
+    end
+
+    private
+
+    def register_collections
+      introspector = Schema::CustomFieldsIntrospector.new(@client)
+
+      ticket_cf = introspector.ticket_custom_fields
+      user_cf   = introspector.user_custom_fields
+      org_cf    = introspector.organization_custom_fields
+
+      add_collection(Collections::Ticket.new(self, custom_fields: ticket_cf))
+      add_collection(Collections::User.new(self, custom_fields: user_cf))
+      add_collection(Collections::Organization.new(self, custom_fields: org_cf))
+
+      @custom_field_mapping = build_custom_field_mapping(ticket_cf, user_cf, org_cf)
+    end
+
+    # Forest column name -> Zendesk Search field name. Lives on the instance
+    # (not the translator class) so multiple Zendesk datasources in the same
+    # agent don't share state.
+    def build_custom_field_mapping(ticket_cf, user_cf, org_cf)
+      mapping = {}
+      ticket_cf.each { |cf| mapping[cf[:column_name]] = "custom_field_#{cf[:zendesk_id]}" }
+      (user_cf + org_cf).each do |cf|
+        next unless cf[:zendesk_key]
+
+        mapping[cf[:column_name]] ||= cf[:zendesk_key]
+      end
+      mapping
+    end
+  end
+end

data/lib/forest_admin_datasource_zendesk/query/condition_tree_translator.rb

@@ -0,0 +1,122 @@
+require 'active_support/core_ext/time/zones'
+
+module ForestAdminDatasourceZendesk
+  module Query
+    # See https://developer.zendesk.com/api-reference/ticketing/ticket-management/search/
+    #
+    # Unsupported operators raise UnsupportedOperatorError rather than
+    # silently producing the wrong query. Only the AND aggregator is
+    # supported (Zendesk Search has no general OR).
+    class ConditionTreeTranslator
+      Operators = ForestAdminDatasourceToolkit::Components::Query::ConditionTree::Operators
+      Branch    = ForestAdminDatasourceToolkit::Components::Query::ConditionTree::Nodes::ConditionTreeBranch
+      Leaf      = ForestAdminDatasourceToolkit::Components::Query::ConditionTree::Nodes::ConditionTreeLeaf
+
+      def self.call(condition_tree, timezone: nil, custom_fields: {})
+        return '' if condition_tree.nil?
+
+        new(timezone: timezone, custom_fields: custom_fields).translate(condition_tree)
+      end
+
+      def initialize(timezone: nil, custom_fields: {})
+        @timezone = timezone || 'UTC'
+        @custom_fields = custom_fields || {}
+      end
+
+      def translate(node)
+        case node
+        when Branch then translate_branch(node)
+        when Leaf   then translate_leaf(node)
+        else
+          raise UnsupportedOperatorError, "Unknown condition node: #{node.class}"
+        end
+      end
+
+      private
+
+      def translate_branch(branch)
+        unless branch.aggregator.to_s.casecmp('and').zero?
+          raise UnsupportedOperatorError,
+                "Zendesk Search API does not support arbitrary OR aggregation; got #{branch.aggregator.inspect}"
+        end
+
+        branch.conditions.map { |c| translate(c) }.reject(&:empty?).join(' ')
+      end
+
+      def translate_leaf(leaf)
+        field = mapped_field(leaf.field)
+        value = leaf.value
+
+        if leaf.field == 'requester_email' && leaf.operator == Operators::EQUAL
+          return "requester:#{format_value(value)}"
+        end
+
+        case leaf.operator
+        when Operators::EQUAL        then "#{field}:#{format_value(value)}"
+        when Operators::NOT_EQUAL    then "-#{field}:#{format_value(value)}"
+        when Operators::IN           then translate_in(field, value, negate: false)
+        when Operators::NOT_IN       then translate_in(field, value, negate: true)
+        when Operators::GREATER_THAN, Operators::AFTER  then "#{field}>#{format_value(value)}"
+        when Operators::LESS_THAN,    Operators::BEFORE then "#{field}<#{format_value(value)}"
+        when Operators::PRESENT      then "#{field}:*"
+        when Operators::BLANK        then "-#{field}:*"
+        else
+          raise UnsupportedOperatorError,
+                "Zendesk datasource does not yet translate operator '#{leaf.operator}' on field '#{field}'"
+        end
+      end
+
+      # An empty `IN []` would translate to '', which the branch then drops —
+      # silently turning "match nothing" into "match everything". Raise instead.
+      def translate_in(field, value, negate:)
+        values = Array(value)
+        if values.empty?
+          raise UnsupportedOperatorError,
+                "#{negate ? "NOT_IN" : "IN"} on field '#{field}' was given an empty array; " \
+                'pass at least one value or use the BLANK / PRESENT operators.'
+        end
+
+        prefix = negate ? '-' : ''
+        values.map { |v| "#{prefix}#{field}:#{format_value(v)}" }.join(' ')
+      end
+
+      def mapped_field(field)
+        @custom_fields[field] || field
+      end
+
+      def format_value(value)
+        case value
+        when nil            then raise_nil_value_error
+        when Time, DateTime then value.utc.strftime('%Y-%m-%dT%H:%M:%SZ')
+        when Date           then format_date(value)
+        when String         then format_string(value)
+        else                     value.to_s
+        end
+      end
+
+      # `field:` with a nil value would parse as a presence check on Zendesk's
+      # side — silently the wrong query. PRESENT / BLANK is the supported path.
+      def raise_nil_value_error
+        raise UnsupportedOperatorError,
+              'Filter value is nil; use the PRESENT or BLANK operator to filter for absence.'
+      end
+
+      def format_date(value)
+        Time.use_zone(@timezone) do
+          Time.zone.local(value.year, value.month, value.day).utc.strftime('%Y-%m-%dT%H:%M:%SZ')
+        end
+      rescue ArgumentError
+        ForestAdminDatasourceZendesk.logger.warn(
+          "[forest_admin_datasource_zendesk] unknown timezone '#{@timezone}', falling back to UTC"
+        )
+        value.strftime('%Y-%m-%dT00:00:00Z')
+      end
+
+      def format_string(value)
+        return value unless value.match?(/[\s"():-]/)
+
+        %("#{value.gsub('"', '\\"')}")
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_zendesk/schema/custom_fields_introspector.rb

@@ -0,0 +1,114 @@
+module ForestAdminDatasourceZendesk
+  module Schema
+    # Returns entries shaped { column_name:, zendesk_id:, zendesk_key:, schema: }.
+    # `zendesk_key` is set for user/org fields (Zendesk addresses those by key);
+    # ticket fields use `zendesk_id` only.
+    class CustomFieldsIntrospector
+      ColumnSchema = ForestAdminDatasourceToolkit::Schema::ColumnSchema
+      Operators    = ForestAdminDatasourceToolkit::Components::Query::ConditionTree::Operators
+
+      STRING_OPS = [Operators::EQUAL, Operators::NOT_EQUAL, Operators::IN, Operators::NOT_IN,
+                    Operators::PRESENT, Operators::BLANK].freeze
+      NUMBER_OPS = (STRING_OPS + [Operators::GREATER_THAN, Operators::LESS_THAN]).freeze
+      DATE_OPS   = [Operators::EQUAL, Operators::BEFORE, Operators::AFTER,
+                    Operators::PRESENT, Operators::BLANK].freeze
+
+      ZENDESK_TO_COLUMN_TYPE = {
+        'text' => 'String',
+        'textarea' => 'String',
+        'regexp' => 'String',
+        'partialcreditcard' => 'String',
+        'integer' => 'Number',
+        'decimal' => 'Number',
+        'date' => 'Dateonly',
+        'checkbox' => 'Boolean',
+        'dropdown' => 'Enum',
+        'tagger' => 'Enum',
+        'multiselect' => 'Json',
+        'lookup' => 'Number'
+      }.freeze
+
+      def initialize(client)
+        @client = client
+      end
+
+      def ticket_custom_fields
+        introspect(@client.fetch_ticket_fields, key_strategy: :ticket)
+      end
+
+      def user_custom_fields
+        introspect(@client.fetch_user_fields, key_strategy: :user_or_org)
+      end
+
+      def organization_custom_fields
+        introspect(@client.fetch_organization_fields, key_strategy: :user_or_org)
+      end
+
+      private
+
+      def introspect(raw_fields, key_strategy:)
+        Array(raw_fields)
+          .select { |raw| usable_field?(raw, key_strategy) }
+          .filter_map { |raw| build_entry(raw, key_strategy) }
+      end
+
+      # Skip non-removable ticket fields: those are system fields the Ticket
+      # schema already declares (subject, status, ...), and re-adding them
+      # would conflict.
+      def usable_field?(raw, key_strategy)
+        return false unless raw['active']
+        return false if key_strategy == :ticket && raw['removable'] == false
+
+        ZENDESK_TO_COLUMN_TYPE.key?(raw['type'])
+      end
+
+      def build_entry(raw, key_strategy)
+        column_type = ZENDESK_TO_COLUMN_TYPE.fetch(raw['type'])
+        name, key   = column_naming(raw, key_strategy)
+        { column_name: name, zendesk_id: raw['id'], zendesk_key: key,
+          schema: build_schema(raw, column_type) }
+      end
+
+      def column_naming(raw, strategy)
+        case strategy
+        when :ticket then ["custom_#{raw["id"]}", nil]
+        when :user_or_org
+          key = raw['key'] || "custom_#{raw["id"]}"
+          [key, key]
+        end
+      end
+
+      def build_schema(raw, column_type)
+        opts = {
+          column_type: column_type,
+          filter_operators: filter_operators_for(column_type),
+          is_read_only: false,
+          is_sortable: false
+        }
+
+        if column_type == 'Enum'
+          opts[:enum_values] = Array(raw['custom_field_options']).filter_map { |o| o['value'] }
+          # Forest rejects empty Enum schemas; fall back to String so the column
+          # still appears.
+          if opts[:enum_values].empty?
+            opts[:column_type] = 'String'
+            opts[:filter_operators] = STRING_OPS
+            opts.delete(:enum_values)
+          end
+        end
+
+        ColumnSchema.new(**opts)
+      end
+
+      def filter_operators_for(column_type)
+        case column_type
+        when 'Number' then NUMBER_OPS
+        when 'Dateonly' then DATE_OPS
+        when 'Boolean' then [Operators::EQUAL, Operators::NOT_EQUAL]
+        when 'Json'    then []
+        else                STRING_OPS
+        end
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_zendesk/version.rb

@@ -0,0 +1,3 @@
+module ForestAdminDatasourceZendesk
+  VERSION = "1.28.1"
+end