gitlab-customer-support-operations_zendesk 1.0.0

data/lib/support_ops_zendesk/zendesk/groups.rb

@@ -0,0 +1,385 @@
+# frozen_string_literal: true
+
+# Defines the module SupportOps.
+module SupportOps
+  # Defines the module Zendesk
+  module Zendesk
+    ##
+    # Defines the class Groups within the module {SupportOps::Zendesk}.
+    #
+    # @author Jason Colyer
+    # @since 1.0.0
+    # @attr [String] created_at The time the group was created
+    # @attr [Boolean] default If the group is the default one for the account
+    # @attr [Boolean] deleted Deleted groups get marked as such
+    # @attr [String] description The description of the group
+    # @attr [Integer] id Automatically assigned when creating groups
+    # @attr [Boolean] is_public If true, the group is public. If false, the group is private. You can't change a private group to a public group
+    # @attr [String] name The name of the group
+    # @attr [String] updated_at The time of the last update of the group
+    class Groups < SupportOps::Zendesk::Base
+      # @!parse
+      #   # Creates/updates a group
+      #   # 
+      #   # @author Jason Colyer
+      #   # @since 1.0.0
+      #   # @return [Object] Instance of {SupportOps::Zendesk::Groups}
+      #   # @note This is inherited from {SupportOps::Zendesk::Base#save!}
+      #   # @see
+      #   #   https://developer.zendesk.com/api-reference/ticketing/groups/groups/#create-group
+      #   #   Zendesk API > Groups > Create Group
+      #   # @see
+      #   #   https://developer.zendesk.com/api-reference/ticketing/groups/groups/#update-group
+      #   #   Zendesk API > Groups > Update Group
+      #   # @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_group = SupportOps::Zendesk::Groups.new
+      #   #   new_group.name = 'My Group'
+      #   #
+      #   #   new_group.save!
+      #   #
+      #   #   pp new_group.id
+      #   #   # => 122
+      #   # @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_group = SupportOps::Zendesk::Groups.get!(122)
+      #   #   existing_group.name = 'My Group 2'
+      #   #
+      #   #   existing_group.save!
+      #   #
+      #   #   pp new_group.name
+      #   #   # => "My Group 2"
+      #   def save!; end
+      # @!parse
+      #   # Deletes a group
+      #   # 
+      #   # @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/groups/groups/#delete-group
+      #   #   Zendesk API > Groups > Delete Group
+      #   # @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_group = SupportOps::Zendesk::Groups.get!(122)
+      #   #   existing_group.delete!
+      #   def delete!; end
+      # @!parse
+      #   # Lists group memberships
+      #   #
+      #   # @author Jason Colyer
+      #   # @since 1.0.0
+      #   # @return [Object]
+      #   # @note This is inherited from {SupportOps::Zendesk::Base#memberships}
+      #   # @see
+      #   #   https://developer.zendesk.com/api-reference/ticketing/groups/group_memberships/#list-memberships
+      #   #   Zendesk API > Group Memberships > List Memberships
+      #   # @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_group = SupportOps::Zendesk::Groups.get!(122)
+      #   #   memberships = existing_group.memberships
+      #   #
+      #   #   pp memberships.count
+      #   #   # => 38
+      #   def memberships; end
+      # @!parse
+      #   # Lists group users
+      #   #
+      #   # @author Jason Colyer
+      #   # @since 1.0.0
+      #   # @return [Object]
+      #   # @note This is inherited from {SupportOps::Zendesk::Base#users}
+      #   # @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_group = SupportOps::Zendesk::Groups.get!(122)
+      #   #   users = existing_group.users
+      #   #
+      #   #   pp users.count
+      #   #   # => 38
+      #   def users; end
+      define_attributes :created_at, :default, :deleted, :description, :id,
+                        :is_public, :name, :updated_at
+      readonly_attributes :created_at, :id, :updated_at
+
+      ##
+      # Lists all groups in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @return [Array]
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/groups/groups/#list-groups
+      #   Zendesk API > Groups > List Groups
+      # @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
+      #
+      #   groups = SupportOps::Zendesk::Groups.list
+      #   pp groups.count
+      #   # => 25
+      #   pp groups.last.name
+      #   # => "I'm the 25th group"
+      def self.list
+        response = client.connection.get('groups?page[size]=100')
+        Oj.load(response.body)['groups'].map { |g| Groups.new(g) }
+      end
+
+      ##
+      # Lists all assignable groups in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @return [Array]
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/groups/groups/#list-assignable-groups
+      #   Zendesk API > Assignable Groups > List Groups
+      # @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
+      #
+      #   groups = SupportOps::Zendesk::Groups.list_assignable
+      #   pp groups.count
+      #   # => 20
+      #   pp groups.last.name
+      #   # => "I'm the 20th group and I'm not deleted"
+      def self.list_assignable
+        response = client.connection.get('groups/assignable?page[size]=100')
+        Oj.load(response.body)['groups'].map { |g| Groups.new(g) }
+      end
+
+      ##
+      # Locates a group 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::Groups to use as a cache
+      # @return [Object] An instance of {SupportOps::Zendesk::Groups}
+      # @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
+      #
+      #   groups = SupportOps::Zendesk::Groups.list
+      #   group = SupportOps::Zendesk::Groups.find_by_name(name: 'Test Group', cache: groups)
+      #   pp group.name
+      #   # => "Test Group"
+      #   pp group.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
+          groups = args[:cache]
+        else
+          groups = list
+        end
+        groups.detect { |c| c.name.downcase == args[:name].to_s.downcase }
+      end
+
+      ##
+      # Returns an approximate count of groups 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/groups/groups/#count-groups
+      #   Zendesk API > Groups > Count Groups
+      # @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
+      #
+      #   orgs = SupportOps::Zendesk::Groups.count
+      #   pp orgs['value']
+      #   # => 25
+      def self.count
+        response = client.connection.get('groups/count')
+        Oj.load(response.body)['count']
+      end
+
+      ##
+      # Locates a specific group in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/groups/groups/#show-group
+      #   Zendesk API > Groups > Show Group
+      # @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
+      #
+      #   groups = SupportOps::Zendesk::Groups.get(123456)
+      #   pp groups.name
+      #   # => "Test Group"
+      def self.get(object)
+        if object.is_a? Groups
+          Groups.new(id: id).find
+        else
+          Groups.new(id: object).find
+        end
+      end
+
+      ##
+      # Locates a specific group in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/groups/groups/#show-group
+      #   Zendesk API > Groups > Show Group
+      # @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
+      #
+      #   groups = SupportOps::Zendesk::Groups.get!(123456)
+      #   pp groups.name
+      #   # => "Test Group"
+      def self.get!(object)
+        if object.is_a? Groups
+          Groups.new(id: id).find!
+        else
+          Groups.new(id: object).find!
+        end
+      end
+
+      private
+      
+      ##
+      # @private
+      def get_record
+        response = self.client.connection.get("groups/#{self.id}")
+        return nil if response.status != 200
+
+        Oj.load(response.body)['group']
+      end
+
+      ##
+      # @private
+      def create_record
+        response = self.client.connection.post("groups", { group: attributes_for_save }.to_json)
+        body = Oj.load(response.body)
+        raise "Failed to create group => #{body['details']}" if response.status != 201
+        body['group']
+      end
+
+      ##
+      # @private
+      def update_record
+        raise "Failed to update group => You didn't change anything in the object" if attributes_for_save.keys == [:id]
+        response = self.client.connection.put("groups/#{self.id}", { group: attributes_for_save }.to_json)
+        body = Oj.load(response.body)
+        raise "Failed to update group #{self.id} => #{body['details']}" if response.status != 200
+        body['group']
+      end
+
+      ##
+      # @private
+      def delete_record
+        response = self.client.connection.delete("groups/#{self.id}")
+        raise "Failed to delete group => #{body['details']}" if response.status != 204
+        true
+      end
+
+      ##
+      # @private
+      def memberships_record
+        memberships_list = []
+        opts = 'page[size]=100'
+        loop do
+          response = client.connection.get("groups/#{self.id}/memberships?#{opts}")
+          body = Oj.load(response.body)
+          memberships_list += body['group_memberships'].map { |o| GroupMemberships.new(o) }
+          break unless body['meta']['has_more']
+
+          opts = body['links']['next'].split('?').last
+        end
+        memberships_list
+      end
+
+      ##
+      # @private
+      def users_record
+        user_list = []
+        group_memberships = self.memberships
+        user_list
+        memberships.each do |m|
+          user_list.push(Users.get!(m.user_id))
+        end
+        user_list
+      end
+    end
+  end
+end