gitlab-customer-support-operations_zendesk 1.0.0

data/lib/support_ops_zendesk/zendesk/satisfaction_reasons.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+# Defines the module SupportOps.
+module SupportOps
+  # Defines the module Zendesk
+  module Zendesk
+    ##
+    # Defines the class SatisfactionReasons within the module {SupportOps::Zendesk}.
+    #
+    # @author Jason Colyer
+    # @since 1.0.0
+    # @attr [String] created_at The time the reason was created
+    # @attr [String] deleted_at The time the reason was deleted
+    # @attr [Integer] id Automatically assigned upon creation
+    # @attr [String] raw_value The dynamic content placeholder, if present, or the current "value", if not.
+    # @attr [Integer] reason_code An account-level code for referencing the reason. Custom reasons are assigned an auto-incrementing integer (non-system reason codes begin at 1000).
+    # @attr [String] updated_at The time the reason was updated
+    # @attr [String] value Translated value of the reason in the account locale
+    # @todo list
+    # @todo find_by_name
+    # @todo get
+    # @todo get!
+    class SatisfactionReasons < SupportOps::Zendesk::Base
+      define_attributes :created_at, :deleted_at, :id, :raw_value, :reason_code,
+                        :updated_at, :value
+      readonly_attributes :created_at, :deleted_at, :id, :reason_code,
+                          :updated_at
+
+      ##
+      # Lists all satisfaction reasons in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @return [Array]
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/ticket-management/satisfaction_reasons/#list-reasons-for-satisfaction-rating
+      #   Zendesk API > Satisfaction Reasons > List Reasons for Satisfaction Rating
+      # @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
+      #
+      #   reasons = SupportOps::Zendesk::SatisfactionReasons.list
+      #   pp reasons.first.reason_code
+      #   # => 1003
+      def self.list
+        response = client.connection.get('satisfaction_reasons')
+        Oj.load(response.body)['satisfaction_reasons'].map { |s| SatisfactionReasons.new(s) }
+      end
+
+      ##
+      # Locates a satisfaction reason within Zendesk by name. Can utilize a cache for quicker results
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @overload find_by_name(key: value)
+      #   @param name [String required] The name to search for
+      #   @param cache [Array] An Array of SupportOps::Zendesk::SatisfactionReasons to use as a cache
+      # @return [Object] An instance of {SupportOps::Zendesk::SatisfactionReasons}
+      # @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
+      #
+      #   reasons = SupportOps::Zendesk::SatisfactionReasons.list
+      #   reason = SupportOps::Zendesk::SatisfactionReasons.find_by_name(name: 'Agent did not respond quickly', cache: reasons)
+      #   pp reason.value
+      #   # => "Agent did not respond quickly"
+      #   pp reason.reason_code
+      #   # => 1003
+      def self.find_by_name(**args)
+        raise 'You have to provide a name' unless args[:name]
+        if args[:cache]
+          raise 'Provided cache is not an Array' unless args[:cache].is_a? Array
+          reasons = args[:cache]
+        else
+          reasons = list
+        end
+        reasons.detect { |c| c.value.downcase == args[:name].to_s.downcase }
+      end
+
+      ##
+      # Locates a specific satisfaction reason in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/ticket-management/satisfaction_reasons/#show-reason-for-satisfaction-rating
+      #   Zendesk API > Satisfaction Reasons > Show Reason for Satisfaction Rating
+      # @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
+      #
+      #   reason = SupportOps::Zendesk::SatisfactionReasons.get(120447)
+      #   pp reason.reason_code
+      #   # => 1001
+      def self.get(object)
+        if object.is_a? SatisfactionReasons
+          SatisfactionReasons.new(id: id).find
+        else
+          SatisfactionReasons.new(id: object).find
+        end
+      end
+
+      ##
+      # Locates a specific satisfaction reason in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/ticket-management/satisfaction_reasons/#show-reason-for-satisfaction-rating
+      #   Zendesk API > Satisfaction Reasons > Show Reason for Satisfaction Rating
+      # @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
+      #
+      #   reason = SupportOps::Zendesk::SatisfactionReasons.get!(120447)
+      #   pp reason.reason_code
+      #   # => 1001
+      def self.get!(object)
+        if object.is_a? SatisfactionReasons
+          SatisfactionReasons.new(id: id).find!
+        else
+          SatisfactionReasons.new(id: object).find!
+        end
+      end
+
+      private
+      
+      ##
+      # @private
+      def get_record
+        response = self.client.connection.get("satisfaction_reasons/#{self.id}")
+        return nil if response.status != 200
+
+        Oj.load(response.body)['satisfaction_reason']
+      end
+    end
+  end
+end

data/lib/support_ops_zendesk/zendesk/schedule_holidays.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Defines the module SupportOps.
+module SupportOps
+  # Defines the module Zendesk
+  module Zendesk
+    ##
+    # Defines the class ScheduleHolidays within the module {SupportOps::Zendesk}.
+    #
+    # @author Jason Colyer
+    # @since 1.0.0
+    # @attr [String] end_date Must be in ISO 8601 date format. For example: "2021-01-01".
+    # @attr [Integer] id Automatically assigned upon creation
+    # @attr [String] name Name of the schedule holiday
+    # @attr [String] start_date Must be in ISO 8601 date format. For example, "2021-01-01".
+    # @todo List Holidays for Schedule => https://developer.zendesk.com/api-reference/ticketing/ticket-management/schedules/#list-holidays-for-schedule
+    # @todo Show Holiday => https://developer.zendesk.com/api-reference/ticketing/ticket-management/schedules/#show-holiday
+    # @todo Create Holiday => https://developer.zendesk.com/api-reference/ticketing/ticket-management/schedules/#create-holiday
+    # @todo Update Holiday => https://developer.zendesk.com/api-reference/ticketing/ticket-management/schedules/#update-holiday
+    # @todo Delete Holiday => https://developer.zendesk.com/api-reference/ticketing/ticket-management/schedules/#delete-holiday
+    class ScheduleHolidays < SupportOps::Zendesk::Base
+      define_attributes :end_date, :id, :name, :start_date
+
+      private
+    end
+  end
+end

data/lib/support_ops_zendesk/zendesk/schedules.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+# Defines the module SupportOps.
+module SupportOps
+  # Defines the module Zendesk
+  module Zendesk
+    ##
+    # Defines the class Schedules within the module {SupportOps::Zendesk}.
+    #
+    # @author Jason Colyer
+    # @since 1.0.0
+    # @attr [String] created_at Time the schedule was created
+    # @attr [Integer] id Automatically assigned upon creation
+    # @attr [Array] intervals An array of starting and ending times for the schedule
+    # @attr [String] name Name of the schedule
+    # @attr [String] time_zone Time zone of the schedule
+    # @attr [String] updated_at Time the schedule was last updated
+    # @todo Create Schedule => https://developer.zendesk.com/api-reference/ticketing/ticket-management/schedules/#create-schedule
+    # @todo Update Schedule => https://developer.zendesk.com/api-reference/ticketing/ticket-management/schedules/#update-schedule
+    # @todo Delete Schedule => https://developer.zendesk.com/api-reference/ticketing/ticket-management/schedules/#delete-schedule
+    # @todo Update Intervals for a Schedule => https://developer.zendesk.com/api-reference/ticketing/ticket-management/schedules/#update-intervals-for-a-schedule
+    class Schedules < SupportOps::Zendesk::Base
+      # @!parse
+      #   # Lists holidays on a schedule
+      #   # 
+      #   # @author Jason Colyer
+      #   # @since 1.0.0
+      #   # @return [Boolean]
+      #   # @note This is inherited from {SupportOps::Zendesk::Base#holidays}
+      #   # @see
+      #   #   https://developer.zendesk.com/api-reference/ticketing/ticket-management/schedules/#list-holidays-for-schedule
+      #   #   Zendesk API > Schedules > List Holidays for Schedule
+      #   # @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_schedule = SupportOps::Zendesk::Schedules.get!(123456)
+      #   #   holidays = existing_schedule.holidays
+      #   #   pp holidays.last.name
+      #   #   # => "Boxing Day"
+      #   def holidays; end
+      define_attributes :created_at, :id, :intervals, :name, :time_zone,
+                        :updated_at
+      readonly_attributes :created_at, :id, :updated_at
+
+      ##
+      # Lists schedules in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @return [Array]
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/ticket-management/schedules/#list-schedules
+      #   Zendesk API > Schedules > List Schedules
+      # @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
+      #
+      #   schedules = SupportOps::Zendesk::Schedules.list
+      #   pp schedules.count
+      #   # => 5
+      def self.list
+        response = client.connection.get('business_hours/schedules')
+        body = Oj.load(response.body)
+        body['schedules'].map { |s| Schedules.new(s) }
+      end
+
+      ##
+      # Locates a specific schedule in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/ticket-management/schedules/#show-schedule
+      #   Zendesk API > Schedules > Show Schedule
+      # @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
+      #
+      #   schedule = SupportOps::Zendesk::Schedule.get(123456)
+      #   pp schedule.name
+      #   # => "Business Hours"
+      def self.get(object)
+        if object.is_a? Schedules
+          Schedules.new(id: id).find
+        else
+          Schedules.new(id: object).find
+        end
+      end
+
+      ##
+      # Locates a specific schedule in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/ticket-management/schedules/#show-schedule
+      #   Zendesk API > Schedules > Show Schedule
+      # @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
+      #
+      #   schedule = SupportOps::Zendesk::Schedule.get(123456)
+      #   pp schedule.name
+      #   # => "Business Hours"
+      def self.get!(object)
+        if object.is_a? Schedules
+          Schedules.new(id: id).find!
+        else
+          Schedules.new(id: object).find!
+        end
+      end
+
+      ##
+      # Locates a schedule within Zendesk by name. Can utilize a cache for quicker results
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @overload find_by_name(key: value)
+      #   @param name [String required] The name to search for
+      #   @param cache [Array] An Array of SupportOps::Zendesk::Schedules to use as a cache
+      # @return [Object] An instance of {SupportOps::Zendesk::Schedules}
+      # @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
+      #
+      #   schedules = SupportOps::Zendesk::Schedules.list
+      #   schedule = SupportOps::Zendesk::Schedules.find_by_name(name: 'Business Hours', cache: schedules)
+      #   pp schedule.name
+      #   # => "Business Hours"
+      #   pp schedule.id
+      #   # => 123456
+      def self.find_by_name(**args)
+        raise 'You have to provide a name' unless args[:name]
+        if args[:cache]
+          raise 'Provided cache is not an Array' unless args[:cache].is_a? Array
+          schedules = args[:cache]
+        else
+          schedules = list
+        end
+        schedules.detect { |c| c.name.downcase == args[:name].to_s.downcase }
+      end
+
+      private
+
+      ##
+      # @private
+      def get_record
+        response = self.client.connection.get("business_hours/schedules/#{self.id}")
+        return nil if response.status != 200
+
+        Oj.load(response.body)['schedule']
+      end
+
+      ##
+      # @private
+      def holidays_record
+        response = self.client.connection.get("business_hours/schedules/#{self.id}/holidays")
+        body = Oj.load(response.body)
+        body['holidays'].map { |h| ScheduleHolidays.new(h) }
+      end
+    end
+  end
+end

data/lib/support_ops_zendesk/zendesk/search.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+# Defines the module SupportOps.
+module SupportOps
+  # Defines the module Zendesk
+  module Zendesk
+    ##
+    # Defines the class Search within the module {SupportOps::Zendesk}.
+    #
+    # @author Jason Colyer
+    # @since 1.0.0
+    class Search < SupportOps::Zendesk::Base
+      ##
+      # A wrapper for {SupportOps::Zendesk::Search#search} that specifies to use type:ticket
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @overload tickets(key: value)
+      #   @param query [String required] The search query to perform to search for
+      # @return [Array]
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/ticket-management/search/#list-search-results
+      #   Zendesk API > Search > List Search Results
+      # @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
+      #
+      #   results = SupportOps::Zendesk::Search.tickets(query: 'custom_field_360018253094:americas__usa tags:ultimate satisfaction:badwithcomment')
+      #   pp results.first.id
+      #   # => 125834
+      def self.tickets(**args)
+        raise 'You have to provide a search query' unless args[:query]
+        search(type: 'ticket', query: args[:query])
+      end
+
+      ##
+      # A wrapper for {SupportOps::Zendesk::Search#search} that specifies to use type:user
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @overload users(key: value)
+      #   @param query [String required] The search query to perform to search for
+      # @return [Array]
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/ticket-management/search/#list-search-results
+      #   Zendesk API > Search > List Search Results
+      # @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
+      #
+      #   results = SupportOps::Zendesk::Search.users(query: 'email:alice@example.com')
+      #   pp results.first.name
+      #   # => "Alice Example"
+      def self.users(**args)
+        raise 'You have to provide a search query' unless args[:query]
+        search(type: 'user', query: args[:query])
+      end
+
+      ##
+      # A wrapper for {SupportOps::Zendesk::Search#search} that specifies to use type:organization
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @overload organizations(key: value)
+      #   @param query [String required] The search query to perform to search for
+      # @return [Array]
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/ticket-management/search/#list-search-results
+      #   Zendesk API > Search > List Search Results
+      # @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
+      #
+      #   results = SupportOps::Zendesk::Search.organizations(query: 'salesforce_id:ABCDEFGH0123456*')
+      #   pp results.first.notes
+      #   # => "This org is escalated. Please talk to support managers."
+      def self.organizations(**args)
+        raise 'You have to provide a search query' unless args[:query]
+        search(type: 'organization', query: args[:query])
+      end
+
+      ##
+      # A wrapper for {SupportOps::Zendesk::Search#search} that specifies to use type:group
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @overload groups(key: value)
+      #   @param query [String required] The search query to perform to search for
+      # @return [Array]
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/ticket-management/search/#list-search-results
+      #   Zendesk API > Search > List Search Results
+      # @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
+      #
+      #   results = SupportOps::Zendesk::Search.groups(query: 'Support')
+      #   pp results.first.name
+      #   # => "Support AMER"
+      def self.groups(**args)
+        raise 'You have to provide a search query' unless args[:query]
+        search(type: 'group', query: args[:query])
+      end
+
+      ##
+      # Perform a search and list the first 1000 results
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @overload search(key: value)
+      #   @param type [String required] The search type to perform
+      #   @param query [String required] The search query to perform to search for
+      # @return [Array]
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/ticket-management/search/#list-search-results
+      #   Zendesk API > Search > List Search Results
+      # @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
+      #
+      #   search = SupportOps::Zendesk::Search.search(type: 'organization', query: 'salesforce_id:ABCDEFGH0123456*')
+      #   pp search.first.notes
+      #   # => "This org is escalated. Please talk to support managers."
+      def self.search(**args)
+        raise 'You have to provide a search type' unless args[:type]
+        raise 'You have to provide a search query' unless args[:query]
+        array = []
+        page = 1
+        loop do
+          response = client.connection.get "search?page=#{page}&query=type:#{args[:type]} #{ERB::Util.url_encode(args[:query])}"
+          body = Oj.load(response.body)
+          raise "Bad search performed => #{body}" if response.status == 422
+          array += body['results'].map { |r| object_from_type(args[:type], r) }
+          break if array.count >= 1000
+          break if body['next_page'].nil?
+
+          page += 1
+        end
+        array
+      end
+
+      ##
+      # Returns the type of Object to use depending on the type of query
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @param type [String] The type of search to perform
+      # @param result [Hash] The search result item
+      # @return [Object]
+      def self.object_from_type(type, result)
+        return Tickets.new(result) if type == 'ticket'
+        return Users.new(result) if type == 'user'
+        return Organizations.new(result) if type == 'organization'
+        return Groups.new(result) if type == 'group'
+
+        nil
+      end
+    end
+  end
+end