aspera-cli 4.2.2 → 4.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 69d9db9ef64b0b49f9a0dc83949bc1dbff6934dc158132e4bce6b8fc12a8d0bd
-  data.tar.gz: 60a1d6b8cbf0b0d2f7128f8131d31a94166a856eb17197db3578d3aa0e760dff
+  metadata.gz: 4f09023e74080acc5ac3370a944a210b371a0f1492cd3ad89a9816affc35cd8e
+  data.tar.gz: 808993db319171f042de4c6be8a81cdc609af02f9ff67bd1cea5f0d0070ace40
 SHA512:
-  metadata.gz: 5a918f2f400041eff1655d97829ff5cf64d52a09e1223032823891205cbdeba8109619fd43f9b8ebc7d55022b6e0b72b0f935c357be4b58cfd3a85343431f830
-  data.tar.gz: 4927dabefd461997ea0ff07a8a4c2034f767a5925bac6c88faa4370e34d62f1fbca31ba2e8a65ebf723a168da9974c8aacfa8da5662087151f32df1f9e71d4d7
+  metadata.gz: 9620be95b310ae3b2ab7537858b91f3a5ab8a60eca2cba61e31fc19d535314ea0f419b41537de4cb91a4346977365e94ea6d2d9065136fb38e813ce865c83333
+  data.tar.gz: 9ddf8860dcac5ce8c69afdedbd2b4a2b1f1242d04a3b416e6b9cf66ae7271c0b079dafc4200f8b450b34263a3f2385e701868959bcca9128f34464ab6ce07258

data/README.md

@@ -1,7 +1,7 @@
 [comment1]: # (Do not edit this README.md, edit docs/README.erb.md, for details, read docs/README.md)
-# `ascli` : Command Line Interface for IBM Aspera products
+<font size="+12"><center>`ascli` : Command Line Interface for IBM Aspera products</center></font>
 
-Version : 4.2.2
+Version : 4.3.0
 
 _Laurent/2016-2021_
 
@@ -13,7 +13,7 @@ Ruby Gem: [https://rubygems.org/gems/aspera-cli](https://rubygems.org/gems/asper
 
 Ruby Doc: [https://www.rubydoc.info/gems/aspera-cli](https://www.rubydoc.info/gems/aspera-cli)
 
-Ruby version must be >= > 2.4
+Required Ruby version: > 2.4
 
 # <a name="when_to_use"></a>When to use and when not to use
 
@@ -29,7 +29,8 @@ So it is designed for:
 
 `ascli` can be seen as a command line tool integrating:
 
-* a configuration file (config.yaml) and advanced command line options
+* a configuration file (config.yaml)
+* advanced command line options
 * cURL (for REST calls)
 * Aspera transfer (ascp)
 
@@ -81,7 +82,7 @@ Once the gem is installed, `ascli` shall be accessible:
 
 ```
 $ ascli --version
-4.2.2
+4.3.0
 ```
 
 ## First use
@@ -151,7 +152,7 @@ It is possible to install *either* directly on the host operating system (Linux,
 
 The direct installation is recommended and consists in installing:
 
-* [Ruby](#ruby) version >= > 2.4
+* [Ruby](#ruby) version > 2.4
 * [aspera-cli](#the_gem)
 * [Aspera SDK (ascp)](#fasp_prot)
 
@@ -199,7 +200,7 @@ Use this method to install on the native host.
 
 A ruby interpreter is required to run the tool or to use the gem and tool.
 
-Ruby minimum version: > 2.4. Ruby version 3 is also supported.
+Required Ruby version: > 2.4. Ruby version 3 is also supported.
 
 *Ruby can be installed using any method* : rpm, yum, dnf, rvm, brew, windows installer, ... .
 
@@ -207,7 +208,7 @@ Refer to the following sections for a proposed method for specific operating sys
 
 The recommended installation method is `rvm` for systems with "bash-like" shell (Linux, Macos, Windows with cygwin, etc...).
 If the generic install is not suitable (e.g. Windows, no cygwin), you can use one of OS-specific install method.
-If you have a simpler better way to install Ruby version >= > 2.4 : use it !
+If you have a simpler better way to install Ruby version > 2.4 : use it !
 
 ### Generic: RVM: single user installation (not root)
 
@@ -1185,11 +1186,19 @@ The `transfer-info` accepts the following optional parameters:
 <tr><td>spawn_timeout_sec</td><td>Float</td><td>3</td><td>Multi session</td><td>Verification time that ascp is running</td></tr>
 <tr><td>spawn_delay_sec</td><td>Float</td><td>2</td><td>Multi session</td><td>Delay between startup of sessions</td></tr>
 <tr><td>wss</td><td>Bool</td><td>false</td><td>Web Socket Session</td><td>Enable use of web socket session in case it is available</td></tr>
+<tr><td>multi_incr_udp</td><td>Bool</td><td>true</td><td>Multi Session</td><td>Increment UDP port on multi-session<br/>If true, each session will have a different UDP port starting at `fasp_port` (or default 33001)<br/>Else, each session will use `fasp_port` (or `ascp` default)</td></tr>
 <tr><td>resume</td><td>Hash</td><td>nil</td><td>Resumer parameters</td><td>See below</td></tr>
 </table>
 
 Resume parameters:
 
+In case of transfer interruption, the agent will resume a transfer up to `iter_max` time.
+Sleep between iteration is:
+
+```
+max( sleep_max , sleep_initial * sleep_factor ^ (iter_index-1) )
+```
+
 <table>
 <tr><th>Name</th><th>Type</th><th>Default</th><th>Feature</th><th>Description</th></tr>
 <tr><td>iter_max</td><td>int</td><td>7</td><td>Resume</td><td>Max number of retry on error</td></tr>
@@ -1202,7 +1211,7 @@ Examples:
 
 ```
 $ ascli ... --transfer-info=@json:'{"wss":true,"resume":{"iter_max":10}}'
-$ ascli ... --transfer-info=@json:'{"spawn_delay_sec":2.5}'
+$ ascli ... --transfer-info=@json:'{"spawn_delay_sec":2.5,"multi_incr_udp":false}'
 ```
 
 ### IBM Aspera Connect Client GUI
@@ -1490,6 +1499,7 @@ ascli aoc automation workflow list --value=@json:'{"show_org_workflows":"true"}'
 ascli aoc bearer_token --display=data --scope=user:all
 ascli aoc faspex
 ascli aoc files bearer /
+ascli aoc files bearer_token_node /
 ascli aoc files browse /
 ascli aoc files browse / -N --link=my_aoc_publink_folder
 ascli aoc files delete /testsrc
@@ -1505,6 +1515,7 @@ ascli aoc files short_link list --value=@json:'{"purpose":"shared_folder_auth_li
 ascli aoc files transfer --from-folder=/testsrc --to-folder=/testdst testfile.bin
 ascli aoc files upload --to-folder=/testsrc testfile.bin
 ascli aoc files upload -N --to-folder=/ testfile.bin --link=my_aoc_publink_folder
+ascli aoc files upload Test.pdf --transfer=node --transfer-info=@json:@stdin:
 ascli aoc files v3 info
 ascli aoc org -N --link=my_aoc_publink_recv_from_aocuser
 ascli aoc organization
@@ -1669,7 +1680,7 @@ ascli sync start --parameters=@json:'{"sessions":[{"name":"test","reset":true,"r
 ```
 $ ascli -h
 NAME
-	ascli -- a command line tool for Aspera Applications (v4.2.2)
+	ascli -- a command line tool for Aspera Applications (v4.3.0)
 
 SYNOPSIS
 	ascli COMMANDS [OPTIONS] [ARGS]
@@ -2004,7 +2015,7 @@ For this, specify the option: `--use-generic-client=no`.
 
 This will guide you through the steps to create.
 
-## <a name="aocwizard"></a>Configuration: using manual setup
+## <a name="aocmanual"></a>Configuration: using manual setup
 
 If you used the wizard (recommended): skip this section.
 
@@ -2268,10 +2279,10 @@ $ ascli aoc admin res user list --query='@json:{"q":"dummyuser"}' --fields=id,em
 : 98398 : dummyuser1@example.com :
 : 98399 : dummyuser2@example.com :
 :.......:........................:
-$ thelist=$(echo $(ascli aoc admin res user list --query='@json:{"q":"dummyuser"}' --fields=id,email --field=id --format=csv)|tr ' ' ,)
+$ thelist=$(ascli aoc admin res user list --query='@json:{"q":"dummyuser"}' --fields=id --format=json --display=data|jq -cr 'map(.id)')
 $ echo $thelist
-98398,98399
-$ ascli aoc admin res user --bulk=yes --id=@json:[$thelist] delete
+["113501","354061"]
+$ ascli aoc admin res user --bulk=yes --id=@json:"$thelist" delete
 :.......:.........:
 :  id   : status  :
 :.......:.........:
@@ -2280,6 +2291,14 @@ $ ascli aoc admin res user --bulk=yes --id=@json:[$thelist] delete
 :.......:.........:
 ```
 
+* <a name="deactuser"></a>Find deactivated users since more than 2 years
+
+```
+ascli aoc admin res user list --query=@ruby:'{"deactivated"=>true,"q"=>"last_login_at:<#{(DateTime.now.to_time.utc-2*365*86400).iso8601}"}'
+```
+
+To delete them use the same method as before
+
 * Display current user's workspaces
 
 ```
@@ -2675,7 +2694,37 @@ $ ascli ats api_key create
 +--------+----------------------------------------------+
 $ ascli config id my_ibm_ats update --ats-key=ats_XXXXXXXXXXXXXXXXXXXXXXXX --ats-secret=YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
 ```
+## Cross Organization transfers
+
+It is possible to transfer files directly between organizations without having to first download locally and then upload...
+
+Although optional, the creation of [option preset](#lprt) is recommended to avoid placing all parameters in the command line.
 
+Procedure to send a file from org1 to org2:
+
+* Get access to Organization 1 and create a [option preset](#lprt): e.g. `org1`, for instance, use the [Wizard](#aocwizard)
+* Check that access works and locate the source file e.g. `mysourcefile`, e.g. using command `files browse`
+* Get access to Organization 2 and create a [option preset](#lprt): e.g. `org2`
+* Check that access works and locate the destination folder `mydestfolder`
+* execute the following:
+
+```
+$ ascli -Porg1 aoc files node_info /mydestfolder --format=json --display=data | ascli -Porg2 aoc files upload mysourcefile --transfer=node --transfer-info=@json:@stdin:
+```
+
+Explanation:
+
+* `-Porg1 aoc` use Aspera on Cloud plugin and load credentials for `org1`
+* `files node_info /mydestfolder` generate transfer information including node api credential and root id, suitable for the next command
+* `--format=json` format the output in JSON (instead of default text table)
+* `--display=data` display only the result, and remove other information, such as workspace name
+* `|` the standard output of the first command is fed into the second one
+* `-Porg2 aoc` use Aspera on Cloud plugin and load credentials for `org2`
+* `files upload mysourcefile` upload the file named `mysourcefile` (located in `org1`)
+* `--transfer=node` use transfer agent type `node` instead of default `direct`
+* `--transfer-info=@json:@stdin:` provide `node` transfer agent information, i.e. node API credentials, those are expected in JSON format and read from standard input
+
+Note that when using a POSIX shell, another possibility to write `cmd1 | cmd2 --transfer-info=@json:stdin:` is `cmd2 --transfer-info=@json:$(cmd1)` instead of ``
 ## Examples
 
 Example: create access key on softlayer:
@@ -2994,7 +3043,7 @@ $ ascli faspex v4 dropbox list
 $ ascli faspex v4 dropbox delete --id=36
 ```
 
-## remote sources
+## Remote sources
 
 Faspex lacks an API to list the contents of a remote source (available in web UI). To workaround this,
 the node API is used, for this it is required to add a section ":storage" that links
@@ -3045,29 +3094,38 @@ $ for p in 1 2 3;do ascli shares2 admin users list --value=@json:'{"page":'$p'}'
 # Plugin: IBM Cloud Object Storage
 
 The IBM Cloud Object Storage provides the possibility to execute transfers using FASP.
-It uses the same transfer service as Aspera on Cloud.
-see [https://status.aspera.io](https://status.aspera.io)
+It uses the same transfer service as Aspera on Cloud, called Aspera Transfer Service (ATS).
+Available ATS regions: [https://status.aspera.io](https://status.aspera.io)
+
+There are two possibilities to provide credentials. If you already have the endpoint, apikey and CRN, use the forst method. If you dont have credentials but have access to the IBM Cloud console, then use the second method.
 
-Required options are either:
+## Using endpoint, apikey and Ressource Instance ID (CRN)
+
+If you have those parameters already, then following options shall be provided:
 
 * `bucket` bucket name
 * `endpoint` storage endpoint url, e.g. https://s3.hkg02.cloud-object-storage.appdomain.cloud
 * `apikey` API Key
 * `crn` resource instance id
 
-or:
+For example, let us create a default configuration:
 
-* `bucket` bucket name
-* `region` bucket region, e.g. eu-de
-* `service_credentials` see below
+```
+$ ascli conf id mycos update --bucket=mybucket --endpoint=https://s3.us-east.cloud-object-storage.appdomain.cloud --apikey=abcdefgh --crn=crn:v1:bluemix:public:iam-identity::a/xxxxxxx
+$ ascli conf id default set cos mycos
+```
+
+Then, jump to the transfer example.
+
+## Using service credential file
 
-Service credentials are directly created using the IBM cloud web ui. Navigate to:
+If you are the COS administrator and dont have yet the credential: Service credentials are directly created using the IBM cloud web ui. Navigate to:
 
 Navigation Menu &rarr; Resource List &rarr; Storage &rarr; Cloud Object Storage &rarr; Service Credentials &rarr; &lt;select or create credentials&gt; &rarr; view credentials &rarr; copy
 
 Then save the copied value to a file, e.g. : `$HOME/cos_service_creds.json`
 
-or using the CLI:
+or using the IBM Cloud CLI:
 
 ```
 $ ibmcloud resource service-keys
@@ -3098,33 +3156,38 @@ The field `resource_instance_id` is for option `crn`
 
 The field `apikey` is for option `apikey`
 
-Endpoints for regions can be found by querying the `endpoints` URL.
+(If needed: endpoints for regions can be found by querying the `endpoints` URL.)
+
+The required options for this method are:
+
+* `bucket` bucket name
+* `region` bucket region, e.g. eu-de
+* `service_credentials` see below
 
-For convenience, let us create a default configuration, for example:
+For example, let us create a default configuration:
 
 ```
 $ ascli conf id mycos update --bucket=laurent --service-credentials=@val:@json:@file:~/service_creds.json --region=us-south
 $ ascli conf id default set cos mycos
 ```
 
-or using direct parameters:
+## Operations, transfers
 
-```
-$ ascli conf id mycos update --bucket=mybucket --endpoint=https://s3.us-east.cloud-object-storage.appdomain.cloud --apikey=abcdefgh --crn=crn:v1:bluemix:public:iam-identity::a/xxxxxxx
-$ ascli conf id default set cos mycos
-```
+Let's assume you created a default configuration from once of the two previous steps (else specify the access options on command lines).
 
-Now, Ready to do operations, a subset of "node" plugin operations are supported, basically node API:
+A subset of `node` plugin operations are supported, basically node API:
 
 ```
-$ ascli cos node browse /
-$ ascli cos node upload myfile.txt
+$ ascli cos node info
+$ ascli cos node upload 'faux:///sample1G?1g'
 ```
 
+Note: we generate a dummy file `sample1G` if size 2GB using the `faux` PVCL (man ascp), but you can of course send a real file by specifying a real file instead.
+
 # Plugin: IBM Aspera Sync
 
-A basic plugin to start an "async" using `ascli`. The main advantage is the possibility
-to start from ma configuration file, using `ascli` standard options.
+A basic plugin to start an "async" using `ascli`.
+The main advantage is the possibility to start from ma configuration file, using `ascli` standard options.
 
 # Plugin: Preview
 
@@ -3712,6 +3775,11 @@ So, it evolved into `ascli`:
 
 # Changes (Release notes)
 
+* 4.3.0
+
+	* new: parameter `multi_incr_udp` for option `transfer_info`: control if UDP port is incremented when multi-session is used on `direct` transfer agent.
+	* new: command `aoc files node_info` to get node information for a given folder in the Files application of AoC. Allows cross-org or cross-workspace transfers.
+
 * 4.2.2
 
 	* new: `faspex package list` retrieves the whole list, not just first page

data/docs/README.erb.md

@@ -1,24 +1,24 @@
 [comment1]: # (Do not edit this README.md, edit docs/README.erb.md, for details, read docs/README.md)
-<%
- # check that required env vars exist, and files
+<% #```ruby
+# 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
-cmd=ENV["EXENAME"] # just command name
+cmd=ENV['EXENAME'] # just command name
 tool='`'+cmd+'`'   # used in text with formatting of command
 evp=cmd.upcase+'_' # prefix for env vars
 opprst='option preset' # just the name for "option preset"
-prst='['+opprst+'](#lprt)'
-prsts='['+opprst+'s](#lprt)'
+prst='['+opprst+'](#lprt)' # name with link
+prsts='['+opprst+'s](#lprt)' # name with link (plural)
 prstt=opprst.capitalize # in title
 gemspec=Gem::Specification::load(ENV["GEMSPEC"]) or raise "error loading #{ENV["GEMSPEC"]}"
 geminstadd=gemspec.version.to_s.match(/\.[^0-9]/)?' --pre':''
 $LOAD_PATH.unshift(ENV["INCL_DIR_GEM"])
 require 'aspera/fasp/parameters'
 def spec_table
-    r='<table><tr><th>Field</th><th>Type</th>'
-    Aspera::Fasp::Parameters::SUPPORTED_AGENTS_SHORT.each do |c|
+  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>'
@@ -36,9 +36,9 @@ def spec_table
     end
     r << '</table>'
     return r
-end
+end #```
 -%>
-# <%=tool%> : Command Line Interface for IBM Aspera products
+<font size="+12"><center><%=tool%> : Command Line Interface for IBM Aspera products</center></font>
 
 Version : <%= gemspec.version.to_s %>
 
@@ -52,7 +52,7 @@ Ruby Gem: [<%= gemspec.metadata['rubygems_uri'] %>](<%= gemspec.metadata['rubyge
 
 Ruby Doc: [<%= gemspec.metadata['documentation_uri'] %>](<%= gemspec.metadata['documentation_uri'] %>)
 
-Ruby version must be >= <%= gemspec.required_ruby_version %>
+Required Ruby version: <%= gemspec.required_ruby_version %>
 
 # <a name="when_to_use"></a>When to use and when not to use
 
@@ -68,7 +68,8 @@ So it is designed for:
 
 <%=tool%> can be seen as a command line tool integrating:
 
-* a configuration file (config.yaml) and advanced command line options
+* a configuration file (config.yaml)
+* advanced command line options
 * cURL (for REST calls)
 * Aspera transfer (ascp)
 
@@ -190,7 +191,7 @@ It is possible to install *either* directly on the host operating system (Linux,
 
 The direct installation is recommended and consists in installing:
 
-* [Ruby](#ruby) version >= <%= gemspec.required_ruby_version %>
+* [Ruby](#ruby) version <%= gemspec.required_ruby_version %>
 * [<%= gemspec.name %>](#the_gem)
 * [Aspera SDK (ascp)](#fasp_prot)
 
@@ -238,7 +239,7 @@ Use this method to install on the native host.
 
 A ruby interpreter is required to run the tool or to use the gem and tool.
 
-Ruby minimum version: <%= gemspec.required_ruby_version %>. Ruby version 3 is also supported.
+Required Ruby version: <%= gemspec.required_ruby_version %>. Ruby version 3 is also supported.
 
 *Ruby can be installed using any method* : rpm, yum, dnf, rvm, brew, windows installer, ... .
 
@@ -246,7 +247,7 @@ Refer to the following sections for a proposed method for specific operating sys
 
 The recommended installation method is `rvm` for systems with "bash-like" shell (Linux, Macos, Windows with cygwin, etc...).
 If the generic install is not suitable (e.g. Windows, no cygwin), you can use one of OS-specific install method.
-If you have a simpler better way to install Ruby version >= <%= gemspec.required_ruby_version %> : use it !
+If you have a simpler better way to install Ruby version <%= gemspec.required_ruby_version %> : use it !
 
 ### Generic: RVM: single user installation (not root)
 
@@ -1224,11 +1225,19 @@ The `transfer-info` accepts the following optional parameters:
 <tr><td>spawn_timeout_sec</td><td>Float</td><td>3</td><td>Multi session</td><td>Verification time that ascp is running</td></tr>
 <tr><td>spawn_delay_sec</td><td>Float</td><td>2</td><td>Multi session</td><td>Delay between startup of sessions</td></tr>
 <tr><td>wss</td><td>Bool</td><td>false</td><td>Web Socket Session</td><td>Enable use of web socket session in case it is available</td></tr>
+<tr><td>multi_incr_udp</td><td>Bool</td><td>true</td><td>Multi Session</td><td>Increment UDP port on multi-session<br/>If true, each session will have a different UDP port starting at `fasp_port` (or default 33001)<br/>Else, each session will use `fasp_port` (or `ascp` default)</td></tr>
 <tr><td>resume</td><td>Hash</td><td>nil</td><td>Resumer parameters</td><td>See below</td></tr>
 </table>
 
 Resume parameters:
 
+In case of transfer interruption, the agent will resume a transfer up to `iter_max` time.
+Sleep between iteration is:
+
+```
+max( sleep_max , sleep_initial * sleep_factor ^ (iter_index-1) )
+```
+
 <table>
 <tr><th>Name</th><th>Type</th><th>Default</th><th>Feature</th><th>Description</th></tr>
 <tr><td>iter_max</td><td>int</td><td>7</td><td>Resume</td><td>Max number of retry on error</td></tr>
@@ -1241,7 +1250,7 @@ Examples:
 
 ```
 $ <%=cmd%> ... --transfer-info=@json:'{"wss":true,"resume":{"iter_max":10}}'
-$ <%=cmd%> ... --transfer-info=@json:'{"spawn_delay_sec":2.5}'
+$ <%=cmd%> ... --transfer-info=@json:'{"spawn_delay_sec":2.5,"multi_incr_udp":false}'
 ```
 
 ### IBM Aspera Connect Client GUI
@@ -1543,7 +1552,7 @@ For this, specify the option: `--use-generic-client=no`.
 
 This will guide you through the steps to create.
 
-## <a name="aocwizard"></a>Configuration: using manual setup
+## <a name="aocmanual"></a>Configuration: using manual setup
 
 If you used the wizard (recommended): skip this section.
 
@@ -1807,10 +1816,10 @@ $ <%=cmd%> aoc admin res user list --query='@json:{"q":"dummyuser"}' --fields=id
 : 98398 : dummyuser1@example.com :
 : 98399 : dummyuser2@example.com :
 :.......:........................:
-$ thelist=$(echo $(<%=cmd%> aoc admin res user list --query='@json:{"q":"dummyuser"}' --fields=id,email --field=id --format=csv)|tr ' ' ,)
+$ thelist=$(<%=cmd%> aoc admin res user list --query='@json:{"q":"dummyuser"}' --fields=id --format=json --display=data|jq -cr 'map(.id)')
 $ echo $thelist
-98398,98399
-$ <%=cmd%> aoc admin res user --bulk=yes --id=@json:[$thelist] delete
+["113501","354061"]
+$ <%=cmd%> aoc admin res user --bulk=yes --id=@json:"$thelist" delete
 :.......:.........:
 :  id   : status  :
 :.......:.........:
@@ -1819,6 +1828,14 @@ $ <%=cmd%> aoc admin res user --bulk=yes --id=@json:[$thelist] delete
 :.......:.........:
 ```
 
+* <a name="deactuser"></a>Find deactivated users since more than 2 years
+
+```
+ascli aoc admin res user list --query=@ruby:'{"deactivated"=>true,"q"=>"last_login_at:<#{(DateTime.now.to_time.utc-2*365*86400).iso8601}"}'
+```
+
+To delete them use the same method as before
+
 * Display current user's workspaces
 
 ```
@@ -2214,7 +2231,37 @@ $ <%=cmd%> ats api_key create
 +--------+----------------------------------------------+
 $ <%=cmd%> config id my_ibm_ats update --ats-key=ats_XXXXXXXXXXXXXXXXXXXXXXXX --ats-secret=YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
 ```
+## Cross Organization transfers
+
+It is possible to transfer files directly between organizations without having to first download locally and then upload...
 
+Although optional, the creation of <%=prst%> is recommended to avoid placing all parameters in the command line.
+
+Procedure to send a file from org1 to org2:
+
+* Get access to Organization 1 and create a <%=prst%>: e.g. `org1`, for instance, use the [Wizard](#aocwizard)
+* Check that access works and locate the source file e.g. `mysourcefile`, e.g. using command `files browse`
+* Get access to Organization 2 and create a <%=prst%>: e.g. `org2`
+* Check that access works and locate the destination folder `mydestfolder`
+* execute the following:
+
+```
+$ <%=cmd%> -Porg1 aoc files node_info /mydestfolder --format=json --display=data | <%=cmd%> -Porg2 aoc files upload mysourcefile --transfer=node --transfer-info=@json:@stdin:
+```
+
+Explanation:
+
+* `-Porg1 aoc` use Aspera on Cloud plugin and load credentials for `org1`
+* `files node_info /mydestfolder` generate transfer information including node api credential and root id, suitable for the next command
+* `--format=json` format the output in JSON (instead of default text table)
+* `--display=data` display only the result, and remove other information, such as workspace name
+* `|` the standard output of the first command is fed into the second one
+* `-Porg2 aoc` use Aspera on Cloud plugin and load credentials for `org2`
+* `files upload mysourcefile` upload the file named `mysourcefile` (located in `org1`)
+* `--transfer=node` use transfer agent type `node` instead of default `direct`
+* `--transfer-info=@json:@stdin:` provide `node` transfer agent information, i.e. node API credentials, those are expected in JSON format and read from standard input
+
+Note that when using a POSIX shell, another possibility to write `cmd1 | cmd2 --transfer-info=@json:stdin:` is `cmd2 --transfer-info=@json:$(cmd1)` instead of ``
 ## Examples
 
 Example: create access key on softlayer:
@@ -2533,7 +2580,7 @@ $ <%=cmd%> faspex v4 dropbox list
 $ <%=cmd%> faspex v4 dropbox delete --id=36
 ```
 
-## remote sources
+## Remote sources
 
 Faspex lacks an API to list the contents of a remote source (available in web UI). To workaround this,
 the node API is used, for this it is required to add a section ":storage" that links
@@ -2584,29 +2631,38 @@ $ for p in 1 2 3;do <%=cmd%> shares2 admin users list --value=@json:'{"page":'$p
 # Plugin: IBM Cloud Object Storage
 
 The IBM Cloud Object Storage provides the possibility to execute transfers using FASP.
-It uses the same transfer service as Aspera on Cloud.
-see [https://status.aspera.io](https://status.aspera.io)
+It uses the same transfer service as Aspera on Cloud, called Aspera Transfer Service (ATS).
+Available ATS regions: [https://status.aspera.io](https://status.aspera.io)
+
+There are two possibilities to provide credentials. If you already have the endpoint, apikey and CRN, use the forst method. If you dont have credentials but have access to the IBM Cloud console, then use the second method.
+
+## Using endpoint, apikey and Ressource Instance ID (CRN)
 
-Required options are either:
+If you have those parameters already, then following options shall be provided:
 
 * `bucket` bucket name
 * `endpoint` storage endpoint url, e.g. https://s3.hkg02.cloud-object-storage.appdomain.cloud
 * `apikey` API Key
 * `crn` resource instance id
 
-or:
+For example, let us create a default configuration:
 
-* `bucket` bucket name
-* `region` bucket region, e.g. eu-de
-* `service_credentials` see below
+```
+$ <%=cmd%> conf id mycos update --bucket=mybucket --endpoint=https://s3.us-east.cloud-object-storage.appdomain.cloud --apikey=abcdefgh --crn=crn:v1:bluemix:public:iam-identity::a/xxxxxxx
+$ <%=cmd%> conf id default set cos mycos
+```
+
+Then, jump to the transfer example.
+
+## Using service credential file
 
-Service credentials are directly created using the IBM cloud web ui. Navigate to:
+If you are the COS administrator and dont have yet the credential: Service credentials are directly created using the IBM cloud web ui. Navigate to:
 
 Navigation Menu &rarr; Resource List &rarr; Storage &rarr; Cloud Object Storage &rarr; Service Credentials &rarr; &lt;select or create credentials&gt; &rarr; view credentials &rarr; copy
 
 Then save the copied value to a file, e.g. : `$HOME/cos_service_creds.json`
 
-or using the CLI:
+or using the IBM Cloud CLI:
 
 ```
 $ ibmcloud resource service-keys
@@ -2637,33 +2693,38 @@ The field `resource_instance_id` is for option `crn`
 
 The field `apikey` is for option `apikey`
 
-Endpoints for regions can be found by querying the `endpoints` URL.
+(If needed: endpoints for regions can be found by querying the `endpoints` URL.)
 
-For convenience, let us create a default configuration, for example:
+The required options for this method are:
+
+* `bucket` bucket name
+* `region` bucket region, e.g. eu-de
+* `service_credentials` see below
+
+For example, let us create a default configuration:
 
 ```
 $ <%=cmd%> conf id mycos update --bucket=laurent --service-credentials=@val:@json:@file:~/service_creds.json --region=us-south
 $ <%=cmd%> conf id default set cos mycos
 ```
 
-or using direct parameters:
+## Operations, transfers
 
-```
-$ <%=cmd%> conf id mycos update --bucket=mybucket --endpoint=https://s3.us-east.cloud-object-storage.appdomain.cloud --apikey=abcdefgh --crn=crn:v1:bluemix:public:iam-identity::a/xxxxxxx
-$ <%=cmd%> conf id default set cos mycos
-```
+Let's assume you created a default configuration from once of the two previous steps (else specify the access options on command lines).
 
-Now, Ready to do operations, a subset of "node" plugin operations are supported, basically node API:
+A subset of `node` plugin operations are supported, basically node API:
 
 ```
-$ <%=cmd%> cos node browse /
-$ <%=cmd%> cos node upload myfile.txt
+$ <%=cmd%> cos node info
+$ <%=cmd%> cos node upload 'faux:///sample1G?1g'
 ```
 
+Note: we generate a dummy file `sample1G` if size 2GB using the `faux` PVCL (man ascp), but you can of course send a real file by specifying a real file instead.
+
 # Plugin: IBM Aspera Sync
 
-A basic plugin to start an "async" using <%=tool%>. The main advantage is the possibility
-to start from ma configuration file, using <%=tool%> standard options.
+A basic plugin to start an "async" using <%=tool%>.
+The main advantage is the possibility to start from ma configuration file, using <%=tool%> standard options.
 
 # Plugin: Preview
 
@@ -3233,6 +3294,11 @@ So, it evolved into <%=tool%>:
 
 * <%= gemspec.version.to_s %>
 
+	* new: parameter `multi_incr_udp` for option `transfer_info`: control if UDP port is incremented when multi-session is used on `direct` transfer agent.
+	* new: command `aoc files node_info` to get node information for a given folder in the Files application of AoC. Allows cross-org or cross-workspace transfers.
+
+* 4.2.2
+
 	* new: `faspex package list` retrieves the whole list, not just first page
 	* new: support web based auth to aoc and faspex 5 using HTTPS, new dependency on gem `webrick`
 	* new: the error "Remote host is not who we expected" displays a special remediation message

data/docs/test_env.conf

@@ -156,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