gitlab_support_readiness 1.0.0

data/lib/support_readiness/zendesk/organizations.rb

@@ -0,0 +1,515 @@
+# frozen_string_literal: true
+
+# Defines the module Readiness.
+module Readiness
+  # Defines the module Zendesk
+  module Zendesk
+    ##
+    # Defines the class Organizations within the module {Readiness::Zendesk}.
+    #
+    # @author Jason Colyer
+    # @since 1.0.0
+    # @todo Merge org
+    # @todo Show merge
+    # @todo List merges
+    class Organizations < Readiness::Client
+      attr_accessor :details, :domain_names, :external_id, :group_id, :id, :name, :notes, :organization_fields, :shared_comments, :shared_tickets, :tags
+
+      ##
+      # Creates a new {Readiness::Zendesk::Organizations} instance
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @param object [Object] An instance of {Readiness::Zendesk::Organizations}
+      # @example
+      #   require 'support_readiness'
+      #   Readiness::Zendesk::Organizations.new
+      def initialize(object = {})
+        @details = object['details']
+        @domain_names = object['domain_names']
+        @external_id = object['external_id']
+        @group_id = object['group_id']
+        @id = object['id']
+        @name = object['name']
+        @notes = object['notes']
+        @organization_fields = object['organization_fields']
+        @shared_comments = object['shared_comments']
+        @shared_tickets = object['shared_tickets']
+        @tags = object['tags']
+      end
+
+      ##
+      # Lists the first 100 organizations
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @param client [Object] An instance of {Readiness::Zendesk::Client}
+      # @return [Array]
+      # @see https://developer.zendesk.com/api-reference/ticketing/organizations/organizations/#list-organizations Zendesk API > Organizations > List Organizations
+      # @example
+      #   require 'support_readiness'
+      #   config = Readiness::Zendesk::Configuration.new
+      #   config.username = 'alice@example.com'
+      #   config.token = 'test123abc'
+      #   config.url = 'https://example.zendesk.com/api/v2'
+      #   client = Readiness::Zendesk::Client.new(config)
+      #   orgs = Readiness::Zendesk::Organizations.list(client)
+      #   pp orgs.first.id
+      #   # => 4112492
+      def self.list(client)
+        response = client.connection.get("organizations?page[size]=100")
+        handle_request_error(0, 'Zendesk', response.status) unless response.status == 200
+        Oj.load(response.body)['organizations'].map { |o| Organizations.new(o) }
+      end
+
+      ##
+      # Lists many organizations. Does not stop until it ends or the page limit is hit.
+      # This method can take a long time to run depending on the parameters used.
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @param client [Object] An instance of {Readiness::Zendesk::Client}
+      # @param limit [Integer] The number of pages to stop at. Using 0 means to list all.
+      # @return [Array]
+      # @see https://developer.zendesk.com/api-reference/ticketing/organizations/organizations/#list-organizations Zendesk API > Organizations > List Organizations
+      # @example
+      #   require 'support_readiness'
+      #   config = Readiness::Zendesk::Configuration.new
+      #   config.username = 'alice@example.com'
+      #   config.token = 'test123abc'
+      #   config.url = 'https://example.zendesk.com/api/v2'
+      #   client = Readiness::Zendesk::Client.new(config)
+      #   orgs = Readiness::Zendesk::Organizations.list_many(client, 4)
+      #   pp orgs.count
+      #   # => 400
+      def self.list_many(client, limit = 0, sort = 'id')
+        array = []
+        opts = "page[size]=100"
+        loop do
+          response = client.connection.get("organizations?#{opts}")
+          handle_request_error(0, 'Zendesk', response.status) unless response.status == 200
+          body = Oj.load(response.body)
+          array += body['organizations'].map { |o| Organizations.new(o) }
+          break if limit != 0 && array.count >= (limit * 100)
+          break unless body['meta']['has_more']
+
+          opts = body['links'] ['next'].split('?').last
+        end
+        array
+      end
+
+      ##
+      # Show information on the approximate count of organizations.
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @param client [Object] An instance of {Readiness::Zendesk::Client}
+      # @return [Hash]
+      # @see https://developer.zendesk.com/api-reference/ticketing/organizations/organizations/#count-organizations Zendesk API > Organizations > Count Organizations
+      # @example
+      #   require 'support_readiness'
+      #   config = Readiness::Zendesk::Configuration.new
+      #   config.username = 'alice@example.com'
+      #   config.token = 'test123abc'
+      #   config.url = 'https://example.zendesk.com/api/v2'
+      #   client = Readiness::Zendesk::Client.new(config)
+      #   count = Readiness::Zendesk::Organizations.count(client)
+      #   pp count.value
+      #   # => 54590
+      def self.count(client)
+        response = client.connection.get('organizations/count')
+        handle_request_error(0, 'Zendesk', response.status) unless response.status == 200
+        Oj.load(response.body)['count']
+      end
+
+      ##
+      # Locates an organization within Zendesk. This will not exit on error (except Authentication errors)
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @param client [Object] An instance of {Readiness::Zendesk::Client}
+      # @param oid [Integer] The organization ID to find
+      # @return [Hash]
+      # @see https://developer.zendesk.com/api-reference/ticketing/organizations/organizations/#show-organization Zendesk API > ORganizations > Show Organization
+      # @example
+      #   require 'support_readiness'
+      #   config = Readiness::Zendesk::Configuration.new
+      #   config.username = 'alice@example.com'
+      #   config.token = 'test123abc'
+      #   config.url = 'https://example.zendesk.com/api/v2'
+      #   client = Readiness::Zendesk::Client.new(config)
+      #   org = Readiness::Zendesk::Organizations.find(client, 4112492)
+      #   pp org.name
+      #   # => "Groablet Enterprises"
+      def self.find(client, oid)
+        response = client.connection.get("organizations/#{oid}")
+        handle_request_error(0, 'Zendesk', response.status,  { action: 'get', id: oid }) unless response.status == 200
+        return Organizations.new(Oj.load(response.body)['organization']) if response.status == 200
+
+        Oj.load(response.body)
+      end
+
+      ##
+      # Locates an organization within Zendesk. This will exit on error
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @param client [Object] An instance of {Readiness::Zendesk::Client}
+      # @param oid [Integer] The organization ID to find
+      # @return [Object] An instance of {Readiness::Zendesk::Organizations}
+      # @see https://developer.zendesk.com/api-reference/ticketing/organizations/organizations/#show-organization Zendesk API > Organizations > Show Organization
+      # @example
+      #   require 'support_readiness'
+      #   config = Readiness::Zendesk::Configuration.new
+      #   config.username = 'alice@example.com'
+      #   config.token = 'test123abc'
+      #   config.url = 'https://example.zendesk.com/api/v2'
+      #   client = Readiness::Zendesk::Client.new(config)
+      #   org = Readiness::Zendesk::Organizations.find!(client, 4112492)
+      #   pp org.name
+      #   # => "Groablet Enterprises"
+      def self.find!(client, oid)
+        response = client.connection.get("organizations/#{oid}")
+        handle_request_error(1, 'Zendesk', response.status, { action: 'Find organization', id: oid }) unless response.status == 200
+        Organizations.new(Oj.load(response.body)['organization'])
+      end
+
+      ##
+      # Locates up to 100 organizations within Zendesk.
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @param client [Object] An instance of {Readiness::Zendesk::Client}
+      # @param oids [Array] The organization IDs to find
+      # @return [Array]
+      # @see https://developer.zendesk.com/api-reference/ticketing/organizations/organizations/#show-many-organizations Zendesk API > Organizations > Show Many Organizations
+      # @example
+      #   require 'support_readiness'
+      #   config = Readiness::Zendesk::Configuration.new
+      #   config.username = 'alice@example.com'
+      #   config.token = 'test123abc'
+      #   config.url = 'https://example.zendesk.com/api/v2'
+      #   client = Readiness::Zendesk::Client.new(config)
+      #   orgs = Readiness::Zendesk::Organizations.find_many(client, [35436, 20057623])
+      #   pp orgs.map { |o| o.name }
+      #   # => ["Important Customers", "Imperial College"]
+      def self.find_many(client, oids)
+        response = client.connection.get("organizations/show_many?ids=#{oids.join(',')}")
+        handle_request_error(0, 'Zendesk', response.status,  { action: 'get', id: oids }) unless response.status == 200
+        Oj.load(response.body)['organizations'].map { |o| Organizations.new(o) }
+      end
+
+      ##
+      # Creates an organization. Will exit if unsuccessful
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @param client [Object] An instance of {Readiness::Zendesk::Client}
+      # @param organization [Object] An instance of {Readiness::Zendesk::Organizations}
+      # @return [Object] An instance of {Readiness::Zendesk::Organizations}
+      # @see https://developer.zendesk.com/api-reference/ticketing/organizations/organizations/#create-organization Zendesk API > Organizations > Create Organization
+      # @example
+      #   require 'support_readiness'
+      #   config = Readiness::Zendesk::Configuration.new
+      #   config.username = 'alice@example.com'
+      #   config.token = 'test123abc'
+      #   config.url = 'https://example.zendesk.com/api/v2'
+      #   client = Readiness::Zendesk::Client.new(config)
+      #   org = Readiness::Zendesk::Organizations.new
+      #   org.name = 'My Organization'
+      #   create = Readiness::Zendesk::Organizations.create!(client, org)
+      #   pp create.id
+      #   # => 23409462
+      def self.create!(client, organization)
+        response = client.connection.post 'organizations', to_clean_json_with_key(organization, 'organization')
+        handle_request_error(1, 'Zendesk', response.status, { action: 'Create organization', message: Oj.load(response.body)}) unless response.status == 201
+        Organizations.new(Oj.load(response.body)['organization'])
+      end
+
+      ##
+      # Creates or updates an organization. Will exit if unsuccessful
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @param client [Object] An instance of {Readiness::Zendesk::Client}
+      # @param organization [Object] An instance of {Readiness::Zendesk::Organizations}
+      # @return [Object] An instance of {Readiness::Zendesk::Organizations}
+      # @see https://developer.zendesk.com/api-reference/ticketing/organizations/organizations/#create-or-update-organization Zendesk API > Organizations > Create Or Update Organization
+      # @example
+      #   require 'support_readiness'
+      #   config = Readiness::Zendesk::Configuration.new
+      #   config.username = 'alice@example.com'
+      #   config.token = 'test123abc'
+      #   config.url = 'https://example.zendesk.com/api/v2'
+      #   client = Readiness::Zendesk::Client.new(config)
+      #   org = Readiness::Zendesk::Organizations.find!(client, 123)
+      #   org.name = 'My Organization'
+      #   create = Readiness::Zendesk::Organizations.create_or_update!(client, org)
+      #   pp create.name
+      #   # => 'My Organization'
+      # @example
+      #   require 'support_readiness'
+      #   config = Readiness::Zendesk::Configuration.new
+      #   config.username = 'alice@example.com'
+      #   config.token = 'test123abc'
+      #   config.url = 'https://example.zendesk.com/api/v2'
+      #   client = Readiness::Zendesk::Client.new(config)
+      #   org = Readiness::Zendesk::Organizations.new
+      #   org.name = 'My Organization'
+      #   create = Readiness::Zendesk::Organizations.create_or_update!(client, org)
+      #   pp create.id
+      #   # => 23409462
+      def self.create_or_update!(client, organization)
+        response = client.connection.post 'organizations/create_or_update', to_clean_json_with_key(organization, 'organization')
+        handle_request_error(1, 'Zendesk', response.status, { action: 'Create or update organization', id: organization.name, message: Oj.load(response.body)}) unless [200, 201].include?(response.status)
+        Organizations.new(Oj.load(response.body)['organization'])
+      end
+
+      ##
+      # Updates an organization. Will exit if unsuccessful
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @param client [Object] An instance of {Readiness::Zendesk::Client}
+      # @param organization [Object] An instance of {Readiness::Zendesk::Organizations}
+      # @return [Object] An instance of {Readiness::Zendesk::Organizations}
+      # @see https://developer.zendesk.com/api-reference/ticketing/organizations/organizations/#update-organization Zendesk API > Organizations > Update Organization
+      # @example
+      #   require 'support_readiness'
+      #   config = Readiness::Zendesk::Configuration.new
+      #   config.username = 'alice@example.com'
+      #   config.token = 'test123abc'
+      #   config.url = 'https://example.zendesk.com/api/v2'
+      #   client = Readiness::Zendesk::Client.new(config)
+      #   org = Readiness::Zendesk::Organizations.find!(client, 4112492)
+      #   org.notes = 'Something interesting'
+      #   update = Readiness::Zendesk::Organizations.update!(client, org)
+      #   pp update.notes
+      #   # => "Something interesting"
+      def self.update!(client, organization)
+        response = client.connection.put "organizations/#{organization.id}", to_clean_json_with_key(organization, 'organization')
+        handle_request_error(1, 'Zendesk', response.status, { action: 'Update organization', id: organization.id, message: Oj.load(response.body)}) unless response.status == 200
+        Organizations.new(Oj.load(response.body)['organization'])
+      end
+
+      ##
+      # Deletes an organization. Will exit if unsuccessful
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @param client [Object] An instance of {Readiness::Zendesk::Client}
+      # @param organization [Object] An instance of {Readiness::Zendesk::Organizations}
+      # @return [Boolean]
+      # @see https://developer.zendesk.com/api-reference/ticketing/organizations/organizations/#delete-organization Zendesk API > Organizations > Delete Organization
+      # @example
+      #   require 'support_readiness'
+      #   config = Readiness::Zendesk::Configuration.new
+      #   config.username = 'alice@example.com'
+      #   config.token = 'test123abc'
+      #   config.url = 'https://example.zendesk.com/api/v2'
+      #   client = Readiness::Zendesk::Client.new(config)
+      #   org = Readiness::Zendesk::Organizations.find!(client, 16)
+      #   delete = Readiness::Zendesk::Organizations.delete!(client, org)
+      #   pp delete
+      #   # => true
+      def self.delete!(client, organization)
+        response = client.connection.delete "organizations/#{organization.id}"
+        handle_request_error(1, 'Zendesk', response.status, { action: 'Delete an organization', id: organization.id, message: Oj.load(response.body)}) unless response.status == 204
+        true
+      end
+
+      ##
+      # Lists tickets for an organization.
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @param client [Object] An instance of {Readiness::Zendesk::Client}
+      # @param organization [Object] An instance of {Readiness::Zendesk::Organizations}
+      # @return [Array]
+      # @see https://developer.zendesk.com/api-reference/ticketing/tickets/tickets/#list-tickets Zendesk API > Tickets > List Tickets
+      # @example
+      #   require 'support_readiness'
+      #   config = Readiness::Zendesk::Configuration.new
+      #   config.username = 'alice@example.com'
+      #   config.token = 'test123abc'
+      #   config.url = 'https://example.zendesk.com/api/v2'
+      #   client = Readiness::Zendesk::Client.new(config)
+      #   org = Readiness::Zendesk::Organizations.find!(client, 16)
+      #   tickets = Readiness::Zendesk::Organizations.tickets(client, org)
+      #   pp tickets.first.status
+      #   # => "pending"
+      def self.tickets(client, organization)
+        array = []
+        opts = "page[size]=100"
+        loop do
+          response = client.connection.get("organizations/#{organization.id}/tickets?#{opts}")
+          handle_request_error(0, 'Zendesk', response.status) unless response.status == 200
+          body = Oj.load(response.body)
+          array += body['tickets'].map { |t| Tickets.new(t) }
+          break unless body['meta']['has_more']
+
+          opts = body['links'] ['next'].split('?').last
+        end
+        array
+      end
+
+      ##
+      # Lists users for an organization.
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @param client [Object] An instance of {Readiness::Zendesk::Client}
+      # @param organization [Object] An instance of {Readiness::Zendesk::Organizations}
+      # @return [Array]
+      # @see https://developer.zendesk.com/api-reference/ticketing/users/users/#list-users Zendesk API > USers > List Users
+      # @example
+      #   require 'support_readiness'
+      #   config = Readiness::Zendesk::Configuration.new
+      #   config.username = 'alice@example.com'
+      #   config.token = 'test123abc'
+      #   config.url = 'https://example.zendesk.com/api/v2'
+      #   client = Readiness::Zendesk::Client.new(config)
+      #   org = Readiness::Zendesk::Organizations.find!(client, 16)
+      #   users = Readiness::Zendesk::Organizations.users(client, org)
+      #   pp users.count
+      #   # => 28
+      def self.users(client, organization)
+        array = []
+        opts = "page[size]=100"
+        loop do
+          response = client.connection.get("organizations/#{organization.id}/users?#{opts}")
+          handle_request_error(0, 'Zendesk', response.status) unless response.status == 200
+          body = Oj.load(response.body)
+          array += body['users'].map { |u| Users.new(u) }
+          break unless body['meta']['has_more']
+
+          opts = body['links'] ['next'].split('?').last
+        end
+        array
+      end
+
+      ##
+      # Creates multiple organizations via a batch job
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @param client [Object] An instance of {Readiness::Zendesk::Client}
+      # @param organizations [Array] An array of {Readiness::Zendesk::Organizations} instances
+      # @return [object] A {Readiness::Zendesk::JobStatuses} instance
+      # @see https://developer.zendesk.com/api-reference/ticketing/organizations/organizations/#create-many-organizations Zendesk API > ORganizations > Create Many Organizations
+      # @example
+      #   require 'support_readiness'
+      #   config = Readiness::Zendesk::Configuration.new
+      #   config.username = 'alice@example.com'
+      #   config.token = 'test123abc'
+      #   config.url = 'https://example.zendesk.com/api/v2'
+      #   client = Readiness::Zendesk::Client.new(config)
+      #   org1 = Readiness::Zendesk::Organizations.new
+      #   org1.name = 'Org 1'
+      #   org2 = Readiness::Zendesk::Organizations.new
+      #   org2.name = 'Org 2'
+      #   orgs = [org1, org2]
+      #   creates = Readiness::Zendesk::Organizations.create_many!(client, orgs)
+      #   pp creates.id
+      #   # => "8b726e606741012ffc2d782bcb7848fe"
+      def self.create_many!(client, organizations)
+        data = { organizations: organizations.map { |o| to_hash(o).compact } }.to_json
+        response = client.connection.post('organizations/create_many', data)
+        handle_request_error(1, 'Zendesk', response.status, { action: 'Create many organizations', message: Oj.load(response.body)}) unless response.status == 200
+        JobStatuses.new(Oj.load(response.body)['job_status'])
+      end
+
+      ##
+      # Updates multiple organizations via a batch job
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @param client [Object] An instance of {Readiness::Zendesk::Client}
+      # @param organizations [Array] An array of {Readiness::Zendesk::Organizations} instances
+      # @return [object] A {Readiness::Zendesk::JobStatuses} instance
+      # @see https://developer.zendesk.com/api-reference/ticketing/organizations/organizations/#update-many-organizations Zendesk API > ORganizations > Update Many Organizations
+      # @example
+      #   require 'support_readiness'
+      #   config = Readiness::Zendesk::Configuration.new
+      #   config.username = 'alice@example.com'
+      #   config.token = 'test123abc'
+      #   config.url = 'https://example.zendesk.com/api/v2'
+      #   client = Readiness::Zendesk::Client.new(config)
+      #   org1 = Readiness::Zendesk::Organizations.find!(client, 123)
+      #   org1.notes = 'Escalated customer, please use due diligence'
+      #   org2 = Readiness::Zendesk::Organizations.find!(client, 456)
+      #   org2.notes = 'Escalated customer, please use due diligence'
+      #   orgs = [org1, org2]
+      #   updates = Readiness::Zendesk::Organizations.update_many!(client, orgs)
+      #   pp updates.id
+      #   # => "8b726e606741012ffc2d782bcb7848fe"
+      def self.update_many!(client, organizations)
+        data = { organizations: organizations.map { |o| to_hash(o).compact } }.to_json
+        response = client.connection.put('organizations/update_many', data)
+        handle_request_error(1, 'Zendesk', response.status, { action: 'Update many organizations', message: Oj.load(response.body)}) unless response.status == 200
+        JobStatuses.new(Oj.load(response.body)['job_status'])
+      end
+
+      ##
+      # Deletes multiple organizations via a batch job
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @param client [Object] An instance of {Readiness::Zendesk::Client}
+      # @param oids [Array] An array of organization IDs to delete
+      # @return [object] A {Readiness::Zendesk::JobStatuses} instance
+      # @see https://developer.zendesk.com/api-reference/ticketing/organizations/organizations/#bulk-delete-organizations Zendesk API > ORganizations > Bulk Delete Organizations
+      # @example
+      #   require 'support_readiness'
+      #   config = Readiness::Zendesk::Configuration.new
+      #   config.username = 'alice@example.com'
+      #   config.token = 'test123abc'
+      #   config.url = 'https://example.zendesk.com/api/v2'
+      #   client = Readiness::Zendesk::Client.new(config)
+      #   deletes = Readiness::Zendesk::Organizations.delete_many!(client, [123, 456])
+      #   pp deletes.id
+      #   # => "8b726e606741012ffc2d782bcb7848fe"
+      def self.delete_many!(client, oids)
+        response = client.connection.delete "organizations/destroy_many?ids=#{oids.join(',')}"
+        handle_request_error(1, 'Zendesk', response.status, { action: 'Delete many organizations', message: Oj.load(response.body)}) unless response.status == 200
+        JobStatuses.new(Oj.load(response.body)['job_status'])
+      end
+
+      ##
+      # Lists members of an organization
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @param client [Object] An instance of {Readiness::Zendesk::Client}
+      # @param organization [Object] An instance of {Readiness::Zendesk::Organizations}
+      # @return [Array]
+      # @see https://developer.zendesk.com/api-reference/ticketing/organizations/organization_memberships/#list-memberships Zendesk API > Organization Memberships > List Memberships
+      # @example
+      #   require 'support_readiness'
+      #   config = Readiness::Zendesk::Configuration.new
+      #   config.username = 'alice@example.com'
+      #   config.token = 'test123abc'
+      #   config.url = 'https://example.zendesk.com/api/v2'
+      #   client = Readiness::Zendesk::Client.new(config)
+      #   org = Readiness::Zendesk::Organizations.find!(client, 123)
+      #   members = Readiness::Zendesk::Organizations.memberships(client, org)
+      #   pp members.first.user_id
+      #   # => 29
+      def self.memberships(client, organization)
+        array = []
+        opts = "page[size]=100"
+        loop do
+          response = client.connection.get("organizations/#{organization.id}/organization_memberships?#{opts}")
+          handle_request_error(0, 'Zendesk', response.status) unless response.status == 200
+          body = Oj.load(response.body)
+          array += body['organization_memberships'].map { |o| OrganizationMemberships.new(o) }
+          break if limit != 0 && array.count >= (limit * 100)
+          break unless body['meta']['has_more']
+
+          opts = body['links'] ['next'].split('?').last
+        end
+        array
+      end
+    end
+  end
+end