Global

Type Definitions

AllTransfersInfo :Object

The data format for statistics for all existing transfers. See TransferInfo

Properties:
Name Type Default Description
iteration_token Number 0

A marker that represents the moment in time that the transfer status was retrieved. If it is passed as an argument to a AW4.Connect#getAllTransfers call, the response returned will only contain transfers that have had activity since the previous call. Note that this token persists even if the user restarts Connect.
result_count Number 0

The number of TransferInfo objects returned AllTransfersInfo.transfers.
transfers Array

An array that contains TransferInfo objects.
Example
{
 "iteration_token": 28,
 "result_count": 3,
 "transfers": [
   TransferInfo,
   TransferInfo,
   TransferInfo
  ]
}

AsperaConnectSettings :Object

The data format for the connect web app parameters.

Properties:
Name Type Description
app_id String

A secure, random identifier for all transfers associated with this webapp. Do not hardcode this id. Do not use the same id for different users. Do not including the host name, product name in the id. Do not use monotonically increasing ids. If you do not provide one, a random id will be generated for you and persisted in localStorage.
back_link String

Link to the webapp.
request_id String

Universally Unique IDentifier for the webapp.
Example
{
  "app_id": "TUyMGQyNDYtM2M1NS00YWRkLTg0MTMtOWQ2OTkxMjk5NGM4",
  "back_link": "http://demo.asperasoft.com",
  "request_id": "36d3c2a4-1856-47cf-9865-f8e3a8b47822"
}

ConnectSpec :Object

Connect-specific parameters when starting a transfer.

Properties:
Name Type Attributes Default Description
allow_dialogs Boolean <optional>
 true

If this value is false, Connect will no longer prompt or display windows automatically, except to ask the user to authorize transfers if the server is not on the list of trusted hosts.
back_link String <optional>
 URL of current page

A URL to associate with the transfer. Connect will display this link in the context menu of the transfer.
return_files Boolean <optional>
 true

If this value is false, TransferInfo will not contain files. Use this option to prevent performance deterioration when transferring large number of files.
return_paths Boolean <optional>
 true

If this value is false, the transfer_spec property in TransferInfo will not contain paths. Use this option to prevent performance deterioration when specifying a large number of source paths.
use_absolute_destination_path Boolean <optional>
 false

By default, the destination of a download is relative to the user's Connect download directory setting. Setting this value to true overrides this behavior, using absolute paths instead.
Example
{
  "allow_dialogs" : false,
  "back_link" : "www.foo.com",
  "return_paths" : false,
  "return_files" : false,
  "use_absolute_destination_path" : true
}

dataTransfer :Object

This object holds the data of the files that have been selected by the user. It may hold one or more data items.

Format

{
  "dataTransfer" : {
    "files": [
      {
        "lastModifiedDate": "Wed Jan 24 12:22:02 2019",
        "name": "/Users/aspera/Desktop/foo.txt",
        "size": 386,
        "type": "text/plain"
      },
      {
        "lastModifiedDate": "Mon Jan 22 18:01:02 2019",
        "name": "/Users/aspera/Desktop/foo.rb",
        "size": 609,
        "type": "text/x-ruby-script"
      }
    ]
  }
}

Error :Object

This object is returned if an error occurs. It contains an error code and a message.

Note that this is not related to the Javascript Error object, but is used only to document the format of errors returned by this API.

Example
{
  "error": {
    "code": Number,
    "internal_message": String,
    "user_message": String
  }
}

EVENT :Object

AW4.Connect.EVENT

Properties:
Name Type Default Description
ALL string "all"

all event
TRANSFER string "transfer"

transfer event
STATUS string "status"

status event
Example
AW4.Connect.EVENT.ALL // returns "all"
AW4.Connect.EVENT.STATUS // returns "status"
AW4.Connect.EVENT.TRANSFER // returns "transfer"

FileFilters :Object

A set of file extension filters.

Example

[
  {
    filter_name : "Text file",
    extensions : ["txt"]
  },
  {
    filter_name : "Image file",
    extensions : ["jpg", "png"]
  },
  {
    filter_name : "All types",
    extensions : ["*"]
  }
]

STATUS :Object

AW4.Connect.STATUS

Properties:
Name Type Default Description
INITIALIZING string "INITIALIZING"

initializing status event
RETRYING string "RETRYING"

retrying status event
RUNNING string "RUNNING"

running status event
OUTDATED string "OUTDATED"

outdated status event
FAILED string "FAILED"

failed status event
EXTENSION_INSTALL string "EXTENSION_INSTALL"

extension install event type
Example
AW4.Connect.STATUS.INITIALIZING // returns "INITIALIZING"
AW4.Connect.STATUS.RETRYING // returns "RETRYING"
// etc...

TRANSFER_STATUS :Object

AW4.Connect.TRANSFER_STATUS

The possible states of a transfer reported bystatus in TransferInfo.

Properties:
Name Type Default Description
CANCELLED String "cancelled"

The user stopped the transfer.
COMPLETED String "completed"

The transfer finished successfully.
FAILED String "failed"

The transfer had an error.
INITIATING String "initiating"

The transfer reqeust was accepted. Now starting transfer.
QUEUED String "queued"

The transfer is waiting for other transfers to finish. The queue is configurable in Connect.
REMOVED String "removed"

The user deleted the transfer.
RUNNING String "running"

Transfer in progress.
WILLRETRY String "willretry"

Transfer waiting to retry after a recoverable error.

TransferInfo :Object

The data format for statistics for on transfer session.

See TransferSpec and AsperaConnectSettings for definitions.

Properties:
Name Type Default Description
add_time String

The time when the transfer was added (according to the system's clock).
aspera_connect_settings Object

AsperaConnectSettings
bytes_expected Number

The number of bytes that are still remaining to be written.
bytes_written Number

The number of bytes that have already been written to disk.
calculated_rate_kbps Number

The current rate of the transfer in kbps.
current_file String

The full path of the current file.
elapsed_usec Number

The duration in microseconds of the transfer since it started transferring.
explorer_path String

The path opened in Explorer/Finder when user clicks 'Open Containing Folder' in Connect's Activity window.
end_time String

The time when the transfer was completed.
file_counts Object

A running aggregate count of files in the transfer session that have already been processed with information about the number of files attempted, completed, failed, and skipped. Note: "completed" includes the number of files transferred or skipped.

Format:

{
  "attempted": 2,
  "completed": 2,
  "failed": 0,
  "skipped": 1
}
files Array

A list of files that have been active in this transfer session. Note that files that have not been active yet in this session will not be reported (and you can assume bytes_written is 0).

Format:

[
  {
    "bytes_expected": 10485760,
    "bytes_written": 1523456,
    "fasp_file_id": "3c40b511-5b2dfebb-a2e63483-9b58cb45-9cd9abff",
    "file": "/Users/aspera/Downloads/connect_downloads/10MB.3"
  }, {
    "bytes_expected": 10485760,
    "bytes_written": 10485760,
    "fasp_file_id": "d5b7deea-2d5878f4-222661f6-170ce0f2-68880a6c",
    "file": "/Users/aspera/Downloads/connect_downloads/10MB.2"
  }
]
modify_time String

The last time the transfer was modified
percentage Number

The progress of the transfer over 1.
previous_status String

The previous status of the transfer.
remaining_usec Number

The ETA of the transfer in microseconds.
start_time String

The time when the transfer moved to initiating status.
status String

The status of the transfer. See TRANSFER_STATUS.
title String

The name of the file.
transfer_iteration_token Number

A marker that represents the moment in time that the transfer status was checked.
transfer_spec Object

TransferSpec
transport "fasp" | "http" "fasp"

fasp - (default)
http - Set when a fasp transfer could not be performed and http fallback was used.
uuid String
Example
{
      "add_time": "2012-10-05T17:53:16",
      "aspera_connect_settings": AsperaConnectSettings,
      "bytes_expected": 102400,
      "bytes_written": 11616,
      "calculated_rate_kbps": 34,
      "current_file": "/temp/tinyfile0001",
      "elapsed_usec": 3000000,
      "explorer_path": "/Users/aspera/Downloads/connect_downloads/10MB.3",
      "end_time": "",
      "file_counts": {
          "attempted": 1,
          "completed": 1,
          "failed": 0,
          "skipped": 1
      },
      "files": [
         {
           "bytes_expected": 10485760,
           "bytes_written": 1523456,
           "fasp_file_id": "3c40b511-5b2dfebb-a2e63483-9b58cb45-9cd9abff",
           "file": "/Users/aspera/Downloads/connect_downloads/10MB.3"
         }, {
           "bytes_expected": 10485760,
           "bytes_written": 10485760,
           "fasp_file_id": "d5b7deea-2d5878f4-222661f6-170ce0f2-68880a6c",
           "file": "/Users/aspera/Downloads/connect_downloads/10MB.2"
         }
      ],
      "modify_time": "2012-10-05T17:53:18",
      "percentage": 0.113438,
      "previous_status": "initiating",
      "remaining_usec": 21000000,
      "start_time": "2012-10-05T17:53:16",
      "status": "running",
      "title": "tinyfile0001",
      "transfer_iteration_token": 18,
      "transfer_spec": TransferSpec,
      "transport": "fasp",
      "uuid": "add433a8-c99b-4e3a-8fc0-4c7a24284ada",
    }

TransferSpec :Object

The parameters for starting a transfer.

Properties:
Name Type Attributes Default Description
authentication "password" | "token" <optional>
 "password"

The type of authentication to use.
cipher "none" | "aes-128" <optional>
 "aes-128"

The algorithm used to encrypt data sent during a transfer. Use this option when transmitting sensitive data. Increases CPU utilization.
content_protection "encrypt" | "decrypt" <optional>

Enable content protection (encryption-at-rest), which keeps files encrypted on the server. Encrypted files have the extension ".aspera-env".

encrypt - Encrypt uploaded files. If content_protection_passphrase is not specified, Connect will prompt for the passphrase.

decrypt - Decrypt downloaded fiels. If content_protection_passphrase is not specified, Connect will prompt for the passphrase.
content_protection_passphrase String <optional>

A passphrase to encrypt or decrypt files when using content_protection.
cookie String <optional>

Data to associate with the transfer. The cookie is reported to both client and server-side applications monitoring fasp™ transfers. It is often used by applications to identify associated transfers.
create_dir Boolean <optional>
 false

Creates the destination directory if it does not already exist. When enabling this option, the destination path is assumed to be a directory path.
obfuscate_file_names Boolean <optional>
 false

If this value is true, Connect will obfuscate all filenames. All files will be renamed to have random names. Applies only to uploads. This is not reversible.
destination_root String <optional>
 "/"

The transfer destination file path. If destinations are specified in paths, this value is prepended to each destination.

Note that the download destination paths are relative to the user's Connect download directory setting unless ConnectSpec.use_absolute_destination_path is enabled.
dgram_size Number <optional>

The IP datagram size for fasp™ to use. If not specified, fasp™ will automatically detect and use the path MTU as the datagram size. Use this option only to satisfy networks with strict MTU requirements.
direction "send" | "receive"

Whether to perform an upload or download.

send - Upload
receive - Download
fasp_port Number <optional>
 33001

The UDP port for fasp™ to use. The default value is satisfactory for most situations. However, it can be changed to satisfy firewall requirements.
http_fallback Boolean <optional>
 false

Attempts to perform an HTTP transfer if a fasp™ transfer cannot be performed.
http_fallback_port Number <optional>

The port where the Aspera HTTP server is servicing HTTP transfers. Defaults to port 443 if a cipher is enabled, or port 80 otherwise.
lock_min_rate Boolean <optional>
 false

Prevents the user from changing the minimum rate during a transfer.
lock_rate_policy Boolean <optional>
 false

Prevents the user from changing the rate policy during a transfer.
lock_target_rate Boolean <optional>
 false

Prevents the user from changing the target rate during a transfer.
min_rate_kbps Number <optional>

The minimum speed of the transfer. fasp™ will only share bandwidth exceeding this value.

Note: This value has no effect if rate_policy is fixed.

Default: Server-side minimum rate default setting (aspera.conf). Will respect both local and server-side minimum rate caps if set.
overwrite_policy "always" | "none" | "diff" | "older" | "diff+older" <optional>
 "diff"

Overwrite destination files with the source files of the same name.

none - Never overwrite the file. However, if the parent folder is not empty, its access, modify, and change times may still be updated.

always - Always overwrite the file. The destination file will be overwritten even if it is identical to the source.

diff - Overwrite the file if it is different from the source, depending on the resume property.

older - Overwrite the file if its timestamp is older than the source timestamp.

diff+older - Overwrite the file if it is older and different than the source, depending on the resume property.

If the overwrite_policy is diff or diff+older, difference is determined by the resume property. If resume is empty or none is specified, the source and destination files are always considered different and the destination file is always overwritten. If attributes, the source and destination files are compared based on file attributes (currently file size). If sparse_checksum, the source and destination files are compared based on sparse checksum. If full_checksum, the source and destination files are compared based on full checksum.
paths Array

A list of the file and directory paths to transfer. Use destination_root to specify the destination directory.

Source list format

  [
    {
      "source": "/foo"
    }, {
      "source": "/bar/baz"
    },
    ...
  ]

Optionally specify a destination path - including the file name - for each file. This format is useful for renaming files or sending to different destinations. Note that for this format all paths must be file paths (not directory paths).

Source-Destination pair format

  [
    {
      "source": "/foo",
      "destination": "/qux/foofoo"
    }, {
      "source": "/bar/baz",
      "destination": "/qux/bazbaz"
    },
    ...
  ]
rate_policy "fixed" | "high" | "fair" | "low" <optional>
 "fair"

The congestion control behavior to use when sharing bandwidth.

fixed - Transfer at the target rate regardless of actual network capacity. Do not share bandwidth.

high - When sharing bandwidth, transfer at twice the rate of a transfer using "fair" policy.

fair - Share bandwidth equally with other traffic.

low - Use only unutilized bandwidth.
remote_host String

The fully qualified domain name or IP address of the transfer server.
remote_password String <optional>

The password to use when authentication is set to password. If this value is not specified, Connect will prompt the user.
remote_user String <optional>

The username to use for authentication. For password authentication, if this value is not specified, Connect will prompt the user.
resume "none" | "attributes" | "sparse_checksum" | "full_checksum" <optional>
 "sparse_checksum"

The policy to use when resuming partially transferred (incomplete) files.

none - Transfer the entire file again.

attributes - Resume if the files' attributes match.

sparse_checksum - Resume if the files' attributes and sparse (fast) checksums match.

full_checksum - Resume if the files' attributes and full checksums match. Note that computing full checksums of large files takes time, and heavily utilizes the CPU.
save-before-overwrite "yes" | "no" <optional>
 "no"

If a transfer would result in an existing file being overwritten, move that file to <filename>.yyyy.mm.dd.hh.mm.ss.index.<ext> in the same directory before writing the new file. File attributes are maintained in the renamed file.

Note: resume must be set to "none" for this to take effect.
source_root String <optional>
 "/"

A path to prepend to the source paths specified in paths. If this is not specified, then paths should contain absolute paths.
ssh_port Number <optional>
 33001

The server's TCP port that is listening for SSH connections. fasp™ initiates transfers through SSH.
target_rate_cap_kbps Number <optional>

Limit the transfer rate that the user can adjust the target and minimum rates to. Default: no limit.
target_rate_kbps Number <optional>

The desired speed of the transfer. If there is competing network traffic, fasp™ may share this bandwidth, depending on the rate_policy.

Default: Server-side target rate default setting (aspera.conf). Will respect both local and server-side target rate caps if set.
token String <optional>

Used for token-based authorization, which involves the server-side application generating a token that gives the client rights to transfer a predetermined set of files.
Example
##### Minimal example
{
  "paths": [
    {
      "source": "/foo/1"
    }
  ],
  "remote_host": "10.0.203.80",
  "remote_user": "aspera",
  "direction": "send"
}

##### Download example
{
  "paths": [
    {
      "source": "tinyfile0001"
    }, {
      "source": "tinyfile0002"
    }
  ],
  "obfuscate_file_names": false,
  "overwrite_policy": "diff",
  "remote_host": "demo.asperasoft.com",
  "remote_user": "asperaweb",
  "authentication": "password",
  "remote_password": "**********",
  "fasp_port": 33001,
  "ssh_port": 33001,
  "http_fallback": true,
  "http_fallback_port": 443,
  "direction": "receive",
  "create_dir": false,
  "source_root": "aspera-test-dir-tiny",
  "destination_root": "/temp",
  "rate_policy": "high",
  "target_rate_kbps": 1000,
  "min_rate_kbps": 100,
  "lock_rate_policy": false,
  "target_rate_cap_kbps": 2000,
  "lock_target_rate": false,
  "lock_min_rate": false,
  "resume": "sparse_checksum",
  "cipher": "aes-128",
  "cookie": "foobarbazqux",
  "dgram_size": 1492,
  "preserve_times": true,
  "tags": {
    "your_company": {
      "key": "value"
    }
  }
}

TransferSpecs :Object

The response returned to the AW4.Connect#startTransfer success callback.

Properties:
Name Type Description
transfer_specs Array

An array that contains TransferSpec and ConnectSpec objects.
Example
{
 "transfer_specs": [
    {
       "transfer_spec": TransferSpec,
       "aspera_connect_settings": ConnectSpec
    }
  ]
}