Usage examples

CLI examples

Upload a single file to a workspace

Upload a single file to a workspace on the elements machine at /data/snfs1/.projects/test-production/test-workspace/:

elements-http-upload -t <api-token> -H https://<elements-host> \\
  my-test-file:/data/snfs1/.projects/test-production/test-workspace/

The API token can be obtained on your profile page of your elements installation, the host is the domain of your elements installation (e.g. hcdc-mams.hereon.de). If you omit the file name in the remote location (such as in this case), the file name of the local file (here my-test-file) will be used. Note that the trailing slash is important in this case

Upload multiple files to the same directory

Upload multiple files to the same directory with the [-d]{.title-ref} option:

elements-http-upload -t <api-token> -H https://<elements-host> \\
  -d /data/snfs1/.projects/test-production/test-workspace/ \\
  my-first-test-file my-second-test-file

The -d option (or --target-root) allows you to avoid repeating the root in the remote elements installation. You can also still use relative paths for the REMOTE-DEST which will then be prefixed by the target root:

elements-http-upload -t <api-token> -H https://<elements-host> \\
  -d /data/snfs1/.projects/test-production/test-workspace/ \\
  my-first-test-file:target-folder-1/ \\
  my-second-test-file:target-folder-2/my-second-test-file-remote

Upload an entire directory

Upload an entire directory with -r:

elements-http-upload -r -t <api-token> -H https://<elements-host> \\
    local-folder:/data/snfs1/.projects/test-production/test-workspace/remote-folder

Python API usage example

You can also directly call the upload() function to upload the files from within python. This function takes the files to upload and the connection settings and performs the update.

The arguments to this functions can be strings as in the CLI demo above, or a dictionary with source and target being set. The keyword arguments are what is suitble for the elements_http_upload.models.UploadSettings model (i.e. including everything from the elements_http_upload.models.ConnectionSettings model). Here is an example uploading two files, one configured as a string and one configured as a dictionary:

from elements_http_upload import upload

source_target_str = "my-test-file:/data/snfs1/.projects/test-production/test-workspace/my-test-file"
source_target_dict = {
    "source": "my-test-file2",
    "target": "/data/snfs1/.projects/test-production/test-workspace/my-test-file2",
}

upload(
    source_target_str,
    source_target_dict,
    host="https://<elements-host>",
    api_token="<api-token>",
    silent=True,  # prevents the progress bar
)

Configuration

In the examples above we set the token and host explicitly via the command line/script. You can however configure these settings also using environment variables. The UploadSettings and elements_http_upload.models.ConnectionSettings models are configured as such. You just have to prefix the attribute with ELEMENTS_UPLOAD_. So setting the environment variable ELEMENTS_UPLOAD_TOKEN is the same as using the -t option, or in other words

ELEMENTS_UPLOAD_TOKEN=<api-token> ELEMENTS_UPLOAD_HOST=https://<elements-host> \\
  elements-http-upload -d /data/snfs1/.projects/test-production/test-workspace/ \\
  my-first-test-file:target-folder-1/

is the same as

elements-http-upload -t <api-token> -H https://<elements-host> \\
  -d /data/snfs1/.projects/test-production/test-workspace/ \\
  my-first-test-file:target-folder-1/