FileStreamService.svc methods and messages

This service allows uploading a single file directly into the storage space of any extension that supports file streaming. It returns a unique identifier which can be used in future requests to the Create.Extension.Instance method to refer to the uploaded file for further processing. It is up to the extension to determine the unique identifier and how to process the uploaded file.

Motives for a new uploading method

There are two important motives for having an alternative method of uploading files:

  1. Using the upload method of the FileService the data has to be stored in a temporary storage from the Organisation API, even though it is not actually ever used by the Organisation API. This means that we need to do unnecessary file transfers, significantly impacting the performance of the Organisation API. For example, creating pages using the new file upload method should be significantly faster than before.

  2. It allows for a uniform method for 3rd party extensions to also support hooking into the Organisation API. Together with the new GetExtensions and Create.Extension.Instance method it will become possible for any 3rd party extension to be created using the Organisation API.

The differences between the old and new upload

We separate the upload of files from the creation of migrated content as the same file often appears in multiple areas of itslearning. Files can be created in multiple sections of itslearning, but only need to be uploaded once. This rule does not apply to extensions. When uploading to extension, file can be used only once.

The files have to be uploaded as streams. It gives a certain performance benefit, as opposed to using the FileService.svc methods which use buffering. The methods use MTOM encoding instead of Base64. For optimal performance, client should use chunked transfer encoding. Files are retained in the temporary area for 14 days and are then removed. They can be re-uploaded if required.

This is a synchronous message.

Please note that file uploads are limited to 500MB.

Following file extensions are denied for upload:

  • empty file extension

  • .exe

  • .com

  • .vb

  • .vbs

  • .vbe

  • .cmd

  • .bat

  • .ws

  • .wsf

  • .src

  • .shs

  • .pif

  • .hta

  • .jar

  • .js

  • .jse

  • .lnk

Header input parameters

Name

Description

Type

Mandatory/Optional

SiteId

Site where action will be executed.

Integer

Optional

ExtensionId

The extension the file should be streamed to. This must be an extension which supports file streaming.

Integer

Mandatory

Name

Name of the file, including file extension (ex: test.txt).

Text

Mandatory

Body input parameters

Name

Description

Type

Mandatory/Optional

Content

File content.

Stream

Mandatory


Sample request with MTOM enabled:

Sample request (MTOM enabled)
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="http://tempuri.org/">
<soapenv:Header>
<tem:Name>NameOfTheFile.jpg</tem:Name>
<tem:ExtensionId>5</tem:ExtensionId>
</soapenv:Header>
<soapenv:Body>
<tem:StreamMessage>
<tem:Content><Include href="cid:file" xmlns="http://www.w3.org/2004/08/xop/include"/></tem:Content>
</tem:StreamMessage>
</soapenv:Body>
</soapenv:Envelope>
{RAW BYTES TO BE ADDED HERE}

Sample complete RAW request with MTOM enabled:

Sample complete RAW request with MTOM enabled
POST https://migra.itslearning.com/FileStreamService.svc HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: multipart/related; type="application/xop+xml"; start="<rootpart@soapui.org>"; start-info="text/xml"; boundary="----=_Part_21_6337481.1433166616124"
SOAPAction: "http://tempuri.org/IFileStreamService/UploadFile"
MIME-Version: 1.0
Content-Length: 2725
Host: migra.a11.loc
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
 
------=_Part_21_6337481.1433166616124
Content-Type: application/xop+xml; charset=UTF-8; type="text/xml"
Content-Transfer-Encoding: 8bit
Content-ID: <rootpart@soapui.org>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="http://tempuri.org/">
<soapenv:Header>
<wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<wsse:UsernameToken wsu:Id="UsernameToken-4A463033B84B8D6A4F143316661612422">
<wsse:Username>username</wsse:Username>
<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">password</wsse:Password>
<wsse:Nonce EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary">eh6/O0zWuDWLpu/0rEZT4A==</wsse:Nonce>
<wsu:Created>2015-06-01T13:50:16.123Z</wsu:Created>
</wsse:UsernameToken>
</wsse:Security>
<tem:Name>soapui32.png</tem:Name>
<tem:ExtensionId>5000</tem:ExtensionId>
</soapenv:Header>
<soapenv:Body>
<tem:StreamMessage>
<tem:Content>
<inc:Include href="cid:soapui32.png" xmlns:inc="http://www.w3.org/2004/08/xop/include"/>
</tem:Content>
</tem:StreamMessage>
</soapenv:Body>
</soapenv:Envelope>
------=_Part_21_6337481.1433166616124
Content-Type: application/octet-stream
Content-Transfer-Encoding: binary
Content-ID: <soapui32.png>
Content-Disposition: attachment; name="soapui32.png"
[Raw bytes here]

Sample response:

Sample response
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<s:Header>
<o:Security s:mustUnderstand="1" xmlns:o="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
<u:Timestamp u:Id="_0">
<u:Created>2013-10-25T12:06:35.899Z</u:Created>
<u:Expires>2013-10-25T12:11:35.899Z</u:Expires>
</u:Timestamp>
</o:Security>
</s:Header>
<s:Body>
<FileStreamUploadResponse xmlns="http://tempuri.org/">
<FileId>6277b5bc-e408-478c-aad3-e86fcc32a269</FileId>
</FileStreamUploadResponse>
</s:Body>
</s:Envelope>