Merge pull request #607 from zendesk/jury.razumau/custom_fields

add way to refer to custom fields by their names

Author: razumau

lib/zendesk_api/client.rb

@@ -32,6 +32,8 @@ class Client
     attr_reader :config
     # @return [Array] Custom response callbacks
     attr_reader :callbacks
+    # @return [Hash] Memoized account data
+    attr_reader :account_data
 
     # Handles resources such as 'tickets'. Any options are passed to the underlying collection, except reload which disregards
     # memoization and creates a new Collection instance.
@@ -95,6 +97,7 @@ def initialize
 
       @callbacks = []
       @resource_cache = {}
+      @account_data = {}
 
       check_url
       check_instrumentation
@@ -153,6 +156,11 @@ def self.check_deprecated_namespace_usage(attributes, name)
       end
     end
 
+    def refresh_custom_fields_metadata
+      account_data[:custom_fields] ||= {}
+      ticket_fields.each { |field| account_data[:custom_fields][field.title] = field.id }
+    end
+
     protected
 
     # Called by {#connection} to build a connection. Can be overwritten in a

lib/zendesk_api/resource.rb

@@ -76,6 +76,14 @@ def initialize(client, attributes = {})
       @attributes.clear_changes unless new_record?
     end
 
+    def account_data
+      @client.account_data
+    end
+
+    def refresh_custom_fields_metadata
+      @client.refresh_custom_fields_metadata
+    end
+
     # Passes the method onto the attributes hash.
     # If the attributes are nested (e.g. { :tickets => { :id => 1 } }), passes the method onto the nested hash.
     def method_missing(*args, &)

lib/zendesk_api/resources.rb

@@ -546,6 +546,43 @@ def to_param
 
     has_many :incidents, class: Ticket
 
+    class CustomFieldAccessor
+      def initialize(ticket)
+        @ticket = ticket
+      end
+
+      def [](field_name)
+        find_by_name(field_name)["value"]
+      end
+
+      def []=(field_name, value)
+        find_by_name(field_name)["value"] = value
+      end
+
+      private
+
+      def find_by_name(field_name)
+        @ticket.refresh_custom_fields_metadata unless @ticket.account_data.has_key?(:custom_fields)
+
+        custom_field_id = @ticket.account_data[:custom_fields][field_name]
+        raise ArgumentError, "No custom field named '#{field_name}' found in field definitions" if custom_field_id.nil?
+
+        custom_field = @ticket.custom_fields.find { |cf| cf["id"] == custom_field_id }
+        raise ArgumentError, "No custom field with id #{custom_field_id} found. Field name: '#{field_name}'" if custom_field.nil?
+
+        custom_field
+      end
+    end
+
+    # Returns a custom field accessor that supports bracket notation.
+    # Usage:
+    #   ticket.custom_field["field name"]            # get
+    #   ticket.custom_field["field name"] = "value"  # set
+    # You need to call `save!` on a ticket after changing a custom field value.
+    def custom_field
+      @custom_field_accessor ||= CustomFieldAccessor.new(self)
+    end
+
     # Gets a incremental export of tickets from the start_time until now.
     # @param [Client] client The {Client} object to be used
     # @param [Integer] start_time The start_time parameter

spec/live/Readme.md

@@ -12,3 +12,4 @@ In case you want to create a test account from scratch:
  - Add photo to user profile of that end user.
  - Create a new ticket and cc "zendesk-api-client-ruby-end-user-#{client.config.username}" (run tests once to create this user)
  - Ensure you allow admins to set up user password (or `POST /api/v2/users/{user_id}/password.json` will fail). You can check this in the admin centre > security > advanced
+ - Add ticket custom field with the display name "Custom field name" and field type "Text".

spec/live/ticket_spec.rb

@@ -110,6 +110,36 @@ def valid_attributes
     it_should_be_readable :tickets, :recent
   end
 
+  describe "custom fields" do
+    before do
+      @ticket = ZendeskAPI::Ticket.create(client, {
+        subject: "live spec subject for custom fields test",
+        description: "live spec description for custom fields test"
+      })
+    end
+
+    after do
+      @ticket&.destroy!
+    end
+
+    it "can write and read custom fields" do
+      @ticket.custom_field["Custom field name"] = "Custom field value"
+      @ticket.save!
+
+      @ticket.reload!
+      expect(@ticket.custom_field["Custom field name"]).to eq("Custom field value")
+    end
+
+    it "raises ArgumentError for non-existent fields" do
+      expect { @ticket.custom_field["This field does not exist"] }.to raise_error(ArgumentError)
+    end
+
+    it "stores custom fields metadata on a client" do
+      _custom_field_value = @ticket.custom_field["Custom field name"]
+      expect(@ticket.account_data[:custom_fields]["Custom field name"]).to eq(9961714922394)
+    end
+  end
+
   describe ".incremental_export" do
     let(:results) { ZendeskAPI::Ticket.incremental_export(client, Time.at(1023059503)) } # ~ 10 years ago