gitlab-customer-support-operations_zendesk 1.0.0

data/lib/support_ops_zendesk/zendesk/user_fields.rb

@@ -0,0 +1,312 @@
+# frozen_string_literal: true
+
+# Defines the module SupportOps.
+module SupportOps
+  # Defines the module Zendesk
+  module Zendesk
+    ##
+    # Defines the class UserFields within the module {SupportOps::Zendesk}.
+    #
+    # @author Jason Colyer
+    # @since 1.0.0
+    # @attr [Boolean] active If true, this field is available for use
+    # @attr [String] created_at The time of the last update of the ticket field
+    # @attr [Array] custom_field_options Required and presented for a custom field of type "dropdown"; each option is represented by an object with a name and value property
+    # @attr [String] description User-defined description of this field's purpose
+    # @attr [Integer] id Automatically assigned upon creation
+    # @attr [String] key A unique key that identifies this custom field; this is used for updating the field and referencing in placeholders; the key must consist of only letters, numbers, and underscores; it can't be only numbers
+    # @attr [Integer] position Ordering of the field relative to other fields
+    # @attr [String] raw_description The dynamic content placeholder, if present, or the description value, if not
+    # @attr [String] raw_title The dynamic content placeholder, if present, or the title value, if not
+    # @attr [String] regexp_for_validation Regular expression field only; the validation pattern for a field value to be deemed valid
+    # @attr [Hash] relationship_filter A filter definition that allows your autocomplete to filter down results
+    # @attr [String] relationship_target_type A representation of what type of object the field references; options are "zen:user", "zen:organization", "zen:ticket", and "zen:custom_object:{key}" where key is a custom object key
+    # @attr [Boolean] system If true, only active and position values of this field can be changed
+    # @attr [String] tag Optional for custom field of type "checkbox"; not presented otherwise
+    # @attr [String] title The title of the custom field
+    # @attr [String] type he custom field type: "checkbox", "date", "decimal", "dropdown", "integer", "lookup", "multiselect", "regexp", "text", or "textarea"
+    # @attr [String] update_at The time of the last update of the ticket field
+    class UserFields < SupportOps::Zendesk::Base
+      # @!parse
+      #   # Creates/updates a user field
+      #   # 
+      #   # @author Jason Colyer
+      #   # @since 1.0.0
+      #   # @return [Object] Instance of {SupportOps::Zendesk::UserFields}
+      #   # @note This is inherited from {SupportOps::Zendesk::Base#save!}
+      #   # @see
+      #   #   https://developer.zendesk.com/api-reference/ticketing/users/user_fields/#create-user-field
+      #   #   Zendesk API > User Fields > Create User Field
+      #   # @see
+      #   #   https://developer.zendesk.com/api-reference/ticketing/users/user_fields/#update-user-field
+      #   #   Zendesk API > User Fields > Update User Field
+      #   # @example
+      #   #   require 'support_ops_zendesk'
+      #   #
+      #   #   SupportOps::Zendesk::Configuration.configure do |config|
+      #   #     config.url = 'https://gitlab.zendesk.com/api/v2'
+      #   #     config.username = 'jason@example.com'
+      #   #     config.token = 'abc123'
+      #   #   end
+      #   #
+      #   #   new_field = SupportOps::Zendesk::UserFields.new
+      #   #   new_field.title = 'Support description'
+      #   #   new_field.type = 'text'
+      #   #   new_field.description = 'This field describes the support plan this organization has'
+      #   #   new_field.key = 'support_description'
+      #   #
+      #   #   new_field.save!
+      #   #
+      #   #   pp new_field.id
+      #   #   # => 23409462
+      #   # @example
+      #   #   require 'support_ops_zendesk'
+      #   #
+      #   #   SupportOps::Zendesk::Configuration.configure do |config|
+      #   #     config.url = 'https://gitlab.zendesk.com/api/v2'
+      #   #     config.username = 'jason@example.com'
+      #   #     config.token = 'abc123'
+      #   #   end
+      #   #
+      #   #   existing_field = SupportOps::Zendesk::UserFields.get!(23409462)
+      #   #   existing_field.title = 'Support description (text)'
+      #   #
+      #   #   existing_field.save!
+      #   #
+      #   #   pp existing_field.title
+      #   #   # => "Support description (text)"
+      #   def save!; end
+      # @!parse
+      #   # Deletes a user field
+      #   # 
+      #   # @author Jason Colyer
+      #   # @since 1.0.0
+      #   # @return [Boolean]
+      #   # @note This is inherited from {SupportOps::Zendesk::Base#delete!}
+      #   # @see
+      #   #   https://developer.zendesk.com/api-reference/ticketing/users/user_fields/#delete-user-field
+      #   #   Zendesk API > User Fields > Delete User Field
+      #   # @example
+      #   #   require 'support_ops_zendesk'
+      #   #
+      #   #   SupportOps::Zendesk::Configuration.configure do |config|
+      #   #     config.url = 'https://gitlab.zendesk.com/api/v2'
+      #   #     config.username = 'jason@example.com'
+      #   #     config.token = 'abc123'
+      #   #   end
+      #   #
+      #   #   existing_field = SupportOps::Zendesk::UserFields.get!(23409462)
+      #   #   existing_field.delete!
+      #   def delete!; end
+      # @!parse
+      #   # Lists field options for a user field
+      #   # 
+      #   # @author Jason Colyer
+      #   # @since 1.0.0
+      #   # @return [Boolean]
+      #   # @note This is inherited from {SupportOps::Zendesk::Base#field_options}
+      #   # @see
+      #   #   https://developer.zendesk.com/api-reference/ticketing/users/user_fields/#list-user-field-options
+      #   #   Zendesk API > User Fields > List User Field Options
+      #   # @example
+      #   #   require 'support_ops_zendesk'
+      #   #
+      #   #   SupportOps::Zendesk::Configuration.configure do |config|
+      #   #     config.url = 'https://gitlab.zendesk.com/api/v2'
+      #   #     config.username = 'jason@example.com'
+      #   #     config.token = 'abc123'
+      #   #   end
+      #   #
+      #   #   existing_field = SupportOps::Zendesk::UserFields.get!(23409462)
+      #   #   options = existing_field.field_options
+      #   #   pp options.count
+      #   #   # => 5
+      #   def field_options; end
+      define_attributes :active, :created_at, :custom_field_options,
+                        :description, :id, :key, :position, :raw_description,
+                        :raw_title, :regexp_for_validation,
+                        :relationship_filter, :relationship_target_type,
+                        :system, :tag, :title, :type, :updated_at
+      readonly_attributes :created_at, :id, :system, :updated_at
+
+      ##
+      # Lists user fields in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @overload list(key: value)
+      #   @param limit [Integer optional] The limit to the number of user fields
+      #     returned. Default to 0 (i.e. no limit)
+      # @return [Array]
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/users/user_fields/#list-user-fields
+      #   Zendesk API > User Fields > List User Fields
+      # @see SupportOps::Zendesk::Configuration Setting up a client
+      # @example
+      #   require 'support_ops_zendesk'
+      #
+      #   SupportOps::Zendesk::Configuration.configure do |config|
+      #     config.url = 'https://gitlab.zendesk.com/api/v2'
+      #     config.username = 'jason@example.com'
+      #     config.token = 'abc123'
+      #   end
+      #
+      #   fields = SupportOps::Zendesk::UserFields.list(limit: 10)
+      #   pp fields.count
+      #   # => 10
+      #   pp fields.last.title
+      #   # => "I'm the 10th user field"
+      def self.list(**args)
+        args[:limit] = 0 unless args[:limit]
+        array = []
+        opts = 'page[size]=100'
+        loop do
+          response = client.connection.get("user_fields?#{opts}")
+          body = Oj.load(response.body)
+          array += body['user_fields'].map { |u| UserFields.new(u) }
+          break if args[:limit].to_i.positive? && array.count >= args[:limit].to_i
+          break unless body['meta']['has_more']
+
+          opts = body['links']['next'].split('?').last
+        end
+        return array if args[:limit].to_i.zero?
+        
+        array.first(args[:limit].to_i)
+      end
+
+      ##
+      # Locates a specific user field in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/users/user_fields/#show-user-field
+      #   Zendesk API > User Fields > Show User Field
+      # @see SupportOps::Zendesk::Configuration Setting up a client
+      # @example
+      #   require 'support_ops_zendesk'
+      #
+      #   SupportOps::Zendesk::Configuration.configure do |config|
+      #     config.url = 'https://gitlab.zendesk.com/api/v2'
+      #     config.username = 'jason@example.com'
+      #     config.token = 'abc123'
+      #   end
+      #
+      #   field = SupportOps::Zendesk::UserFields.get(25)
+      #   pp field.title
+      #   # => "I'm the 25th user field"
+      def self.get(object)
+        if object.is_a? UserFields
+          UserFields.new(id: id).find
+        else
+          UserFields.new(id: object).find
+        end
+      end
+
+      ##
+      # Locates a specific user field in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/users/user_fields/#show-user-field
+      #   Zendesk API > User Fields > Show User Field
+      # @see SupportOps::Zendesk::Configuration Setting up a client
+      # @example
+      #   require 'support_ops_zendesk'
+      #
+      #   SupportOps::Zendesk::Configuration.configure do |config|
+      #     config.url = 'https://gitlab.zendesk.com/api/v2'
+      #     config.username = 'jason@example.com'
+      #     config.token = 'abc123'
+      #   end
+      #
+      #   field = SupportOps::Zendesk::UserFields.get!(25)
+      #   pp field.title
+      #   # => "I'm the 25th user field"
+      def self.get!(object)
+        if object.is_a? UserFields
+          UserFields.new(id: id).find!
+        else
+          UserFields.new(id: object).find!
+        end
+      end
+
+      ##
+      # Reorders the user field positions in Zendesk. Must include all of them.
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @param field_ids [Array] The IDs of user fields in the new order
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/users/user_fields/#reorder-user-field
+      #   Zendesk API > User Fields > Reorder User Field
+      # @see SupportOps::Zendesk::Configuration Setting up a client
+      # @example
+      #   require 'support_ops_zendesk'
+      #
+      #   SupportOps::Zendesk::Configuration.configure do |config|
+      #     config.url = 'https://gitlab.zendesk.com/api/v2'
+      #     config.username = 'jason@example.com'
+      #     config.token = 'abc123'
+      #   end
+      #
+      #   pp SupportOps::Zendesk::UserFields.reorder!([25, 38, 24, 37])
+      #   # => true
+      def self.reorder!(field_ids)
+        current_order = list.sort_by { |l| l.position }.map { |l| l.id }
+        raise 'You must include all user field IDs here' unless field_ids.count == current_order.count
+        raise 'You did not make any changes' if current_order == field_ids
+        data = { organization_field_ids: field_ids }.to_json
+        response = client.connection.put('user_fields/reorder', data)
+        body = Oj.load(response.body)
+        raise "Unable to reorder user fields => #{body}" if response.status != 200
+        true
+      end
+
+      private
+
+      ##
+      # @private
+      def get_record
+        response = self.client.connection.get("user_fields/#{self.id}")
+        return nil if response.status != 200
+
+        Oj.load(response.body)['user_field']
+      end
+
+      ##
+      # @private
+      def create_record
+        response = self.client.connection.post("user_fields", { user_field: attributes_for_save }.to_json)
+        body = Oj.load(response.body)
+        raise "Failed to create user field => #{body['details']}" if response.status != 201
+        body['user_field']
+      end
+
+      ##
+      # @private
+      def update_record
+        raise "Failed to update user field => You didn't change anything in the object" if attributes_for_save.keys == [:id]
+        response = self.client.connection.put("user_fields/#{self.id}", { user_field: attributes_for_save }.to_json)
+        body = Oj.load(response.body)
+        raise "Failed to update user field #{self.id} => #{body['details']}" if response.status != 200
+        body['user_field']
+      end
+
+      ##
+      # @private
+      def delete_record
+        response = self.client.connection.delete("user_fields/#{self.id}")
+        raise "Failed to delete user field => #{body['details']}" if response.status != 204
+        true
+      end
+
+      ##
+      # @private
+      def field_options_record
+        UserFieldOptions.list(user_field_id: self.id)
+      end
+    end
+  end
+end