Overview

SOAP Web Services

The Aspera Web Services Interface is a key component of all Aspera Servers and Point to Point Products.  The Web Service Interface allows other applications, local or over a network; to initiate, monitor and control transfers. You can learn more about SOAP Web Services by viewing the Introduction video. These tasks can easily be accomplished and this section will explain how to complete these tasks. An overview of these Web Services is shown below:

  • Initiating Transfers can be accomplished by simply submitting an XML string describing the transfer parameters.
  • Monitoring Transfers can be accomplished in a local or remote application that can subscribe for all events or specific ones as defined by the developer. The topics available to subscribe to include: session start, stop, status, error.  Your application will receive notifications in the form of a Web Service call with the requested data.  If you prefer you can also submit a query for current status.
  • Controlling Current Transfers can be accomplished by resubmitting parameters with your new configuration or sending a pause, resume or cancel command.

The Aspera Web Services Interface is comprised of three main web services:

  • JobNet which allows the initiation of FASP transfers.
  • IScpTransferNet which provides job level event notifications and supports querying for job level statistics, where a 'job' represents a transfer task that was requested by the user.
  • FASPSessionNet which provides session level event notifications and querying for session level statistics, where a 'session' represents an actual FASP transfer instance.

It is important to note that a job starts a session which transfers the files and if a session encounters an error and stops the same job will start a second session to get the files transferred.

The asperacentral service provides the SOAP based API's. By default the service runs in the background as a daemon. For debugging purposes, you may run the service in "no-daemon" mode and print out the logs to the console. On Linux you can stop the asperacentral service with the following command:

/etc/init.d/asperacentral stop

To start the service in "no-daemon" mode for debugging you can run the following command:

/etc/init.d/asperacentral --no-daemon -DDD -L-

To help demonstrate this flow of events a detailed diagram is seen below:

soap diagram

 


Overview

Monitor Jobs that your Program Initiated

When your application initiates an Aspera transfer you may also want to monitor the status of these transfers.  This can be accomplished by:

  1. Implementing a Job Observer service, a Session Observer service and subscribing to event notifications for all transfer jobs using the IScpTransferNET::Subscribe method and the FASPSessionNet::Subscribe method for Sessions. This must be done before submitting the Job Order so you do not miss any notifications that occur immediately at start.
  2. Submitting the Job Order using the JobNET::Submit method.  Your program's Job Observer will receive a job event of 'Connecting' after you submit the Job Order. This event will contain the Session ID of the transfer session that has been started.  This session ID will be included in all session status information received by your application.
  3. If your program needs to display the current progress of an ongoing transfer session you can simply query the session using FASPSessionNet::QuerySession. You could also include the 'Statistics' tag in the Topics for the subscription, but if you use this method the notifications may be too verbose as statistics are sent every second.

Monitor Transfers Initiated by Remote Clients

If your application needs to monitor an Aspera transfer that was initiated by a remote client you will need to use the FASPSessionNet service to register for status events and to query the sessions.  The following steps are used for a server monitoring application:

  1. Implement a Session Observer service and subscribe to it for event notifications for all FASP Sessions using the FASPSessionNet::Subscribe method.
  2. Retrieve the list of Sessions IDs for all ongoing FASP sessions using FASPSessionNet::ListSessions and store their state.
  3. By doing this you will receive FASP Session events when new sessions are created or when the status of ongoing sessions change.  You can update your records accordingly with this data to allow your application to have current data.
  4. If you require progress statistics for any FASP Sessions you can query the FASP Session directly using FASPSessionNet::QuerySession.  If you are writing both the client and server side monitoring program you can simply identify client transfers in the server monitoring program by having your client program store unique identifying information in the ApplicationData cookie.

Server Architecture

Aspera Central provides a server side component that can be used for tracking and controlling FASP transfers.  Transfer requests are initiated, authenticated, and secured via a SSH server. Once the initiation is complete the data transfer can be monitored through the SOAP Interface that is provided by Aspera Central.  You can have web applications integrate with Aspera Central to provide the required backend functionality needed for your application.  If you need to monitor network bandwidth and transfer progress you can utilize any network monitoring tool you prefer.  An example of a normal Server architecture is seen below.

soap arch 

 


Security

SOAP Web Services can be accessed securely using HTTP basic authentication. This is possible by using the Node API which requires that all requests be user authenticated.  If you wish to add additional levels of security you can have the HTTP requests sent over a SSL/TLS transport, which allows you to implement a secure application using existing technologies.  All operations available using http://server:40001/services/soap can be securely consumed through http://server:9091/services/soap and https://server:9092/services/soap with HTTP basic authentication.  In order to use the Node API you will first need to configure Node in the Aspera Server and add a Node User.  For more information on how to setup Node, please read the Node Documentation.

Example Call

A normal command to list all the job types supported by the Aspera Server would be:

curl -k -i --basic -u "nodeadmin:aspera" -H "Content-Type: text/xml;charset=UTF-8" -H "SOAPAction:JobNET-200601#ListTypes" -d "<?xml version=\"1.0\" encoding=\"UTF-8\"?><soapenv:Envelope xmlns:soapenv=\"http://schemas.xmlsoap.org/soap/envelope/\"><soapenv:Header></soapenv:Header><soapenv:Body><ns1:ListTypesRequest xmlns:ns1=\"urn:Aspera:XML:JobNET:2006/01:Types\"></ns1:ListTypesRequest></soapenv:Body></soapenv:Envelope>" -X POST "https://10.20.103.134:9092/services/soap/JobNET-200601"

In the above command, the request is being authenticated using basic HTTP and SSL.  It should be noted that the curl option -k disables certificate validation and is done for demonstration.  The SOAP envelope being used in the above call is seen below:

 

If the request is successful you will get the following response:

 

Code Example

Download Full Example

To illustrate this concept you can download the Java Sample code using the link above.  This sample demonstrates how to implement a simple interface to securely consume Aspera SOAP Web Services.  This includes the interface com.aspera.webservices.model.AsperaWebSOAPServices, which exposes various operations offered by the Aspera SOAP Web Services API.  The goal of this example is to provide two distinct implementations of the interface:

  • Using standard Aspera Central SOAP endpoints (http://server:40001/services/soap)
  • Using the Node API endpoints (https://server:9092/services/soap)

Both implementations share the code for operation calls and differ only in the way the services are created.  For example, in order to call the method the interface relays the call to the appropriate service endpoint, which will then send the SOAP request to the server.  For example,

AsperaWebSOAPServices client = ...client.listSupportedJobTypes();

In Java this command would be implemented with:

ListTypesRequest req = new ListTypesRequest();m_JobService.listTypes(req);

 


Service Messages

Session Related Service Messages

SetRateParameters

void SetRateParameters( xsd:string SessionID, asfx:RateParametersType RateParameters ) 

Sets the rate parameters of a FASP session.

Parameters

  • SessionID: An identifier of the FASP session being modified.
  • RateParameters: Rate parameters to assign to the FASP session.

Faults

  • asf:SessionNotFoundFault

SOAP Action

  • FASPSessionNET-200601#SetRateParameters

SetPolicy

void SetPolicy( xsd:string SessionID, xsd:string Policy ) 

Sets the rate parameters of a FASP session. Valid values for the Policy argument are Fixed, Fair, and Trickle.

Parameters

  • SessionID: An identifier of the FASP session being modified.
  • Policy: Rate policy to assign to the FASP session.

Faults

  • asf:SessionNotFoundFault

SOAP Action

  • FASPSessionNET-200601#SetPolicy

SetTargetRate

void SetTargetRate( xsd:string SessionID, xsd:unsignedInt TargetRate ) 

Sets the target rate of a FASP session.

Parameters

  • SessionID: An identifier of the FASP session being modified.
  • TargetRate: Target rate, in Kbps, to assign to the FASP session.

Faults

  • asf:SessionNotFoundFault

SOAP Action

  • FASPSessionNET-200601#SetTargetRate

SetMinimumRate

void SetMinimumRate( xsd:string SessionID, xsd:unsignedInt MinimumRate ) 

Sets the minimum rate of a FASP session.

Parameters

  • SessionID: An identifier of the FASP session being modified.
  • MinimumRate: Minimum rate, in Kbps, to assign to the FASP session.

Faults

  • asf:SessionNotFoundFault

SOAP Action

  • FASPSessionNET-200601#SetMinimumRate

SetBandwidthCap

void SetBandwidthCap( xsd:string SessionID, xsd:unsignedInt BandwidthCap ) 

Sets the bandwidth cap of a FASP session.

Parameters

  • SessionID: An identifier of the FASP session being modified.
  • BandwidthCap: Bandwidth cap, in Kbps, to assign to the FASP session.

Faults

  • asf:SessionNotFoundFault

SOAP Action

  • FASPSessionNET-200601#SetBandwidthCap

Job Related Service Messages

ListJobs

ArrayOf xsd:string ListJobs()

List the active Aspera.IScpTransfer jobs.

Return

  • An array of job IDs.

SOAP Action

  • IScpTransferNET-200604#ListJobs

CancelJob

void CancelJob( xsd:string JobID )

Cancels an Aspera.IScpTransfer job.

Parameters

  • JobID: An identifier of the job to cancel.

Faults

  • iscp:JobNotFoundFault

SOAP Action

  • IScpTransferNET-200604#Cancel

 


Consolidated Web Services

A new SOAP service interface has been released that consolidates all non-deprecated operations of the existing SOAP Web Service Interfaces (Job Submissions, Job Monitoring, and Observer and Session Management) into a coherent and single full feature web service interface.  The Transfer service allows an application to:

  • Query for supported job types
  • Submit transfer job instructions for execution by Aspera Central
  • Get the identifiers of all the jobs
  • Cancel transfer jobs
  • Reliably query for transfer sessions
  • Modify the rate parameters of transfer sessions
  • Cancel transfer session.

This service can be found at http://serveraddress:40001/services/soap/Transfer-201210.

Job Operations

List Job Types

  • operation: ListTypes
  • soapAction: JobNET-200601#ListTypes

Submit Job

  • operation: Submit
  • soapAction: JobNET-200601#Submit

List Jobs

  • operation: ListJobs
  • soapAction: IScpTransferNET-200604#ListJobs

Cancel Job

  • operation: CancelJob
  • soapAction: IScpTransferNET-200604#Cancel

Session Operations

Modify Rate Parameters

Operation SOAPAction
SetRateParameters FASPSessionNET-200601#SetRateParameters
SetPolicy FASPSessionNET-200601#SetPolicy
SetTargetRate FASPSessionNET-200601#SetTargetRate
SetMinimumRate FASPSessionNET-200601#SetBandwidthCap
SetBandwidthCap FASPSessionNET-200601#SetBandwidthCap

Cancel Session

  • operation: CancelSession
  • soapAction: FASPSessionNET-200601#Cancel

Reliable Session Monitoring

Reliable Query

Operation SOAPAction
GetSessions FASPSessionNET-200911#GetSessions
GetSessionInfo FASPSessionNET-200911#GetSessionInfo
GetSessionStatistics FASPSessionNET-200911#GetSessionStatistics
GetFileTransfers FASPSessionNET-200911#GetFileTransfers
GetFileTransferInfo FASPSessionNET-200911#GetFileTransferInfo
GetFileTransferStatistics FASPSessionNET-200911#GetFileTransferStatistics
GetInfo FASPSessionNET-200911#GetInfo
GetStatistics FASPSessionNET-200911#GetStatistics

Additional Operations

Additional Operations that are included in the new Transfer Web Service can be found in the sub sections of each consolidated service found on the left bar.  Each of these services contain the full list of operations that are available to them and are included in this consolidated web service.

WSDL File

Below is an example of the WSDL file that describes the services and its data type.

 Download WSDL File

 

 


Validate Job Order

Paste the XML for the job order that you want to validate and click the Validate button.

Validate Job Order

 


Job Submission

Job Submission

The SOAP Web Service JobNET-200601 allows an application to query for supported job types and submit job instructions for execution.  This Web Service is normally found at the following location: http://127.0.0.1:40001/services/soap/JobNET-200601. The actual host and port will vary for each deployment, however, the path is the normal location that provides the implementation of this service on all instances of Aspera Central. Each deployed instance of Aspera Central may have a different set of job modules installed; this can cause each instance to have different capabilities. You can invoke ListTypes() to determine what job types are available on any given instance of Aspera Central. Once you know the capabilities of the system you can submit instructions for execution by invoking Submit().

 


Service Messages

This section includes a list of SOAP Service Messages available including their arguments and return values.

ListTypes

ArrayOf xsd:string ListTypes()

List the supported job types. It should be noted that jobs are installed as Aspera Central Modules and are loaded at run time, this means that different instances can have different capabilities.

Return

  • An array of job types.

SOAP Action

  • JobNET-200601#ListTypes

Submit

asjx:JobResultType Submit( xsd:string Type, xsd:string Definition )

Submits a job request. The payload of the Definition argument will vary depending on the value of type. The type indicates what job module will handle the job request.

Parameters

  • Type: An identifier that indicates the type of job being submitted.
  • Definition: A set of instructions that indicate the operations to be performed during job execution.

Return

  • A job result.

Faults

  • asj:JobTypeNotFoundFault
  • asj:JobFormatInvalidFault
  • asj:JobSubmissionErrorFault

SOAP Action

  • JobNET-200601#Submit

 


Data Types

This section includes information on the data types that are defined by the XML schema.

Namespaces

The XML namespaces below are declared and used within the JobNET-200601 SOAP Web Service.

xsd http://www.w3.org/2001/XMLSchema 
wsdl http://schemas.xmlsoap.org/wsdl/ 
soap http://schemas.xmlsoap.org/wsdl/soap/  
asj http://www.asperasoft.com/xml/job-net/2006/01/JobNET.wsdl 
asjx urn:Aspera:XML:JobNET:2006/01:Types

Types

<asjx:jobresulttype>

Contains information indicating the result of a job submission.

Elements

  • xsd:string Type - The job type.
  • xsd:string ID - An identifier assigned to the job instance.

Faults

<asjx:JobTypeNotFoundFaultType>

A fault indicating that the requested job type was not found.

Elements

  • xsd:string Type - The job type.
<asjx:JobFormatInvalidFaultType>

A fault indicating that the format of the job instructions is incorrect.

Elements

  • xsd:string Detail - Additional details about the fault.
<asjx:JobSubmissionErrorFaultType>

A fault indicating that an error was encountered while attempting to submit the job.

Elements

  • xsd:string Detail - Additional details about the fault.

 


WSDL File

The Job.wsdl file demonstrates an example binding to http://127.0.0.1:40001/services/soap/JobNET-200601.  This file comprises the service that is used for code generation by the Web Service framework.  To use this file you must change the soap:address flag, which is located at the bottom of the file.

 Download WSDL File

 

 


Job Definitions

The data types that are described in this section are used in the XML order description format for Aspera.IScpTransfer Job Types.

Job Order Description (Parameters)

Version The current version is 2.  string
Agent Identifies the agent responsible for submitting the job. It is recommended that it takes the form of Company.Application, such as Aspera.AsperaConnect.  string
Operation Specifies the transfer operation to perform, i.e. download or upload. When set to Pull, files will be downloaded from the remote location to the local location. When set to Push, files will be uploaded from the local location to the remote location.

string.

Possible values: {'Pull', 'Push'}

ApplicationData Application-level data that will be carried by a fasp session.
 
Cookie An arbitrary field used for application-specific requirements. This field can be used as a placeholder for a unique reference. The difference with PrivateData Key is that the Cookie is known to both the local (Client) and the remote (Server), while the PrivateData Key is known to the local (Client). string
Token This field is used for token-based authorization. string

 

RemoteLocation Identifies the remote endpoint and file locations involved in the transfer.
 
System Identifies a system on the network.
 
Address IP address or host name of the system. string
Port SSH port over which the transfer will be initiated.

unsignedShort.

Default 22

UserName A user name used to authenticate on the system. string
Password A password used to authenticate on the system. string
Authentication Specifies the parameters used to authenticate on the remote system. When using SSH key authentication, make sure that the key file on the node is not a shared key. On the node computer, the key file should be a "private" key in the specified user account.
 
Methods SSH methods to use for authentication
 
Method Specifies the authentication mechanism. A single or up to 3 instances of the Method elements can be nested in the Methods element.

Possible values: {'Public Key'|'Password'|'Token'}

KeyPath The path to SSH key if Public key authentication method is used
KeyPassphrase A string denoting the passphrase for the key
Files Paths to the transfer contents on the remote host.
 
Path A transfer file path. For user name with document root path configured, the path must expressed relative to the user document root path.
A single or many instances of the Path elements can be nested in the Files element.
string

 

 

RootPath string. Path prefix (since version 3.3).
Proxy If this parameter is defined, the transfer will use fasp-proxy. Specifies the Destination Network Address Translation (DNAT or secure DNAT) parameters to use a fasp-proxy for the transfer: user name, password and proxy URL.
 
Url string. Specifies the address of the Aspera high-speed proxy server in the form of: dnat(s)://[user[:password]@]server[:port]. Default ports for DNAT and DNATS protocols are 9091 and 9092. 
User string. Not needed if the Url element contains the user name.
Password string. Not needed if the Url element contains the password.
HttpFallback This parameter defines HTTP fallback support for the transfer (since 3.5.4).
 
Allow

Possible values: {'Yes'|'No'}.

Default: No

KeyFile string.
CertificateFile string.
Port unsignedShort.
ProxyAdress string.

 

LocalLocation Identifies local file paths involved in the transfer.
 
System Identifies a user in the local system on the network. Optional.
 
UserName A user name used to authenticate on the system. string
Password A password used to authenticate on the system. Optional. string
Files Paths to the transfer contents on the local host.
 
Path A transfer file path. For user name with document root path configured, the path must expressed relative to the user document root path.
A single or many instances of the Path elements can be nested in the Files element.
string

 

 

RootPath string. Path prefix (since version 3.3).

 

FileParameters Specifies file-related parameters pertaining to the transfer.
 
CreatePath Specifies whether or not destination directories should be created if they don't exist.

Possible values: {'Yes'|'No'}.

Default: No

ResumeCheck Specifies the mechanism to use when resuming partially transferred files.

Possible values: {'None'|'Attributes'|'Sparse Checksum'|'Full Checksum'}

Default: Sparse Checksum

ManifestPolicy Manifest policy. It states if manifest files should be generated or not for transfers.

Possible values: {'None'|'Text'}

Default: None

ManifestPath Manifest file path. If this property is set, while the ManifestPolicy is not explicitly defined, the system infers that the value of the ManifestPolicy property is "Text", and will generate manifest files. string
ManifestInprogressSuffix Manifest file path suffix when the manifest is still in progress (since 3.5.4). string
Protection Specifies if encryption at rest will be applied to the transfer. A passphrase will be set to secure the process.

Possible values: {'None'|'Encrypt'|'Decrypt'}

Default: None

Passphrase A passphrase to use for encryption at rest. string
PreCalculateJobSize Specifies whether the aggregate size of all files in the job is to be calculated before starting the transfer.

Possible values: {'Yes'|'No'}.

Default: No

RemoveAfterTransfer Specifies whether the source files are deleted after the transfer. All folders in the source path will still remain. Also refer to RemoveEmptyDirectories.

Possible values: {'Yes'|'No'}.

Default: No

RemoveEmptyDirectories Specifies whether empty directories in the source path are deleted after the transfer.

Possible values: {'Yes'|'No'}.

Default: No

RemoveEmptySourceDirectory (since 3.6.1).

Possible values: {'Yes'|'No'}.

Default: No

SymbolicLinks Specifies symbolic links are handled during the transfer.

Possible values: {'Follow'|'Copy'|'Skip'|'Copy+Force'}

Default: Follow

PreserveTimestamps Specifies whether source timestamps are preserved at the destination.

Possible values: {'Yes'|'No'}.

Default: No

PreserveModificationTime Specifies whether modification timestamps are preserved (since version 3.5.4).

Possible values: {'Yes'|'No'}.

Default: No

PreserveAccessTime Specifies whether access timestamps are preserved (since version 3.5.4).

Possible values: {'Yes'|'No'}.

Default: No

PreserveCreationTime Specifies whether creation timestamps are preserved (since version 3.5.4).

Possible values: {'Yes'|'No'}.

Default: No

PreserveSourceAccessTime Specifies whether source access timestamps are preserved at the destination (since version 3.5.4).

Possible values: {'Yes'|'No'}.

Default: No

PreserveUID Specifies whether UIDs are preserved (since version 3.5.4).

Possible values: {'Yes'|'No'}.

Default: No

PreserveGID Specifies whether GIDs are preserved (since version 3.5.4).

Possible values: {'Yes'|'No'}.

Default: No

ReadBlockSize Specifies the read block size, in bytes. unsignedInt.
WriteBlockSize Specifies the write block size, in bytes. unsignedInt.
Overwrite Specifies the transfer behavior if a content to transfer already exists at destination.

Possible values: {'Always'|'Never'|'Diff'|'Older'|'DiffAndOlder'}

Default: Diff

Exclude Specifies path exclusion patterns. Paths that match excluded patterns are not transferred.
Pattern Exclusion pattern. A single or up to 16 instances of the Pattern elements can be nested in the Exclude element. string
Include Specifies path inclusion patterns. Paths that match included patterns are transferred (since 3.6.1).
Pattern Inclusion pattern. A single or up to 16 instances of the Pattern elements can be nested in the Include element.

Several Rules (Include/Exclude blocks) can be specified. Rules are applied in the order that they are encountered, and the first matching rule (whether including or excluding) takes precedence.

For example: apply rules V, W, X, Y, Z, in that order.
<Include><Pattern>V</Pattern></Include> <Exclude><Pattern>W</Pattern><Pattern>X</Pattern><Pattern>Y</Pattern></Exclude> <Include><Pattern>Z</Pattern></Include>

string
DeleteBeforeTransfer (since version 3.7.0).

Possible values: {'Yes'|'No'}.

Default: No

SourceBase If this option is utilized, ascp will strip the source base path, while preserving the rest of the directory structure. For example, consider the "clips" directory with a file: /clips/outgoing/file1 and we want to transfer file1 within the "outgoing" folder (but not the "outgoing" folder, itself). By setting SourceBase element to /clips/outgoing/, the transferred file will appear in the destination directory as (docroot)/file1. string
PartialFileSuffix A suffix for partial files (since 3.5.4). string
ExcludeOlderThan A time in seconds since epoch. Excludes from the transfer files older than the specifed time, based on when the file was last changed (since 3.5.4). string
ExcludeNewerThan A time in seconds since epoch. Excludes from the transfer files newer than the specifed time, based on when the file was last changed (since 3.5.4). string
SaveBeforeOverwrite If Partialfilesuffix and SaveBeforeOverwrite are defined, the suffix defined in SaveBeforeOverwrite is used (since 3.5.4). string
FileChecksum Checksum algorithm (since 3.5.4).

Possible values: {'MD5'|'SHA1'|'None'}

Default: None

SkipSpecialFiles (since version 3.5.4).

Possible values: {'Yes'|'No'}.

Default: No

MoveAfterTransfer Defines an archive directory, where to move source files after transfer success (since 3.5.5). string
Compression Compression algorithm. If not specified, no compression is applied (since 3.6.0).

Possible values: {'None'|'qlz'|'zlib'|'lz4'}

Default: None

SparseFile Defines sparse file support (since 3.6.0).

Possible values: {'Yes'|'No'}

Default: No

Tags (since 3.6.0). string in a JSON format

 

 
LinkParameters
Specifies link-related parameters pertaining to the transfer.

Link capacity can be detected automatically by using <AutoDetectCapacity> property.

Link capacity can also be set manually by using <RemoteCapacity> and or <LocalCapacity>:

  • If <RemoteCapacity> is not defined, <LocalCapacity> is used as the link capacity.
  • <RemoteCapacity> is used as link capacity when its defined value is less than the value of <LocalCapacity>.
  • If none of <RemoteCapacity> and <LocalCapacity> is defined, the bandwidth cap will limit the transfer rates.
     
 
RemoteCapacity   unsignedInt
LocalCapacity   unsignedInt
AutoDetectCapacity Indicates whether or not fasp should automatically detect the link capacity during transfer. Performing automatic detection allows rates to be set at a percentage of the measured value. When automatic bandwidth discovery is enabled (<AutoDetectCapacity> set to Yes) and the rates expressed as percentage (<MinimumRateAsPercent> or <TargetRateAsPercent> set to Yes), then the rates will be a percentage of the measured bandwidth. Otherwise, rates must be specified in Kbps.

Possible values: {'Yes'|'No'}.

Default: No

 

RateParameters Specifies rate-related parameters pertaining to the transfer.
 
Policy Specifies the rate policy the transfer should utilize.

Possible values: {'Fixed'|'Fair'|'Trickle'}

TargetRate The target rate of data transmission, in Kbps or %. If <TargetRateAsPercent> is set to Yes, this value will be interpreted as a percentage and should be set to values between 0 and 100, inclusive. The target rate cannot exceed the link capacity and the <BandwidthCap>.

unsignedInt.

TargetRateAsPercent Indicates whether or not the value of <TargetRate> should be interpreted as a percentage (of the link capacity, see <LinkParameters> or the measured bandwidth). When automatic bandwidth discovery is enabled (<AutoDetectCapacity> set to Yes) and the rate as percentage is enabled (<TargetRateAsPercent> set to Yes), then the target rate will be a percentage of the measured bandwidth.

Possible values: {'Yes'|'No'}.

Default: No

MinimumRate The minimum rate of data transmission, in Kbps or %. If <MinimumRateAsPercent> is set to Yes, this value will be interpreted as a percentage and should be set to values between 0 and 100, inclusive. The minimum rate cannot exceed the target rate, the link capacity and the <BandwidthCap>.

unsignedInt.

MinimumRateAsPercent Indicates whether or not the value of <MinimumRate> should be interpreted as a percentage (of the link capacity, see <LinkParameters> or the measured bandwidth). When automatic bandwidth discovery is enabled (<AutoDetectCapacity> set to Yes) and the rate as percentage is enabled (<MinimumRateAsPercent> set to Yes), then the minimum rate will be a percentage of the measured bandwidth.

Possible values: {'Yes'|'No'}.

Default: No

BandwidthCap A cap on data transfer rates, in Kbps. A value of 10,000,000 indicates that no bandwidth cap will be applied.

unsignedInt.

Default: 10000000

Priority Priority when sharing virtual bandwidth cap. 1 for higher priority, 2 for regular.

unsignedInt.

Possible values: {1, 2}

Default: 2

 

ChannelParameters Specifies channel-related parameters pertaining to the transfer.
 
Port UDP port over which data will be transported.

unsignedShort.

Default: 33001

DatagramSize The datagram size fasp will use when transmitting data. If this property is set, while the <AutoDetectPathMTU> is not explicitly defined, the system infers that the value of the <AutoDetectPathMTU> property is "No", and uses the datagram size value provided in this element.

unsignedInt.

Default: 1492

AutoDetectPathMTU Indicates whether or not fasp should automatically detect the path MTU (maximum transmission unit).

Possible values: {'Yes'|'No'}.

Default: Yes

IPV6 (since version 3.5.4).

Possible values: {'Yes'|'No'}.

Default: No

 

SecurityParameters

Specifies security-related parameters pertaining to the transfer.
 
EncryptionCipher Specifies the encryption cipher used to encrypt data during transfer.

Possible values: {'None'|'AES-128'}

Default: None

SSHFingerprint (since version 3.5.4). string

 

RetryParameters Specifies retry-related parameters pertaining to the transfer. Retry parameters in user preferences will be applied if this element is not defined.
 
Count Number of transfer attempts. Default is 3. unsignedInt
BaseInterval Base time interval, in seconds. The base time interval specifies the base time that will elapse between a failed transfer and a retry attempt. After each subsequent failure, the time interval will be doubled, up to the maximum value as specified by <MaximumInterval>. Setting <BaseInterval> and <MaximumInterval> to the same value, effectively indicates a constant time interval between retry attempts. Default is 1 second. unsignedInt
MaximumInterval Maximum time interval, in seconds. The maximum time interval limits the increasing of the time interval that occurs as a result of multiple, subsequent failures. unsignedInt

 

 

PrivateData Application defined private data. This field can be used by a client application as a placeholder for a local (unique) reference. It differs from the Cookie in that the Cookie is known to both the local (Client) and the remote (Server), while the PrivateData Key is known to the local (Client).
 
Key The local reference key string

 

RawOptions (since 3.7.0).

If you wish to view a more detailed version of the Job Descriptions, please refer to the Job Description Documentation available in the next section.

Example Job Order

This example describes a Job Order, in this case a Pull Operation) in XML format.

XML Format

 

Plain Text

 

 


Using Azure

If the application which triggered the transfer is not running on either your Aspera On-Demand instance or the customer's Aspera Server you should use the SOAP Job API.  This API allows you to send a SOAP request to one of the Aspera Nodes to start the transfer.  When working in Azure the approach is to leverage the SOAP API with the REST Node API by issuing Basic Authenticated HTTP requests.  For example, to start the transfer you could use the following cURL command:

curl -v -k -i --basic -u "ASPERA_ON_DEMAND_USERNAME:ASPERA_ON_DEMAND_PRIMARY_ACCESS_KEY" -H "Expect: " -H "Content-Type: text/xml;charset=UTF-8" -H "SOAPAction: JobNET-200601#Submit" -d @soap_payload.xml -X POST "https://ASPERA_ON_DEMAND_HOST_NAME.azure.asperaondemand.com:9092/services/soap/JobNET-200601"

In this example, the soap_payload.xml file would be the following:

 

An example of the job order that you would be used to transfer from an Azure-based Aspera On-Demand server would be:

 

 


Sample Payloads

The following example shows a typical SOAP Job Submission payload where the remote location is an Aspera On-Demand Server running in Azure with Azure Storage.  In order to use this example the SOAP service must be running on Aspera Central 3.3 or higher.  Other useful examples of basic usage are included to help demonstrate normal usage.  It should be noted that the Order needs to be submitted using HTML entities (&lt; and &gt; instead of < and >).  The top part of your XML should be regular XML, however, everything in between needs to be HTML entities instead.

XML Format

 

Plain Text

 

It should be noted that the AZURE_STORAGE_ACCOUNT_NAME and AZURE_STORAGE_PRIMARY_ACCESS_KEY must by URL encoded in order for this example to work.

 


Example Submission

For demonstrations, you could send a request to either http://SERVER_NAME:40001/services/soap/Transfer-201210 or http://my.host.com:40001/services/soap/JobNET-200601 (since 201210 includes all non deprecated features of 200601) with the XML payload of:

 

This request would yield the following result, which you could then use Reliable Query on to perform your final operations as needed.

 

Create Destination Directory and Rename

Since Aspera Central 3.3 you can use the SOAP Job API to transfer files to a destination folder that does not exist on a Remote Aspera Server and rename the source files at the destination. This is possible by using the RootPath which allows you to define a base destination directory. The following example Job Order will send the files /srcPath/sourceFile1 and /srcPath/sourceFile2 to a remote base directory located at /path/to/dst where the source files will be stored in different subdirectories and renamed respectively to /f1SubDir/sourceFile1-renamed and /f2SubDir/sourceFile2-renamed.

 

 


Notes

Additional notes and hints are provided on this page.  These may provide deeper information on certain topics, like Rate Parameters and MTU.

Rate Parameters

The basic way to define a target rate at 500 Kbps (5 Mbps) is by simply using:

<RateParameters>  <TargetRate>5000</TargetRate><RateParameters>

Target rate can also be achieved by combining parameters which are available in the LinkParameters and RateParameters sections. The way these parameters relate is demonstrated below.

  • Set AutoDetectCapacity to YES
    • TargetRateAsPercentage (or MinimumRateAsPercentage) set to Yes, then the rate is a percentage in the generated Aspera command. This will be calculated as the percentage of the measured bandwidth.
    • TargetRateAsPercentage (or MinimumRateAsPercentage) set to No, then the rate has the value defined for TargetRate (or MinimumRate) in the generated Aspera command.
  • Set AutoDetectCapacity to NO
    • TargetRateAsPercentage (or MinimumRateAsPercentage) set to Yes, then the rate is calculated as a percentage of the link capacity in the generated Aspera command.
    • TargetRateAsPercentage (or MinimumRateAsPercentage) set to No, then the rate has the value defined for TargetRate (or MinimumRate) in the generated Aspera command.
  • Link Capacity
    • The link capacity is equal to the LocalCapacity if RemoteCapacity is not defined or if RemoteCapacity is defined greater than LocalCapacity.
    • If the link capacity is not defined in terms of LocalCapacity or RemoteCapacity, the link limit is the BandwidthCap.

Examples

This example yields a target rate of 45000 Kbps (-I 45000) and a minimum rate of 200 Kbps (-m 200).

 

This example yields a target rate of 800000 Kbps (-l is 40% of the remote capacity 2000000 Kbps) and a minimum rate of 200 Kbps (-m 200).

 

This example yields a target rate of 40% (-l is 40% of the measured bandwidth) and a minimum rate of 200 Kbps (-m 200).

 

This example yields a target rate of 4000000 Kbps (-l is 40% of the default bandwidth cap 10,000,000 Kbps) and a minimum rate of 200 Kbps (-m 200)

 

MTU Auto Detection

By default FASP automatically detects the maximum transmit unit (MTU) to use when transmitting data. To disable this feature you can set the AutoDetectPathMTU parameter to false, this parameter can be found in the ChannelParameters section of the Job Order. You can also specify the datagram size (1492b by default) to do this you would set the DatagramSize parameter. You should note that if the AutoDetectPathMTU parameter is not set and a DatagramSize is, the AutoDetectPathMTU is assumed to be false and will use the set value. However, if you explicitly state that the AutoDetectPathMTU is true than any DatagramSize will be ignored. An example of the ChannelParameters is seen below.

<ChannelParameters>  <DatagramSize>1500</DatagramSize>  <AutoDetectPathMTU>false</AutoDetectPathMTU><ChannelParameters>

 


Job Definitions Documentation

The job definitions documention below explains the different job order types.

To view the documentation, please select the version you wish to view

 


Job Monitoring

Job Monitoring (Reliable Query)

The SOAP Web Service FASPSessionNET-200911 allows an application to reliably query FASP transfers without having to setup an observer.  The service is implemented in Aspera Central and runs at [server]/services/soap/FASPSessionNET-200911.  The SOAP messages transmitted to and from this service use literal style SOAP encoding. For more detailed information, see the Reliable Query page.

 


Getting Started

To get started using this Web Service you must enable the local datastore.  This can be accomplished by setting the persistent_store configuration option to 'enable' in the configuration manager or you can edit the aspera.conf file directly. An example of this configuration is seen below.


<central_server>
  <persistent_store>enable</persistent_store></central_server>

Aspera Central stores data about the session and file transfer in the local datastore and uses this as a time-sensitive cache. You can customize the behavior by configuring the following options in the aspera.conf file (in the central_server tag).

Option Accepted Values Description
persistent_store enable | disable Enables or disables the recording of session and file transfer information in the persistent store. In order to increase performance, it is better to configure the local store on a different disk than the one usually used with FASP.
persistent_store_path see default datastore location The path where the datastore is created. The path can be absolute or relative to Central's base directory.
If the path points to an existing directory, the datastore is created in that directory with the name "central-store.db". Otherwise, the datastore will be created with the provided name, creating directories as necessary.
persistent_store_max_age Unlimited | [sec]  86400(24 hours) The maximum age of sessions and file transfers in the datastore. Older items are purged from the store periodically. Age is expressed in seconds from the end time of a session or transfer.
persistent_store_on_error exit | ignore Defines the behavior of Central when it fails to persist data in the datastore:
  • exit: the Central service quits. If configured accordingly, all running and new fasp transfers will fail subsequently.
  • ignore: Central continues, ignoring the error. Note that this leads to unrecoverable data loss!
event_buffer_capacity 1000 The number of events that can be buffered temporarily in memory. Increase in high-concurrency situations with many small file transfers.
event_buffer_overrun block | drop Defines the behavior when the buffer reaches its capacity:
  • block: blocks new notifications, possibly slowing down transfers.
  • drop: drops the notification; this may lead to unrecoverable data loss!
compact_on_startup enable | disable If enabled, the datastore is compacted upon startup of Central. This might take several seconds depending on the actual size of the datastore.

The datastore is normally stored in the following locations, depending on your system:

Windows

  • C:\Program Files\Aspera\Enterprise Server\var\central-store.db

Macintosh

  • /Library/Application Support/Aspera/Enterprise Server/var/central-store.db

Linux, FreeBSD, Isilon and Solaris

  • /opt/aspera/var/central-store.db

When running a high performance system or expecting a high quantity of small file transfers it is recommended to put the database on a separate disk that is fast. When expecting 500 to 100,000 sessions you should expect to need at least 29 MB of disk space, and when expecting 5,000 to 1,000,000 sessions you should expect 289 MB of disk space.  These numbers are just estimates and real world conditions will define how much space you need to allocate; a typical session uses around 400 bytes of disk space and a typical file transfer uses around 300 bytes.

It is recommended that you occasionally run VACUUM to help keep the database compact and avoid fragmentation.  When you frequently insert, update and delete items the data in the database becomes fragmented and is scattered across the database file.  To run VACUUM look in the option/configuration folder in your Central installation.  The VACUUM is automatically started at Central startup when the compact_on_startup parameter is enabled, you can also start it by using the command line --compact-db option when starting Central.

 

 


Overview

File transfers to and from an Aspera Node are always executed in the context of the session.  A session can contain one or multiple file transfers.  This section will go over information like lifecycle, states, filters, iterations and other attributes of this Web Service.

Session & File Transfer Lifecycle

Events associated with a session usually include:

  • Session Start - A transfer session starts.
  • File Transfer Start - A file transfer starts transferring within the session.
  • File Transfer Stop - A file transfer stops, either completing successfully or failing.
  • Session Stop - A transfer session completes successfully or fails.

Multiple file transfer events can occur during the lifecycle of a session.  Each event will be recorded in Central's data cache and can be queried through the API.  Progress information is also logged and can be retrieved through the various API calls available.

States

A session can have the following states, these states are returned with any query and you can also filter via the state.

  • Running - The session is in progress.
  • Paused - The session was paused (e.g. by setting the target bandwidth to 0).
  • Completed - The session has completed successfully.
  • Cancelled - The session was aborted.
  • Error - The session stopped due to an error.
  • Willretry - The session has failed and will retry automatically after its retry period has elapsed (see Retries below).
  • Orphaned - The session has terminated at a time when Aspera Central was not running, and therefore so no exact final session information is available.

A transfer can have the following states

  • Running - The file transfer is in progress.
  • Completed - The file transfer has completed successfully.
  • Error - The file transfer stopped due to an error.

Filters

Filters allow you to select the desired information and restrict the number of results that will be returned.  When using filters, the following rules apply:

  • Empty (not set) filter criteria mean "ALL"
  • If a filter criterion is defined as an array of values, the individual values are combined in a logical OR expression.  For example, SessionFilter(Ids={1,5,6}) accepts sessions with ID 1 or 5 or 6.
  • If multiple filter criteria are defined, they are combined in a logical AND expression. For example, SessionFilter(Status={completed}, Initiators={192.168.1.12}, MaxResults=20) accepts only completed sessions that were initiated by the computer with IP address "192.168.1.12" and returns the first 20 sessions. See also Paged Queries below.
  • Combinations of array-based criteria are evaluated as follows: (criteria1.value1 OR criteria1.value2) AND (criteria2.value1 OR ...) AND ... For example, SessionFilter(Status={completed, failed}, Initiators={192.168.1.12}) is evaluated as: (Status is completed OR Status is failed) AND (Initiator is 192.168.1.12)

Query Results Order

The results of an API query are always ordered by last modification date with the newest first.  The API queries can return information on both ongoing and completed sessions or transfers.  Completed items are returned first in the list of results followed by ongoing sessions ordered by their ID number.

Iterators

Aspera Central stores all events in the order they occur. The web-services interface provides an "event" (or "change") iterator. An application can query for a session or file transfer events, and each response will return an iteration token that can be thought of as the maximum "last modification date" of the items in the result set. Since results are always ordered by increasing last modification date, querying again using the same filters and the iteration token from the previous query, will return the next set of results with a larger modification date. The iterator ensures that an application can reliable get all events regardless of how many it reads at runtime or how many events are being generated by the ongoing transfers. The iteration token is a fixed-size String of 48 alphanumeric characters.

Paged Queries

Query results are always ordered by last modification date.  Since the ordering is done before applying the filters you will want to apply a MaxResults filter that can be used in conjunction with the iteration token to find the results you are looking for. For example:

  • GetSessions(MaxResults=100)
    • returns session 1-100 and an IterationToken1.
  • GetSessions(MaxResults=100, IterationToken1)
    • returns sessions 101-200, IterationToken2
  • GetSessions(MaxResults=100, IterationToken2)
    • returns sessions 201-235, IterationToken3 (assuming that there are no more than 235 sessions)
  • GetSessions(MaxResults=100, IterationToken3)
    • returns an empty list, IterationToken3 (same as in previous call)

Change Queries

Another situation where the iteration token is useful is when an application wants to query Aspera Central periodically in order to retrieve "all changes" since the last API call. This mechanism can easily be combined with paging to quickly retrieve the last X number of changes since the last call.

Paged queries cannot be used to retrieve a large number of ongoing sessions or transfers in a batch since ongoing sessions or transfers are associated with the same last modification date and therefore subsequent queries will return the same result, unless the item has completed.

CURRENT_POSITION Token

The special iteration token "CURRENT_POSITION" can be used to retrieve information that has the last modification date of "NOW", this allows you to view only changes that are new and ignore the existing history.  The "CURRENT_POSITION" token will never return a completed session or transfer, only ongoing items.

Retries

Transfers submitted can contain a retry policy that will allow Central to retry the failed transfer based on the conditions (count, BaseInerval and MaximumInterval).  If an item is a retry, than it will contain additional fields relating to the retry status in any queries. When a job is submitted and fails, it will retry and receive the state "willretry". It will attempt to retry the job until the policy states otherwise (for example it reaches the max number of retries).  Since Aspera Server version 3.3 after it fails to complete it will receive the status "error", prior to version 3.3 the status would remain "willretry" and the developer would need to use sessionInfo to compare the values JobRetryCount and JobMaxRetries.

 


Service Messages

This document includes a list of SOAP Service Messages available including their arguments and return values.

GetSessions

SessionKeysResult GetSessions(SessionFilter)

Returns the keys of all sessions matching the provided SessionFilter.

GetSessionInfo

SessionInfoResult GetSessionInfo (SessionFilter)

Returns all available information about sessions matching the provided SessionFilter.

GetSessionStatistics

SessionStatisticsResult GetSessionStatistics (SessionFilter)

Returns statistics for all sessions matching the provided SessionFilter. For ongoing sessions, the statistics represent current progress information. For finished sessions, the statistics are the final values.

GetFileTransfers

FileTransferKeysResult GetFileTransfers (FileTransferFilter)

Returns the keys of all file transfers matching the provided FileTransferFilter.

GetFileTransferInfo

FileTransferInfoResult GetFileTransferInfo (FileTransferFilter)

Returns the absolute names of all files matching the provided FileTransferFilter.

GetFileTransferStatistics

FileTransferStatisticsResult GetFileTransferStatistics (FileTransferFilter)

Returns statistics for all file transfers matching the provided FileTransferFilter. For ongoing transfers, the statistics represent current progress information. For finished transfers, the statistics are the final values.

The file transfer filter extends the session filter (i.e. it includes all of the session filter's criteria). The API first selects all sessions according to the session filter criteria, and then applies the file transfer filter criteria to the transfers belonging those sessions.

GetInfo

InfoResult GetInfo (FileTransferFilter)

Returns all available information for sessions and transfers matching the provided filter. This call is the combination of a GetSessionInfo(SessionFilter) and a GetFileTransferInfo(FileTransferFilter) call in one. Session information is returned only for sessions that match the session-specific filter criteria of the FileTransferFilter. Transfer information is returned for transfers that belong to the previously selected sessions and match the transfer-specific filter criteria of the FileTransferFilter.

GetStatistics

StatisticsResult GetStatistics (FileTransferFilter)

Returns statistics for sessions and transfers matching the provided filter. This call is the combination of a GetSessionStatistics(SessionFilter) and a GetFileTransferStatistics(FileTransferFilter) call in one. Session statistics are returned only for sessions that match the session-specific filter criteria of the FileTransferFilter. Transfer statistics are returned for transfers that belong to the previously selected sessions and match the transfer-specific filter criteria of the FileTransferFilter.

 


Data Types

This document includes information on the data types that are defined by the XML schema.

Namespaces

The XML namespaces below are declared and used within the FASPSessionNET-200911 SOAP Web Service.

xsd http://www.w3.org/2001/XMLSchema 
wsdl http://schemas.xmlsoap.org/wsdl/ 
soap http://schemas.xmlsoap.org/wsdl/soap/  
asf http://www.asperasoft.com/xml/faspsession-net/2009/11/FASPSessionNET.wsdl
asfx urn:Aspera:XML:FASPSessionNET:2009/11:Types

Generic Filters

  • string IterationToken
    • Token (returned by previous call) to retrieve the next batch of results. See paged queries.
  • int MaxResults
    • Maximum number of results to return. This value should never exceed 1000. If the expected number of results is greater than MaxResults value, one should use the IterationToken to iterate through the entire result set.

Session Filter

A session filter allows you to restrict the sessions that are returned by the API call.

  • string[] SessionUUID
    • Accepted session UUIDs.
  • string[] SessionStatus
    • Accepted session statuses.
  • string[] ServerAddress
    • Accepted IP addresses or hostnames of the servers.
  • string[] ClientAddress
    • Accepted IP addresses or hostnames of the clients.
  • string[] Cookie
    • Accepted cookies.
  • String CookieFilter
    • A regular expression to match the session's "cookie".
  • string[] JobId
    • Accepted job IDs.
  • enum Direction: {incoming, outgoing}
    • Incoming or outgoing transfer.
  • dateTime MinSessionStartDate
    • Minimum session start date.
  • dateTime MaxSessionStartDate
    • Maximum session start date.
  • dateTime MinSessionEndDate
    • Minimum session end date.
  • dateTime MaxSessionEndtDate
    • Maximum session end date.
  • string[] PrivateKey
    • Accepted private keys (from the PrivateData sections of a Job order)
  • boolean LastSessionOnly
    • In the context of jobs submitted with a retry policy, enabling this filter option will return information on only the last session of a given job instead of all retry attempts. Sessions that do not belong to a job (e.g. sessions started manually on the command line), will be returned as well.

File Transfer Filters

A file transfer filter allows specifying which file transfers are returned by the respective API calls. The file transfer filter extends the session filter. The API first selects all sessions according to the session filter criteria, and then applies the file transfer filter criteria to the transfers belonging to those sessions.

  • int64[] TransferId
    • Accepted transfer IDs
  • string[] TransferStatus
    • Accepted statuses
  • string[] Filepath
    • List of accepted absolute file paths.
  • string FilenameFilter
    • A regular expression that must match a file's full path.
  • dateTime MinTransferStartDate
    • Minimum start date of the transfer.
  • dateTime MaxTransferStartDate
    • Maximum start date of the transfer.
  • dateTime MinTransferEndDate
    • Minimum end date of the transfer.
  • dateTime MaxTransferEndtDate
    • Maximum end date of the transfer.

Query Results

This is the base type for most result values returned by the API.

  • int ResultCount
    • The number of entries returned in this result.
  • int RemainingResultCount
    • The number of remaining results that were filtered out because of the MaxResults filter criteria. Used with paged queries.
  • string IterationToken
    • A token that can be passed as filter criteria in a subsequent API call with an otherwise identical filter. See paged queries.

Session Key Result

This extends Query Results.

  • SessionKey[]

Session Key

  • string UUID
    • The session UUID.
  • string JobId
    • The job ID if this session was initiated through the API, 0 otherwise.

Session Statistics Results

This extends Query Results.

  • SessionStatistics[]

Session Statistics

This extends Session Key

  • string Status
    • Session status.
    • Values: running | paused | completed | cancelled | error | willretry | orphaned
  • int ErrorCode
    • Error code if the session failed.
  • string ErrorDescription
    • Error description if the session failed.
  • int ExpectedFileCount
    • Expected total number of files in this session. Reported only if PreCalc is turned on.
  • int ExpectedDirCount
    • Expected total number of directories in this session. Reported only if PreCalc is turned on.
  • long ExpectedByteCount
    • Expected total number bytes that will be transferred in this session. Reported only if PreCalc is turned on.
  • int FileCount
    • Total number of complete, failed, and transferring files.
  • int FilesComplete
    • Number of files that have been successfully transferred.
  • int FilesFailed
    • Number of files that have failed to transfer.
  • int FilesTransferring
    • Number of files currently being transferred.
  • long BytesWritten
    • Total number of bytes that have been written to disk at the destination.
  • long BytesTransferred
    • Total number of bytes that have been transferred during the session.
  • long BytesLost
    • Total number of bytes that have been lost during the session.
  • long Elapsed
    • Running time of the session, in microseconds.
  • int NetworkDelay
    • Current network delay in milliseconds.
  • string RateInfo
    • Unused

Session Info Results

This extends Query Results

  • SessionInfo[]

Session Info

This extends Session Statistics

  • dateTime StartDate
    • Date and time when the session started (UTC).
  • dateTime EndDate
    • Date and time when the session ended (UTC).
  • string Token
    • Token used for external authorization.
  • string Cookie
    • Arbitrary field used for application-specific requirements.
  • enum Direction
    • The direction of the transfer.
    • Values: incoming | outgoing
  • string ServerEndpoint
    • Indicates which endpoint is acting as the server.
    • The value of this element will either be Local or Remote, indicating which endpoint is acting as the server.
    • Values: Local | Remote
  • string ServerAddress
    • IP address or host name of the system.
  • int ServerSSHPort
    • SSH (TCP) port over which the transfer was initiated.
  • int ServerFASPPort
    • fasp (UDP) port over which data is being transferred.
  • string User
    • The user used to authenticate the session on the server.
  • string ClientEndpoint
    • Indicates which endpoint is acting as the client. The value of this element will either be Local or Remote, indicating which endpoint is acting as the client.
    • Values: Local | Remote
  • string ClientAddress
    • IP address or host name of the system.
  • int ClientFASPPort
    • fasp (UDP) port over which data is being transferred.
  • string RatePolicy
    • Indicates the rate policy being utilized by the transfer.
    • Values: Fixed | High | Fair | Trickle
  • int TargetRate
    • Target rate of data transmission, in Kbps.
  • int MinimumRate
    • Minimum rate of data transmission, in Kbps.
  • int BandwidthCap
    • Cap on data transfer rates, in Kbps.
    • If empty or 0, will use default of 10Mbps.
  • string EncryptionCipher
    • Indicates the encryption cipher being used to encrypt data during transfer.
    • Values: None | AES128
  • int JobRetryCount
    • The Xth attempt to successfully complete the transfer job. 0 for the initial session or if the session was not initiated through a transfer job.
  • int JobMaxRetries
    • The maximum number of retries to successfully complete job or 0 if the session was not initiated through a transfer job.
  • string PrivateKey
    • The private key from the PrivateData section of a transfer job.
  • string SourcePath
    • Submitted source path.
  • string DestinationPath
    • Submitted destination path.
  • int VLinkId
    • Unused.

File Transfer Key Result

This extends Query Results

  • FileTransferKey[]

File Transfer Keys

  • string SessionUUID
    • The UUID of the session that the transfer belongs to.
  • string Path
    • The full path of the transferred file.
  • long LocalId
    • The local transfer ID
  • string UUID
    • Unused.

File Transfer Statistics Results

This extends Query Results

  • FileTransferStatistics[]

File Transfer Statistics

This extends File Transfer Keys

  • string Status
    • File transfer status.
    • Values: running | completed | error
  • int ErrorCode
    • Error code if the transfer failed.
  • string ErrorDescription
    • Error description if the transfer failed.
  • long size
    • The file size.
  • long StartOffset
    • Byte position at which the transfer started. Usually, this will be equal to 0. However, in the case of a resumed transfer, this indicates the file offset from where the transfer was resumed.
  • long BytesWritten
    • Number of bytes written to the destination file.
  • long BytesContiguous
    • Number of contiguous bytes written to the destination file.
  • long BytesLost
    • Number of bytes lost on the network (and retransmitted).
  • long Elapsed
    • Running time of the transfer in micro seconds.

File Transfer Info Results

This extends Query Results

  • FileTransferInfo[]

File Transfer Info

This extends File Transfer Statistics

  • dateTime StartDate
    • Date and time when the transfer started (UTC).
  • dateTime EndDate
    • Date and time when the transfer ended (UTC).
  • string Checksum
    • Checksum calculated from file data.
  • string ChecksumType
    • Type of checksum.
  • string FileType
    • Unused.
  • string Action
    • Unused.
  • string ContentProtection
    • Unused.

Info Results

This extends Query Results

  • SessionInfo[]
  • FileTransferInfo[]

Statistics Results

This extends Query Results

  • SessionStatistics[]
  • FileTransferStatistics[]

Filter Changed Error

This error is returned if a query attempts to use a filter with an invalid iteration token. An iteration token is always linked to the filter that was used in the initial call that retrieved it. Repeating a query with the iteration token from a previous call requires that the filter remains otherwise unchanged.

 


WSDL File

The FASPSession200911.wsdl file provides an example binding to http://127.0.0.1:40001/services/soap/FASPSessionNET-200911.  This file comprises the service that is used for code generation by the Web Service framework.  To use this file you must change the soap:address flag, which is located at the bottom of the file.

 Download WSDL File

 

 


Examples

Fully working examples and cURL commands are provided on this page.  This includes examples in Java, Ruby and C# as well as cURL commands that are useful in Reliable Query.  To view the examples please download them and open them in their corresponding IDE or compiler or copy the cURL commands to a command prompt or terminal window.

cURL Command

The cURL command below will get all of the information for 'running' sessions. The XML used in the command is seen below the command with proper structure for easier reading. This command will include multiple returned items, but the main ones to note are the ResultCount and and the RemainingResultCount which when added together will give you the total number of of running transfers.

It should be noted that persistent store in Central must be enabled or you will not be able to use Reliably Query.

curl -k -i --basic -u "[user]:[password]" -H "Content-Type: text/xml;charset=UTF-8" -H "SOAPAction:FASPSessionNET-200911#GetSessionInfo" -d "<?xml version=\"1.0\" encoding=\"UTF-8\"?><soapenv:Envelope xmlns:soapenv=\"http://schemas.xmlsoap.org/soap/envelope/\" xmlns:typ=\"urn:Aspera:XML:FASPSessionNET:2009/11:Types\"><soapenv:Header></soapenv:Header><soapenv:Body><typ:GetSessionInfoRequest><SessionFilter><SessionStatus>running</SessionStatus></SessionFilter></typ:GetSessionInfoRequest></soapenv:Body></soapenv:Envelope>" -X POST "[server]/services/soap/Transfer-201210"

XML used in cURL command above

 

If you need to get information about a transfer for an extended period of time (more than about three minutes from submission) you should you should use a combination of the /transfers/204 Node endpoint and the Reliable Query API with a filter using a cookie instead of the job ID. This will ensure that you can continuously monitor the transfer. For example, the command below will query using a cookie called "smart-xfer-cookie". To help you better understand the command, the XML payload is seen formatted under the command.

curl -k -i --basic -u "[user]:[password]" -H "Content-Type: text/xml;charset=UTF-8" -H "SOAPAction:FASPSessionNET-200911#GetSessionInfo" -d "<?xml version=\"1.0\" encoding=\"UTF-8\"?><soapenv:Envelope xmlns:soapenv=\"http://schemas.xmlsoap.org/soap/envelope/\" xmlns:typ=\"urn:Aspera:XML:FASPSessionNET:2009/11:Types\"><soapenv:Header></soapenv:Header><soapenv:Body><typ:GetSessionInfoRequest><SessionFilter><Cookie>smart-xfer-cookie</Cookie></SessionFilter></typ:GetSessionInfoRequest></soapenv:Body></soapenv:Envelope>" -X POST "https://[server]:9092/services/soap/Transfer-201210"

XML used in cURL command above

 

Command Line Tool

WCF Monitoring Transfers Application

 


Observer and Session Management

Observer and Session Management

The SOAP Web Service FASPSessionNet-200601 allows an application to monitor and manage FASP sessions that are controlled by Aspera Central.  This service can be used by an application in a polling or event-driven fashion. Developers familiar with the practice of constructing and deploying service oriented architectures should be accustomed to this setup. This SOAP service is implemented by Aspera Central and usually runs in the /services/soap/FASPSessionNET-200601 directory of the Aspera Central installation. The SOAP messages use documented SOAP style encoding.

 


Overview

The FASPSessionNET-200601 service can be used by an application to poll or allow subscriptions to notifications. This section goes over these two options in more detail. If you are familiar with service oriented architectures you should be accustomed to these mechanisms.

Notificationsnotifications

Notifications allow an application to subscribe to a set of events. When an event occurs, and an application is subscribed to it, a notification will be delivered to the application. In this scenario, the application is referred to as an observer. Implementing a notification observer allows an application to receive near real-time information about ongoing FASP session in an event-driven fashion.

In order to operate as an observer the application must act as a SOAP server, typically using HTTP as a transport layer. This introduces some complexity at the application-level. However, the benefits of being event-driven often justifies this.  In order to act as an observer, an application registers a subscription to a set of topics. When the subscription is registered, the application identifies the endpoint that notifications will be delivered to. An endpoint is referenced by an address and an optional SOAP action. When an event occurs that corresponds to a subscribed topic, a notification will be delivered to the registered endpoint.

The mechanisms employed for delivering notifications are based on two standards. The first is Web Services Addressing, which is defined by the W3C. The second is Web Services Notification, defined by OASIS. Developers familiar with these standards will notice many similarities.  Endpoints are identified by an EndpointReferenceType. This type has two elements, Address and Action. Address specifies the uniform resource identifier (URI) of the observer. Typically, this will take the form of http://observer.example.com/service/location. Action is used for routing any SOAP messages to the appropriate handler. The action is optional, and its value is usually dependent on the web services framework being used.

An application registers a subscription by invoking the Subscribe() method. This method includes two EndpointReferenceType objects, as well as a TopicExpressionType parameters. A topic expression contains an array of session topics that the application wants to subscribe to. The two endpoint references identify a subscription observer and a session observer. In a typical case, the address used will be identical for both observers; with only the action being different which allows the order message to be routed to the correct handler.  When a subscription is established, a set of subscription topics are implicitly registered. Whenever an event occurs that corresponds to one of these topics a notification will be delivered to the subscription observer. This allows the observer to know when the subscription will expire or terminate, and maintain it as needed. The observer must implement the SubscriptionNotify() method in order to receive these notifications.  However, the session topics must be explicitly requested by the observing application. This allows the observer to receive notifications corresponding to only those events in which it is interested. When a session event occurs that an observer is subscribed to a notification will be delivered through the SessionNotify() method; which the observing application must implement.

Pollingpolling

Applications can poll this service to find FASP sessions and query them for detailed information. The messages returned from ListSessions() and QuerySessions() provide the primary requirements needed to use these polling techniques.  For example, An application can invoke ListSessions() which will return an array of session identifiers and one ID for each FASP session that is currently active.  Once the list of IDs has been received it can be followed by multiple invocations of QuerySession() utilizing the IDs that were received earlier.  Once this completes the application will have all of the details about any active FASP sessions.  The polling interval can be determined by the requirements of your application.  When the polling interval increases there is a higher potential to miss information.  The needs of your application and expected use should be weighed to get the best performance while ensuring proper polling of the information.

Deprecated Items

The Observer and Session Management Web Services have a few items that have been deprecated. To learn more about these items please see the deprecated section under Resources or use the links below. It is not recommended to use these, instead you should use Reliable Query.

 


Service Messages

This section includes a list of SOAP Service Messages available including their arguments and return values.

GetSessions

asfx:SubscriptionResourceType Subscribe( xsd:string SessionID, asfx:EndpointReferenceType SubscriptionObserver, asfx:EndpointReferenceType SessionObserver, asfx:TopicExpressionType Topics, xsd:unsignedInt Duration )

Subscribes to a FASP session. If the argument SessionID is set to 0, a subscription to all FASP sessions will be established.

Parameters

  • SessionID: An identifier of the FASP session being subscribed to.
  • SubscriptionObserver: A reference to a web services endpoint that will receive subscription notifications.
  • SessionObserver: A reference to a web services endpoint that will receive session notifications.
  • Topics: A list of topics being subscribed to.
  • Duration: Duration, in seconds, before the subscription will expire.

Return

  • A subscription resource.

Faults

  • asf:SessionNotFoundFault

SOAP Action

  • FASPSessionNET-200601#Subscribe

UpdateSubscription

asfx:SubscriptionResourceType UpdateSubscription( xsd:string SubscriptionID, asfx:TopicExpressionType Topics, xsd:unsignedInt Duration )

Updates an existing subscription. The list of topics specified by Topics will be added to any topics currently associated with the subscription. The time specified by Duration will establish a new expiration date for the subscription. A subscription can be updated to an earlier or later expiration date.

Parameters

  • SubscriptionID: An identifier of the subscription being updated.
  • Topics: A list of topics to add to the subscription.
  • Duration: Duration, in seconds, before the subscription will expire.

Return

  • A subscription resource.

Faults

  • asf:SubscriptionNotFoundFault

SOAP Action

  • FASPSessionNET-200601#UpdateSubscription

Unsubscribe

asfx:SubscriptionResourceType Unsubscribe( xsd:string SubscriptionID, asfx:TopicExpressionType Topics )

Updates an existing subscription. The list of topics specified by Topics will be removed from the subscription. If, after the topics have been removed, no topics remain in the subscription, the subscription will be terminated.

Parameters

  • SubscriptionID: An identifier of the subscription being unsubscribed from.
  • Topics: A list of topics being removed from the subscription.

Return

  • A subscription resource.

Faults

  • asf:SubscriptionNotFoundFault

SOAP Action

  • FASPSessionNET-200601#Unsubscribe

ListSessions

ArrayOf xsd:string ListSessions()

List the active FASP sessions.

Return

  • An array of session IDs.

SOAP Action

  • FASPSessionNET-200601#ListSessions

QuerySession

asfx:SessionType QuerySession( xsd:string SessionID )

Returns information about an active FASP session.

Parameters

  • SessionID: An identifier of the FASP session being queried.

Return

  • A FASP session.

Faults

  • asf:SessionNotFoundFault

SOAP Action

  • FASPSessionNET-200601#QuerySession

SetRateParameters

void SetRateParameters( xsd:string SessionID, asfx:RateParametersType RateParameters )

Sets the rate parameters of a FASP session.

Parameters

  • SessionID: An identifier of the FASP session being modified.
  • RateParameters: Rate parameters to assign to the FASP session.

Faults

  • asf:SessionNotFoundFault

SOAP Action

  • FASPSessionNET-200601#SetRateParameters

SetPolicy

void SetPolicy( xsd:string SessionID, xsd:string Policy )

Sets the rate parameters of a FASP session. Valid values for the Policy argument are Fixed, Fair, and Trickle.

Parameters

  • SessionID: An identifier of the FASP session being modified.
  • Policy: Rate policy to assign to the FASP session.

Faults

  • asf:SessionNotFoundFault

SOAP Action

  • FASPSessionNET-200601#SetPolicy

SetTargetRate

void SetTargetRate( xsd:string SessionID, xsd:unsignedInt TargetRate )

Sets the rate parameters of a FASP session. Valid values for the Policy argument are Fixed, Fair, and Trickle.

Parameters

  • SessionID: An identifier of the FASP session being modified.
  • TargetRate: Target rate, in Kbps, to assign to the FASP session.

Faults

  • asf:SessionNotFoundFault

SOAP Action

  • FASPSessionNET-200601#SetTargetRate

SetMinimumRate

void SetMinimumRate( xsd:string SessionID, xsd:unsignedInt MinimumRate )

Sets the minimum rate of a FASP session.

Parameters

  • SessionID: An identifier of the FASP session being modified.
  • MinimumRate: Minimum rate, in Kbps, to assign to the FASP session.

Faults

  • asf:SessionNotFoundFault

SOAP Action

  • FASPSessionNET-200601#SetMinimumRate

SetBandwidthCap

void SetBandwidthCap( xsd:string SessionID, xsd:unsignedInt BandwidthCap )

Sets the bandwidth cap of a FASP session.

Parameters

  • SessionID: An identifier of the FASP session being modified.
  • BandwidthCap: Bandwidth cap, in Kbps, to assign to the FASP session.

Faults

  • asf:SessionNotFoundFault

SOAP Action

  • FASPSessionNET-200601#SetBandwidthCap

Cancel

void Cancel( xsd:string SessionID )

Cancels a FASP session.

Parameters

  • SessionID: An identifier of the FASP session to cancel.

Faults

  • asf:SessionNotFoundFault

SOAP Action

  • FASPSessionNET-200601#Cancel

 


Data Types

This document includes information on the data types that are defined by the XML schema.

Namespaces

The XML namespaces below are declared and used within the FASPSessionNET-200601 SOAP Web Service.

xsd http://www.w3.org/2001/XMLSchema 
wsdl http://schemas.xmlsoap.org/wsdl/ 
soap http://schemas.xmlsoap.org/wsdl/soap/  
asf http://www.asperasoft.com/xml/faspsession-net/2006/01/FASPSessionNET.wsdl
asfx urn:Aspera:XML:FASPSessionNET:2006/01:Types

AggregateStatisticsType

<asfx:AggregateStatisticsType>

Aggregate statistics related to the transfer.

  • xsd:unsignedInt FileCount - Total number of complete, failed, and transferring files.
  • xsd:unsignedInt FilesComplete - Number of file that have been successfully transferred.
  • xsd:unsignedInt FilesFailed - Number of file that have failed to transfer.
  • xsd:unsignedInt FilesTransferring - Number of files currently being transferred.
  • xsd:unsignedLong BytesWritten - Total number of bytes that have been written to disk.
  • xsd:unsignedLong BytesTransferred - Total number of bytes that have been transferred during the session.
  • xsd:unsignedLong BytesLost - Total number of bytes that have been lost during the session.
  • xsd:unsignedLong uSecondsElapsed - Running time of the session, in microseconds.

ApplicationDataType

<asfx:ApplicationDataType>

Application-level data that will be carried by a FASP session.

  • xsd:string Token - A token used for external authorization.
  • xsd:string Cookie - An arbitrary field used for application-specific requirements.

ClientType

<asfx:ClientType>

Information pertaining to the client endpoint.

  • xsd:string Endpoint - Indicates which endpoint is acting as the client.
    • Valid Values: Local | Remote
  • xsd:string Address - IP address or host name of the system.
  • xsd:unsignedShort FASPPort - FASP (UDP) port over which data is being transferred.

EndportReferenceType

<asfx:EndpointReferenceType>

Represents a system acting as a web services endpoint.

  • xsd:string Address - Uniform Resource Identifier (URI) of the endpoint.
  • xsd:string Action - SOAP action to carry in any messages sent to the system.
    • The SOAP action will vary depending on the web services framework being used. In some cases, it is not required at all. When it is required, it is typically used to route the request to the appropriate handler.

ErrorType

<asfx:ErrorType>

Indicates session error details.

  • xsd:int Code - Error code indicating the reason the session failed. As long as the session is successful, this value will be 0.
  • xsd:string Description - Detiled description of the error that occurred.

FileStatisticsType

<asfx:FileStatisticsType>

File statistics related to the transfer.

  • xsd:string Name - Name of the currently transferring file.
  • xsd:unsignedLong Size - Size, in bytes, of the currently transferring file.
  • xsd:unsignedLong BytesWritten - Total number of bytes that have been written to disk.
  • xsd:unsignedLong BytesContiguous - Total number of bytes that are contiguous on disk.
  • xsd:unsignedLong BytesLost - Total number of bytes that have been lost during the session.
  • xsd:unsignedLong StartByte - The position, in bytes, where the file was started for this session.  Usually, this will be equal to 0. However, in the case of a resumed transfer, this will indicate the the file offset from where the transfer was resumed.
  • xsd:unsignedLong uSecondsElapsed - Running time of the transfer for the current file, in microseconds.
  • xsd:int ErrorCode - Error code indicating the reason the file failed to transfer. As long as the file is being sucessfully transferred, this value will be 0.
  • xsd:string ErrorDescription - Detiled description of the error that occurred.

NetworkSatisticsType

<asfx:NetworkStatisticsType>

Network statistics related to the transfer.

xsd:unsignedInt Delay - This element is currently unused.

xsd:float Efficiency - This element is currently unused.

OperationType

<asfx:OperationType>

Indicates the transfer operation being carried out.

  • xsd:string Operation - Indicates the type of operation. The value of this element will either be Download or Upload, depending on the direction of the transfer. The direction is always determined by viewing the transfer from the perspective of the client.
    • Valid Values: Download | Upload
  • xsd:string SourcePath - This element is unused.
  • xsd:string DestinationPath - This element is unused.

RateParametersType

<asfx:RateParametersType>

Indicates rate-related information pertaining to the transfer.

  • xsd:string Policy - Indicates the rate policy being utilized by the transfer.
    • Valid Values: Fixed | Fair | Trickle 
  • xsd:unsignedInt TargetRate - The target rate of data transmission, in Kbps.
  • xsd:unsignedInt MinimumRate - The minimum rate of data transmission, in Kbps.
  • xsd:unsignedInt BandwidthCap - A cap on data transfer rates, in Kbps.

SecurityParametersType

<asfx:SecurityParametersType>

Indicates security-related pertaining to the transfer.

  • xsd:string EncryptionCipher - Indicates the encryption cipher being used to encrypt data during transfer.
    • Valid Values: None | AES128

ServerType

<asfx:ServerType>

Information pertaining to the server endpoint. 

  • xsd:string Endpoint - Indicates which endpoint is acting as the server.  The value of this element will either be Local or Remote, indicating which endpoint is acting as the server.
    • Valid Values: Local | Remote 
  • xsd:string Address - IP address or host name of the system. 
  • xsd:unsignedShort SSHPort - SSH (TCP) port over which the transfer was initiated.
  • xsd:unsignedShort FASPPort - FASP (UDP) port over which data is being transferred.
  • xsd:string User - The user used to authenticate the transfer.

SessionType

<asfx:SessionType>

Indicates information about a FASP session. 

  • xsd:string SessionID - An identifier that uniquely identifies the session.
  • asfx:ApplicationDataType ApplicationData - Application-level data carried by the session.
  • asfx:OperationType Operation - Operation being performed by the session.
  • asfx:ServerType Server - Server endpoint participating in the session.
  • asfx:ClientType Client - Client endpoint participating in the session.
  • asfx:RateParametersType RateParameters - Rate parameters used by the session.
  • asfx:SecurityParametersType SecurityParameters - Security parameters used by the session.
  • asfx:StatisticsType Statistics - Statistics obtained during the session. 
  • asfx:ErrorType Error - Error details for the session.

StatisticsType

<asfx:StatisticsType>

Statistics related to the transfer.

  • asfx:AggregateStatisticsType Aggregate - Statistics aggregated accross all files transferred during the session.
  • asfx:FileStatisticsType File - Statistics about the current file being transferred during the session.
  • asfx:NetworkStatisticsType Network - Network statistics collected during the session.

SubscriptionResourceType

<asfx:SubscriptionResourceType>

A subscription resource established by an endpoint. 

  • xsd:string ID - An identifier used to uniquely identify the subscription.
  • asfx:EndpointReferenceType Observer - An endpoint that will receive notifications about events occuring to the resource subscribed to. 
  • asfx:TopicExpressionType Topics - A list of topics that the observer is interested in receiving notifications about.
  • xsd:unsignedInt TimeRemaining - The remaining time, in seconds, before the subscription will expire.

TopicExpressionType

<asfx:TopicExpressionType>

Contains an array of topics. 

  • ArrayOf xsd:string Topic - An array of strings that indicate individual topics.

SubscriptionNotFoundFaultType

<asfx:SubscriptionNotFoundFaultType>

A fault indicating that the subscription was not found. 

  • xsd:string SubscriptionID - Subscription identifier.

SessionNotFoundFaultType

<asfx:SessionNotFoundFaultType>

A fault indicating that the session was not found. 

  • xsd:string SessionID - Session identifier.

 


WSDL File

The FASPSessionNET-200601 has a WSDL and XSD file that provides an example binding to http://127.0.0.1:40001/services/soap/FASPSessionNET-200601. These files comprise the services that are used for code generation by the Web Service framework. To use these files you must change the soap:address flag, which is located at the bottom of the WSDL file.

WSDL File

 Download WSDL File

FASPSession.wsdl

 

XSD File

 Download WSDL File

FASPSessionTypes.xsd

 

 


Sample Code

Sample Code

This section includes application examples of submitting job orders using SOAP.  The examples can easily be altered to meet your business logic.  

C# Job Submission

 Download Full ExampleDownload Full Example

To begin with the C# Job Submission example you will need to download the .NET Central SDK code using the Download Full Example link above. It includes all of the dependencies you will need to use in order to make the appropriate calls in your application.  Below is an example C# application showing how to use the dependencies.

C# Source Code

 

PHP Direct Job Submission

 Download Full Example

To begin with the PHP Direct Job Submission example you will need to download the PHP Source code using the link above. The transfer_class.php file serves as a class file that can simply be referenced by your application. The source code for the class file and application is seen below.

PHP Direct Source Code

Application

 

Transfer Class

 

PHP Node API Job Submission

 Download Full Example

To begin with the PHP Node API Job Submission example you will need to download the PHP Source code using the link above. The transfer_class.php file serves as a class file that can simply be referenced by your application. The source code for the class file and application is seen below. In addition to a normal PHP 5 Server you will need the php-curl extension for this example.  If using a WAMP bundle php-curl is most likely already installed.  You can install php5-curl using your preferred package manager, you will need to restart your web server service after installing php-curl.

PHP Node Source Code

Application

 

Transfer Class

 

 


Video player

Video

×