sf_cli 0.0.4 → 0.0.6

data/lib/sf_cli/sf/data/get_record.rb

@@ -0,0 +1,42 @@
+module SfCli::Sf::Data
+  module GetRecord
+
+    # get a object record. (eqivalent to *sf* *data* *get* *record*)
+    #
+    # *object_type* --- \Object Type (ex. Account)<br>
+    #
+    # *record_id* --- id of the object<br>
+    #
+    # *where* --- hash object that is used to identify a record<br>
+    #
+    # *target_org* --- an alias of paticular org, not default one<br>
+    #
+    # *model_class* --- the object model class<br>
+    #
+    # ======
+    #   sf.data.get_record :Account, record_id: 'xxxxxxx'
+    #   sf.data.get_record :Account, where: {Name: 'Jonny B.Good', Country: 'USA'}
+    #
+    #   CustomObject = Struct.new(:Id, :Name)
+    #   sf.data.get_record :TheCustomObject__c, record_id: 'xxxxx', model_class: CustomObject  # returns a CustomObject instance
+    #
+    # For more command details, see {the command reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm#cli_reference_data_get_record_unified]
+    #
+    def get_record(object_type, record_id: nil, where: nil, target_org: nil, model_class: nil)
+      where_conditions = field_value_pairs(where)
+      flags = {
+        :"sobject"    => object_type,
+        :"record-id"  => record_id,
+        :"where"      => (where_conditions.nil? ? nil : %|"#{where_conditions}"|),
+        :"target-org" => target_org,
+      }
+      action = __method__.to_s.tr('_', ' ')
+      json = exec(action, flags: flags, redirection: :null_stderr)
+
+      result = json['result']
+      result.delete 'attributes'
+
+      model_class ? model_class.new(**result) : result
+    end
+  end
+end

data/lib/sf_cli/sf/data/helper_methods.rb

@@ -16,6 +16,18 @@ module SfCli
           hash
         end
 
+        def prepare_record_in_bulk_mode(hash) # :doc:
+          hash.keys.each do |k|
+            match_result = /(.*)\.(.*)/.match(k)
+            if match_result
+              hash[match_result[1]] = {match_result[2] => hash[k]}
+              hash.delete k
+            end
+          end
+
+          hash
+        end
+
         def children?(h)
           return false unless h.instance_of?(Hash)
 

data/lib/sf_cli/sf/data/query.rb

@@ -0,0 +1,120 @@
+require_relative './helper_methods'
+require_relative './query_helper'
+
+module SfCli::Sf::Data
+  module Query
+    # get object records using SOQL.
+    #
+    # *soql* --- SOQL<br>
+    #
+    # *target_org* --- an alias of paticular org, or username can be used<br>
+    #
+    # *format* --- get the command's raw output. human, csv, json can be available<br>
+    #
+    # *model_class* --- the object model class<br>
+    #
+    # *bulk* --- use Bulk API<br>
+    #
+    # *timeout* --- max minutes to wait for the job complete in Bulk API mode<br>
+    #
+    # ======
+    #   sf.data.query 'SELECT Id, Name FROM Account LIMIT 1' # => [{Id: "abc", Name: "account name"}]
+    #
+    #   Account = Struct.new(:Id, :Name)
+    #   sf.data.query('SELECT Id, Name From Account Limit 3', model_class: Account)  # returns an array of Account struct object
+    #
+    #   # child-parent relationship is supported
+    #   sf.data.query 'SELECT Id, Name, Account.Name From Contact Limit 1'  #  [{Id: "abc", Name: "contact name", Account: {Name: "account name"}}]
+    #
+    #   # parent-children relationship is supported
+    #   sf.data.query 'SELECT Id, Name, (SELECT Name From Contacts) FROM Account Limit 1'  #  [{Id: "abc", Name: "account name", Contacts: [{Name: "contact name"}]}]
+    #
+    # When using Bulk API, you get the records when the query job completes within time limit.
+    # The method returns a tapple(an array), which changes its contents according to the job result.
+    #
+    # ======
+    #   done, result = sf.data.query 'SELECT Id, Name FROM Account', bulk: true              # max wait 1 min to get result (default)
+    #   done, result = sf.data.query 'SELECT Id, Name FROM Account', bulk: true, timeout: 5  # max wait 5 min to get result
+    #   done, result = sf.data.query 'SELECT Id, Name FROM Account', bulk: true, timeout: 0  # returns immediately
+    #
+    #   rows = result   if done     # if job is completed, the result is an array of record
+    #   job_id = result unless done # if job hasn't completed or it has aborted, the result is the job ID
+    #
+    # For more command details, see {the command reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm#cli_reference_data_query_unified]
+    #
+    # About querying with auto generated object model, see the section {"Object Model support"}[link://files/README_rdoc.html#label-Object+Model+support+-28experimental-2C+since+0.0.4-29] in README.
+    #
+    def query(soql, target_org: nil, format: nil, bulk: false, timeout: nil, model_class: nil)
+      flags    = {
+        :"query"    => %("#{soql}"),
+        :"target-org" => target_org,
+        :"result-format" => format,
+        :"wait" => (bulk ? timeout : nil),
+      }
+      switches = {
+        bulk: bulk,
+      }
+      raw_output = format ? true : false
+      format = format&.to_sym || :json
+
+      result = exec(__method__, flags: flags, switches: switches, redirection: :null_stderr, raw_output: raw_output, format: format)
+
+      return_result(result, raw_output, bulk, model_class)
+    end
+
+    # resume a bulk query job, which you previously started, and get records
+    #
+    # *job_id* ---  job ID you want to resume<br>
+    #
+    # *target_org* --- an alias of paticular org, or username can be used<br>
+    #
+    # *format* --- get the command's raw output. human, csv, json can be available<br>
+    #
+    # *model_class* --- the object model class<br>
+    #
+    # ======
+    #   # start a query job
+    #   result1 = sf.data.query 'SELECT Id, Name FROM Account', bulk: true, timeout: 0  # returns immediately
+    #
+    #   result1 # => [false, "<job id>"]
+    #
+    #   # the job has already started asynchronously.
+    #   # So you should check and get the result.
+    #   done, result2 = sf.data.query_resume job_id: result1.last
+    #
+    #   puts 'get the records!' if done # the job has completed
+    #
+    #   result2 # => if done is true, this is an array of record. Otherwise it should be the Job ID.
+    #
+    # For more command details, see {the command reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm#cli_reference_data_query_resume_unified]
+    def query_resume(job_id:, target_org: nil, format: nil, model_class: nil)
+      flags    = {
+        :"bulk-query-id" => job_id,
+        :"target-org" => target_org,
+        :"result-format" => format,
+      }
+      raw_output = format ? true : false
+      format = format || :json
+
+      action = __method__.to_s.tr('_', ' ')
+      result = exec(action, flags: flags, redirection: :null_stderr, raw_output: raw_output, format: format)
+
+      return_result(result, raw_output, true, model_class)
+    end
+
+    def return_result(result, raw_output, bulk, model_class)
+      result_adjuster = 
+        if raw_output
+          RawOutputResultAdjuster.new(result)
+        elsif bulk
+          BulkResultAdjuster.new(result, model_class)
+        else
+          RegularResultAdjuster.new(result, model_class)
+        end
+
+      result_adjuster.get_return_value
+    end
+
+    private :return_result
+  end
+end

data/lib/sf_cli/sf/data/query_helper.rb

@@ -0,0 +1,57 @@
+require_relative './helper_methods'
+
+module SfCli::Sf::Data
+  module Query
+    class RegularResultAdjuster # :nodoc: all
+      include ::SfCli::Sf::Data::HelperMethods
+
+      attr_reader :result, :model_class
+
+      def initialize(result, model_class)
+        @result = result
+        @model_class = model_class
+      end
+
+      def get_return_value
+        result['result']['records'].each_with_object([]) do |h, a|
+          record = prepare_record(h)
+          a << (model_class ? model_class.new(**record) : record)
+        end
+      end
+    end
+
+    class BulkResultAdjuster # :nodoc: all
+      include ::SfCli::Sf::Data::HelperMethods
+
+      attr_reader :result, :model_class
+
+      def initialize(result, model_class)
+        @result = result
+        @model_class = model_class
+      end
+
+      def get_return_value
+        done = result['result']['done']
+        id   = result['result']['id']
+        rows = result['result']['records'].each_with_object([]) do |h, a|
+            record = prepare_record_in_bulk_mode(h)
+            a << (model_class ? model_class.new(**record) : record)
+          end
+
+        done ? [done, rows] : [done, id]
+      end
+    end
+
+    class RawOutputResultAdjuster # :nodoc: all
+      attr_reader :result
+
+      def initialize(result)
+        @result = result
+      end
+
+      def get_return_value
+        result
+      end
+    end
+  end
+end

data/lib/sf_cli/sf/data/resume.rb

@@ -0,0 +1,87 @@
+module SfCli::Sf::Data
+  module Resume
+    JobInfo = Struct.new(
+      :id,
+      :operation,
+      :object,
+      :createdById,
+      :createdDate,
+      :systemModstamp,
+      :state,
+      :concurrencyMode,
+      :contentType,
+      :numberBatchesQueued,
+      :numberBatchesInProgress,
+      :numberBatchesCompleted,
+      :numberBatchesFailed,
+      :numberBatchesTotal,
+      :numberRecordsProcessed,
+      :numberRetries,
+      :apiVersion,
+      :numberRecordsFailed,
+      :totalProcessingTime,
+      :apiActiveProcessingTime,
+      :apexProcessingTime
+    ) do
+      def opened?
+        state == 'Open'
+      end
+
+      def upload_completed?
+        state == 'UploadComplete'
+      end
+
+      def in_progress?
+        state == 'InProgress'
+      end
+
+      def completed?
+        state == 'JobComplete'
+      end
+
+      def failed?
+        state == 'Failed'
+      end
+
+      def aborted?
+        state == 'Aborted'
+      end
+    end
+
+    # View the status of a bulk job.
+    #
+    # *job_id* ---  job ID you want to resume<br>
+    #
+    # *target_org* --- an alias of paticular org, or username can be used<br>
+    #
+    # ======
+    #   # start a delete job
+    #   jobinfo = sf.data.delete_bulk sobject: :TestCustomObject__c, file: 'delete.csv' # this returns immediately
+    #   jobinfo.id  # => "750J4000003g1OaIAI" it's job ID
+    #
+    #   jobinfo2 = sf.data.resume job_id: jobinfo.id
+    #
+    #   puts 'yey!' if job_info2.completed? # the job has completed
+    #
+    # The job info object has methods to check the job status:
+    # - opened?
+    # - upload_completed?
+    # - in_progress?
+    # - completed?
+    #
+    # To know job status more, take a look at {the bulk API developer guide}[https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/bulk_api_2_job_states.htm]
+    #
+    # For more command details, see {the command reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm#cli_reference_data_resume_unified]
+    #
+    def resume(job_id:, target_org: nil)
+      flags = {
+        :"job-id"     => job_id,
+        :"target-org" => target_org,
+      }
+      json = exec(__method__, flags: flags, redirection: :null_stderr)
+
+      json['result'].delete '$'
+      JobInfo.new(**json['result'])
+    end
+  end
+end

data/lib/sf_cli/sf/data/search.rb

@@ -0,0 +1,50 @@
+module SfCli::Sf::Data
+  module Search
+    # search objects using SOSL.
+    #
+    # *sosl* --- SOSL<br>
+    #
+    # *target_org* --- an alias of paticular org, or username can be used<br>
+    #
+    # *format* --- get the command's raw output. human, csv, json can be available. *NOTE*: if you choose csv, csv files are downloaded in current directory<br>
+    #
+    # ======
+    #  # example (in irb):
+    #
+    #  > sf.data.search "FIND {TIM OR YOUNG OR OIL} IN Name Fields"
+    #  =>
+    #  {"Lead"=>["00Q5j00000WgEuDEAV"],
+    #   "Account"=>["0015j00001U2XvNAAV", "0015j00001U2XvMAAV", "0015j00001U2XvJAAV"],
+    #   "Contact"=>
+    #    ["0035j00001HB84BAAT",
+    #     "0035j00001HB84DAAT"],
+    #   "Opportunity"=>
+    #    ["0065j00001XHJLjAAP",
+    #     "0065j00001XHJLTAA5",
+    #     "0065j00001XHJLJAA5"],
+    #   "User"=>["0055j00000CcL2bAAF", "0055j00000CcL1YAAV"]}
+    #
+    # For more command details, see {the command reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm#cli_reference_data_search_unified]
+    #
+    def search(sosl, target_org: nil, format: nil)
+      flags = {
+        :"query"         => %|"#{sosl}"|,
+        :"target-org"    => target_org,
+        :"result-format" => format,
+      }
+      raw_output = format ? true : false
+      format = format&.to_sym || :json
+
+      result = exec(__method__, flags: flags, redirection: :null_stderr, raw_output: raw_output, format: format)
+
+      return if format == :csv
+      return result if format == :human
+
+      result['result']['searchRecords']
+        .group_by{|r| r['attributes']['type']}
+        .each_with_object({}) do |(object_type, records), result|
+          result[object_type] = records.map{|r| r['Id']}
+        end
+    end
+  end
+end

data/lib/sf_cli/sf/data/update_record.rb

@@ -0,0 +1,38 @@
+module SfCli::Sf::Data
+  module UpdateRecord
+
+    # update a object record.
+    #
+    # *object_type* --- \Object Type (ex. Account)<br>
+    #
+    # *record_id* --- id of the object<br>
+    #
+    # *where* --- field values that is used to identify a record<br>
+    #
+    # *values* --- field values for update<br>
+    #
+    # *target_org* --- an alias of paticular org, or username can be used<br>
+    #
+    # ==== examples
+    #   sf.data.update_record :Account, record_id: 'xxxxxxx', values: {Name: 'New Account Name'}
+    #   sf.data.update_record :Hoge__c, where: {Name: 'Jonny B.Good', Country: 'USA'}, values: {Phone: 'xxxxx', bar: 2000}
+    #
+    # For more command details, see {the command reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm#cli_reference_data_update_record_unified]
+    #
+    def update_record(object_type, record_id: nil, where: nil, values: nil, target_org: nil)
+      where_conditions  = field_value_pairs(where)
+      field_values      = field_value_pairs(values)
+      flags = {
+        :"sobject"    => object_type,
+        :"record-id"  => record_id,
+        :"where"      => (where_conditions.nil? ? nil : %|"#{where_conditions}"|),
+        :"values"     => (field_values.nil? ? nil : %|"#{field_values}"|),
+        :"target-org" => target_org,
+      }
+      action = __method__.to_s.tr('_', ' ')
+      json = exec(action, flags: flags, redirection: :null_stderr)
+
+      json['result']['id']
+    end
+  end
+end

data/lib/sf_cli/sf/data/upsert_bulk.rb

@@ -0,0 +1,50 @@
+require_relative './bulk_result_v2'
+
+module SfCli::Sf::Data
+  module UpsertBulk
+    # update records using Bulk API 2.0
+    #
+    # *file* --- a \CSV file for update records<br>
+    #
+    # *sobject* --- \Object Type (ex. Account)<br>
+    #
+    # *external_id* --- Name of the external ID field, or the Id field<br>
+    #
+    # *timeout* --- max minutes to wait for the job complete the task.<br>
+    #
+    # *target_org* --- an alias of paticular org, or username can be used<br>
+    #
+    # ======
+    #   # start a upsert job
+    #   jobinfo = sf.data.upsert_bulk sobject: :TestCustomObject__c, file: 'upsert.csv' # this returns immediately
+    #   jobinfo.id  # => "750J4000003g1OaIAI" it's job ID
+    #
+    #   # you can check if the upsert job completed
+    #   sf.data.upsert_resume job_id: jobinfo.id
+    #
+    #   # Or, you can wait for the job completion with one try.
+    #   result = sf.data.upsert_bulk sobject: :TestCustomObject__c, file: 'upsert.csv', timeout: 5  # wait within 5 minutes
+    #
+    # For more command details, see {the command reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm#cli_reference_data_upsert_bulk_unified]
+    #
+    def upsert_bulk(file:, sobject:, external_id:, timeout: nil, target_org: nil)
+      flags = {
+        :"file"    => file,
+        :"sobject"    => sobject,
+        :"external-id"  => external_id,
+        :"wait"      => timeout,
+        :"target-org" => target_org,
+      }
+      action = __method__.to_s.tr('_', ' ')
+      json = exec(action, flags: flags, redirection: :null_stderr)
+
+      job_info =  ::SfCli::Sf::Data::JobInfo.new(**json['result']['jobInfo'])
+      return job_info unless json['result']['records']
+
+      ::SfCli::Sf::Data::BulkResultV2.new(
+        job_info: job_info,
+        records:  ::SfCli::Sf::Data::BulkRecordsV2.new(**json['result']['records'])
+      )
+    end
+  end
+end

data/lib/sf_cli/sf/data/upsert_resume.rb

@@ -0,0 +1,47 @@
+require_relative './bulk_result_v2'
+
+module SfCli::Sf::Data
+  module UpsertResume
+    # resume a bulk upsert job you previously started with Bulk API 2.0 and return a bulk result object.
+    #
+    # *job_id* ---  job ID you want to resume<br>
+    #
+    # *timeout* --- max minutes to wait for the job complete the task.<br>
+    #
+    # *target_org* --- an alias of paticular org, or username can be used<br>
+    #
+    # ======
+    #   # start a upsert job
+    #   jobinfo = sf.data.upsert_bulk sobject: :TestCustomObject__c, file: 'upsert.csv' # this returns immediately
+    #   jobinfo.id  # => "750J4000003g1OaIAI" it's job ID
+    #
+    #   # the job has already started asynchronously.
+    #   # So you should check its progress.
+    #   # if you want to wait for the job complete the task, try 'timeout' option.
+    #   result = sf.data.upsert_resume job_id: jobinfo.id
+    #
+    #   puts 'yey!' if result.job_info.completed? # the job has completed
+    #
+    # To know more about a job result, take a look at SfCli::Sf::Data module
+    #
+    # For more command details, see {the command reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm#cli_reference_data_upsert_resume_unified]
+    #
+    def upsert_resume(job_id:, timeout: nil, target_org: nil)
+      flags = {
+        :"job-id"     => job_id,
+        :"wait"       => timeout,
+        :"target-org" => target_org,
+      }
+      action = __method__.to_s.tr('_', ' ')
+      json = exec(action, flags: flags, redirection: :null_stderr)
+
+      job_info =  ::SfCli::Sf::Data::JobInfo.new(**json['result']['jobInfo'])
+      return job_info unless json['result']['records']
+
+      ::SfCli::Sf::Data::BulkResultV2.new(
+        job_info: job_info,
+        records:  ::SfCli::Sf::Data::BulkRecordsV2.new(**json['result']['records'])
+      )
+    end
+  end
+end

data/lib/sf_cli/sf/model/base_methods.rb

@@ -0,0 +1,62 @@
+module SfCli
+  module Sf
+    module Model
+      module BaseMethods
+        def self.included(c)
+          c.extend ClassMethods
+        end
+
+        module ClassMethods
+          def connection
+            @connection
+          end
+
+          def connection=(conn)
+            @connection = conn
+          end
+
+          def describe
+            connection.describe(name.to_sym)
+          end
+        end
+
+        def initialize(attributes = {})
+          @original_attributes = {}
+          @current_attributes = {}
+          @updated_attributes = {}
+
+          attributes.each do |k, v|
+            field_name = k.to_sym
+            if self.class.field_names.include?(field_name)
+              @original_attributes[field_name] = v
+              __send__ (field_name.to_s + '='), v
+            elsif self.class.parent_relations.find{|r| r[:name] == field_name}
+              __send__ (field_name.to_s + '='), v
+            elsif self.class.children_relations.find{|r| r[:name] == field_name}
+              __send__ (field_name.to_s + '='), (v.nil? ? [] : v)
+            end
+          end
+        end
+
+        def to_h(keys: nil)
+          self.class.field_names.each_with_object({}) do |name, hash|
+            if keys&.instance_of?(Array)
+              hash[name] = __send__(name) if keys.include?(name)
+            else
+              hash[name] = __send__(name)
+            end
+          end
+        end
+
+        def new_record?
+          self.Id.nil?
+        end
+
+        def persisted?
+          new_record? == false
+        end
+      end
+    end
+  end
+end
+

data/lib/sf_cli/sf/model/class_definition.rb

@@ -1,4 +1,6 @@
-require_relative './schema'
+require_relative './base_methods'
+require_relative './dml_methods'
+require_relative './query_methods'
 
 module SfCli
   module Sf
@@ -7,60 +9,27 @@ module SfCli
         attr_reader :schema
 
         def initialize(schema)
-          @schema = Schema.new(schema)
+          @schema = schema
         end
 
         def to_s
           <<~Klass
             Class.new do
-              #{ class_methods }
+              include ::SfCli::Sf::Model::BaseMethods
+              include ::SfCli::Sf::Model::DmlMethods
+              include ::SfCli::Sf::Model::QueryMethods
 
-              field_names.each do |name|
-                attr_accessor name
-              end
+              attr_reader :original_attributes, :current_attributes, :updated_attributes
+
+              #{ class_methods }
 
+              #{ field_attribute_methods  }
               #{ parent_relation_methods }
               #{ children_relation_methods }
-
-              #{ define_initialize }
-
-              #{ define_to_h }
             end
           Klass
         end
 
-        def define_initialize
-          <<~EOS
-            def initialize(attributes = {})
-              attributes.each do |k, v|
-                field_name = k.to_sym
-                if self.class.field_names.include?(field_name)
-                  #instance_variable_set ('@' + field_name.to_s).to_sym, v
-                  __send__ (field_name.to_s + '='), v
-                elsif self.class.parent_relations.find{|r| r[:name] == field_name}
-                  __send__ (field_name.to_s + '='), v
-                elsif self.class.children_relations.find{|r| r[:name] == field_name}
-                  __send__ (field_name.to_s + '='), (v.nil? ? [] : v)
-                end
-              end
-            end
-          EOS
-        end
-
-        def define_to_h
-          <<~EOS
-            def to_h(keys: nil)
-              self.class.field_names.each_with_object({}) do |name, hash|
-                if keys&.instance_of?(Array)
-                  hash[name] = __send__(name) if keys.include?(name)
-                else
-                  hash[name] = __send__(name)
-                end
-              end
-            end
-          EOS
-        end
-
         def class_methods
           <<~EOS
             class << self
@@ -79,6 +48,28 @@ module SfCli
           EOS
         end
 
+        def field_attribute_methods
+          schema.field_names.each_with_object('') do |name, s|
+            s << <<~EOS
+              def #{name}
+                @#{name}
+              end
+
+              def #{name}=(value)
+                @#{name} = value
+                return if %i[Id LastModifiedDate IsDeleted SystemModstamp CreatedById CreatedDate LastModifiedById].include?(:#{name})
+
+                current_attributes[:#{name}] = value
+                if current_attributes[:#{name}] == original_attributes[:#{name}]
+                  updated_attributes[:#{name}] = nil
+                else
+                  updated_attributes[:#{name}] = value
+                end
+              end
+            EOS
+          end
+        end
+
         def parent_relation_methods
           schema.parent_relations.each_with_object('') do |r, s|
             s << <<~EOS
@@ -87,7 +78,7 @@ module SfCli
               end
 
               def #{r[:name]}=(attributes)
-                @#{r[:name]} = #{r[:class_name]}.new(attributes)
+                @#{r[:name]} = attributes.nil? ? nil : #{r[:class_name]}.new(attributes)
               end
             EOS
           end