aspera-cli 4.2.0 → 4.4.0

data/docs/doc_tools.rb

@@ -0,0 +1,58 @@
+# get transfer spec parameter description
+$LOAD_PATH.unshift(ENV["INCL_DIR_GEM"])
+require 'aspera/fasp/parameters'
+
+# check that required env vars exist, and files
+%w{EXENAME GEMSPEC INCL_USAGE INCL_COMMANDS INCL_ASESSION INCL_DIR_GEM}.each do |e|
+  raise "missing env var #{e}" unless ENV.has_key?(e)
+  raise "missing file #{ENV[e]}" unless File.exist?(ENV[e]) or !e.start_with?('INCL_')
+end
+
+# set values used in ERB
+# just command name
+def cmd;ENV['EXENAME'];end
+
+# used in text with formatting of command
+def tool;'`'+cmd+'`';end
+
+# prefix for env vars
+def evp;cmd.upcase+'_';end
+
+# just the name for "option preset"
+def opprst;'option preset';end
+
+# name with link
+def prst;'['+opprst+'](#lprt)';end
+
+# name with link (plural)
+def prsts;'['+opprst+'s](#lprt)';end
+
+# in title
+def prstt;opprst.capitalize;end
+
+def gemspec;Gem::Specification::load(ENV['GEMSPEC']) or raise "error loading #{ENV["GEMSPEC"]}";end
+
+def geminstadd;gemspec.version.to_s.match(/\.[^0-9]/)?' --pre':'';end
+
+# transfer spec description generation
+def spec_table
+  r='<table><tr><th>Field</th><th>Type</th>'
+  Aspera::Fasp::Parameters::SUPPORTED_AGENTS_SHORT.each do |c|
+    r << '<th>'<<c.to_s.upcase<<'</th>'
+  end
+  r << '<th>Description</th></tr>'
+  Aspera::Fasp::Parameters.man_table.each do |p|
+    p[:description] << (p[:description].empty? ? '' : "\n") << "(" << p[:cli] << ")" unless p[:cli].to_s.empty?
+    p.delete(:cli)
+    p.keys.each{|c|p[c]='&nbsp;' if p[c].to_s.empty?}
+    p[:description].gsub!("\n",'<br/>')
+    p[:type].gsub!(',','<br/>')
+    r << '<tr><td>'<<p[:name]<<'</td><td>'<<p[:type]<<'</td>'
+    Aspera::Fasp::Parameters::SUPPORTED_AGENTS_SHORT.each do |c|
+      r << '<td>'<<p[c]<<'</td>'
+    end
+    r << '<td>'<<p[:description]<<'</td></tr>'
+  end
+  r << '</table>'
+  return r
+end

data/docs/test_env.conf

@@ -5,7 +5,7 @@ default:
   config: cli_default
   aoc: tst_aoc1
   faspex: tst_faspex
-  faspex5: tst_faspex5_boot
+  faspex5: tst_faspex5
   shares: tst_shares_1
   shares2: tst_shares2
   node: tst_node
@@ -52,6 +52,12 @@ tst_faspex5_boot:
   auth: your value here
   username: your value here
   password: your value here
+tst_faspex5_web:
+  url: your value here
+  auth: your value here
+  redirect_uri: your value here
+  client_id: your value here
+  client_secret: your value here
 tst_faspex5:
   url: your value here
   auth: your value here
@@ -59,6 +65,7 @@ tst_faspex5:
   client_secret: your value here
   private_key: your value here
   username: your value here
+  password: your value here
 tst_shares:
   url: your value here
   username: your value here
@@ -149,4 +156,5 @@ misc:
   email_external: your value here
   aoc_org: your value here
   aoc_user_email: your value here
+  aoc_workspace2: your value here
   http_gw_fqdn_port: your value here

data/examples/aoc.rb

@@ -4,11 +4,22 @@ require 'aspera/log'
 
 Aspera::Log.instance.level=:debug
 
+if ! ARGV.length.eql?(3)
+  Aspera::Log.log.error("wrong number of args: #{ARGV.length}")
+  Aspera::Log.log.error("Usage: #{$0} <aoc URL> <aoc username> <aoc private key content>")
+  Aspera::Log.log.error("Example: #{$0} https://myorg.ibmaspera.com john@example.com $(cat /home/john/my_key.pem)")
+  Process.exit(1)
+end
+
+aoc_url=ARGV[0]
+aoc_user=ARGV[1]
+aoc_key_value=ARGV[2]
+
 aocapi=Aspera::AoC.new(
-url: 'https://myorg.ibmaspera.com',
+url: aoc_url,
 auth: :jwt,
-private_key: File.read('path/to_your_private_key.pem'),
-username: 'my.email@example.com',
+private_key: aoc_key_value,
+username: aoc_user,
 scope: 'user:all',
 subpath: 'api/v1')
 

data/examples/faspex4.rb

@@ -0,0 +1,89 @@
+#!/usr/bin/env ruby
+# find Faspex API here: https://developer.ibm.com/apis/catalog/?search=faspex
+# this example makes use of class Aspera::Rest for REST calls, alternatively class RestClient of gem rest-client could be used
+# this example makes use of class Aspera::Fasp::Local for transfers, alternatively the official "Transfer SDK" could be used
+# Aspera SDK can be downloaded with: `ascli conf ascp install` , it installs in $HOME/.aspera/ascli/sdk
+require 'aspera/rest'
+require 'aspera/log'
+require 'aspera/fasp/local'
+
+tmpdir=ENV['tmp']||Dir.tmpdir || '.'
+
+# Set high log level for the example, decrease to :warn usually
+Aspera::Log.instance.level=:debug
+
+# Set folder where SDK is installed (mandatory)
+# (if ascp is not there, the lib will try to find in usual locations)
+# (if data files are not there, they will be created)
+Aspera::Fasp::Installation.instance.folder = tmpdir
+
+if ! ARGV.length.eql?(3)
+  Aspera::Log.log.error("Wrong number of args: #{ARGV.length}")
+  Aspera::Log.log.error("Usage: #{$0} <faspex URL> <faspex username> <faspex password>")
+  Aspera::Log.log.error("Example: #{$0} https://faspex.com/aspera/faspex john p@sSw0rd")
+  Process.exit(1)
+end
+
+faspex_url=ARGV[0] # typically: https://faspex.example.com/aspera/faspex
+faspex_user=ARGV[1]
+faspex_pass=ARGV[2]
+
+# comment out this if certificate is valid, keep line to ignore certificate
+Aspera::Rest.insecure=true
+
+# 1: Faspex 4 API v3
+#---------------
+
+# create REST API object
+api_v3=Aspera::Rest.new({
+  :base_url => faspex_url,
+  :auth     => {
+  :type     => :basic,
+  :username => faspex_user,
+  :password => faspex_pass
+  }})
+
+# very simple api call
+api_v3.read('me')
+
+# 2: send a package
+#---------------
+
+# create a sample file to send
+file_to_send=File.join(tmpdir,'myfile.bin')
+File.open(file_to_send, "w") {|f| f.write("sample data") }
+# package creation parameters
+package_create_params={'delivery'=>{'title'=>'test package','recipients'=>['aspera.user1@gmail.com'],'sources'=>[{'paths'=>[file_to_send]}]}}
+pkg_created=api_v3.create('send',package_create_params)[:data]
+# get transfer specification (normally: only one)
+transfer_spec=pkg_created['xfer_sessions'].first
+# set paths of files to send
+transfer_spec['paths']=[{'source'=>file_to_send}]
+# get the local agent (i.e. ascp)
+transfer_client=Aspera::Fasp::Local.new
+# disable ascp output on stdout (optional)
+transfer_client.quiet=true
+# start transfer (asynchronous)
+job_id=transfer_client.start_transfer(transfer_spec)
+# wait for all transfer completion (for the example)
+result=transfer_client.wait_for_transfers_completion
+#  notify of any transfer error
+result.select{|i|!i.eql?(:success)}.each do |e|
+  Aspera::Log.log.error("A transfer error occured: #{e.message}")
+end
+
+# 3: Faspex 4 API v4
+#---------------
+api_v4=Aspera::Rest.new({
+  :base_url  => faspex_url+'/api',
+  :auth      => {
+  :type      => :oauth2,
+  :base_url  => faspex_url+'/auth/oauth2',
+  :grant     => :header_userpass,
+  :user_name => faspex_user,
+  :user_pass => faspex_pass,
+  :scope     => 'admin'
+  }})
+
+# Use it. Note that Faspex 4 API v4 is totally different from Faspex 4 v3 APIs, see ref on line 2
+Aspera::Log.dump('users',api_v4.read('users')[:data])

data/lib/aspera/aoc.rb

@@ -2,6 +2,7 @@ require 'aspera/log'
 require 'aspera/rest'
 require 'aspera/hash_ext'
 require 'aspera/data_repository'
+require 'aspera/node'
 require 'base64'
 
 module Aspera
@@ -24,9 +25,9 @@ module Aspera
     JWT_AUDIENCE='https://api.asperafiles.com/api/v1/oauth2/token'
     OAUTH_API_SUBPATH='api/v1/oauth2'
     DEFAULT_TSPEC_INFO={
-      'remote_user' => 'xfer',
-      'ssh_port'    => 33001,
-      'fasp_port'   => 33001
+      'remote_user' => Node::ACCESS_KEY_TRANSFER_USER,
+      'ssh_port'    => Node::SSH_PORT_DEFAULT,
+      'fasp_port'   => Node::UDP_PORT_DEFAULT
     }
 
     private_constant :PRODUCT_NAME,:PROD_DOMAIN,:MAX_REDIRECT,:CLIENT_APPS,:PATHS_PUBLIC_LINK,:JWT_AUDIENCE,:OAUTH_API_SUBPATH,:DEFAULT_TSPEC_INFO
@@ -273,7 +274,7 @@ module Aspera
         transfer_spec['remote_host']=node_file[:node_info]['host']
       else
         # retrieve values from API
-        std_t_spec=get_node_api(node_file[:node_info],SCOPE_NODE_USER).create('files/download_setup',{:transfer_requests => [ { :transfer_request => {:paths => [ {"source"=>'/'} ] } } ] } )[:data]['transfer_specs'].first['transfer_spec']
+        std_t_spec=get_node_api(node_file[:node_info],scope: SCOPE_NODE_USER).create('files/download_setup',{:transfer_requests => [ { :transfer_request => {:paths => [ {"source"=>'/'} ] } } ] } )[:data]['transfer_specs'].first['transfer_spec']
         ['remote_host','remote_user','ssh_port','fasp_port'].each {|i| transfer_spec[i]=std_t_spec[i]}
       end
       # add caller provided transfer spec
@@ -290,26 +291,27 @@ module Aspera
     # @param scope e.g. SCOPE_NODE_USER
     # no scope: requires secret
     # if secret provided beforehand: use it
-    def get_node_api(node_info,node_scope=nil)
-      # X-Aspera-AccessKey required for bearer token only
-      node_rest_params={
-        :base_url => node_info['url'],
-        :headers  => {'X-Aspera-AccessKey'=>node_info['access_key']},
-      }
-      ak_secret=@key_chain.get_secret(node_info['access_key'],false)
-      if ak_secret.nil? and node_scope.nil?
+    def get_node_api(node_info,options={})
+      raise "INTERNAL ERROR: method parameters: options must ne hash" unless options.is_a?(Hash)
+      options.keys.each {|k| raise "INTERNAL ERROR: not valid option: #{k}" unless [:scope,:use_secret].include?(k)}
+      # get optional secret unless :use_secret is false (default is true)
+      ak_secret=@key_chain.get_secret(node_info['access_key'],false) if !options.has_key?(:use_secret) or options[:use_secret]
+      if ak_secret.nil? and !options.has_key?(:scope)
         raise "There must be at least one of: 'secret' or 'scope' for access key #{node_info['access_key']}"
       end
-      # if secret provided on command line or if there is no scope
-      if !ak_secret.nil? or node_scope.nil?
+      node_rest_params={base_url: node_info['url']}
+      # if secret is available
+      if !ak_secret.nil?
         node_rest_params[:auth]={
-          :type     => :basic,
-          :username => node_info['access_key'],
-          :password => ak_secret
+          type:     :basic,
+          username: node_info['access_key'],
+          password: ak_secret
         }
       else
+        # X-Aspera-AccessKey required for bearer token only
+        node_rest_params[:headers]= {'X-Aspera-AccessKey'=>node_info['access_key']}
         node_rest_params[:auth]=self.params[:auth].clone
-        node_rest_params[:auth][:scope]=self.class.node_scope(node_info['access_key'],node_scope)
+        node_rest_params[:auth][:scope]=self.class.node_scope(node_info['access_key'],options[:scope])
       end
       return Node.new(node_rest_params)
     end
@@ -336,7 +338,7 @@ module Aspera
         if entry[:type].eql?('link')
           sub_node_info=self.read("nodes/#{entry['target_node_id']}")[:data]
           sub_opt={method: process_find_files, top_file_id: entry['target_id'], top_file_path: path}
-          get_node_api(sub_node_info,SCOPE_NODE_USER).crawl(self,sub_opt)
+          get_node_api(sub_node_info,scope: SCOPE_NODE_USER).crawl(self,sub_opt)
         end
       rescue => e
         Log.log.error("#{path}: #{e.message}")
@@ -349,7 +351,7 @@ module Aspera
       top_node_info,top_file_id=check_get_node_file(top_node_file)
       Log.log.debug("find_files: node_info=#{top_node_info}, fileid=#{top_file_id}")
       @find_state={found: [], test_block: test_block}
-      get_node_api(top_node_info,SCOPE_NODE_USER).crawl(self,{method: :process_find_files, top_file_id: top_file_id})
+      get_node_api(top_node_info,scope: SCOPE_NODE_USER).crawl(self,{method: :process_find_files, top_file_id: top_file_id})
       result=@find_state[:found]
       @find_state=nil
       return result
@@ -370,7 +372,7 @@ module Aspera
         if @resolve_state[:path].empty?
           @resolve_state[:result][:file_id]=entry['target_id']
         else
-          get_node_api(@resolve_state[:result][:node_info],SCOPE_NODE_USER).crawl(self,{method: :process_resolve_node_file, top_file_id: entry['target_id']})
+          get_node_api(@resolve_state[:result][:node_info],scope: SCOPE_NODE_USER).crawl(self,{method: :process_resolve_node_file, top_file_id: entry['target_id']})
         end
       when 'folder'
         if @resolve_state[:path].empty?
@@ -397,7 +399,7 @@ module Aspera
         result[:file_id]=top_file_id
       else
         @resolve_state={path: path_elements, result: result}
-        get_node_api(top_node_info,SCOPE_NODE_USER).crawl(self,{method: :process_resolve_node_file, top_file_id: top_file_id})
+        get_node_api(top_node_info,scope: SCOPE_NODE_USER).crawl(self,{method: :process_resolve_node_file, top_file_id: top_file_id})
         not_found=@resolve_state[:path]
         @resolve_state=nil
         raise "entry not found: #{not_found}" if result[:file_id].nil?

data/lib/aspera/cli/main.rb

@@ -21,15 +21,17 @@ module Aspera
       private
       # name of application, also foldername where config is stored
       PROGRAM_NAME = 'ascli'
+      # name of the containing gem, same as in <gem name>.gemspec
       GEM_NAME = 'aspera-cli'
-      VERBOSE_LEVELS=[:normal,:minimal,:quiet]
-
-      private_constant :PROGRAM_NAME,:GEM_NAME,:VERBOSE_LEVELS
+      HELP_URL = "http://www.rubydoc.info/gems/#{GEM_NAME}"
+      GEM_URL  = "https://rubygems.org/gems/#{GEM_NAME}"
+      SRC_URL  = "https://github.com/IBM/aspera-cli"
+      STATUS_FIELD = 'status'
 
+      private_constant :PROGRAM_NAME,:GEM_NAME,:HELP_URL,:GEM_URL
       # =============================================================
       # Parameter handlers
       #
-
       def option_insecure; Rest.insecure ; end
 
       def option_insecure=(value); Rest.insecure = value; end
@@ -40,20 +42,19 @@ module Aspera
 
       # minimum initialization
       def initialize(argv)
-        # first thing : manage debug level (allows debugging or option parser)
+        # first thing : manage debug level (allows debugging of option parser)
         early_debug_setup(argv)
+        # compare $0 with expected name
         current_prog_name=File.basename($PROGRAM_NAME)
         unless current_prog_name.eql?(PROGRAM_NAME)
           @plugin_env[:formater].display_message(:error,"#{"WARNING".bg_red.blink.gray} Please use '#{PROGRAM_NAME}' instead of '#{current_prog_name}', '#{current_prog_name}' will be removed in a future version")
         end
-        # overriding parameters on transfer spec
         @option_help=false
         @bash_completion=false
         @option_show_config=false
+        # environment provided to plugin for various capabilities
         @plugin_env={}
-        @help_url='http://www.rubydoc.info/gems/'+GEM_NAME
-        @gem_url='https://rubygems.org/gems/'+GEM_NAME
-        # give command line arguments to option manager (no parsing)
+        # find out application main folder
         app_main_folder=ENV[conf_dir_env_var]
         # if env var undefined or empty
         if app_main_folder.nil? or app_main_folder.empty?
@@ -61,20 +62,21 @@ module Aspera
           raise CliError,"Home folder does not exist: #{user_home_folder}. Check your user environment or use #{conf_dir_env_var}." unless Dir.exist?(user_home_folder)
           app_main_folder=File.join(user_home_folder,Plugins::Config::ASPERA_HOME_FOLDER_NAME,PROGRAM_NAME)
         end
+        # give command line arguments to option manager (no parsing)
         @plugin_env[:options]=@opt_mgr=Manager.new(PROGRAM_NAME,argv,app_banner())
         @plugin_env[:formater]=Formater.new(@plugin_env[:options])
         Rest.user_agent=PROGRAM_NAME
-        # must override help methods before parser called (in other constructors)
+        # declare and parse global options
         init_global_options()
         # secret manager
         @plugin_env[:secret]=Aspera::Secrets.new
         # the Config plugin adds the @preset parser
-        @plugin_env[:config]=Plugins::Config.new(@plugin_env,PROGRAM_NAME,@help_url,Aspera::Cli::VERSION,app_main_folder)
+        @plugin_env[:config]=Plugins::Config.new(@plugin_env,PROGRAM_NAME,HELP_URL,Aspera::Cli::VERSION,app_main_folder)
         # the TransferAgent plugin may use the @preset parser
         @plugin_env[:transfer]=TransferAgent.new(@plugin_env)
-        Log.log.debug('created plugin env'.red)
         # set application folder for modules
         @plugin_env[:persistency]=PersistencyFolder.new(File.join(@plugin_env[:config].main_folder,'persist_store'))
+        Log.log.debug('plugin env created'.red)
         Oauth.persist_mgr=@plugin_env[:persistency]
         Fasp::Parameters.file_list_folder=File.join(@plugin_env[:config].main_folder,'filelists')
         Aspera::RestErrorAnalyzer.instance.log_file=File.join(@plugin_env[:config].main_folder,'rest_exceptions.log')
@@ -88,9 +90,9 @@ module Aspera
         banner << "\t#{PROGRAM_NAME} COMMANDS [OPTIONS] [ARGS]\n"
         banner << "\nDESCRIPTION\n"
         banner << "\tUse Aspera application to perform operations on command line.\n"
-        banner << "\tDocumentation and examples: #{@gem_url}\n"
+        banner << "\tDocumentation and examples: #{GEM_URL}\n"
         banner << "\texecute: #{PROGRAM_NAME} conf doc\n"
-        banner << "\tor visit: #{@help_url}\n"
+        banner << "\tor visit: #{HELP_URL}\n"
         banner << "\nENVIRONMENT VARIABLES\n"
         banner << "\t#{conf_dir_env_var}  config folder, default: $HOME/#{Plugins::Config::ASPERA_HOME_FOLDER_NAME}/#{PROGRAM_NAME}\n"
         banner << "\t#any option can be set as an environment variable, refer to the manual\n"
@@ -188,6 +190,8 @@ module Aspera
 
       protected
 
+      # env var name to override the app's main folder
+      # default main folder is $HOME/<vendor main app folder>/<program name>
       def conf_dir_env_var
         return "#{PROGRAM_NAME}_home".upcase
       end
@@ -219,10 +223,28 @@ module Aspera
         return Main.result_nothing
       end
 
+      # used when one command executes several transfer jobs (each job being possibly multi session)
+      # @param status_table [Array] [{STATUS_FIELD=>[status array],...},...]
+      # each element has a key STATUS_FIELD which contains the result of possibly mulmtiple sessions
+      def self.result_transfer_multiple(status_table)
+        global_status=:success
+        # transform status into string and find if there was problem
+        status_table.each do |item|
+          worst=TransferAgent.session_status(item[STATUS_FIELD])
+          global_status=worst unless worst.eql?(:success)
+          item[STATUS_FIELD]=item[STATUS_FIELD].map{|i|i.to_s}.join(',')
+        end
+        raise global_status unless global_status.eql?(:success)
+        return {:type=>:object_list,:data=>status_table}
+      end
+
       # this is the main function called by initial script just after constructor
       def process_command_line
         Log.log.debug('process_command_line')
+        # catch exception information , if any
         exception_info=nil
+        # false if command shall not be executed ("once_only")
+        execute_command=true
         begin
           # find plugins, shall be after parse! ?
           @plugin_env[:config].add_plugins_from_lookup_folders
@@ -256,7 +278,7 @@ module Aspera
             @plugin_env[:formater].display_results({:type=>:single_object,:data=>@opt_mgr.declared_options(false)})
             Process.exit(0)
           end
-          # locking for singkle execution (only after "per plugin" option, in case lock port is there)
+          # locking for single execution (only after "per plugin" option, in case lock port is there)
           lock_port=@opt_mgr.get_option(:lock_port,:optional)
           if !lock_port.nil?
             begin
@@ -264,11 +286,12 @@ module Aspera
               Log.log.debug("Opening lock port #{lock_port.to_i}")
               @tcp_server=TCPServer.new('127.0.0.1',lock_port.to_i)
             rescue => e
-              raise CliError,"Another instance is already running (#{e.message})."
+              execute_command=false
+              Log.log.warn("Another instance is already running (#{e.message}).")
             end
           end
-          # execute and display
-          @plugin_env[:formater].display_results(command_plugin.execute_action)
+          # execute and display (if not exclusive execution)
+          @plugin_env[:formater].display_results(command_plugin.execute_action) if execute_command
           # finish
           @plugin_env[:transfer].shutdown
         rescue CliBadArgument => e;          exception_info=[e,'Argument',:usage]
@@ -286,10 +309,15 @@ module Aspera
         unless exception_info.nil?
           @plugin_env[:formater].display_message(:error,"ERROR:".bg_red.gray.blink+" "+exception_info[1]+": "+exception_info[0].message)
           @plugin_env[:formater].display_message(:error,"Use '-h' option to get help.") if exception_info[2].eql?(:usage)
+          if exception_info.first.is_a?(Fasp::Error) and exception_info.first.message.eql?('Remote host is not who we expected')
+            @plugin_env[:formater].display_message(:error,"For this specific error, refer to:\n#{SRC_URL}#error-remote-host-is-not-who-we-expected\nAdd this to arguments:\n--ts=@json:'{\"sshfp\":null}'")
+          end
         end
         # 2- processing of command not processed (due to exception or bad command line)
-        @opt_mgr.final_errors.each do |msg|
-          @plugin_env[:formater].display_message(:error,"ERROR:".bg_red.gray.blink+" Argument: "+msg)
+        if execute_command
+          @opt_mgr.final_errors.each do |msg|
+            @plugin_env[:formater].display_message(:error,"ERROR:".bg_red.gray.blink+" Argument: "+msg)
+          end
         end
         # 3- in case of error, fail the process status
         unless exception_info.nil?

data/lib/aspera/cli/plugin.rb

@@ -2,10 +2,15 @@ module Aspera
   module Cli
     # base class for plugins modules
     class Plugin
+      # operation without id
       GLOBAL_OPS=[:create,:list]
+      # operation on specific instance
       INSTANCE_OPS=[:modify,:delete,:show]
       ALL_OPS=[GLOBAL_OPS,INSTANCE_OPS].flatten
-      #private_constant :GLOBAL_OPS,:INSTANCE_OPS,:ALL_OPS
+      # max number of items for list command
+      MAX_ITEMS='max'
+      # max number of pages for list command
+      MAX_PAGES='pmax'
 
       @@done=false
 
@@ -28,7 +33,7 @@ module Aspera
         end
       end
 
-      def entity_command(command,rest_api,res_class_path,display_fields,id_symb,id_default=nil,subkey=false)
+      def entity_command(command,rest_api,res_class_path,display_fields,id_symb,id_default=nil,use_subkey=false)
         if INSTANCE_OPS.include?(command)
           begin
             one_res_id=self.options.get_option(id_symb,:mandatory)
@@ -54,10 +59,11 @@ module Aspera
         when :list
           resp=rest_api.read(res_class_path,parameters)
           data=resp[:data]
+          # TODO: not generic : which application is this for ?
           if resp[:http]['Content-Type'].start_with?('application/vnd.api+json')
-            data=resp[:data][res_class_path]
+            data=data[res_class_path]
           end
-          data=data[res_class_path] if subkey
+          data=data[res_class_path] if use_subkey
           return {:type => :object_list, :data=>data, :fields=>display_fields}
         when :modify
           property=self.options.get_option(:property,:optional)
@@ -74,12 +80,13 @@ module Aspera
       end
 
       # implement generic rest operations on given resource path
-      def entity_action(rest_api,res_class_path,display_fields,id_symb,id_default=nil,subkey=false)
+      def entity_action(rest_api,res_class_path,display_fields,id_symb,id_default=nil,use_subkey=false)
         #res_name=res_class_path.gsub(%r{^.*/},'').gsub(%r{s$},'').gsub('_',' ')
         command=self.options.get_next_command(ALL_OPS)
-        return entity_command(command,rest_api,res_class_path,display_fields,id_symb,id_default,subkey)
+        return entity_command(command,rest_api,res_class_path,display_fields,id_symb,id_default,use_subkey)
       end
 
+      # shortcuts for plugin environment
       def options; return @agents[:options];end
 
       def transfer; return @agents[:transfer];end