gitlab-customer-support-operations_zendesk 1.0.0

data/lib/support_ops_zendesk/zendesk/ticket_forms.rb

@@ -0,0 +1,370 @@
+# frozen_string_literal: true
+
+# Defines the module SupportOps.
+module SupportOps
+  # Defines the module Zendesk
+  module Zendesk
+    ##
+    # Defines the class TicketForms within the module {SupportOps::Zendesk}.
+    #
+    # @author Jason Colyer
+    # @since 1.0.0
+    # @attr [Boolean] active If the form is set as active
+    # @attr [Array] agent_conditions Array of condition sets for agent workspaces
+    # @attr [String] created_at The time the ticket form was created
+    # @attr [Boolean] default Is the form the default form for this account
+    # @attr [String] display_name The name of the form that is displayed to an end user
+    # @attr [Array] end_user_conditions Array of condition sets for end user products
+    # @attr [Boolean] end_user_visible Is the form visible to the end user
+    # @attr [Integer] id Automatically assigned when creating ticket form
+    # @attr [Boolean] in_all_brands Is the form available for use in all brands on this account
+    # @attr [String] name The name of the form
+    # @attr [Integer] position The position of this form among other forms in the account, i.e. dropdown
+    # @attr [String] raw_display_name The dynamic content placeholder, if present, or the "display_name" value, if not.
+    # @attr [String] raw_name The dynamic content placeholder, if present, or the "name" value, if not
+    # @attr [Array] restricted_brand_ids ids of all brands that this ticket form is restricted to
+    # @attr [Array] ticket_field_ids ids of all ticket fields which are in this ticket form; the products use the order of the ids to show the field values in the tickets
+    # @attr [String] updated_at The time of the last update of the ticket form
+    # @todo List Ticket Form Statuses of a Ticket Form => https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_forms/#list-ticket-form-statuses-of-a-ticket-form
+    # @todo Create Ticket Form Statuses => https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_forms/#create-ticket-form-statuses
+    # @todo Bulk Update Ticket Form Statuses of a Ticket Form => https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_forms/#bulk-update-ticket-form-statuses-of-a-ticket-form
+    # @todo Update Ticket Form Status By Id => https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_forms/#update-ticket-form-status-by-id
+    class TicketForms < SupportOps::Zendesk::Base
+      # @!parse
+      #   # Creates/updates a ticket form. Update will update the conditions first if changed to prevent collision update issues.
+      #   # 
+      #   # @author Jason Colyer
+      #   # @since 1.0.0
+      #   # @return [Object] Instance of {SupportOps::Zendesk::TicketForms}
+      #   # @note This is inherited from {SupportOps::Zendesk::Base#save!}
+      #   # @see
+      #   #   https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_forms/#create-ticket-form
+      #   #   Zendesk API > Ticket Forms > Create Ticket Form
+      #   # @see
+      #   #   https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_forms/#update-ticket-form
+      #   #   Zendesk API > Ticket Forms > Update Ticket Form
+      #   # @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_form = SupportOps::Zendesk::TicketForms.new
+      #   #   new_form.name = 'Printer Issues'
+      #   #   new_form.end_user_visible = false
+      #   #   new_form.display_name = 'Printer Issues'
+      #   #   new_form.position = 28
+      #   #   new_form.active = true
+      #   #   new_form.in_all_brands = true
+      #   #   new_form.restricted_brand_ids = []
+      #   #   new_form.ticket_field_ids = [1, 4, 8, 26]
+      #   #   new_form.agent_conditions = []
+      #   #   new_form.end_user_conditions = []
+      #   #   new_form.default = false
+      #   #
+      #   #   new_form.save!
+      #   #
+      #   #   pp new_form.id
+      #   #   # => 35436
+      #   # @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_form = SupportOps::Zendesk::TicketForms.get!(35436)
+      #   #   existing_form.name = 'Printer/Scanner Issues'
+      #   #
+      #   #   existing_form.save!
+      #   #
+      #   #   pp existing_form.name
+      #   #   # => "Printer/Scanner Issues"
+      #   def save!; end
+      # @!parse
+      #   # Deletes a ticket form
+      #   # 
+      #   # @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_forms/#delete-ticket-form
+      #   #   Zendesk API > Ticket Forms > Delete Ticket Form
+      #   # @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_form = SupportOps::Zendesk::TicketForms.get!(35436)
+      #   #
+      #   #   existing_form.delete!
+      #   def delete!; end
+      # @!parse
+      #   # Clones a ticket form
+      #   # 
+      #   # @author Jason Colyer
+      #   # @since 1.0.0
+      #   # @return [Boolean]
+      #   # @note This is inherited from {SupportOps::Zendesk::Base#clone!}
+      #   # @see
+      #   #   https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_forms/#clone-an-already-existing-ticket-form
+      #   #   Zendesk API > Ticket Forms > Clone an Already Existing Ticket Form
+      #   # @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_form = SupportOps::Zendesk::TicketForms.get!(35436)
+      #   #
+      #   #   cloned_form = existing_form.clone!
+      #   #   pp cloned_form.name
+      #   #   # => "Copy of Printer/Scanner Issues"
+      #   def clone!; end
+      define_attributes :active, :agent_conditions, :created_at, :default,
+                        :display_name, :end_user_conditions, :end_user_visible,
+                        :id, :in_all_brands, :name, :position,
+                        :raw_display_name, :raw_name, :restricted_brand_ids,
+                        :ticket_field_ids, :updated_at
+      readonly_attributes :created_at, :id, :updated_at
+
+      ##
+      # Lists ticket forms in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @overload list(key: value)
+      #   @param active [Boolean optional] true returns active ticket forms;
+      #     false returns inactive ticket forms
+      #   @param associated_to_brand [Boolean optional] true returns the ticket
+      #     forms of the brand specified by the url's subdomain
+      #   @param end_user_visible [Boolean optional] true returns ticket forms
+      #     where end_user_visible; false returns ticket forms that are not
+      #     end-user visible
+      #   @param fallback_to_default [Boolean optional] true returns the default
+      #     ticket form when the criteria defined by the parameters results in a
+      #     set without active and end-user visible ticket forms
+      # @return [Array]
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_forms/#list-ticket-forms
+      #   Zendesk API > Ticket Forms > List Ticket Forms
+      # @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
+      #
+      #   forms = SupportOps::Zendesk::TicketFormss.list(active: true)
+      #   pp forms.count
+      #   # => 18
+      #   pp forms.last.name
+      #   # => "Printer Issues"
+      def self.list(**args)
+        args[:limit] = 0 unless args[:limit]
+        opts = ''
+        opts += "&active=#{args[:active]}" unless args[:active].nil?
+        opts += "&associated_to_brand=#{args[:associated_to_brand]}" unless args[:associated_to_brand].nil?
+        opts += "&end_user_visible=#{args[:end_user_visible]}" unless args[:end_user_visible].nil?
+        opts += "&fallback_to_default=#{args[:fallback_to_default]}" unless args[:fallback_to_default].nil?
+        response = client.connection.get("ticket_forms?#{opts}")
+        body = Oj.load(response.body)
+        body['ticket_forms'].map { |t| TicketForms.new(t) }
+      end
+
+      ##
+      # Locates a specific ticket form in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_forms/#show-ticket-form
+      #   Zendesk API > Ticket Forms > Show Ticket Form
+      # @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
+      #
+      #   form = SupportOps::Zendesk::TicketForms.get(250)
+      #   pp form.name
+      #   # => "I'm the 250th ticket form!"
+      def self.get(object)
+        if object.is_a? TicketForms
+          TicketForms.new(id: id).find
+        else
+          TicketForms.new(id: object).find
+        end
+      end
+
+      ##
+      ##
+      # Locates a specific ticket form in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_forms/#show-ticket-form
+      #   Zendesk API > Ticket Forms > Show Ticket Form
+      # @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
+      #
+      #   form = SupportOps::Zendesk::TicketForms.get!(250)
+      #   pp form.name
+      #   # => "I'm the 250th ticket form!"
+      def self.get!(object)
+        if object.is_a? TicketForms
+          TicketForms.new(id: id).find!
+        else
+          TicketForms.new(id: object).find!
+        end
+      end
+
+      ##
+      # Locates up to 100 ticket forms within Zendesk.
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @param ticket_form_ids [Array] The ticket IDs to find
+      # @return [Array]
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_forms/#show-many-ticket-forms
+      #   Zendesk API > Ticket Forms > Show Many Ticket Forms
+      # @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
+      #
+      #   forms = SupportOps::Zendesk::TicketForms.get_many([255, 256])
+      #   pp forms.map { |t| t.name }
+      #   # => ["Camera Issues", "Keyboard Issues"]
+      def self.get_many(ticket_form_ids)
+        raise 'The parameter must be an Array' unless ticket_form_ids.is_a? Array
+        raise 'You can only get a maximum of 100 ticket forms at a time' if ticket_form_ids.count > 100
+
+        response = client.connection.get("ticket_forms/show_many?ids=#{ticket_form_ids.join(',')}")
+        Oj.load(response.body)['ticket_forms'].map { |t| TicketForms.new(t) }
+      end
+
+      ##
+      # Reorders the ticket form positions in Zendesk. Must include all of them.
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @param ticket_form_ids [Array] The IDs of ticket forms in the new order
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_forms/#reorder-ticket-forms
+      #   Zendesk API > Ticket Forms > Reorder Ticket Forms
+      # @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::TicketForms.reorder!([25, 38, 24, 37])
+      #   # => true
+      def self.reorder!(ticket_form_ids)
+        current_order = list.sort_by { |l| l.position }.map { |l| l.id }
+        raise 'You must include all ticket form IDs here' unless ticket_form_ids.count == current_order.count
+        raise 'You did not make any changes' if current_order == ticket_form_ids
+        data = { ticket_form_ids: ticket_form_ids }.to_json
+        response = client.connection.put('ticket_forms/reorder', data)
+        body = Oj.load(response.body)
+        raise "Unable to reorder ticket forms => #{body}" if response.status != 200
+        true
+      end
+
+      private
+
+      ##
+      # @private
+      def get_record
+        response = self.client.connection.get("ticket_forms/#{self.id}")
+        return nil if response.status != 200
+
+        Oj.load(response.body)['ticket_form']
+      end
+
+      ##
+      # @private
+      def create_record
+        response = self.client.connection.post("ticket_forms", { ticket_form: attributes_for_save }.to_json)
+        body = Oj.load(response.body)
+        raise "Failed to create ticket form => #{body['details']}" if response.status != 201
+        body['ticket_form']
+      end
+
+      ##
+      # @private
+      def update_record
+        raise "Failed to update ticket form => You didn't change anything in the object" if attributes_for_save.keys == [:id]
+        save_data = attributes_for_save
+        if save_data[:agent_conditions] || save_data[:end_user_conditions]
+          data_for_conditions_update = {
+            id: save_data[:id]
+          }
+          data_for_conditions_update[:agent_conditions] = save_data.delete(:agent_conditions)
+          data_for_conditions_update[:end_user_conditions] = save_data.delete(:end_user_conditions)
+          response = self.client.connection.put("ticket_forms/#{self.id}", { ticket_form: data_for_conditions_update }.to_json)
+          raise "Failed to update ticket form #{self.id} => #{body['details']}" if response.status != 200
+        end
+        response = self.client.connection.put("ticket_forms/#{self.id}", { ticket_form: save_data }.to_json)
+        body = Oj.load(response.body)
+        raise "Failed to update ticket form #{self.id} => #{body['details']}" if response.status != 200
+        body['ticket_form']
+      end
+
+      ##
+      # @private
+      def delete_record
+        response = self.client.connection.delete("ticket_forms/#{self.id}")
+        raise "Failed to delete ticket form #{self.id} => #{body['details']}" if response.status != 204
+        true
+      end
+
+      ##
+      # @private
+      def clone_record
+        data = { prepend_clone_title: true }.to_json
+        response = self.client.connection.post("ticket_forms/#{self.id}/clone", data)
+        raise "Failed to clone ticket form #{self.id} => #{body['details']}" if response.status != 200
+        TicketForms.new(Oj.load(response.body)['ticket_form'])
+      end
+    end
+  end
+end

data/lib/support_ops_zendesk/zendesk/ticket_user_types.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+# Defines the module SupportOps.
+module SupportOps
+  # Defines the module Zendesk
+  module Zendesk
+    ##
+    # Defines the class TicketUserTypes within the module {SupportOps::Zendesk}.
+    #
+    # @author Jason Colyer
+    # @since 1.0.0
+    # @attr [Integer] id An auto-generated id
+    # @attr [String] name Theh name of the via type
+    class TicketUserTypes < SupportOps::Zendesk::Base
+      define_attributes :id, :name
+      readonly_attributes :id, :name
+
+      ##
+      # Lists via types
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @return [Array]
+      # @example
+      #   require 'support_ops_zendesk'
+      #   types = SupportOps::Zendesk::ViaTypes.list
+      #   pp types.first.name
+      #   # => "Web form"
+      def self.list
+        [
+          { 'id' => 'agent', 'name' => 'Agent' },
+          { 'id' => 'end_user', 'name' => 'End User' }
+        ].map { |v| TicketUserTypes.new(v) }
+      end
+
+      ##
+      # Locates a ticket user type within Zendesk by name
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @param name [String] The via type name to look for
+      # @return [Object] An instance of {SupportOps::Zendesk::ViaTypes}
+      # @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
+      #
+      #   type = SupportOps::Zendesk::TicketUserTypes.find_by_name('End User')
+      #   pp type.id
+      #   # => "end_user"
+      def self.find_by_name(name)
+        type = TicketUserTypes.list.detect { |r| r.name.downcase == name.downcase }
+        if type.nil?
+          search = Search.users(query: "email:#{name}")
+          if search.count == 1
+            type = TicketUserTypes.new({ 'id' => search.first.id, 'name' => search.first.email })
+          end
+        end
+        type
+      end
+    end
+  end
+end