gitlab-customer-support-operations_zendesk 1.0.0

data/lib/support_ops_zendesk/zendesk/automations.rb

@@ -0,0 +1,390 @@
+# frozen_string_literal: true
+
+# Defines the module SupportOps.
+module SupportOps
+  # Defines the module Zendesk
+  module Zendesk
+    ##
+    # Defines the class Automations within the module {SupportOps::Zendesk}.
+    #
+    # @author Jason Colyer
+    # @since 1.0.0
+    # @attr [Array] actions An object describing what the automation will do
+    # @attr [Boolean] active Whether the automation is active
+    # @attr [Hash] conditions An object that describes the conditions under which the automation will execute
+    # @attr [String] created_at The time the automation was created
+    # @attr [Boolean] default If true, the automation is a default automation
+    # @attr [Integer] id Automatically assigned when created
+    # @attr [Integer] position The position of the automation which specifies the order it will be executed
+    # @attr [String] raw_title The raw title of the automation
+    # @attr [String] title The title of the automation
+    # @attr [String] updated_at The time of the last update of the automation
+    # @todo Search Automations => https://developer.zendesk.com/api-reference/ticketing/business-rules/automations/#search-automations
+    class Automations < SupportOps::Zendesk::Base
+      # @!parse
+      #   # Creates/updates an automation
+      #   # 
+      #   # @author Jason Colyer
+      #   # @since 1.0.0
+      #   # @return [Object] Instance of {SupportOps::Zendesk::Automations}
+      #   # @note This is inherited from {SupportOps::Zendesk::Base#save!}
+      #   # @see
+      #   #   https://developer.zendesk.com/api-reference/ticketing/business-rules/automations/#create-automation
+      #   #   Zendesk API > automations > Create Automation
+      #   # @see
+      #   #   https://developer.zendesk.com/api-reference/ticketing/business-rules/automations/#update-automation
+      #   #   Zendesk API > Automations > Update Automation
+      #   # @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_automation = SupportOps::Zendesk::Automations.new
+      #   #   new_automation.title = 'Change priority to low for solved tickets'
+      #   #   new_automation.conditions = {
+      #   #     all: [
+      #   #       {
+      #   #         field: 'status',
+      #   #         operator: 'is',
+      #   #         value: 'solved'
+      #   #       },
+      #   #       {
+      #   #         field: 'priority',
+      #   #         operator: 'is_not',
+      #   #         value: 'low'
+      #   #       }
+      #   #     ],
+      #   #     any: []
+      #   #   }
+      #   #   new_automation.actions = [
+      #   #       {
+      #   #         field: 'priority',
+      #   #         value: 'low'
+      #   #       }
+      #   #   ]
+      #   #
+      #   #   new_automation.save!
+      #   #
+      #   #   pp new_automation.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_automation = SupportOps::Zendesk::Automations.get!(23409462)
+      #   #   existing_automation.title = 'Change ticket priority to low for solved tickets'
+      #   #
+      #   #   existing_automation.save!
+      #   #
+      #   #   pp existing_automation.title
+      #   #   # => "Change ticket priority to low for solved tickets"
+      #   def save!; end
+      # @!parse
+      #   # Deletes an automation
+      #   # 
+      #   # @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/automations/#delete-automation
+      #   #   Zendesk API > Automations > Delete Automation
+      #   # @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_automation = SupportOps::Zendesk::Automations.get!(23409462)
+      #   #   existing_automation.delete!
+      #   def delete!; end
+      define_attributes :actions, :active, :conditions, :created_at, :default,
+                        :id, :position, :raw_title, :title, :updated_at
+      readonly_attributes :created_at, :default, :id, :updated_at
+
+      ##
+      # Lists automations in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @overload list(key: value)
+      #   @param active [Boolean optional] Only active automations if true,
+      #     inactive automations if false, or all if not provided
+      #   @param sort [String optional] Possible values are "alphabetical",
+      #     "created_at", "updated_at", "usage_1h", "usage_24h", or "usage_7d"
+      #     (defaults to "position")
+      #   @param sort_order [String optiona] "asc" for ascending, "desc" for
+      #     descending
+      #   @param limit [Integer optional] The limit to the number of automations
+      #     returned. Default to 0 (i.e. no limit)
+      # @return [Array]
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/business-rules/automations/#list-automations
+      #   Zendesk API > Automations > List Automations
+      # @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
+      #
+      #   automations = SupportOps::Zendesk::Automations.list(limit: 10)
+      #   pp automations.count
+      #   # => 10
+      #   pp automations.last.title
+      #   # => "I'm the 10th automation"
+      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]
+        loop do
+          response = client.connection.get("automations?#{opts}")
+          body = Oj.load(response.body)
+          array += body['automations'].map { |a| Automations.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 automations in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @overload list_active(key: value)
+      #   @param sort [String optional] Possible values are "alphabetical",
+      #     "created_at", "updated_at", "usage_1h", "usage_24h", or "usage_7d"
+      #     (defaults to "position")
+      #   @param sort_order [String optiona] "asc" for ascending, "desc" for
+      #     descending
+      #   @param limit [Integer optional] The limit to the number of automations
+      #     returned. Default to 0 (i.e. no limit)
+      # @return [Array]
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/business-rules/automations/#list-automations
+      #   Zendesk API > Automations > List Automations
+      # @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
+      #
+      #   automations = SupportOps::Zendesk::Automations.list(limit: 10)
+      #   pp automations.count
+      #   # => 10
+      #   pp automations.last.title
+      #   # => "I'm the 10th automation"
+      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]
+        loop do
+          response = client.connection.get("automations/active?#{opts}")
+          body = Oj.load(response.body)
+          array += body['automations'].map { |a| Automations.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 automation in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/business-rules/automations/#show-automation
+      #   Zendesk API > automations > Show Automation
+      # @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
+      #
+      #   automation = SupportOps::Zendesk::Automations.get(25)
+      #   pp automation.title
+      #   # => "I'm the 25th automation"
+      def self.get(object)
+        if object.is_a? Automations
+          Automations.new(id: id).find
+        else
+          Automations.new(id: object).find
+        end
+      end
+
+      ##
+      # Locates a specific automation in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/business-rules/automations/#show-automation
+      #   Zendesk API > automations > Show Automation
+      # @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
+      #
+      #   automation = SupportOps::Zendesk::Automations.get!(25)
+      #   pp automation.title
+      #   # => "I'm the 25th automation"
+      def self.get!(object)
+        if object.is_a? Automations
+          Automations.new(id: id).find!
+        else
+          Automations.new(id: object).find!
+        end
+      end
+
+      ##
+      # Updates multiple automations via a batch job
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @param automations [Array] An array of {SupportOps::Zendesk::Automations} instances
+      # @return [object] A {SupportOps::Zendesk::JobStatuses} instance
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/business-rules/automations/#update-many-automations
+      #   Zendesk API > Automations > Update Many Automations
+      # @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
+      #
+      #   automation1 = SupportOps::Zendesk::Automations.get!(123)
+      #   automation1.name = 'Set severity for low priority tickets non-solved tickets'
+      #   automation2 = SupportOps::Zendesk::Automations.get!(456)
+      #   automation2.name = 'Set severity for medium priority tickets non-solved tickets'
+      #
+      #   updates = SupportOps::Zendesk::Automations.update_many!([automation1, automation2])
+      #   pp updates.id
+      #   # => "82de0b044094f0c67893ac9fe64f1a99"
+      def self.update_many!(automations)
+        raise 'The parameter must be an Array' unless automations.is_a? Array
+        raise 'You can only update a maximum of 100 automations at a time' if automations.count > 100
+        raise 'You can only use SupportOps::Zendesk::Automations instances in the Array' unless automations.reject { |o| o.is_a? SupportOps::Zendesk::Automations }.count.zero?
+
+        data = { automations: automations.map { |a| to_hash(a).compact } }.to_json
+        response = client.connection.put('automations/update_many', data)
+        raise "Failed to update automations => #{body['details']}" if response.status != 200
+        JobStatuses.new(Oj.load(response.body)['job_status'])
+      end
+
+      ##
+      # Deletes multiple automations via a batch job
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @param automation_ids [Array] An array of automation IDs
+      # @return [object] A {SupportOps::Zendesk::JobStatuses} instance
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/business-rules/automations/#bulk-delete-automations
+      #   Zendesk API > Automations > Bulk Delete Automations
+      # @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::Automations.delete_many!([123, 456])
+      #   pp delete.id
+      #   # => "82de0b044094f0c67893ac9fe64f1a99"
+      def self.delete_many!(automation_ids)
+        raise 'The parameter must be an Array' unless automation_ids.is_a? Array
+        raise 'You can only delete a maximum of 100 automations at a time' if automation_ids.count > 100
+
+        response = client.connection.delete("automations/destroy_many?ids=#{automation_ids.join(',')}")
+        raise "Failed to delete automations => #{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("automations/#{self.id}")
+        return nil if response.status != 200
+
+        Oj.load(response.body)['automation']
+      end
+
+      ##
+      # @private
+      def create_record
+        response = self.client.connection.post("automations", { automation: attributes_for_save }.to_json)
+        body = Oj.load(response.body)
+        raise "Failed to create automation => #{body['details']}" if response.status != 201
+        body['automation']
+      end
+
+      ##
+      # @private
+      def update_record
+        raise "Failed to update automation => You didn't change anything in the object" if attributes_for_save.keys == [:id]
+        response = self.client.connection.put("automations/#{self.id}", { automation: attributes_for_save }.to_json)
+        body = Oj.load(response.body)
+        raise "Failed to update automation #{self.id} => #{body['details']}" if response.status != 200
+        body['automation']
+      end
+
+      ##
+      # @private
+      def delete_record
+        response = self.client.connection.delete("automations/#{self.id}")
+        raise "Failed to delete automation => #{body['details']}" if response.status != 204
+        true
+      end
+    end
+  end
+end