gitlab-customer-support-operations_zendesk 1.0.0

data/lib/support_ops_zendesk/zendesk/triggers.rb

@@ -0,0 +1,427 @@
+# frozen_string_literal: true
+
+# Defines the module SupportOps.
+module SupportOps
+  # Defines the module Zendesk
+  module Zendesk
+    ##
+    # Defines the class Triggers within the module {SupportOps::Zendesk}.
+    #
+    # @author Jason Colyer
+    # @since 1.0.0
+    # @attr [Array] actions An array of actions describing what the ticket trigger will do
+    # @attr [Boolean] active Whether the ticket trigger is active
+    # @attr [String] category_id The ID of the category the ticket trigger belongs to
+    # @attr [Hash] conditions An object that describes the circumstances under which the trigger performs its actions
+    # @attr [String] created_at The time the ticket trigger was created
+    # @attr [Boolean] default If true, the ticket trigger is a standard trigger
+    # @attr [String] description The description of the ticket trigger
+    # @attr [Integer] id Automatically assigned when created
+    # @attr [Integer] position Position of the ticket trigger, determines the order they will execute in
+    # @attr [String] raw_title The raw format of the title of the ticket trigger
+    # @attr [String] title The title of the ticket trigger
+    # @attr [String] updated_at The time of the last update of the ticket trigger
+    # @todo Search Ticket Triggers => https://developer.zendesk.com/api-reference/ticketing/business-rules/triggers/#search-ticket-triggers
+    # @todo List Ticket Trigger Action and Condition Definitions => https://developer.zendesk.com/api-reference/ticketing/business-rules/triggers/#list-ticket-trigger-action-and-condition-definitions
+    # @todo List Ticket Trigger Revisions => https://developer.zendesk.com/api-reference/ticketing/business-rules/triggers/#list-ticket-trigger-revisions
+    # @todo Show Ticket Trigger Revision => https://developer.zendesk.com/api-reference/ticketing/business-rules/triggers/#show-ticket-trigger-revision
+    # @todo Reorder Ticket Triggers => https://developer.zendesk.com/api-reference/ticketing/business-rules/triggers/#reorder-ticket-triggers
+    class Triggers < SupportOps::Zendesk::Base
+      # @!parse
+      #   # Creates/updates a trigger
+      #   # 
+      #   # @author Jason Colyer
+      #   # @since 1.0.0
+      #   # @return [Object] Instance of {SupportOps::Zendesk::Triggers}
+      #   # @note This is inherited from {SupportOps::Zendesk::Base#save!}
+      #   # @see
+      #   #   https://developer.zendesk.com/api-reference/ticketing/business-rules/triggers/#create-trigger
+      #   #   Zendesk API > Triggers > Create Ticket Trigger
+      #   # @see
+      #   #   https://developer.zendesk.com/api-reference/ticketing/business-rules/triggers/#update-ticket-trigger
+      #   #   Zendesk API > Triggers > Update Ticket Trigger
+      #   # @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_trigger = SupportOps::Zendesk::Triggers.new
+      #   #   new_trigger.title = 'Change priority to low for solved tickets'
+      #   #   new_trigger.conditions = {
+      #   #     all: [
+      #   #       {
+      #   #         field: 'status',
+      #   #         operator: 'is',
+      #   #         value: 'solved'
+      #   #       },
+      #   #       {
+      #   #         field: 'priority',
+      #   #         operator: 'is_not',
+      #   #         value: 'low'
+      #   #       }
+      #   #     ],
+      #   #     any: []
+      #   #   }
+      #   #   new_trigger.actions = [
+      #   #       {
+      #   #         field: 'priority',
+      #   #         value: 'low'
+      #   #       }
+      #   #   ]
+      #   #   new_trigger.catergory_id = '1234'
+      #   #
+      #   #   new_trigger.save!
+      #   #
+      #   #   pp new_trigger.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_trigger = SupportOps::Zendesk::Triggers.get!(23409462)
+      #   #   existing_trigger.title = 'Change ticket priority to low for solved tickets'
+      #   #
+      #   #   existing_trigger.save!
+      #   #
+      #   #   pp existing_trigger.title
+      #   #   # => "Change ticket priority to low for solved tickets"
+      #   def save!; end
+      # @!parse
+      #   # Deletes a trigger
+      #   # 
+      #   # @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/business-rules/triggers/#delete-ticket-trigger
+      #   #   Zendesk API > Triggers > Delete Ticket Trigger
+      #   # @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_trigger = SupportOps::Zendesk::Triggers.get!(23409462)
+      #   #   existing_trigger.delete!
+      #   def delete!; end
+      # @!parse
+      #   # Gets a trigger's category
+      #   # 
+      #   # @author Jason Colyer
+      #   # @since 1.0.0
+      #   # @return [Boolean]
+      #   # @note This is inherited from {SupportOps::Zendesk::Base#category}
+      #   # @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_trigger = SupportOps::Zendesk::Triggers.get!(23409462)
+      #   #   category = existing_trigger.category
+      #   #   pp category.name
+      #   #   # => "Ticket creation Stage"
+      #   def delete!; end
+      define_attributes :actions, :active, :category_id, :conditions,
+                        :created_at, :default, :description, :id, :position,
+                        :raw_title, :title, :updated_at
+      readonly_attributes :created_at, :default, :id, :updated_at
+
+      ##
+      # Lists triggers in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @overload list(key: value)
+      #   @param active [Boolean optional] Only active triggers if true,
+      #     inactive triggers if false, or all if not provided
+      #   @param category_id [Integer optional] Filter triggers by category ID
+      #   @param sort [String optional] Possible values are "alphabetical",
+      #     "created_at", "updated_at", or "position".
+      #   @param sort_order [String optiona] One of "asc" or "desc"; defaults to
+      #     "asc" for alphabetical and position sort, "desc" for all others
+      #   @param limit [Integer optional] The limit to the number of triggers
+      #     returned. Default to 0 (i.e. no limit)
+      # @return [Array]
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/business-rules/triggers/#list-ticket-triggers
+      #   Zendesk API > Triggers > List Ticket Triggers
+      # @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
+      #
+      #   triggers = SupportOps::Zendesk::Triggers.list(limit: 10)
+      #   pp triggers.count
+      #   # => 10
+      #   pp triggers.last.title
+      #   # => "I'm the 10th trigger"
+      def self.list(**args)
+        args[:limit] = 0 unless args[:limit]
+        sort_order = (args[:sort_order] == 'desc' ? '-' : '')
+        array = []
+        opts = 'page[size]=100'
+        opts += "&sort=#{sort_order}#{args[:sort]}" if args[:sort]
+        opts += "&active=#{args[:active]}" if args[:active]
+        opts += "&category_id=#{args[:category_id]}" if args[:category_id]
+        loop do
+          response = client.connection.get("triggers?#{opts}")
+          body = Oj.load(response.body)
+          array += body['triggers'].map { |a| Triggers.new(a) }
+          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
+
+      ##
+      # Lists active triggers in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @overload list_active(key: value)
+      #   @param category_id [Integer optional] Filter triggers by category ID
+      #   @param sort [String optional] Possible values are "alphabetical",
+      #     "created_at", "updated_at", or "position".
+      #   @param sort_order [String optiona] One of "asc" or "desc"; defaults to
+      #     "asc" for alphabetical and position sort, "desc" for all others
+      #   @param limit [Integer optional] The limit to the number of triggers
+      #     returned. Default to 0 (i.e. no limit)
+      # @return [Array]
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/business-rules/triggers/#list-active-ticket-triggers
+      #   Zendesk API > Triggers > List Active Ticket Triggers
+      # @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
+      #
+      #   triggers = SupportOps::Zendesk::Triggers.list_active(limit: 10)
+      #   pp triggers.count
+      #   # => 10
+      #   pp triggers.last.title
+      #   # => "I'm the 10th trigger"
+      def self.list_active(**args)
+        args[:limit] = 0 unless args[:limit]
+        sort_order = (args[:sort_order] == 'desc' ? '-' : '')
+        array = []
+        opts = 'page[size]=100'
+        opts += "&sort=#{sort_order}#{args[:sort]}" if args[:sort]
+        opts += "&category_id=#{args[:category_id]}" if args[:category_id]
+        loop do
+          response = client.connection.get("triggers?#{opts}")
+          body = Oj.load(response.body)
+          array += body['triggers'].map { |a| Triggers.new(a) }
+          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 trigger in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/business-rules/triggers/#show-ticket-trigger
+      #   Zendesk API > Triggers > Show Ticket Trigger
+      # @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
+      #
+      #   trigger = SupportOps::Zendesk::Triggers.get(25)
+      #   pp trigger.title
+      #   # => "I'm the 25th trigger"
+      def self.get(object)
+        if object.is_a? Triggers
+          Triggers.new(id: id).find
+        else
+          Triggers.new(id: object).find
+        end
+      end
+
+      ##
+      # Locates a specific trigger in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/business-rules/triggers/#show-ticket-trigger
+      #   Zendesk API > Triggers > Show Ticket Trigger
+      # @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
+      #
+      #   trigger = SupportOps::Zendesk::Triggers.get!(25)
+      #   pp trigger.title
+      #   # => "I'm the 25th trigger"
+      def self.get!(object)
+        if object.is_a? Triggers
+          Triggers.new(id: id).find!
+        else
+          Triggers.new(id: object).find!
+        end
+      end
+
+      ##
+      # Updates multiple triggers via a batch job
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @param triggers [Array] An array of {SupportOps::Zendesk::Triggers} instances
+      # @return [object] A {SupportOps::Zendesk::JobStatuses} instance
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/business-rules/triggers/#update-many-ticket-triggers
+      #   Zendesk API > Triggers > Update Many Ticket Triggers
+      # @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
+      #
+      #   trigger1 = SupportOps::Zendesk::Triggers.get!(123)
+      #   trigger1.title = 'Set severity for low priority tickets non-solved tickets'
+      #   trigger2 = SupportOps::Zendesk::Triggers.get!(456)
+      #   trigger2.title = 'Set severity for medium priority tickets non-solved tickets'
+      #
+      #   updates = SupportOps::Zendesk::Triggers.update_many!([trigger1, trigger2])
+      #   pp updates.id
+      #   # => "82de0b044094f0c67893ac9fe64f1a99"
+      def self.update_many!(triggers)
+        raise 'The parameter must be an Array' unless triggers.is_a? Array
+        raise 'You can only update a maximum of 100 triggers at a time' if triggers.count > 100
+        raise 'You can only use SupportOps::Zendesk::Triggers instances in the Array' unless triggers.reject { |o| o.is_a? SupportOps::Zendesk::Triggers }.count.zero?
+
+        data = { triggers: triggers.map { |a| to_hash(a).compact } }.to_json
+        response = client.connection.put('triggers/update_many', data)
+        raise "Failed to update triggers => #{body['details']}" if response.status != 200
+        JobStatuses.new(Oj.load(response.body)['job_status'])
+      end
+
+      ##
+      # Deletes multiple triggers via a batch job
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @param trigger_ids [Array] An array of trigger IDs
+      # @return [object] A {SupportOps::Zendesk::JobStatuses} instance
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/business-rules/triggers/#bulk-delete-ticket-triggers
+      #   Zendesk API > Triggers > Bulk Delete Ticket Triggers
+      # @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
+      #
+      #   delete = SupportOps::Zendesk::Triggers.delete_many!([123, 456])
+      #   pp delete.id
+      #   # => "82de0b044094f0c67893ac9fe64f1a99"
+      def self.delete_many!(trigger_ids)
+        raise 'The parameter must be an Array' unless trigger_ids.is_a? Array
+        raise 'You can only delete a maximum of 100 triggers at a time' if trigger_ids.count > 100
+
+        response = client.connection.delete("triggers/destroy_many?ids=#{trigger_ids.join(',')}")
+        raise "Failed to delete triggers => #{body['details']}" if response.status != 200
+        JobStatuses.new(Oj.load(response.body)['job_status'])
+      end
+
+      private
+
+      ##
+      # @private
+      def get_record
+        response = self.client.connection.get("triggers/#{self.id}")
+        return nil if response.status != 200
+
+        Oj.load(response.body)['trigger']
+      end
+
+      ##
+      # @private
+      def create_record
+        response = self.client.connection.post("triggers", { trigger: attributes_for_save }.to_json)
+        body = Oj.load(response.body)
+        raise "Failed to create trigger => #{body}" if response.status != 201
+        body['trigger']
+      end
+
+      ##
+      # @private
+      def update_record
+        raise "Failed to update trigger => You didn't change anything in the object" if attributes_for_save.keys == [:id]
+        response = self.client.connection.put("triggers/#{self.id}", { trigger: attributes_for_save }.to_json)
+        body = Oj.load(response.body)
+        raise "Failed to update trigger #{self.id} => #{body}" if response.status != 200
+        body['trigger']
+      end
+
+      ##
+      # @private
+      def delete_record
+        response = self.client.connection.delete("triggers/#{self.id}")
+        raise "Failed to delete trigger => #{body}" if response.status != 204
+        true
+      end
+
+      ##
+      # @private
+      def category_record
+        TriggerCategories.get(self.category_id)
+      end
+    end
+  end
+end

data/lib/support_ops_zendesk/zendesk/user_field_options.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+# Defines the module SupportOps.
+module SupportOps
+  # Defines the module Zendesk
+  module Zendesk
+    ##
+    # Defines the class UserFieldOptions within the module {SupportOps::Zendesk}.
+    #
+    # @author Jason Colyer
+    # @since 1.0.0
+    # @attr [Integer] id Automatically assigned upon creation
+    # @attr [String] name The name of the custom field option
+    # @attr [Integer] position Ordering of the field relative to other field options
+    # @attr [String] raw_name The dynamic content placeholder, if present, or the name value, if not
+    # @attr [String] value The corresponding tag and backend value for the field option
+    # @todo Show a User Field Option => https://developer.zendesk.com/api-reference/ticketing/users/user_fields/#show-a-user-field-option
+    class UserFieldOptions < SupportOps::Zendesk::Base
+      # @!parse
+      #   # Creates or updates a user field option
+      #   #
+      #   # @author Jason Colyer
+      #   # @since 1.0.0
+      #   # @return [Object]
+      #   # @note This is inherited from {SupportOps::Zendesk::Base#create_or_update!}
+      #   # @see
+      #   #   https://developer.zendesk.com/api-reference/ticketing/users/user_fields/#create-or-update-a-user-field-option
+      #   #   Zendesk API > User Fields > Create Or Update User Field Option
+      #   # @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_option = SupportOps::Zendesk::UserFieldOptions.new
+      #   #   new_option.name = 'Linux'
+      #   #   new_option.value = 'system_linux'
+      #   #   new_option.user_field_id = 123456
+      #   #
+      #   #   new_option.create_or_update!
+      #   #
+      #   #   pp new_option.name
+      #   #   # => "Linux"
+      #   def create_or_update!; end
+      # @!parse
+      #   # Deletes a user field option
+      #   # 
+      #   # @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-option
+      #   #   Zendesk API > User Fields > Delete User Field Option
+      #   # @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_option = existing_field.field_options.last
+      #   #   existing_option.delete!
+      #   def delete!; end
+      define_attributes :id, :name, :position, :raw_name, :value, :user_field_id
+      readonly_attributes :id, :user_field_id
+
+      ##
+      # Lists user field options in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @overload list(key: value)
+      #   @param user_field_id [Integer required] The user field to find the options for
+      #   @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-field-options
+      #   Zendesk API > User Fields > List User Field Options
+      # @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!(50)
+      #   options = SupportOps::Zendesk::UserFieldOptions.list(user_field_id: field.id)
+      #   pp options.count
+      #   # => 5
+      #   pp options.last.value
+      #   # => "other_or_misc"
+      def self.list(**args)
+        raise 'You must provide a user_field_id value' unless args[:user_field_id]
+        args[:limit] = 0 unless args[:limit]
+        array = []
+        opts = 'page[size]=100'
+        loop do
+          response = client.connection.get("user_fields/#{args[:user_field_id]}/options?#{opts}")
+          body = Oj.load(response.body)
+          body['custom_field_options'].each do |c|
+            c['user_field_id'] = args[:user_field_id]
+          end
+          array += body['custom_field_options'].map { |c| UserFieldOptions.new(c) }
+          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
+
+      private
+
+      ##
+      # @private
+      def create_or_update_record
+        data = {
+          'id' => self.id,
+          'name' => self.name,
+          'value' => self.value,
+          'position' => self.position,
+          'raw_name' => self.raw_name
+        }.compact
+        response = self.client.connection.post("user_fields/#{self.user_field_id}/options", { custom_field_option: data }.to_json)
+        body = Oj.load(response.body)
+        raise "Failed to create or update user field option => #{body}" unless [200, 201].include?(response.status)
+        body['custom_field_option']['user_field_id'] = self.user_field_id
+        body['custom_field_option']
+      end
+
+      ##
+      # @private
+      def delete_record
+        response = client.connection.delete("user_fields/#{self.user_field_id}/options/#{self.id}")
+        raise "Failed to delete user field option #{self.id} => #{body}" if response.status != 204
+        true
+      end
+    end
+  end
+end