gitlab-customer-support-operations_zendesk 1.0.0

data/lib/support_ops_zendesk/zendesk/ticket_fields.rb

@@ -0,0 +1,357 @@
+# frozen_string_literal: true
+
+# Defines the module SupportOps.
+module SupportOps
+  # Defines the module Zendesk
+  module Zendesk
+    ##
+    # Defines the class TicketFields within the module {SupportOps::Zendesk}.
+    #
+    # @author Jason Colyer
+    # @since 1.0.0
+    # @attr [Boolean] active Whether this field is available
+    # @attr [Boolean] agent_can_edit Whether this field is editable by agents
+    # @attr [String] agent_description A description of the ticket field that only agents can see
+    # @attr [Boolean] collapsed_for_agents If true, the field is shown to agents by default; if false, the field is hidden alongside infrequently used fields
+    # @attr [String] created_at The time the custom ticket field was created
+    # @attr [String] creator_app_name Name of the app that created the ticket field, or a null value if no app created the ticket field
+    # @attr [Integer] creator_user_id The id of the user that created the ticket field, or a value of "-1" if an app created the ticket field
+    # @attr [Array] custom_field_options equired and presented for a custom ticket field of type "multiselect" or "tagger"
+    # @attr [Array] custom_statuses List of customized ticket statuses; only presented for a system ticket field of type "custom_status"
+    # @attr [String] description Describes the purpose of the ticket field to users
+    # @attr [Boolean] editable_in_portal Whether this field is editable by end users in Help Center
+    # @attr [Integer] id Automatically assigned when created
+    # @attr [Integer] position The relative position of the ticket field on a ticket
+    # @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] raw_title_in_portal The dynamic content placeholder if present, or the "title_in_portal" value if not
+    # @attr [String] regexp_for_validaition For "regexp" fields 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", or "zen:custom_object:{key}" where key is a custom object key
+    # @attr [Boolean] removable If false, this field is a system field that must be present on all tickets
+    # @attr [Boolean] required If true, agents must enter a value in the field to change the ticket status to solved
+    # @attr [Boolean] required_in_portal If true, end users must enter a value in the field to create the request
+    # @attr [Integer] sub_type_id For system ticket fields of type "priority" and "status"; defaults to 0; a "priority" sub type of 1 removes the "Low" and "Urgent" options; a "status" sub type of 1 adds the "On-Hold" option
+    # @attr [Array] system_field_options Presented for a system ticket field of type "tickettype", "priority" or "status"
+    # @attr [String] tag For "checkbox" fields only; a tag added to tickets when the checkbox field is selected
+    # @attr [String] title The title of the ticket field
+    # @attr [String] title_in_portal The title of the ticket field for end users in Help Center
+    # @attr [String] type System or custom field type; editable for custom field types and only on creation
+    # @attr [String] updated_at The time the custom ticket field was last updated
+    # @attr [Boolean] visibile_in_portal Whether this field is visible to end users in Help Center
+    class TicketFields < SupportOps::Zendesk::Base
+      # @!parse
+      #   # Creates/updates a ticket field
+      #   # 
+      #   # @author Jason Colyer
+      #   # @since 1.0.0
+      #   # @return [Object] Instance of {SupportOps::Zendesk::TicketFields}
+      #   # @note This is inherited from {SupportOps::Zendesk::Base#save!}
+      #   # @see
+      #   #   https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_fields/#create-ticket-field
+      #   #   Zendesk API > Ticket Fields > Create Ticket Field
+      #   # @see
+      #   #   https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_fields/#update-ticket-field
+      #   #   Zendesk API > Ticket Fields > Update Ticket 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::TicketFields.new
+      #   #   new_field.title = 'Support description'
+      #   #   new_field.type = 'text'
+      #   #
+      #   #   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::TicketFields.get!(23409462)
+      #   #   existing_field.title = 'Support description (text)'
+      #   #
+      #   #   existing_field.save!
+      #   #
+      #   #   pp existing_field.title
+      #   #   # => "Support description (text)"
+      #   def save!; end
+      # @!parse
+      #   # Deletes a ticket 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/tickets/ticket_fields/#delete-ticket-field
+      #   #   Zendesk API > Ticket Fields > Delete Ticket 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::TicketFields.get!(23409462)
+      #   #   existing_field.delete!
+      #   def delete!; end
+      # @!parse
+      #   # Lists field options for a ticket 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/tickets/ticket_fields/#list-ticket-field-options
+      #   #   Zendesk API > Ticket Fields > List Ticket 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::TicketFields.get!(23409462)
+      #   #   options = existing_field.field_options
+      #   #   pp options.count
+      #   #   # => 5
+      #   def field_options; end
+      define_attributes :active, :agent_can_edit, :agent_description,
+                        :collapsed_for_agents, :created_at, :creator_app_name,
+                        :creator_user_id, :custom_field_options,
+                        :custom_statuses, :description, :editable_in_portal,
+                        :id, :position, :raw_description, :raw_title,
+                        :raw_title_in_portal, :regexp_for_validaition,
+                        :relationship_filter, :relationship_target_type,
+                        :removable, :required, :required_in_portal,
+                        :sub_type_id, :system_field_options, :tag, :title,
+                        :title_in_portal, :type, :updated_at,
+                        :visibile_in_portal
+      readonly_attributes :agent_can_edit, :created_at, :custom_statuses, :id,
+                          :removable, :system_field_options, :updated_at
+
+      ##
+      # Lists ticket 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 ticket
+      #     fields returned. Default to 0 (i.e. no limit)
+      # @return [Array]
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_fields/#list-ticket-fields
+      #   Zendesk API > Ticket Fields > List Ticket 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::TicketFields.list(limit: 10)
+      #   pp fields.count
+      #   # => 10
+      #   pp fields.last.title
+      #   # => "I'm the 10th ticket field"
+      def self.list(**args)
+        args[:limit] = 0 unless args[:limit]
+        array = []
+        opts = 'page[size]=100'
+        loop do
+          response = client.connection.get("ticket_fields?#{opts}")
+          body = Oj.load(response.body)
+          array += body['ticket_fields'].map { |t| TicketFields.new(t) }
+          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
+
+      ##
+      # Returns an approximate count of ticket fields in the account. If the count exceeds 100,000, it is updated every 24 hours.
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @return [Hash]
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_fields/#count-ticket-fields
+      #   Zendesk API > Ticket Fields > Count Ticket 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::TicketFields.count
+      #   pp fields['value']
+      #   # => 102
+      def self.count
+        response = client.connection.get('ticket_fields/count')
+        Oj.load(response.body)['count']
+      end
+
+      ##
+      # Locates a specific ticket field in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_fields/#show-ticket-field
+      #   Zendesk API > Ticket Fields > Show Ticket 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::TicketFields.get(25)
+      #   pp field.title
+      #   # => "I'm the 25th ticket field"
+      def self.get(object)
+        if object.is_a? TicketFields
+          TicketFields.new(id: id).find
+        else
+          TicketFields.new(id: object).find
+        end
+      end
+
+      ##
+      # Locates a specific ticket field in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_fields/#show-ticket-field
+      #   Zendesk API > Ticket Fields > Show Ticket 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::TicketFields.get!(25)
+      #   pp field.title
+      #   # => "I'm the 25th ticket field"
+      def self.get!(object)
+        if object.is_a? TicketFields
+          TicketFields.new(id: id).find!
+        else
+          TicketFields.new(id: object).find!
+        end
+      end
+
+      ##
+      # Reorders the ticket 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/tickets/ticket_fields/#reorder-ticket-fields
+      #   Zendesk API > Ticket Fields > Reorder Ticket 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::TicketFields.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 ticket 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('ticket_fields/reorder', data)
+        body = Oj.load(response.body)
+        raise "Unable to reorder ticket fields => #{body}" if response.status != 200
+        true
+      end
+
+      private
+
+      ##
+      # @private
+      def get_record
+        response = self.client.connection.get("ticket_fields/#{self.id}")
+        return nil if response.status != 200
+
+        Oj.load(response.body)['ticket_field']
+      end
+
+      ##
+      # @private
+      def create_record
+        response = self.client.connection.post("ticket_fields", { ticket_field: attributes_for_save }.to_json)
+        body = Oj.load(response.body)
+        raise "Failed to create ticket field => #{body}" if response.status != 201
+        body['ticket_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("ticket_fields/#{self.id}", { ticket_field: attributes_for_save }.to_json)
+        body = Oj.load(response.body)
+        raise "Failed to update ticket field #{self.id} => #{body}" if response.status != 200
+        body['ticket_field']
+      end
+
+      ##
+      # @private
+      def delete_record
+        response = self.client.connection.delete("ticket_fields/#{self.id}")
+        raise "Failed to delete ticket field => #{body['details']}" if response.status != 204
+        true
+      end
+
+      ##
+      # @private
+      def field_options_record
+        TicketFieldOptions.list(ticket_field_id: self.id)
+      end
+    end
+  end
+end