The SOAP Web Service IScpTransferNET-200604 allows an application to monitor and query interactive scp transfer jobs being executed by Aspera Central. This service can be used by applications in both a polling fashion, as well as an event-driven model. Developers familiar with the practice of constructing and deploying service oriented architectures (SOA) should be accustomed to these mechanisms.

This SOAP service is implemented by Aspera Central and runs at the following location:
http://127.0.0.1:40001/services/soap/IScpTransferNET-200604

The actual host and port that this service is located at may vary for each deployed instance of Aspera Central. The path portion, /services/soap/IScpTransferNET-200604, is a well-known location that provides an implementation of this service on all instances of Aspera Central. The SOAP messages transmitted to and received from the service use document/literal style SOAP encoding.

Polling

Applications can poll this service to discover Aspera.IScpTransfer jobs and query them for detailed information. Two messages, ListJobs() and QueryJob(), fulfill the primary requirements for applications operating using polling techniques.

An application can first invoke ListJobs(), which will return an array of job identifiers, one ID for each active Aspera.IScpTransfer job. Once the list of job IDs has been obtained, it can be followed by multiple invocations of QueryJob(), using the IDs discovered. After this has been completed, an application will have full details about any active Aspera.IScpTransfer job.

The polling interval will be determined by the requirements of the application in question. Tradeoffs will need to be made between the granularity of the interval, and the frequency of statistics needed for accuracy. As the polling interval increases, there is a potential to miss information. For example, if the polling interval is 10 minutes, a job that took 8 minutes to complete may never be witnessed by the polling application. For critical applications that need near real-time statistics, operating via notifications is recommended.

Notifications

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 Aspera.IScpTransfer jobs in an event-driven fashion.

In order to operate as an observer, the requirement of operating as a SOAP server, typically using HTTP as a transport layer, is imposed upon the application. This introduces some complexity at the application-level. However, the benefits of being event-driven often justifies this requirement.

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-to topic, a notification will be delivered to the registered endpoint.

The mechanisms employed for delivering notifications are based on two standards within the web services community. The first is Web Services Addressing, which is defined by the W3C. The second is Web Services Notification, defined by OASIS. In actual implementation for this service, only simplified functionality is available, in order to reduce complexity. However, 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 to route any SOAP messages to the appropriate handler. The action is optional, and its value is usually dependent on the web services framework in use.

An application registers a subscription by invoking the Subscribe() method. Included as parameters to this method are twoEndpointReferenceType objects, as well as a TopicExpressionType. A topic expression contains an array of job topics that the application wants to subscribe to. The two endpoint references identify a subscription observer and and a session observer. In the typical case, the address used will be identical for both observers, with only the action being different, in order to route messages 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 be expired or terminated, and maintain it as needed. The observer must implement the SubscriptionNotify() method in order to receive these notifications.

On the other hand, the job 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 job event occurs to which an observer is subscribed, a notification will be delivered through the JobNotify() method, which the observing application must implement.

Service Messages

Subscribe

iscpx:SubscriptionResourceType Subscribe( xsd:string JobID,
iscpx:EndpointReferenceType SubscriptionObserver,
iscpx:EndpointReferenceType JobObserver,
iscpx:TopicExpressionType Topics,
xsd:unsignedInt Duration )
Subscribes to a FASP session.

Parameters
JobID:
An identifier of the job 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 job notifications.

Topics:
A list of topics being subscribed to.

Duration:
Duration, in seconds, before the subscription will expire.

Return
A subscription resource.

Faults
iscp:JobNotFoundException

SOAP Action
IScpTransferNET-200604#Subscribe
If the argument JobID is set to 0, a subscription to all Aspera.IScpTransfer jobs will be established.

UpdateSubscription

iscpx:SubscriptionResourceType UpdateSubscription( xsd:string SubscriptionID,
iscpx:TopicExpressionType Topics,
xsd:unsignedInt Duration )
Updates an existing subscription.

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
iscp:SubscriptionNotFoundFault

SOAP Action
IScpTransferNET-200604#Unsubscribe

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.

Unsubscribe

iscpx:SubscriptionResourceType Unsubscribe( xsd:string SubscriptionID,
iscpx:TopicExpressionType Topics )
Updates an existing subscription.

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
iscp:SubscriptionNotFoundFault

SOAP Action
IScpTransferNET-200604#Unsubscribe

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.

ListJobs

ArrayOf xsd:string ListJobs()
List the active Aspera.IScpTransfer jobs.

Return
An array of job IDs.

SOAP Action
IScpTransferNET-200604#ListJobs

QueryJob

iscpx:IScpTransferType QueryJob( xsd:string JobID )
Returns information about an active Aspera.IScpTransfer job.

Parameters
JobID:
An identifier of the job being queried.

Return
A schema representation of the job.

Faults
iscp:JobNotFoundFault

SOAP Action
IScpTransferNET-200604#QueryJob

Cancel

void Cancel( 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

Observer Messages

SubscriptionNotify

void SubscriptionNotify( xsd:string SubscriptionID,
iscpx:EndpointReferenceType Poster,
xsd:string Topic,
iscpx:SubscriptionResourceType Subscription )
Called to notify an observer of a subscription event.

Parameters
SubscriptionID:
An identifier indicating the subscription for which the event occurred.

Poster:
Indicates what web services endpoint was responsible for posting the event.

Topic:
A topic name, indicating specifically which subscription event occurred.

Subscription:
Schema representation of the subscription at the time of the event.

JobNotify

void JobNotify( xsd:string SubscriptionID,
iscpx:EndpointReferenceType Poster,
xsd:string Topic,
iscpx:IScpTransferType Job )
Called to notify an observer of a session event.

Parameters
SubscriptionID:
An identifier indicating the subscription for which the event occurred.

Poster:
Indicates what web services endpoint was responsible for posting the event.

Topic:
A topic name, indicating specifically which job event occurred.

Job:
Schema representation of the job at the time of the event.

Data Types

The following XML namespaces 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/
  • iscp - http://www.asperasoft.com/xml/iscptransfer-net/2006/04/IScpTransferNET.wsdl
  • iscpx - urn:Aspera:XML:IScpTransferNET:2006/04:Types

ApplicationDataType

<iscpx:ApplicationDataType>
Application-level data carried by any launched FASP session.

Elements:
xsd:string Token
A token used for external authorization.

xsd:string Cookie
An arbitrary field used for application-specific requirements.

ArrayOfMethods

<iscpx:ArrayOfMethods>
SSH methods to use for authentication.

Elements:
ArrayOf xsd:string Method
An array of strings that indicate SSH authentication methods.
Valid Values: Password | Public Key | Keyboard Interactive

ArrayOfPaths

<iscpx:ArrayOfPaths>
Specifies a list of files and/or directories.

Elements:
ArrayOf xsd:string Path
An array of strings that indicate file or directory paths.

AuthenticationType

<iscpx:AuthenticationType>
Specifies parameters used to authenticate on a remote system.

Elements:
xsd:ArrayOfMethods Methods
Specifies a list of SSH authentication methods.

xsd:string KeyPath
Path to the private key used in key-based authentication.

ChannelParametersType

<iscpx:ChannelParametersType>
Specifies channel parameters as submitted with a transfer order.

Elements:
xsd:unsignedShort Port
UDP port over which data is transported.

xsd:unsignedInt DatagramSize
The datagram size FASP uses when transmitting data.

xsd:boolean AutoDetectPathMTU
Indicates whether or not FASP should automatically detect the path MTU (maximum transmission unit).

EndpointReferenceType

<iscpx:EndpointReferenceType>
Represents a system acting as a web services endpoint.

Elements:
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.

FileParametersType

<iscpx:FileParametersType>
Specifies file parameters as submitted with a transfer order.

Elements:
xsd:boolean CreatePath
Specifies whether or not destination directories should be created if they don't exist.

xsd:string ResumeCheck
Specifies the mechanism used when resuming partially transferred files.
Valid Values: None | Attributes | Sparse Checksum | Full Checksum

IScpTransferType

<iscpx:IScpTransferType>
Indicates information about an IScpTransfer job.

Elements:
xsd:string ID
An identifier that uniquely identifies the job.

iscpx:OrderType Order
Original order information, as submitted with the job.

iscpx:StatusType Status
Ongoing status information, as represented by the job.

LinkParametersType

<iscpx:LinkParametersType>
Specifies link parameters as submitted with a transfer order.

Elements:
xsd:unsignedInt RemoteCapacity
Indicates the remote link capacity.

xsd:unsignedInt LocalCapacity
Indicates the local link capacity.

xsd:boolean AutoDetectCapacity
Indicates whether or not FASP should automatically detect the link capacity during transfer.

LocalLocationType

<iscpx:LocalLocationType>
Identifies a local endpoint and file locations.

Elements:
iscpx:ArrayOfPaths Files
Specifies a list of files and/or directories.

OrderType

<iscpx:OrderType>
Represents the original order information, being executed by the job.

Elements:
xsd:string Agent
Identifies the agent responsible for submitting the job.

iscpx:WidgetDataType WidgetData
Specifies user interface details displayed in Aspera Connect.

iscpx:ApplicationDataType ApplicationData
Application-level data carried by any launched FASP session.

xsd:string Operation
Indicates the direction of the transfer.

The value of this element will either be Pull or Push, depending on the direction of the transfer. Pull indicates a download to the local endpoint, while push indicates an upload to the remote endpoint.
Valid Values: Pull | Push

iscpx:RemoteLocationType RemoteLocation
Identifies the remote endpoint and file locations.

iscpx:LocalLocationType LocalLocation
Identifies the local endpoint and file locations.

iscpx:FileParametersType FileParameters
Specifies file parameters as submitted with the transfer order.

iscpx:LinkParametersType LinkParameters
Specifies link parameters as submitted with the transfer order.

iscpx:ChannelParametersType ChannelParameters
Specifies channel parameters as submitted with the transfer order.

iscpx:RateParametersType RateParameters
Specifies rate parameters as submitted with the transfer order.

iscpx:SecurityParametersType SecurityParameters
Specifies security parameters as submitted with the transfer order.

iscpx:RetryParametersType RetryParameters
Specifies retry parameters as submitted with the transfer order.

iscpx:PrivateDataType PrivateDataType
Private data section, to be used as needed by an application.

PrivateDataType

<iscpx:PrivateDataType>
Private data section, to be used as needed by an application.

Elements:
xsd:string Key
Arbitrary field, to be used as needed by an application.

RateParametersType

<iscpx:RateParametersType>
Specifies rate parameters as submitted with a transfer order.

Elements:
xsd:string Policy
Specifies the rate policy the transfer should utilize.
Valid Values: Fixed | Fair | Trickle

xsd:unsignedInt TargetRate
The target rate of data transmission, in Kbps or %.

xsd:boolean TargetRateAsPercent
Indicates whether or not the value of TargetRate should be interpreted as a percentage.

xsd:unsignedInt MinimumRate
The minimum rate of data transmission, in Kbps or %.

xsd:boolean MinimumRateAsPercent
Indicates whether or not the value of MinimumRate should be interpreted as a percentage.

xsd:unsignedInt BandwidthCap
A cap on data transfer rates, in Kbps.

xsd:boolean LockPolicy
Indicates whether or not the policy should be locked.

xsd:boolean LockTargetRate
Indicates whether or not the target rate should be locked.

xsd:boolean LockMinimumRate
Indicates whether or not the minimum rate should be locked.

RemoteLocationType

<iscpx:RemoteLocationType>
Identifies a remote endpoint and file locations.

Elements:
iscpx:SystemType System
Identifies a system on the network.

iscpx:AuthenticationType Authentication
Specifies parameters used to authenticate on the remote system.

iscpx:ArrayOfPaths Files
Specifies a list of files and/or directories.
<iscpx:RetryParametersType>
Specifies retry parameters as submitted with the transfer order.

Elements:
xsd:unsignedByte Count
Number of transfer attempts.

xsd:unsignedInt BaseInterval
Base time interval.

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.

xsd:unsignedInt MaximumInterval
Base time interval.
The maximum time interval limits the increasing of the time interval that occurs as a result of multiple, subsequent failures.

RetryStatisticsType

<iscpx:RetryStatisticsType>
Retry statistics collected during a job.

Elements:
xsd:unsignedByte FailedAttempts
Number of failed transfer attempts.

StatisticsType

<iscpx:StatisticsType>
Statistics related to the job.

Elements:
iscpx:RetryStatisticsType Retry
Retry statistics collected during the job.

StatusType

<iscpx:StatusType>
Represents the status of the order, as it is being executed by the job.

Elements:
xsd:string SessionID
Identifier of the current FASP session launched by the transfer job.

If no FASP session has been launched for the job, this element will contain an empty string.

iscpx:StatisticsType Statistics
Statistics related to the job.

SecurityParametersType

<iscpx:SecurityParametersType>
Specifies security parameters as submitted with a transfer order.

Elements:
xsd:string EncryptionCipher
Specifies the encryption cipher used to encrypt data during transfer.
Valid Values: None | AES-128

SubscriptionResourceType

<iscpx:SubscriptionResourceType>
A subscription resource established by an endpoint.

Elements:
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.

SystemType

<iscpx:SystemType>
Identifies a system on the network.

Elements:
xsd:string Address
IP address or host name of the system.

xsd:string Port
SSH port over which the transfer will be initiated.

xsd:string UserName
A username used to authenticate on the system.

xsd:string Password
A password used to authenticate on the system.

TopicExpressionType

<iscpx:TopicExpressionType>
Contains an array of topics.

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

WidgetDataType

<iscpx:WidgetDataType>
Specifies user interface details displayed in Aspera Connect.

Elements:
xsd:string Icon
URL to an icon that is used in UI elements.

xsd:string Title
A brief title that is used in UI elements.

xsd:string SubTitle
A brief subtitle that is used in UI elements.

xsd:boolean Authorize
Indicates whether or not the user was prompted to authorize the transfer.

xsd:boolean Authenticate
Indicates whether or not the user was prompted to provide credentials for the transfer.

SubscriptionNotFoundFaultType

<iscpx:SubscriptionNotFoundFaultType>
A fault indicating that the subscription was not found.

Elements:
xsd:string SubscriptionID
Subscription identifier.

JobNotFoundFaultType

<iscpx:JobNotFoundFaultType>
A fault indicating that the job was not found.

Elements:
xsd:string JobID
Job identifier.

Notification Topics

Subscription Topics

-Expired

This topic indicates the subscription has expired.

An expired subscription will have its resources released, and any record of it will be removed from Aspera Central. The observer for the subscription will no longer receive notifications.

-Notice

This topic indicates a notice of pending expiration.

This event is posted to the observer whenever the subscription has five minutes remaining before expiration. Upon receiving this notification, the observer has a chance to renew the subscription for a longer duration, so that it will not expire.

-Terminated

This topic indicates the subscription has been terminated.

A subscription can be terminated early if it is determined that events can no longer occur for the subscribed topics. This can happen for any number of reasons. A common example would be the completion of an interactive scp transfer job. In this instance, any subscriptions registered for the completed session can be safely terminated before their natural expiration.

A terminated subscription will have its resources released, and any record of it will be removed from Aspera Central. The observer for the subscription will no longer receive notifications.

Job Topics

-Submitted

This topic indicates the submission of an interactive scp transfer job.

-Connecting

This topic indicates the scp transfer job has launched a FASP session.

The scp transfer job has launched a FASP session, which is attempting to connect to the remote host. Information about the FASP session, if desired, can be obtained from the *Depreciated* Observer (FASPSessionNET-200601) service.

-Retrying

This topic indicates the scp transfer is retrying, after a session failure.

A retrying notification indicates that a FASP session launched by the scp transfer job failed, and that the job will attempt to retry the transfer. A new FASP session will be launched, after the requested retry interval has elapsed. When the new FASP session launches, a Connecting (Above) notification will be posted.

-Concluded

This topic indicates that scp transfer job has concluded.

A job is considered concluded after it has successfully completed file transfer, or all retry attempts have been exhausted.

WSDL File

ISCPTransfer.wsdl

Use this WSDL to generate client-side code that can communicate with Aspera Central. The file IScpTransfer.wsdl provides an example binding. In this case, the service is bound to the following URI: http://127.0.0.1:40001/services/soap/IScpTransferNET-200604.  The actual host and port that this service is located at may vary for each deployed instance of Aspera Central.

 Download File

ISCPTransfer.wsdl

 

IScpTransferTypes.xsd

 Download File

IScpTransferTypes.xsd

 

IScpTransferObserver.wsdl

Use this WSDL to generate server-side code that can observe events from Aspera Central. The file IScpTransferObserver.wsdl provides an example binding for implementing observers. In this case, the service is bound to the following URI: http://127.0.0.1:9999/services/soap/IScpTransferNETObserver-200604. SOAP actions within the example observer binding take the following form: IScpTransferNETObserver-200604#OperationName. The location and SOAP actions used to implement an observer can be chosen by the developer. The values needed to establish communication between endpoints will be specified when registering a subscription.

 Download File

IScpTransferObserver.wsdl

 
Video player

Video

×