Thru rest api_1_0_ref_1_7

Thru REST API 1.0 / Reference 1.7 www.thruinc.com | © 2014 Thru, Inc. All rights reserved

Thru REST API Version 1.0 Programming Reference Version 1.7

PROGRAMMING REFERENCE

Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved |

Table of Contents

Table of Contents .......................................................................................................................................................... 2

1 General .................................................................................................................................................................. 5

2 Overview ................................................................................................................................................................ 6

2.1 Web Service REST Design ............................................................................................................................ 6

2.2 Versioning ...................................................................................................................................................... 7

3 Thru REST Services API Security ....................................................................................................................... 8

3.1 Access Signature (HTTP Header) ................................................................................................................. 8

4 Exception Handling .............................................................................................................................................. 9

4.1 Error Response .............................................................................................................................................. 9 4.1.1 Error Data Transfer Object ........................................................................................................................ 9

4.2 Error Codes .................................................................................................................................................... 9

5 Web Service Data Specifications ...................................................................................................................... 10

5.1 API Data Types ............................................................................................................................................ 10

5.2 API Complex Data Constructions ................................................................................................................ 10

5.3 Session Resources ...................................................................................................................................... 10 5.3.1 ThruSessionRequest Structure ............................................................................................................... 10 5.3.2 ThruPublicSession Structure ................................................................................................................... 11

5.4 File System Resources ................................................................................................................................ 12 5.4.1 ThruPublicFolderInfo Structure ................................................................................................................ 12 5.4.2 ThruPublicFileInfo Structure .................................................................................................................... 14 5.4.3 ThruPublicContentResult Structure ......................................................................................................... 16

5.5 Message Resources .................................................................................................................................... 17 5.5.1 ThruPublicMessageInfo Structure ........................................................................................................... 17 5.5.2 ThruPublicMessagesListResult Structure ............................................................................................... 20 5.5.3 ThruPublicMessageRecipientInfo ............................................................................................................ 21

5.6 Search Resources ....................................................................................................................................... 22 5.6.1 ThruPublicSearchCriteria Structure ......................................................................................................... 22

5.7 Server Resources ........................................................................................................................................ 24 5.7.1 ThruPublicServerInfo Structure ............................................................................................................... 24 5.7.2 ThruMessageSettings Structure .............................................................................................................. 24 5.7.3 ThruPasswordSettings Structure ............................................................................................................. 26 5.7.4 ThruUploadSettings Structure ................................................................................................................. 27 5.7.5 ThruMobileSettings .................................................................................................................................. 29

5.8 System Log Resources ................................................................................................................................ 29 5.8.1 ThruPublicSystemLogOperation.............................................................................................................. 29

5.9 Ticket Resource ........................................................................................................................................... 30 5.9.1 ThruTicketInfo Structure .......................................................................................................................... 30

5.10 User Resources ........................................................................................................................................... 31 5.10.1 ThruPublicUserInfo Structure .............................................................................................................. 31 5.10.2 ThruPasswordInfo Structure ............................................................................................................... 33


5.11 Service Resources ....................................................................................................................................... 33 5.11.1 ThruServiceVersion Structure ............................................................................................................. 33 5.11.2 ThruServiceVersionsResult Structure ................................................................................................. 34

5.12 Server Version Resources ........................................................................................................................... 35 5.12.1 ThruServerVersion Structure .............................................................................................................. 35

6 Web Services ...................................................................................................................................................... 37

6.1 Authentication Service ................................................................................................................................. 37 6.1.1 POST New Session Object ..................................................................................................................... 37 6.1.2 DELETE Existing Session Object ............................................................................................................ 37 6.1.3 CHECK Existing Session Object ............................................................................................................. 37

6.2 File System Service ..................................................................................................................................... 38 6.2.1 POST New Folder Information ................................................................................................................ 38 6.2.2 GET Existing Folder Information ............................................................................................................. 38 6.2.3 PUT Updated Folder Information ............................................................................................................. 39 6.2.4 DELETE Existing Folder .......................................................................................................................... 39 6.2.5 GET Home Folder Information ................................................................................................................ 40 6.2.6 GET List of Files and Folders Inside a Home Folder .............................................................................. 40 6.2.7 GET List of Files Inside a Home Folder .................................................................................................. 41 6.2.8 GET List of Folders Inside a Home Folder ............................................................................................. 41 6.2.9 GET Root Folder Information .................................................................................................................. 41 6.2.10 GET List of Files and Folders Inside a Root Folder ............................................................................ 42 6.2.11 GET List of Files Inside a Root Folder ................................................................................................ 42 6.2.12 GET List of Folders Inside a Root Folder ............................................................................................ 42 6.2.13 GET List of Files and Folders Inside a Folder ..................................................................................... 43 6.2.14 GET List of Files Inside a Folder ......................................................................................................... 43 6.2.15 GET List of Folders Inside a Folder .................................................................................................... 44 6.2.16 GET Existing File Information ............................................................................................................. 44 6.2.17 PUT Updated File Information ............................................................................................................. 44 6.2.18 DELETE Existing File .......................................................................................................................... 45

6.3 Message Service ......................................................................................................................................... 46 6.3.1 POST New Thru Message ....................................................................................................................... 46 6.3.2 GET Existing Thru Message .................................................................................................................... 47 6.3.3 DELETE Existing Thru Message ............................................................................................................. 47 6.3.4 PUT Updated Thru Message ................................................................................................................... 48 6.3.5 PUT Discard Thru Message .................................................................................................................... 49 6.3.6 PUT Complete Thru Message ................................................................................................................. 49 6.3.7 GET SentThru List ................................................................................................................................... 49 6.3.8 POST Project Message Storage ............................................................................................................. 50

6.4 Search Service ............................................................................................................................................. 50 6.4.1 POST Find All Thru Files and Folders by Search Criteria ....................................................................... 50 6.4.2 POST Find All Thru Folders by Search Criteria ...................................................................................... 51 6.4.3 POST Find All Thru Files by Search Criteria ........................................................................................... 51

6.5 Server Service ............................................................................................................................................. 52 6.5.1 GET Server Information ........................................................................................................................... 52 6.5.2 GET Message Settings ............................................................................................................................ 52 6.5.3 GET Password Settings .......................................................................................................................... 52 6.5.4 GET Upload Settings ............................................................................................................................... 53 6.5.5 GET Mobile settings ................................................................................................................................ 53

6.6 Favorites Service ......................................................................................................................................... 53 6.6.1 PUT Folder to Favorites .......................................................................................................................... 53 6.6.2 DELETE Folder from Favorites ............................................................................................................... 54 6.6.3 PUT File to Favorites ............................................................................................................................... 54 6.6.4 DELETE File from Favorites .................................................................................................................... 54


6.6.5 GET All Content in Favorites ................................................................................................................... 56 6.6.6 GET Files in Favorites ............................................................................................................................. 56 6.6.7 GET Folders in Favorites ......................................................................................................................... 56

6.7 Service Versions Service ............................................................................................................................. 57 6.7.1 GET Information about Service Versions ................................................................................................ 57

6.8 System Log Service ..................................................................................................................................... 57 6.8.1 POST System Log Operation .................................................................................................................. 57

6.9 Ticket Service............................................................................................................................................... 58 6.9.1 POST New Ticket .................................................................................................................................... 58

6.10 User Service................................................................................................................................................. 58 6.10.1 GET User Information ......................................................................................................................... 58 6.10.2 PUT New Password for the User ........................................................................................................ 58

6.11 Server Version Service ................................................................................................................................ 59 6.11.1 GET Information About Server Version............................................................................................... 59

7 Programmatic File and Folder Transfers. ........................................................................................................ 60

7.1 Downloading. ............................................................................................................................................... 60

7.2 Uploading Files and Folders via basic protocol (deprecated) ...................................................................... 61

7.3 Uploading of files via Extended File Upload/Download Protocol ................................................................. 62

8 File Transfer User Interface Tools .................................................................................................................... 63

8.1 Upload Java/HTML5/HTML4 Tool and API ................................................................................................. 63 8.1.1 Overview .................................................................................................................................................. 63 8.1.2 Security Token ......................................................................................................................................... 63 8.1.3 Upload Tool URL Parameters, option with no Security Token. ............................................................... 64 8.1.4 Upload Tool URL Parameters, option with Security Token. .................................................................... 65 8.1.5 Server Error Codes .................................................................................................................................. 65 8.1.6 JavaScript Samples ................................................................................................................................. 66 8.1.7 URL Samples ........................................................................................................................................... 67

8.2 Java/HTML Download Tool and API ............................................................................................................ 68 8.2.1 Overview .................................................................................................................................................. 68 8.2.2 Security Token ......................................................................................................................................... 68 8.2.3 Download Tool URL Parameters, option with no Security Token ........................................................... 69 8.2.4 Download Tool URL Parameters, option with Security Token ................................................................ 69 8.2.5 Server Error Codes .................................................................................................................................. 71 8.2.6 JavaScript Samples ................................................................................................................................. 71 8.2.7 URL Sample ............................................................................................................................................ 72

Appendix A – Error Codes returned by RESTAPI .................................................................................................... 73

About Trademarks and Abbreviations ...................................................................................................................... 76


1 General

THE PURPOSE OF THIS DOCUMENT IS TO DESCRIBE THRU WEB SERVICES API, ITS PUBLIC ENDPOINTS, DATA SPECIFICATIONS AND ARCHITECTURE. THE DOCUMENT ALSO REVIEWS THE SECURITY, AUTHENTICATION AND SIDE BY SIDE VERSIONING. WS API IMPLEMENTATION UTILIZES ASP.NET MVC REST SDK WHICH PROVIDES AUTOMATIC SERIALIZATION TO AND FROM THE SERVICE DATA OBJECTS.

THIS REFERENCE GUIDE DESCRIBES AND SUMMARIZES THE THRU REST API. THIS DOCUMENT HAS BEEN PREPARED SOLELY FOR INFORMATIONAL PURPOSES AND IS BEING FURNISHED FOR USE BY CUSTOMERS. DISTRIBUTION OF THIS DOCUMENT IS LIMITED TO CUSTOMERS.

THE REFERENCE GUIDE AND ALL INFORMATION CONTAINED HEREIN ARE OF A CONFIDENTIAL NATURE. EACH RECIPIENT WILL TREAT IT IN A CONFIDENTIAL MANNER. SUCH RECIPIENT WILL, NOT DIRECTLY OR INDIRECTLY, DISCLOSE OR PERMIT ITS AGENTS, REPRESENTATIVES, EMPLOYEES, OFFICERS, DIRECTORS OR AFFILIATES TO DISCLOSE ANY SUCH INFORMATION AND SUCH RECIPIENT WILL USE THE DOCUMENT AND ANY RELATED INFORMATION ONLY TO ACCESS THE THRU SERVICE. IF EITHER THE RECIPIENT OR THE COMPANY ELECTS NOT TO PURSUE OR CONTINUE WITH THE THRU SERVICE, THE RECIPIENT MUST RETURN THIS DOCUMENT AND ANY OTHER MATERIAL RELATING TO THE THRU. SERVICE AND THRU, LLC., WITHOUT RETAINING ANY COPIES THEREOF.

THE INFORMATION CONTAINED HEREIN IS PROVIDED ON A CONFIDENTIAL BASIS AND MAY NOT BE REPRODUCED IN WHOLE OR IN PART.

IF YOU REQUIRE ANY MORE INFORMATION REGARDING THE THRU SERVICE PLEASE CONTACT:

THRU. HELP CENTER [email protected] 800.871. 9316


2 Overview

2.1 Web Service REST Design

The Thru REST Services API adheres to the following points of the REST paradigm:

• Interaction between client and server is semi-stateless (no connection is established, but session is used to authorize user)

• The API leverages existing features of the HTTP protocol (URL, headers, request body), not requiring any special messaging protocol/library (SOAP or RPC)

• Platform-independence (client can be running on any operating system)

• Language-independence (client can be developed in any language of preference)

• Request body should be present in application/x-www-form-urlencoded format serialized as a standard query string: a=1&b=2&c=3&d=4&e=5 The standard HTTP header Accept is used to define a data format that will be provided for client in Response. The currently supported formats are:

o Accept: application/xml

o Accept: application/json

• Response data are not bound to a specific format (e.g.: SOAP receives and returns data always in XML). Though the standard data exchange format used in REST architectures (as well as in the Thru API) is XML, the Thru API also supports JSON and, in fact, can be expanded to support other formats in the future. The exchanged data format is determined by the standard HTTP headers Content-Type. The currently supported formats:

o Content-Type:application/xml

o Content-Type:application/json

• API endpoints are designed around resources (e.g.: files, messages) that are identified by uniform URIs. For instance, all API endpoints built for dealing with file system objects start with the same URI https://[ThruWebServer]/REST/[version]/FileSystem. The type of action to be performed on the resource is designated by passing standard HTTP verbs:

o GET (Retrieve resource/resources)

o POST (Create a new resource)

o PUT (Update an existing resource)

o DELETE (Delete an existing resource)


2.2 Versioning

To support changes in the API signature, without breaking existing clients, the Thru REST Services API supports side-by-side versioning. Different versions of the same endpoints can be made available using different URIs, based on the version number.

For instance, if the Thru REST Service API has two versions (1.0 and 1.1), we have two sets of the File URIs:

Version 1.0: http://[ThruWebServer]/REST/1.0/FileSystem/File

Version 1.1: http://[thruWebServer]/REST/1.1/FileSystem/File


3 Thru REST Services API Security

3.1 Access Signature (HTTP Header)

Access to the Thru REST API is secured through the usage of session identifier provided as part of the request header. This session identifier should be received from the Authenticator service (see below). All interactions with Thru REST Services API should take place over HTTPS. However some actions that do not require security mechanisms should be available over HTTP.

Also session identifier allows the API to identify the caller and enforce the necessary access rules to the invoked endpoint.

Note: Not all endpoints require authenticated access. If an endpoint does require authenticated access, the client needs to pass session ID in the Authorization request header:

• Authorization: SessionID


4 Exception Handling

In case of error, besides returning the standard HTTP Server error code (500), the Thru REST Services API endpoints will return more detailed information about the error in a structured format as part of response body.

4.1 Error Response

4.1.1 Error Data Transfer Object

Item Name Data Type Sample Value Comments

Message String “Invalid File ID:

12345”

Describes the type of error, indicating (when possible) which input value(s) could have caused the error

ErrorCode Integer 7001 A numeric code that identifies the type of error

Sample response(in XML)

<ErrorInfo xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<Message>Session no longer exists.</Message>

<ErrorCode>101</ErrorCode>

</ErrorInfo>

4.2 Error Codes

Each type of error generated by the Thru REST Services API has its own numeric code, which is returned in the

ErrorCode field of the ErrorInfo object. The codes can be used to determine client course of action. For the actual

error codes, check Appendix A.


5 Web Service Data Specifications

5.1 API Data Types

The following primitive data types are used by the Thru REST Services API:

String: Sequence of characters in UTF-8 encoding. Empty string is used to represent a non-initialized string value

Integer: 32-bit integer number. Empty value indicates NULL-value

Long: 64-bit integer number. Empty value indicates NULL-value

Boolean: Boolean value. Possible values: True, False. Empty value indicates NULL-value

DateTime: Represents an instant in time, expressed as a date and time of day. In Thru REST services API, Empty value indicates NULL-value. DateTime is represented as a JSON string in following format /Date(ticks)/, where ticks represents the number of milliseconds since January 1, 1970 in Universal Coordinated Time (UTC). Example: “/Date(1337174868623)/”.

5.2 API Complex Data Constructions

The following complex data constructions are used by the Thru REST Services API:

Collection<T>: A collection of objects of the same type. The following XML formatting is used to pass any collection between client and server:

5.3 Session Resources

5.3.1 ThruSessionRequest Structure

ThruSessionRequest structure contains information required for the Thru user authentication.


UserName String Test Username of the user in the system

Password String Password Password of the user

ApplicationId String 12 Application ID through which is sign-in

ClientVersion String 1 Version of the client application

Sample XML

<FileNames>

<String>Name #1</String>

<String>Another Name</String>

</FileNames>

Corresponding Object

Collection<string> FileNames;


Sample Request

UserName=Test&Password=Password&ClientVersion=1&ApplicationId=12

Sample Response

Data Transfer Object

public class ThruSessionRequest

{

public string UserName

public string Password

public string ApplicationId

public string ClientVersion

}

5.3.2 ThruPublicSession Structure

ThruPublicSession structure contains authorization information about user.


SessionID String TOjoy3c1LyReUsXqXX/7u3+0qv

FYXGArgsZ1k0OEGhIfwB2cd365+SCM8Rs5

JOLPMD/IJJSd2Jy7IXLl5t685kgRJo0Tr

bup/VDN+25Lkenh387d4pXJzObepqO

qusnnsA4de+5r4PHfdN0

9niJtsoSOjWZ6XlEN

Unique identification value required for user authorization

UserID Integer 315KQM487N2EV Unique identification number of the user associated with SessionID value

Sample

<?xml version="1.0" encoding="utf-8"?>

<ThruPublicSession xmlns:xsd="http://www.w3.org/2001/XMLSchema"


<SessionId>PKJEkiY2UHPRyWrY3s9pmpk34iTkNSdFoNBD04jUojajM9qJXUwQULllv1R4+Olqhe5fYRo

8qHk+qDzaMOqkv4YAPX4jI6i5E4Il1+qbwl2QJ/OXfEr4MczMSXMFJIgQu5Ed5eani

kXAvIo9mzipP3hPh/LJSwWs

</SessionId>

<UserId>1Q1OBQWVHTROE</UserId>

</ThruPublicSession>



public class ThruPublicSession

{

public string SessionID;

public int UserID;

}

5.4 File System Resources

5.4.1 ThruPublicFolderInfo Structure

ThruPublicFolderInfo structure contains information about folder in Thru file system.


FolderID Integer 0QN8H2VKTGIWE Unique identification number for the folder in Thru file system

ParentFolderID Integer 11ETULS0966VI Unique identification number of the parent folder for the file in Thru file system.

Root folder contains NULL as a value of ParentFolderID field

Name String Admin Name of the folder

Path String FOLDERS/HOME/Admin Path to the folder in folder tree

Description String Description of the folder

Tags Collection<String> Collection of keywords associated with the current folder

Size Long 2450294218 Size of the folder

EffectivePermission Integer 254 Permissions that describe the rights of the current authenticated user over the folder. Each right is linked with the corresponding bit of the EffectivePermission field value in a binary code:

None = 0x00

Show = 0x01

Read = 0x02

Create = 0x04

Download = 0x08

Distribute = 0x010

Manage = 0x020

Modify = 0x040

Delete = 0x080

For example, full control over a folder is equal to the EffectivePermission value of 0x00FF


DateCreated DateTime /Date(1337174868623)/ Date and time when file has been created in Thru file system (UTC)

DateModified DateTime /Date(1337174868623)/ Date and time when file last has been updated (UTC)

CreatedByUserID Integer 1Q1OBQWVHTROE Unique identification number of the user that has added file to Thru file system

ModifiedByUserID Integer 1Q1OBQWVHTROE Unique identification number of the user that last accessed the file

InFavorite Boolean false Indicates is folder marked as favorite

FolderType Integer 0 0 – a regular folder

1 – root folder

2 – home folder

3 – a user’s “My Documents”

folder

4 – a user’s drop box

folder

5 – root folder for common

folders/files

6 – root folder for home

folders

Sample XML

<ThruPublicFolderInfo xmlns:xsd="http://www.w3.org/2001/XMLSchema"


<FolderId>0QN8H2VKTGIWE</FolderId>

<ParentFolderId>11ETULS0966VI</ParentFolderId>

<Name>Admin</Name>

<Path>FOLDERS/HOME/Admin</Path>

<Tags></Tags>

<Size>2450294218</Size>

<EffectivePermission>254</EffectivePermission>

<DateCreated>/Date(1337174868623)/</DateCreated>

<DateModified>/Date(1337174868623)/</DateModified>

<CreatedByUserId>1Q1OBQWVHTROE</CreatedByUserId>

<ModifiedByUserId>1Q1OBQWVHTROE</ModifiedByUserId>

<InFavorite>false</InFavorite>

<FolderType>0</FolderType>

</ThruPublicFolderInfo>


public class ThruPublicFolderInfo

{

public string FolderId

public string ParentFolderId


public string Name

public string Description

public string Path

public string[] Tags

public long? Size

public int? EffectivePermission

public ThruServerDateTime DateCreated

public ThruServerDateTime DateModified

public string CreatedByUserId

public string ModifiedByUserId

public bool? InFavorite;

public int? FolderType;

}

5.4.2 ThruPublicFileInfo Structure

ThruPublicFileInfo structure contains information about file in Thru file system.


FileID Integer 2OMFYXLA6BP9D Unique identification number for the file in Thru file system

ParentFolderID Integer 1UTXM50KW0ISP Unique identification number of the parent folder for the file in Thru file system

Name String 2.html Name of the file

Description String Description of the file

Path FOLDERS/HOME/Admin/

My Documents/2.html

Path to the file in folder tree

Tags Collection<String> Collection of keywords associated with the current folder

Size Long 198 Size of the file

EffectivePermission Integer 254 Permissions that describe the rights of the current authenticated user over the file. Each right is linked with the corresponding bit of the EffectivePermission field value in a binary code:

None = 0x00

Show = 0x01

Read = 0x02

Create = 0x04

Download = 0x08

Distribute = 0x010


Manage = 0x020

Modify = 0x040

Delete = 0x080

DateCreated DateTime /Date(1346072694480)/ Date and time when file has been created in Thru file system (UTC)

DateModified DateTime /Date(1346072694480)/ Date and time when file last has been updated (UTC)

CreatedByUserID Integer 1Q1OBQWVHTROE Unique identification number of the user that has added file to Thru file system

ModifiedByUserID Integer 1Q1OBQWVHTROE Unique identification number of the user that last accessed the file

IsQuarantined Boolean false Indicates is file has been quarantined

InFavorite

Boolean false Indicates is file marked as favorite

Sample XML

<?xml version="1.0" encoding="utf-8" ?>

<ThruPublicFileInfo xmlns:xsd="http://www.w3.org/2001/XMLSchema"


<FileId>2OMFYXLA6BP9D</FileId>

<ParentFolderId>1UTXM50KW0ISP</ParentFolderId>

<Name>2.html</Name>

<Path>FOLDERS/HOME/Admin/My Documents/2.html</Path>

<Tags></Tags>

<Size>198</Size>






<IsQuarantined>false</IsQuarantined>


</ThruPublicFileInfo>


public class ThruPublicFileInfo

{

public string FileId;

public string ParentFolderId;

public string Name;

public string Description;

public string Path;


public string[] Tags;

public long? Size;

public int? EffectivePermission;

public ThruServerDateTime DateCreated;

public ThruServerDateTime DateModified;

public string CreatedByUserId;

public string ModifiedByUserId;

public bool? IsQuarantined;

public bool? InFavorite;

}

5.4.3 ThruPublicContentResult Structure

ThruPublicContentResult structure contains information about the content of the Thru folder.


Files Collection<

ThruPublicFileInfo >

Collection of file information structures

Folders Collection<ThruPublicFolderInfo > Collection of folder information structures

Sample XML

<?xml version="1.0" encoding="utf-8" ?>

<ThruPublicContentResult xmlns:xsd="http://www.w3.org/2001/XMLSchema"


<Folders>

<ThruPublicFolderInfo>

<FolderId>16LTFSCFLMF01</FolderId>


<Name>test</Name>

<Path>FOLDERS/HOME/Admin/My Documents/test</Path>

<Tags></Tags>

<Size>470968940</Size>

<ChildFoldersCount>1</ChildFoldersCount>

<ChildFilesCount>4</ChildFilesCount>







<FolderType>0</FolderType>

</ThruPublicFolderInfo>

</Folders>


<Files>

<ThruPublicFileInfo>

<FileId>2OMFYXLA6BP9D</FileId>


<Name>2.html</Name>

<Path>FOLDERS/HOME/Admin/My Documents/2.html</Path>

<Tags></Tags>

<Size>198</Size>






<IsQuarantined>false</IsQuarantined>


</ThruPublicFileInfo>

</Files>

</ThruPublicContentResult>


public class ThruPublicContentResult

{

public ThruPublicFolderInfo[] Folders;

public ThruPublicFileInfo[] Files;

}

5.5 Message Resources

5.5.1 ThruPublicMessageInfo Structure

ThruPublicMessageInfo structure contains information about Thru message.


MessageID Integer 1HPHF1D8FF8S0 Unique identification number of the message

UserID Integer 1Q1OBQWVHTROE Unique identification number of the user that is creator of message

Subject String test Subject of the message

DateCreated DateTime /Date(1337611985780)/ Date and time when the message has been created (UTC)

DateSent DateTime /Date(1337611985780)/ Date and time when the message has been sent


(UTC)

DateExpired DateTime /Date(1357070340000)/ Date and time after which message is concerned as expired (UTC)

CollectedFlag Boolean True Indicates does message were read at least by one of recipients

PublicMessage String Public text Text of the private part of the message

PrivateMessage String Private text Text of the public part of the message

TrackingNo String T478-026-95732-36971 Number over the message is registered in Thru

RequestLogin Boolean false Flag that indicate is the message request login for access by recipient

SendByClient Boolean false Flag that indicate is the message was sent through the Thru Site or application.

NotifyFlag Boolean false Flag that indicate is the notifications must be sent.

Priority Integer 3 1 - High

2 - Low

3 - Normal

IsExpired Boolean False Flag indicate is the message is expired

ExpireNow Boolean False

MsgHtmlTemplate String Html template over a message will be created

MsgTextTemplate String Text template over a message will be created

ToRecipients Collection

<ThruPublicMessageRecipientInfo>

List of recipient email addresses

CcRecipients Collection


List of Cc recipients

BccRecipients Collection


List of Bcc recipients

FoldersAttached Collection<ThruPublicFolderInfo > Collection of Folder identifiers


FilesAttached Collection<ThruPublicFolderInfo > Collection of File identifiers

Sample XML

<ThruPublicMessageInfo xmlns:xsd="http://www.w3.org/2001/XMLSchema"


<MessageId>0A2POFJY8EB8Q</MessageId>


<Subject>subject</Subject>


<DateSent></DateSent>

<DateExpired>/Date(1353069302683)/</DateExpired>

<CollectedFlag>false</CollectedFlag>

<PublicMessage>body public</PublicMessage>

<PrivateMessage>body private</PrivateMessage>

<TrackingNo>T478-026-61916-68489</TrackingNo>

<RequestLogin>false</RequestLogin>

<SendByClient>true</SendByClient>

<NotifyFlag>true</NotifyFlag>

<Priority>3</Priority>

<IsExpired>false</IsExpired>

<ExpireNow>false</ExpireNow>

<MsgHtmlTemplate><!DOCTYPE HTML PUBLIC "

-/W3C//DTD HTML 4.01 Transitional//EN">

<html> <body> <span><br/>

<thru:bodyToken/>

</span&gt</body> </html></MsgHtmlTemplate>

<MsgTextTemplate>

This email includes secure access to files.

<thru:bodyToken/>

</MsgTextTemplate>

<ToRecipients>


<MsgId>0A2POFJY8EB8Q</MsgId>

<RecipientId>0MS5JFHL8E7N5</RecipientId>

<RecipientEmail>[email protected]</RecipientEmail>

<Collected>false</Collected>

</ThruPublicMessageRecipientInfo>

</ToRecipients>

<CcRecipients></CcRecipients>

<BccRecipients></BccRecipients>

<FoldersAttached></FoldersAttached>

<FilesAttached></FilesAttached>

</ThruPublicMessageInfo>



public class ThruPublicMessageInfo

{

public string MessageId

public string UserId

public string Subject


public ThruServerDateTime DateSent

public ThruServerDateTime DateExpired

public bool? CollectedFlag

public string PublicMessage

public string PrivateMessage

public string TrackingNo

public bool? RequestLogin

public bool? SendByClient

public bool? NotifyFlag

public int? Priority

public bool? IsExpired

public bool? ExpireNow

public string MsgHtmlTemplate

public string MsgTextTemplate

public ThruPublicMessageRecipientInfo[] ToRecipients

public ThruPublicMessageRecipientInfo[] CcRecipients

public ThruPublicMessageRecipientInfo[] BccRecipients

public ThruPublicFolderInfo[] FoldersAttached

public ThruPublicFileInfo[] FilesAttached

}

5.5.2 ThruPublicMessagesListResult Structure

ThruPublicMessagesListResult structure contains collection of Thru messages.


Messages Collection<ThruPublicMessageInfo > Collection of Messages

Sample XML

<ThruPublicMessagesListResult xmlns:xsd="http://www.w3.org/2001/XMLSchema"


<Messages>

<ThruPublicMessageInfo>

<MessageId>1R6NE5OZ8QHXA</MessageId>


<Subject>qsdasdfasd</Subject>


<DateSent>/Date(1337718371363)/</DateSent>


<DateExpired>/Date(1337975940000)/</DateExpired>

<CollectedFlag>true</CollectedFlag>

<PublicMessage></PublicMessage>

<PrivateMessage></PrivateMessage>

<TrackingNo>T478-026-14576-91611</TrackingNo>

<RequestLogin>false</RequestLogin>

<SendByClient>false</SendByClient>

<NotifyFlag>false</NotifyFlag>

<Priority>3</Priority>

<IsExpired>true</IsExpired>

<ExpireNow>false</ExpireNow>

<ToRecipients>


<MsgId>1R6NE5OZ8QHXA</MsgId>

<RecipientId>2MIMZFR1K0471</RecipientId>


<Collected>true</Collected>


</ToRecipients>

<CcRecipients></CcRecipients>

<BccRecipients></BccRecipients>

<FoldersAttached></FoldersAttached>

<FilesAttached></FilesAttached>

</ThruPublicMessageInfo>

</Messages>

</ThruPublicMessagesListResult>


public class ThruPublicMessagesListResult

{

public ThruPublicMessageInfo[] Messages

}

5.5.3 ThruPublicMessageRecipientInfo

ThruPublicMessageRecipientInfo structure contains information about recipient of Thru message.


MsgId String 1R6NE5OZ8QHXA Unique identification number of the Thru message

RecipientId String 2MIMZFR1K0471 Unique identification number of Recipient

RecipientEmail String [email protected] Recipient e-mail


Collected Boolean true Indicates does message were read by recipient

MsgRecipientLevelPublicID String Unique identification number of recipient level

Sample XML


<MsgId>1R6NE5OZ8QHXA</MsgId>

<RecipientId>2MIMZFR1K0471</RecipientId>


<Collected>true</Collected>

<MsgRecipientLevelPublicID>true</MsgRecipientLevelPublicID>



public class ThruPublicMessageRecipientInfo

{

public string MsgId

public string RecipientId

public string RecipientEmail

public bool? Collected

public string MsgRecipientLevelPublicID

}

5.6 Search Resources

5.6.1 ThruPublicSearchCriteria Structure

ThruPublicSearchCriteria structure contains criteria for the search over Thru files and folders.


FolderID Integer 0QN8H2VKTGIWE Indicates the folder from which to start the search

NameCriteria String * String representing the search criteria for the name of Thru file system object

NameCriteriaMatchAll Boolean True Indicates whether all criteria passed in NameCriteria field should be matched

DescriptionCriteria String * String representing the search criteria for the description of Thru file system object

DescriptionCriteriaMatchAll Boolean True Indicates whether all criteria passed in DescriptionCriteria field should be matched


KeywordCriteria String 12* String representing the search criteria for the keywords of Thru file system object

KeywordCriteriaMatchAll Boolean True Indicates whether all criteria passed in KeywordCriteria field should be matched

LastModifiedByUsers Collection<String> Collection of user unique identifiers

DateLastModifiedStart DateTime Date and time when Thru file system object has been modified. Start of Range (UTC)

DateLastModifiedEnd DateTime Date and time when Thru file system object has been modified. End of Range (UTC)

Recursive Boolean True Enable/disable recursive search over folder tree

Sample

folderId=0QN8H2VKTGIWE&NameCriteria=*&

NameCriteriaMatchAll=true&DescriptionCriteria=*&

DescriptionCriteriaMatchAll=true&KeywordCriteria=12*&

KeywordCriteriaMatchAll=true&LastModifiedByUsers=&

DateLastModifiedStart=&DateLastModifiedEnd=&Recursive=true


public class ThruPublicSearchCriteria

{


public string NameCriteria

public bool NameCriteriaMatchAll

public string DescriptionCriteria

public bool DescriptionCriteriaMatchAll

public string KeywordCriteria

public bool KeywordCriteriaMatchAll

public string[] LastModifiedByUsers

public ThruServerDateTime DateLastModifiedStart

public ThruServerDateTime DateLastModifiedEnd

public bool Recursive

}


5.7 Server Resources

5.7.1 ThruPublicServerInfo Structure

ThruPublicServerInfo structure contains information about the configuration of server and its health status.


SiteID Integer 14RD6GNEUV4ZV Identifier of the current site

Name String test.example.com Pretty name of the current site

Title String Thru Site name Title of the site

Welcome String Welcome ‘Welcome’ text of the site

Enabled Boolean True Indicate is the site enabled

Sample

<ThruPublicServerInfo xmlns:xsd=http://www.w3.org/2001/XMLSchema


<SiteId>14RD6GNEUV4ZV</SiteId>

<Name>test.example.com</Name>

<Title>Thru Site name</Title>

<Welcome>Thru is a secure and safe application you can use to store,

organize and distribute your files. Your username determines your ability to view,

download and upload files.</Welcome>

<Enabled>true</Enabled>

</ThruPublicServerInfo>


public class ThruPublicServerInfo

{

public string SiteId

public string Name

public string Title

public string Welcome

public bool Enabled

}

5.7.2 ThruMessageSettings Structure

ThruMessageSettings structure contains information about the configuration of Thru messages.


SeparateEmailsLimit Integer 1000 For tracking purposes, the system creates separate emails per recipient if the message requires a link to Thru server and request login

http://www.w3.org/2001/XMLSchema


is turned off. This parameter prevents massive email generation.

SmtpServerRecipientLimit Integer 0 If your SMTP server has a limit, and the limit is entered here, Thru Server will block messages which exceed the limit. If the limit is NOT entered here, and a message exceeds recipient limit, SMTP server will send the message with a partial recipient list and the user will get an error message.

MsgRequestLoginType Integer 3 1 - Never (No registration for external download) 2 - Always (external download always requires registration)

3 – User Choice (request login is turned off by default but the user can turn it on when sending a message)

MsgRequestloginUserChoiceDefault Boolean False If request recipient login is 'User Choice' - turn on request login as default value for a new message.

ExpiredMsgNotificationEnabled Boolean True Enable expired message notification

WebUseMsgPwdInsteadOfRequestLogin Boolean false On the web interface, use message password instead of recipient login. This option only allowed if Request recipient login' is 'Never'.

DefaultExpirationIntervalDays Integer 10 Default expiration interval in Days

AllowSetAfterDefaultExpirationInterval Boolean False Allow to specify the message expiration interval larger than default

Sample XML

<ThruMessageSettings xmlns:xsd="http://www.w3.org/2001/XMLSchema"


<SeparateEmailsLimit>1000</SeparateEmailsLimit>

<SmtpServerRecipientLimit>0</SmtpServerRecipientLimit>

<MsgRequestLoginType>3</MsgRequestLoginType>

<MsgRequestloginUserChoiceDefault>false</MsgRequestloginUserChoiceDefault>

<ExpiredMsgNotificationEnabled>true</ExpiredMsgNotificationEnabled>

<WebUseMsgPwdInsteadOfRequestLogin>false</WebUseMsgPwdInsteadOfRequestLogin>

<PrivateMessageNotificationEnabled>false</PrivateMessageNotificationEnabled>

<DefaultExpirationIntervalDays>10</DefaultExpirationIntervalDays>

<AllowSetAfterDefaultExpirationInterval>false</AllowSetAfterDefaultExpirationInter

val>

</ThruMessageSettings>


public class ThruMessageSettings

{

public int SeparateEmailsLimit


public int SmtpServerRecipientLimit

public int MsgRequestLoginType

public bool MsgRequestloginUserChoiceDefault

public bool ExpiredMsgNotificationEnabled

public bool WebUseMsgPwdInsteadOfRequestLogin

public bool PrivateMessageNotificationEnabled

public int DefaultExpirationIntervalDays

public bool AllowSetAfterDefaultExpirationInterval

}

5.7.3 ThruPasswordSettings Structure

ThruPasswordSettings structure contains information about configuration of the password strength, expiration and lockout policies.


AutomaticExpiration Boolean True Enable/Disable automatic password expiration

ExpirationDays Integer 10 Expiration days

ExpirationWarningNotificationDays Integer 0 Send expiration warning notification – warning days

AutomaticLoginLockout Boolean True Enable/Disable automatic login lockout

MaxLoginAttempts Integer 5 Max login attempts

LockoutDurationSeconds Integer 20 Lockout duration seconds

BlockPreviousPasswords Boolean False Do not allow reuse of previous passwords

PreviousPasswordCount Integer 3 Number of previous passwords to check

MinimumPasswordLength Integer 6 Minimum password length

RequireSpecialCharacter Boolean False At least one special character required

RequireLetter Boolean False At least one letter required

RequireDigit Boolean False At least one digit required

RequireUppercaseLetter Boolean False At least one uppercase letter required

RequireLowercaseLetter Boolean False At least one lowercase letter required

Sample XML

<ThruPasswordSettings xmlns:xsd="http://www.w3.org/2001/XMLSchema"


<AutomaticExpiration>true</AutomaticExpiration>


<ExpirationDays>10</ExpirationDays>

<ExpirationWarningNotificationDays>0</ExpirationWarningNotificationDays>

<AutomaticLoginLockout>true</AutomaticLoginLockout>

<MaxLoginAttempts>5</MaxLoginAttempts>

<LockoutDurationSeconds>20</LockoutDurationSeconds>

<BlockPreviousPasswords>false</BlockPreviousPasswords>

<PreviousPasswordCount>3</PreviousPasswordCount>

<MinimumPasswordLength>6</MinimumPasswordLength>

<RequireSpecialCharacter>false</RequireSpecialCharacter>

<RequireLetter>false</RequireLetter>

<RequireDigit>false</RequireDigit>

<RequireUppercaseLetter>false</RequireUppercaseLetter>

<RequireLowercaseLetter>false</RequireLowercaseLetter>

</ThruPasswordSettings>


public class ThruPasswordSettings

{

public bool? AutomaticExpiration

public int? ExpirationDays

public int? ExpirationWarningNotificationDays

public bool? AutomaticLoginLockout

public int? MaxLoginAttempts

public int? LockoutDurationSeconds

public bool? BlockPreviousPasswords

public int? PreviousPasswordCount

public int? MinimumPasswordLength

public bool? RequireSpecialCharacter

public bool? RequireLetter

public bool? RequireDigit

public bool? RequireUppercaseLetter

public bool? RequireLowercaseLetter

}

5.7.4 ThruUploadSettings Structure

ThruUploadSettings structure contains information of upload settings.


UploadAppletBatchMaxCount Integer 0 The maximum number of files uploaded in batch by the applet to the server in a single HTTP request. To indicate that there is no limit, use the value 0.

UploadAppletChunkCount Integer 20 The maximum number of chunks to divide a file to be uploaded by the applet, before we start


increasing the chunk size from the minimum size.

UploadAppletChunkMaxSizeMb Integer 100 The maximum size (in Megabytes) of a file chunk uploaded by the applet to the server.

UploadAppletChunkMinSizeMb Integer 60 The minimum size (in Megabytes) of a file chunk uploaded by the applet to the server.

UploadAppletDeleteOnCancelDefault Boolean False Indicates whether the default behavior for the applet on an upload cancellation is to delete partially uploaded files.

UploadAppletDeleteOnCancelEnabled Boolean True Indicates whether the user can opt on the behavior for the applet on an upload cancellation. If true, user can opt; false, otherwise.

UploadAppletZippingEnabled Boolean False

UploadAppletZippingMinFileSizeKb Integer 10

Sample XML

<ThruUploadSettings xmlns:xsd="http://www.w3.org/2001/XMLSchema"


<UploadAppletBatchMaxCount>0</UploadAppletBatchMaxCount>

<UploadAppletChunkCount>20</UploadAppletChunkCount>

<UploadAppletChunkMaxSizeMb>100</UploadAppletChunkMaxSizeMb>

<UploadAppletChunkMinSizeMb>60</UploadAppletChunkMinSizeMb>

<UploadAppletDeleteOnCancelDefault>false</UploadAppletDeleteOnCancelDefault>

<UploadAppletDeleteOnCancelEnabled>true</UploadAppletDeleteOnCancelEnabled>

<UploadAppletZippingEnabled>false</UploadAppletZippingEnabled>

<UploadAppletZippingMinFileSizeKb>10</UploadAppletZippingMinFileSizeKb>

</ThruUploadSettings>


public class ThruUploadSettings

{

public int UploadAppletBatchMaxCount

public int UploadAppletChunkCount

public int UploadAppletChunkMaxSizeMb

public int UploadAppletChunkMinSizeMb

public bool UploadAppletDeleteOnCancelDefault

public bool UploadAppletDeleteOnCancelEnabled

public bool UploadAppletZippingEnabled

public int UploadAppletZippingMinFileSizeKb

}


5.7.5 ThruMobileSettings

ThruMobileSettings structure contains information of mobile application settings.


SessionRecheckIntervalSeconds Integer 60

EnableOpenInAnotherApplication Boolean True

LocalSessionOfflineLifetimeSeconds Integer 180

MobilePolicyUpdateIntervalSeconds Integer 300

Sample XML

<ThruMobileSettings xmlns:xsd="http://www.w3.org/2001/XMLSchema"


<SessionRecheckIntervalSeconds>60</SessionRecheckIntervalSeconds>

<EnableOpenInAnotherApplication>true</EnableOpenInAnotherApplication>

<LocalSessionOfflineLifetimeSeconds>180</LocalSessionOfflineLifetimeSeconds>

<MobilePolicyUpdateIntervalSeconds>300</MobilePolicyUpdateIntervalSeconds>

</ThruMobileSettings>


public class ThruMobileSettings

{

public int SessionRecheckIntervalSeconds

public bool EnableOpenInAnotherApplication

public int LocalSessionOfflineLifetimeSeconds

public int MobilePolicyUpdateIntervalSeconds

}

5.8 System Log Resources

5.8.1 ThruPublicSystemLogOperation

ThruPublicSystemLogOperation structure contains information operation that will be logged in Thru.


LogOperationId String Operation Id that is assigned for request operation

OperationType Integer MobileOpenFileInExternalApplication = 0x4000000

FolderId String Identifier of the folder in Thru file system

FileId String Identifier of the file in Thru file system

MobileReceiverAppName String Mobile application name


Sample

Request:

OperationType=67108864&FileId=30FZAAT6ULN30&MobileReceiverAppName=test

Response:

<ThruPublicSystemLogOperation xmlns:xsd="http://www.w3.org/2001/XMLSchema"


<LogOperationId>1UEVYEHGF7GVW</LogOperationId>

<OperationType>67108864</OperationType>

<FileId>30FZAAT6ULN30</FileId>

<MobileReceiverAppName>test</MobileReceiverAppName>

</ThruPublicSystemLogOperation>


public class ThruPublicSystemLogOperation

{

public string LogOperationId

public int OperationType


public string FileId

public string MobileReceiverAppName

}

5.9 Ticket Resource

5.9.1 ThruTicketInfo Structure

ThruTicketInfo structure contains email fields


Subject String Subject Subject text

Body String Message Body text

Sample

Subject=test&Body=message


public class ThruTicketInfo

{

public string Subject

public string Body

}


5.10 User Resources

5.10.1 ThruPublicUserInfo Structure

ThruPublicUserInfo structure contains information about user of Thru.


UserId String 1Q1OBQWVHTROE Identifier of user in Thru

Name String admin User name that is used for sign-in in Thru

DomainUsername String If user is in domain, this field represent it domain name

FirstName String Ad User’s first name

LastName String Test User’s last name

FullName String Ad Test User’s full name

Email String [email protected] User’s e-mail address

Phone String User’s phone number

CompanyName String Company name

Role Integer 5 User’s role on Thru:

None = 0,

Guest = 1,

Recipient = 2,

Member = 3,

Manager = 4,

Administrator = 5,

System = 6

DateCreated DateTime /Date(1337174868567)/ User’s date create (UTC)

DateModified DateTime /Date(1351871161613)/ User’s last date modify (UTC)

CreatedByUserId String Identifier of the user that is create the specified user

ModifiedByUserId String 2T5LRH8F1R2QK Identifier of the user that is modify the specified user

DateLastPasswordChanged DateTime /Date(1343838136630)/ The date of the last password modification

PasswordNeverExpires Boolean True Flag indicate is the user password is never expires

Sample XML


<ThruPublicUserInfo xmlns:xsd="http://www.w3.org/2001/XMLSchema"



<Name>admin</Name>

<FirstName>Ad</FirstName>

<LastName>3</LastName>

<FullName>Ad 3</FullName>

<Email>[email protected]</Email>

<Phone></Phone>

<CompanyName></CompanyName>

<Role>5</Role>



<ModifiedByUserId>2T5LRH8F1R2QK</ModifiedByUserId>

<DateLastPasswordChanged>/Date(1343838136630)/</DateLastPasswordChanged>

<PasswordNeverExpires>true</PasswordNeverExpires>

</ThruPublicUserInfo>


public class ThruPublicUserInfo

{

public string UserId

public string Name

public string DomainUsername

public string FirstName

public string LastName

public string FullName

public string Email

public string Phone

public string CompanyName

public int Role


public ThruServerDateTime DateModified

public string CreatedByUserId

public string ModifiedByUserId

public ThruServerDateTime DateLastPasswordChanged

public bool PasswordNeverExpires

}


5.10.2 ThruPasswordInfo Structure

ThruPasswordInfo structure contains information that is required for password change.


OldPassword String password Current user password

NewPassword String _password1 New password that is required to set

ConfirmPassword String _password1 Confirmation of the New password field

Sample

OldPassword=password&NewPassword=_password1&ConfirmPassword=_password1


public class ThruPasswordInfo

{

public string OldPassword

public string NewPassword

public string ConfirmPassword

}

5.11 Service Resources

5.11.1 ThruServiceVersion Structure

ThruServiceVersion structure contains information about versions of specific REST service in the ThruServer.


ServiceName String FileSystem Service name

SupportedVersions String 1.0 Service version

Sample

<ThruServiceVersion>

<ServiceName>FileSystem</ServiceName>

<SupportedVersions>

<string>1.0</string>

</SupportedVersions>

</ThruServiceVersion>


public class ThruServiceVersion

{

public string ServiceName


public string[] SupportedVersions

}

5.11.2 ThruServiceVersionsResult Structure

ThruServiceVersionsResult structure contains information about versions of REST services in the ThruServer.


ServiceVersions Collection<ThruServiceVersion > REST Services

Sample

<ThruServiceVersionsResult xmlns:xsd="http://www.w3.org/2001/XMLSchema"


<ServiceVersions>


<ServiceName>Authentication</ServiceName>

<SupportedVersions>





<ServiceName>FileSystem</ServiceName>

<SupportedVersions>





<ServiceName>Message</ServiceName>

<SupportedVersions>





<ServiceName>Search</ServiceName>

<SupportedVersions>





<ServiceName>Favorites</ServiceName>

<SupportedVersions>






<ServiceName>Server</ServiceName>

<SupportedVersions>





<ServiceName>Ticket</ServiceName>

<SupportedVersions>





<ServiceName>SystemLog</ServiceName>

<SupportedVersions>





<ServiceName>User</ServiceName>

<SupportedVersions>




</ServiceVersions>

</ThruServiceVersionsResult>


public class ThruServiceVersionsResult

{

public ThruServiceVersion[] ServiceVersions

}

5.12 Server Version Resources

5.12.1 ThruServerVersion Structure

ThruServerVersion structure contains information about version of ThruServer.


Major Integer 7 Major version

Minor Integer 8 Minor version

Buildnumber Integer 23 Build number


Suffix String 1.1.2 Suffix, addition version identificator. This field can be empty.

Revision Integer 11234 Revision number

Sample

<ThruServerVersion>

<Major>7</Major>

<Minor>8</Minor>

<Buildnumber>23</Buildnumber>

<Suffix></Suffix>

<Revision>12714</Revision>

</ThruServerVersion>


public class ThruServerVersion

{

public int Major {get, set; }

public int Minor { get, set; }

public int Buildnumber { get, set; }

public string Suffix { get; set; }

public int Revision {get, set; }

}


6 Web Services

6.1 Authentication Service

6.1.1 POST New Session Object

Url [ThruWebServer]/REST/[version]/Session

Verb POST

Required HTTP Headers Accept: (application/xml or application/json), Device_UUID (any unique identifier for the client device is required)

Description Verify user credentials and authenticate Thru user in the system

Request Body ThruSessionRequest object

Return Data Object ThruPublicSession object

Invocation Scenario(s) Verify customer credentials

Authenticate customer

Remarks Example request: UserName=admin&Password=adminadmin&

ClientVersion=1&ApplicationId=12

6.1.2 DELETE Existing Session Object


Verb DELETE

Required HTTP Headers Accept: (application/xml or application/json)

Description Logs out Thru customer from the system.

Request Body None

Return Data Object None

Invocation Scenario(s) Expire session object

Logs out customer from the system

Remarks

6.1.3 CHECK Existing Session Object


Verb GET


http://thruwebserver/PortalServices/WS/%5bVersion%5d%20/Offer/%5bWinPlatformOfferId




Description Check if customer is authenticated.

Request Body None


Invocation Scenario(s) Check session object

Remarks

6.2 File System Service

6.2.1 POST New Folder Information

Url [ThruWebServer]/REST/[version]/FileSystem/Folder

Verb POST


Description Creates a new folder in Thru file system

Request Body ThruPublicFolderInfo object

Return Data Object Updated ThruPublicFolderInfo object

Invocation Scenario(s) Create a new folder

Remarks Example request: Name=New+Folder&ParentFolderId=1UTXM50KW0ISP&

Description=Description&Tags%5B%5D=567&Tags%5B%5D=897

6.2.2 GET Existing Folder Information

Url [ThruWebServer]/REST/[version]/FileSystem/Folder/[FolderId]

Verb GET


Description Retrieves a folder information based on the provided ID

Request Body None

Return Data Object ThruPublicFolderInfo object

Invocation Scenario(s) Get a folder information in order to fulfill it

Remarks All returned dates are in UTC.




6.2.3 PUT Updated Folder Information


Verb PUT


Content-Type: (application/xml or application/json)

Description Updates folder information based on the provided information. Information should be passed

in the body as a serialized representation of the ThruPublicFolderInfo DTO.

Request Body ThruPublicFolderInfo object

Return Data Object Updated ThruPublicFolderInfo object

Invocation Scenario(s) Renaming folder

Move folder and its content to another folder

Remarks Value of the FolderID field in the posted ThruPublicFileInfo DTO should reference to the existing and non-deleted folder. Otherwise, exception will be thrown .

Not all properties of ThruPublicFolderInfo can be modified:

Name

ParentFolderID

Description

Keywords

The following properties should not be provided; if provided, their values will be ignored:

FolderID

EffectivePermission

DateCreated

DateModified

CreatedByUserID

ModifiedByUserID

Exception will be thrown in case current user doesn’t have a right to do such modifications

ModifiedByUserID field of the folder will be updated if the statement succeeds

After successful processing of the command updated ThruPublicFolderInfo object will be

returned

Example request: folderId=3V45C8UTHL0A3&Name=&ParentFolderId=&

Description=New+Description&Tags%5B%5D=

6.2.4 DELETE Existing Folder


Verb DELETE





Description Deletes folder and its content based on the provided information. No additional data should be passed on the request body

Request Body None


Invocation Scenario(s) Mark folder and all underlying files and folders as deleted

Remarks The folder could be restored later by administrator based on the Thru server configuration

6.2.5 GET Home Folder Information

Url [ThruWebServer]/REST/[version]/FileSystem/Home

Verb GET


Description Retrieves a home folder information of the authenticated user

Request Body None


Invocation Scenario(s) Get a home folder information of the authenticated user


6.2.6 GET List of Files and Folders Inside a Home Folder

Url [ThruWebServer]/REST/[version]/FileSystem/Home/Content

Verb GET


Description Retrieves a collection of file and folder information structures based on the home folder information of the authenticated user.

Request Body None

Return Data Object

ThruPublicContentResult object

Invocation Scenario(s) Get a full content of the folder

Remarks




6.2.7 GET List of Files Inside a Home Folder

Url [ThruWebServer]/REST/[version]/FileSystem/Home/Content/Files

Verb GET


Description Retrieves a collection of file information structures based on the home folder information of the authenticated user.

Request Body None

Return Data Object


Invocation Scenario(s) Get files in the folder

Remarks

6.2.8 GET List of Folders Inside a Home Folder

Url [ThruWebServer]/REST/[version]/FileSystem/Home/Content/Folders

Verb GET


Description Retrieves a collection of folder information structures based on the home folder information of the authenticated user.

Request Body None

Return Data Object


Invocation Scenario(s) Get folders in the folder

Remarks

6.2.9 GET Root Folder Information

Url [ThruWebServer]/REST/[version]/FileSystem/Root

Verb GET


Description Retrieves a root folder information of the authenticated user

Request Body None






Invocation Scenario(s) Get information of the root folder


6.2.10 GET List of Files and Folders Inside a Root Folder

Url [ThruWebServer]/REST/[version]/FileSystem/Root/Content

Verb GET


Description Retrieves a collection of file and folder information structures based on the root folder information of the authenticated user.

Request Body None

Return Data Object



Remarks

6.2.11 GET List of Files Inside a Root Folder

Url [ThruWebServer]/REST/[version]/FileSystem/Root/Content/Files

Verb GET


Description Retrieves a collection of file information structures based on the root folder information of the authenticated user.

Request Body None

Return Data Object



Remarks

6.2.12 GET List of Folders Inside a Root Folder

Url [ThruWebServer]/REST/[version]/FileSystem/Root/Content/Folders





Verb GET


Description Retrieves a collection of folder information structures based on the root folder information of the authenticated user.

Request Body None

Return Data Object



Remarks

6.2.13 GET List of Files and Folders Inside a Folder

Url [ThruWebServer]/REST/[version]/FileSystem/Folder/[FolderId]/Content

Verb GET


Description Retrieves a collection of file and folder information structures based on the provided parent folder ID.

Request Body None

Return Data Object



Remarks

6.2.14 GET List of Files Inside a Folder

Url [ThruWebServer]/REST/[version]/FileSystem/Folder/[folderId]/Content/Files

Verb GET


Description Retrieves a collection of file information structures based on the provided parent folder ID.

Request Body None

Return Data Object






Remarks

6.2.15 GET List of Folders Inside a Folder

Url [ThruWebServer]/REST/[version]/FileSystem/ Folder/[folderId]/Content/Folders

Verb GET


Description Retrieves a collection of folder information structures based on the provided parent folder ID.

Request Body None

Return Data Object



Remarks

6.2.16 GET Existing File Information

Url [ThruWebServer]/REST/[version]/FileSystem/File/[FileId]

Verb GET


Description Retrieves a file information based on the provided ID

Request Body None

Return Data Object

ThruPublicFileInfo object

Invocation Scenario(s) Get a file information in order to fulfill it


6.2.17 PUT Updated File Information


Verb PUT


Description Updates file information based on the provided information. Information should be passed in





the body as a serialized representation of the ThruPublicFileInfo DTO

Request Body

ThruPublicFileInfo object

Return Data Object Updated ThruPublicFileInfo object

Invocation Scenario(s) Renaming file

Move file to another folder

Remarks Value of the FileID field in the posted ThruPublicFileInfo DTO should reference to the existing, non-deleted, non-quarantined file. Otherwise, exception will be thrown

Not all properties of

ThruPublicFileInfo can be modified:

Name

ParentFolderID

Description

Keywords

ParentFolderID

The following properties should not be provided; if provided, their values will be ignored:

Size

DateCreated

DateModified

CreatedByUserID

ModifiedByUserID

IsQuarantined

ModifiedByUserID field of the file will be updated if the statement succeeded

After successful processing of the command updated

ThruPublicFileInfo object will be returned

6.2.18 DELETE Existing File


Verb DELETE


Description Deletes file based on the provided information. No additional data should be passed on the request body.

Request Body None




Invocation Scenario(s) Mark file whose ID is specified in URL as deleted

Remarks Possibly later this file can be restored by administrator based on the Thru server configuration

6.3 Message Service

6.3.1 POST New Thru Message

Url [ThruWebServer]/REST/[version]/Message

Verb POST


Description Creates Thru message according to ThruPublicMessageInfo structure passed in HTTP

request

Request Body ThruPublicMessageInfo object

Return Data Object Updated ThruPublicMessageInfo object

Invocation Scenario(s) Send one or more files and folders to recipients

Send private message to recipients

Remarks ToRecipients, CcRecipients, BccRecipients fields in ThruPublicMessageInfo should be

present in request as a string array. These fields will bind to required structure on server side. DateExpired must be converted to UTC.

Example POST parameters: BccRecipients[][email protected]

BccRecipients[][email protected]

CcRecipients[][email protected]

CcRecipients[][email protected]

DateExpired=

FilesAttached[]=

FoldersAttached[]=

NotifyFlag=

Priority=3

PrivateMessage=body private

PublicMessage=body public

RequestLogin=false

SendByClient=true

Subject=subject

ToRecipients[][email protected]

ToRecipients[][email protected]

UserPassword=

1 To-recipient should be provided at least.



DateExpired must be converted to UTC. If SendByClient is true, after calling this method the client must:

1. send email notification and call the REST method ‘completeMessage‘ which sets message’s DateSent.

2. Or call the REST method ‘discardMessage’ to cancel the creation of ‘distribution’ object on the server. Created by this method message will be deleted on the server.

The returned ThruPublicMessageInfo contains ‘MsgHtmlTemplate’ parameter which

must be parsed by the client. The token <thru:bodyToken/> must be replaced with the public message. The token <thru:passwordToken/> (if exists) must be replaced with the field MsgRecipientLevelPublicID of the first To recipient.

6.3.2 GET Existing Thru Message

Url [ThruWebServer]/REST/[version]/Message/[MessageId]

Verb GET


Description Retrieves message information based on the provided ID.

Request Body None

Return Data Object ThruPublicMessageInfo object

Invocation Scenario(s) Get a message in the Thru server


6.3.3 DELETE Existing Thru Message


Verb DELETE


Description Deletes message based on the provided information. No additional data should be passed on the request body.

Request Body None


Invocation Scenario(s) Mark message whose ID is specified in URL as deleted

Remarks




6.3.4 PUT Updated Thru Message


Verb PUT


Content-Type: (application/xml or application/json)

Description Updates message information based on the provided information. Information should be

passed in the body as a serialized representation of the ThruPublicMessageInfo DTO

Request Body ThruPublicMessageInfo object

Return Data Object Updated ThruPublicMessageInfo object

Invocation Scenario(s) Delete attached folders

Delete attached files

Delete recipients from the To, Cc, Bcc

Change expired date

Expire message now

Remarks Value of the MessageID field in the posted ThruPublicMessageInfo DTO should reference

to the existing, non-deleted message. Otherwise, exception will be thrown.

Not all properties of ThruPublicMessageInfo can be modified:

DateExpired

ExpireNow

ToRecipients, CcRecipients, BccRecipients

FoldersAttached, FilesAttached

DateExpired must be converted to UTC.

Recipients to delete must be provided in ToRecipients field. They will be deleted from To, Cc and Bcc lists.

If provided, the values of the following fields are ignored:

Subject

Priority

PublicMessage

PrivateMessage

CollectedFlag

RequestLogin

SendByClient

DateCreated

DateSent

After successful processing of the command updated

ThruPublicFileInfo object will be returned.



6.3.5 PUT Discard Thru Message

Url [ThruWebServer]/REST/[version]/Message/Discard/[MessageId]

Verb PUT


Description Discard message based on the provided information. No additional data should be passed on the request body.

Request Body None


Invocation Scenario(s) Mark message that’s ID is specified in URL as deleted

Remarks This method can be called only after the method ‘New Thru message’ is called

6.3.6 PUT Complete Thru Message

Url [ThruWebServer]/REST/[version]/Message/Complete/[MessageId]

Verb PUT


Description Complete message based on the provided information. No additional data should be passed on the request body.

Request Body None


Invocation Scenario(s) Mark message that’s ID is specified in URL as completed.

Remarks This method can be called only after the method ‘New Thru message’ is called

6.3.7 GET SentThru List

Url [ThruWebServer]/REST/[version]/Message/Content/[skip]/[take]

Verb GET


Description Get list of the sent messages. Attachments are not included in returned data object.

Request Body None


Invocation Scenario(s) Search over all Thru messages available for the current authenticated user.





Attachments are not included in result, use GET Existing Thru Message.

Optional:

1. Skip custom number of messages.

2. Take custom number of messages.

Remarks

6.3.8 POST Project Message Storage

Url [ThruWebServer]/REST/[version]/Message/Storage/[type]

Verb POST


Description Retrieves a folder information of the message storage.

Request Body “Subject”: <subject> in case of Type is set “Days”. Current version of this method supports only one type=‘Days.’


Invocation Scenario(s) Find or if not exist create folder for message storage.

Optional: type of the folder name.

Remarks

6.4 Search Service

6.4.1 POST Find All Thru Files and Folders by Search Criteria

Url [ThruWebServer]/REST/[version]/Search/[Skip]/[Take]

Verb POST


Description Retrieves a collection of folder and file structures based on the provided search criteria structure.

Request Body ThruPublicSearchCriteria object

Return Data Object


Invocation Scenario(s) Search over all Thru files and folders available to the current authenticated user.

Remarks NameCriteria, DescriptionCriteria, KeywordCriteria are automatically wrapped by the ‘*’ if not contains it as part of criteria. For ex: “text” -> “*text*”, but “tex*t” -> “tex*t”




6.4.2 POST Find All Thru Folders by Search Criteria

Url [ThruWebServer]/REST/[version]/Search/Folders/[Skip]/[Take]

Verb POST


Description Retrieves a collection of folder structures based on provided search criteria structure.


Return Data Object


Invocation Scenario(s) Search over all Thru folders available to the current authenticated user.

Remarks

ThruPublicContentResult always contain null for

ThruPublicFileInfo

NameCriteria, DescriptionCriteria, KeywordCriteria are automatically wrapped by the ‘*’ if not contains it as part of criteria. For ex: “text” -> “*text*”, but “tex*t” -> “tex*t”

6.4.3 POST Find All Thru Files by Search Criteria

Url [ThruWebServer]/REST/[version]/Search/Files/[Skip]/[Take]

Verb POST


Description Retrieves a collection of files structures based on the provided search criteria structure.


Return Data Object


Invocation Scenario(s) Search over all Thru files available to the current authenticated user.

Remarks

ThruPublicContentResult always contain null for ThruPublicFolderInfo

NameCriteria, DescriptionCriteria, KeywordCriteria are automatically wrapped by the ‘*’ if not contains it as part of criteria. For ex: “text” -> “*text*”, but “tex*t” -> “tex*t”




6.5 Server Service

6.5.1 GET Server Information

Url [ThruWebServer]/REST/[version]/Server/Info

Verb GET


Description Retrieves information about current server.

Request Body None

Return Data Object ThruPublicServerInfo object

Invocation Scenario(s) Get file information in order to fulfill it.

Remarks

6.5.2 GET Message Settings

Url [ThruWebServer]/REST/[version]/Server/MessageSettings

Verb GET


Description Retrieves information about message settings in the server.

Request Body None

Return Data Object ThruMessageSettings object

Invocation Scenario(s) Get information about message settings in order to fulfill it.

Remarks

6.5.3 GET Password Settings

Url [ThruWebServer]/REST/[version]/Server/PasswordSettings

Verb GET


Description Retrieves information about password settings in the server

Request Body None

Return Data Object ThruPasswordSettings object





Invocation Scenario(s) Get information about password settings in order to fulfill it.

Remarks

6.5.4 GET Upload Settings

Url [ThruWebServer]/REST/[version]/Server/UploadSettings

Verb GET


Description Retrieves information about upload settings in the server.

Request Body None

Return Data Object ThruUploadSettings object

Invocation Scenario(s) Get information about upload settings in the server.

Remarks

6.5.5 GET Mobile settings

Url [ThruWebServer]/REST/[version]/Server/MobileSettings

Verb GET


Description Retrieves information about mobile settings in the server.

Request Body None

Return Data Object ThruMobileSettings object

Invocation Scenario(s) Get information about mobile settings in the server.

Remarks

6.6 Favorites Service

6.6.1 PUT Folder to Favorites

Url [ThruWebServer]/REST/[version]/Favorites/Folder/[FolderId]

Verb PUT


Description Add folder with the specified id to favorites.





Request Body None


Invocation Scenario(s) Mark folder whose ID is specified in URL as favorite

Remarks

6.6.2 DELETE Folder from Favorites

Url [ThruWebServer]/REST/[version]/Favorites/Folder/[FolderId]

Verb DELETE


Description Remove folder with the specified ID from favorites.

Request Body None


Invocation Scenario(s) Remove folder whose ID is specified in URL from favorites

Remarks

6.6.3 PUT File to Favorites

Url [ThruWebServer]/REST/[version]/Favorites/File/[FileId]

Verb PUT


Description Add file with the specified ID to favorites.

Request Body None


Invocation Scenario(s) Mark file whose ID is specified in URL as favorite.

Remarks

6.6.4 DELETE File from Favorites

Url [ThruWebServer]/REST/[version]/Favorites/File/[FileId]

Verb DELETE






Description Remove file with the specified ID from favorites.

Request Body None


Invocation Scenario(s) Remove file whose ID is specified in URL from favorites.

Remarks


6.6.5 GET All Content in Favorites

Url [ThruWebServer]/REST/[version]/Favorites/Content

Verb GET


Description Retrieves a collection of file and folder information structures marked as favorites. Result can be filtered by options.

Request Body

Return Data Object


Invocation Scenario(s) Get a full content in favorites.

Get files in favorites.

Get folders in favorites.

Remarks

6.6.6 GET Files in Favorites

Url [ThruWebServer]/REST/[version]/Favorites/Content/Files

Verb GET


Description Retrieves a collection of file information structures marked as favorites. Result can be filtered by options.

Request Body

Return Data Object


Invocation Scenario(s) Get files in favorites.

Remarks

6.6.7 GET Folders in Favorites

Url [ThruWebServer]/REST/[version]/Favorites/Content/Folders

Verb GET


Description Retrieves a collection of folder information structures marked as favorites. Result can be filtered by options.





Request Body

Return Data Object


Invocation Scenario(s) Get folders in favorites.

Remarks

6.7 Service Versions Service

6.7.1 GET Information about Service Versions

Url [ThruWebServer]/REST/[version]/ServiceVersions

Verb GET


Description Gets information about versions of REST services in the ThruServer .

Request Body None

Return Data Object ThruServiceVersion object

Invocation Scenario(s) Get list of services and their versions.

Remarks

6.8 System Log Service

6.8.1 POST System Log Operation

Url [ThruWebServer]/REST/[version]/SystemLog/[operationId]

Verb POST


Security Header Required

Description Add new log operation based on the provided ThruPublicSystemLogOperation structure.

Request Body ThruPublicSystemLogOperation object

Return Data Object ThruPublicSystemLogOperation object with system log operation id

Invocation Scenario(s) Add new system log data.

Remarks




6.9 Ticket Service

6.9.1 POST New Ticket

Url [ThruWebServer]/REST/[version]/Ticket

Verb POST



Description Send ticket based on the provided information.

Request Body ThruTicketInfo object


Invocation Scenario(s) Send email to reseller.

Remarks

6.10 User Service

6.10.1 GET User Information

Url [ThruWebServer]/REST/[version]/User/Info

Verb GET



Description Get information about currently logged user.

Request Body None

Return Data Object ThruPublicUserInfo object

Invocation Scenario(s) Get information about user.

Remarks

6.10.2 PUT New Password for the User

Url [ThruWebServer]/REST/[version]/User/Password

Verb PUT







Description Set new password for the user.

Request Body ThruPasswordInfo object


Invocation Scenario(s) Set new password.

Remarks

6.11 Server Version Service

6.11.1 GET Information About Server Version

Url [ThruWebServer]/REST/ServerVersion

Verb GET

Required HTTP Headers

Accept: (application/xml or application/json)

Description Gets information about version of Thru Server .

Request Body None

Return Data Object ThruServerVersion Structure object

Invocation Scenario(s)

Get version.

Remarks Example:

Server version 7.8.13.0.3.12312

Return:

Major: 7

Minor: 8

Buildnumber: 13

Suffix: 0.3

Revision: 12312



7 Programmatic File and Folder Transfers.

7.1 Downloading.

File and folder downloads from Thru server should be implemented via HTTP GET to a URL servername/download.aspx, the URL requires authentication via SessionID for existing user session.

External application that connects to a Thru server should browse to a Thru folder that contains required files using web services. Once in the right folder, Web call GetFiles returns an array of FTHFileData objects, each object contains FileID for the files stored in requested parent folder. WS call GetFolders returns an array of FTHFolderData objects, each object contains FolderID for the folders stored in requested parent folder

Single File download: using HTTP library such as web client library included into .NET framework, external application issue the HTTP GET command to the URL servername/download.aspx?fileid=FileID&sessionid=SessionID , where FileID is retrieved by previous GetFiles WS call and SessionID parameter is returned by one of the Open() web service calls. In response Thru server starts writing selected file as a binary stream into HTTP client, the stream has to be saved into the local file system. It is highly recommended to open HTTPS connection to provide secure download.

Single Folder Download: using HTTP library such as web client library included into .NET framework, external application issues the HTTP GET command to the URL servername/download.aspx?folderid=FolderID&sessionid=SessionID, where FolderID is retrieved by previous GetFolders web call and SessionID parameter is returned by one of the Open() web service calls. In response Thru server creates an archive in a ZIP format that includes all subfolders of a selected folder and starts writing an archive file as a binary stream into HTTP client. The stream has to be saved into the local file. Archive file is named following the pattern foldername.zip. When external application has to download a folder, it is generally recommended to navigate down Thru folder tree and download files separately for better control at the file level, as opposed to downloading the whole folder that comes in a zipped form and has to be unzipped by a client application.

Downloading of multiple files and folders: using HTTP library such as web client library included into .NET framework, external application issue the HTTP GET command to the URL servername/download.aspx?fileid=FileID1, …FileDN& folderid=FolderID1, …FolderDN&sessionid=SessionID , where FileID1, …FileIDN is a comma-separated list of File IDs returned by a previous call to GetFiles and FolderD1, …FolderDN is a comma separated list of folder IDs returned by a previous call to GetFolders. SessionID parameter is returned by one of the Open() web service calls. In response Thru server packages requested files and folders into ZIP archive named using the pattern “THRU-XXXXXXXXXX.zip” where XXX represents random combination of hexadecimal letters and digits, and starts writing the ZIP archive as a binary stream into HTTP client. The stream has to be saved into the local file system. It is highly recommended to open HTTPS connection to provide secure download. The following values of HTTP headers are returned in all cases:

o Content-Type "application/binary"

o Content-Disposition: attachment; filename=filename.ext (to save the file under original name)

o Content-Length: <file size in bytes>

In case of error the following custom HTTP header is returned that contains an error code and message:

o "X-FTH-Error", error contents is ErrorCode and Error Message separated by pipe character: “ErrorCode | ErrorMessage”


7.2 Uploading Files and Folders via basic protocol (deprecated)

File upload is implemented by a Thru server via HTTP POST command to a URL servername/upload.aspx that requires authentication via session ID. It is recommended to use HTTPS connection for security purposes.

Size of each uploaded file is limited to 2GB. To upload the files larger than 2GB please use extended upload protocol.

HTTP POST command is used to send the parameters and upload files as part of multipart forms of the following type:

<FORM ENCTYPE="multipart/form-data" action=" servername/upload.aspx " method=post> <INPUT NAME="file" TYPE="file"> <INPUT NAME="filename0" TYPE="hidden" value=”filename.ext”> <INPUT NAME="Description0" TYPE="hidden" value=”description_here”> <INPUT NAME=" SessionID" TYPE="hidden" value=sessionID> <INPUT NAME=" folderID " TYPE="hidden" value= folderID > <INPUT NAME=" EntityCount " TYPE="hidden" value = 1> <INPUT NAME=" overwrite" TYPE="hidden" value=[1 or 0 here]> <INPUT NAME=" NoRedirect " TYPE="hidden" value=”any value here”>

File/Folder upload process can be implemented using .NET framework web client library or any other file upload library like COM objects from third-party vendors.

Upload via HTTP POST should be used in conjunction with web services to log into the server, browse to the target location and retrieve information on FileIDs and FolderIDs.

Web client library used by external application should issue HTTP POST command to the page servername/upload.aspx with the following set of fields:

‘file’ contains file body. File size is limited to 2GB due to HTTP POST implementation by the browsers.

‘filename0’ (ends with zero): name that will be given to the file in Thru server.

‘Description0’ (ends with zero): name that will be given to the file in Thru server.

‘SessionID’ should be set to current sessionID, returned by one of the Open() web service calls.

‘folderID’ should be set to id of the target parent folder where a file should be uploaded. The folderID has to be retrieved via prior calls to web services such as GetFolders or GetFolder.

“EntityCount” should be set to 1 since only one file is uploaded

“overwrite” flag equals 1 means that existing file with the same name in the same parent folder should be overwritten, if set to 0, the new file name will be versioned to name[i]

"NoRedirect" parameter has to be defined in the POST request and set to any value for web libraries that call Thru server 3

rd party applications. Please note this is mandatory parameter for external applications.

The following values of HTTP headers are returned as result of upload:

In case of successful upload:

"X-FileID0" (ends with zero) contains File ID of newly created file in Thru server.

In case of error:

"X-FTH-Error", error contents is ErrorCode and Error Message separated by pipe character: “ErrorCode | ErrorMessage”


To upload multiple files external application should repeat the file uploading process specified in for each file

To upload the folder hierarchies to Thru server, external application should use connect to Thru server using one of Open() web service calls and use call CreateFolder() to create Thru folder. Each file should be uploaded according to the process specified in 2.6.2. There is no size limit on the folder upload except for 2GB upload per each file.

7.3 Uploading of files via Extended File Upload/Download Protocol

Extended transfer protocol allows uploading of multiple files and folders in a single transaction and supports pause, resume and cleanup of partially uploaded files for data consistency. There is no limitation on the size of uploaded file since files are uploaded by the chunks.

The protocol is used by Thru connectors for Microsoft Outlook, iOS and Android applications.

Please see protocol specification in the document Thru Server Extended File Upload Download Protocol Ref x_y.docx available at Thru web site www.thruinc.com.


8 File Transfer User Interface Tools

8.1 Upload Java/HTML5/HTML4 Tool and API

8.1.1 Overview

Any third party web or native application can use Thru Upload Tool to transfer files and folders of unlimited size to a Thru server with pause/resume and network recover capabilities, no coding against protocol is required. To upload files and folders 3rd party application should call a URL in the following format: https://thruservername/ExternalJavaUpload.aspx and supply parameters as specified below. Java applet displays and uploads files and folders to the target folder. If Java is not installed on the workstation, upload tool uses HTML5 or HTML4 depending on the browser capability, starting with server version 7.8.25.

8.1.2 Security Token

The API links calling the upload pop up tool can be protected from being manually copied and used by a different user under the existing SessionID.

Token based security is used to protect a call to upload tool. Token is encrypted by an application calling Thru API using a secret key shared with Thru. The token it passed to the Thru server and is decrypted using the shared key.

Security token structure for upload tool is represented in JSON with following fields:

{

“Version” ,

“FolderID”,

“Email”,

“AllowedIP”,

“TimeStamp”,

“Session”

}

Where the parameters are:

Version : version of token object. Supported value: 1. FolderID : ID of folder that is used for files/folders uploading by upload tool, returned by one of folder management API calls. Email : email of a user to record in audit records with operation. Could be different from a user account which opened a Thru server. AllowedIP : IP address allowed to perform the upload, will be checked by Thru server. If the IP address of connecting browser does not match AllowedIP, operation is blocked. TimeStamp : time of token creation, used for token validation to protect against token replay. Thru server will check that token is not beyond expiration time interval defined in Thru server. Note: Date should be strictly in the format MM/DD/YYY H:MM PM Session : unique identifier of the Thru user session received as result of Open() or OpenImmutable() call. Will be used for access control and logging purposes.


Sample Token: { "Version":"1", " FolderID":"1056", "Email":"[email protected]", "AllowedIP":"64.95.64.190", "TimeStamp":"10/04/2013 11:05:11", "Session":"a2a1163e-555a-469d-bfb4-4da33980409b" }

The following methods and options should be used by calling application to encrypt the token :

Encryption algorithm: Advanced Encryption Standard (AES-256) symmetric algorithm.

Encryptor specified key: shared key in base64string format

Initialization vector (IV): shared key in base64string format

Security token for URL should use base64string format. Sample of token encryption parameters:

Encryptor specified key: AFA3wdfEuCrdFw8QaHFzN6LRXaBoCTHxcWnqNImp7g3=

Initialization vector (IV): JHnmhMkTjkl8fHqYx/l7bA==

Encrypted token in base64string format: jGldNNh7rMjT/fLL27vyQDPXUl/UjBKKfgrzLAxmopIxotP/T20Mz5J180jhG3Soqkz8bB1AV6rz3NMcyYtmm3mdo+CLeD0FDfgJZ6cw1Iqs9V+R79KsJ1mzfUKGrgQmrOq1NlosLcBtzmoVLK4+Cqkt+bkNBdYoYw8DITFkHd/VsEHCnk5pjPd89mDATyjTu4xMCXFVH20lP7tTOU75k61LLSj3X6bHzCuorKcUzp7nuvxve0se9cOdFQ3TA6XH78IMGmdoOz9JgDPIThjeO==

8.1.3 Upload Tool URL Parameters, option with no Security Token.

ThruSessionID [mandatory] : Unique identifier of the current session

ThruFolderID [mandatory] : Unique identifier of a folder on Thru server

ThruSuccessUrl [mandatory] : Browser window containing Java upload applet will be redirected to this URL on successful upload

ThruErrorReportingUrl [mandatory] : Browser window containing Java applet will be redirected to this URL on failed upload. If upload failed, server will return server error code (see below) in parameter “ThruErrorCode”. If an error occurred and ThruErrorReportingURL is not defined then server will throw an exception in the page which contains Java upload applet.

Note: the value of ThruErrorReportingUrl is not validated. You should verify it is a valid URL that does exist when integrating Thru java upload applet.

ThruFileFilter [optional] : specifies which file types can be uploaded via Java applet Format: <Description> : <extension1>, <extension2> … <extensionN> . Example: ThruFileFilter=“Zip files (*.zip, *.7z, *.tar): zip, 7z, tar” will allow upload of files with zip, 7z, tar extensions. Browsing in Add button is allowed only to the files of specified type. Drag and drop for all other file types is ignored. If parameter is not specified, all file types can be uploaded.


ThruFileFilterExceptions [optional] : specifies which file types cannot be uploaded via Java applet. Format: <extension1>, <extensionX>. Example: ThruFileFilterExceptions=exe,msi,mp3 will prevent uploading of the file types exe, msi, mp3.

Note: Parameters ThruFileFilter and ThruFileFilterExceptions are mutually exclusive, only one can be used on java upload URL. If the same file extension is specified in ThruFileFilter and ThruFileFilterExceptions, the latter overrides the former.

8.1.4 Upload Tool URL Parameters, option with Security Token.

ThruFolderID [mandatory] : base64string value that represents encrypted security token

ThruSuccessUrl [mandatory] : Browser window containing Java upload applet will be redirected to this URL on successful upload

ThruErrorReportingUrl [mandatory] : Browser window containing Java applet will be redirected to this URL on failed upload. If upload failed, server will return server error code (see below) in parameter “ThruErrorCode”. If an error occurred and ThruErrorReportingURL is not defined then server will throw an exception in the page which contains Java upload applet.

Note: the value of ThruErrorReportingUrl is not validated. You should verify it is a valid URL that does exist when integrating Thru java upload applet.

ThruFileFilter [optional] : specifies which file types can be uploaded via Java applet Format: <Description> : <extension1>, <extension2> … <extensionN> . Example: ThruFileFilter=“Zip files (*.zip, *.7z, *.tar): zip, 7z, tar” will allow upload of files with zip, 7z, tar extensions. Browsing in Add button is allowed only to the files of specified type. Drag and drop for all other file types is ignored. If parameter is not specified, all file types can be uploaded.

ThruFileFilterExceptions [optional] : specifies which file types cannot be uploaded via Java applet. Format: <extension1>, <extensionX>. Example: ThruFileFilterExceptions=exe,msi,mp3 will prevent uploading of the file types exe, msi, mp3.

Note: Parameters ThruFileFilter and ThruFileFilterExceptions are mutually exclusive, only one can be used on java upload URL. If the same file extension is specified in ThruFileFilter and ThruFileFilterExceptions, the latter overrides the former.

ThruApplicationID [mandatory] : id of application for which the security token is created

8.1.5 Server Error Codes

These codes are passed as parameters to the ThruErrorReportingUrl in case any error occurs:

0 Unknown error, information is not available. 1 SessionID is not a valid Guid variable. 2 FolderID is not a valid integer variable. 3 Unknown ThruSessionID. Supplied session identifier does not exist on server 4 Folder with specified ID does not exist. 5 Upload failed. This is generic error code returned for any unknown error in upload. 6. ApplicationId is not present in URL 7. Token is invalid or expired


8.1.6 JavaScript Samples

(Session and folder ID are fictitious)

<html> <head> <script language="javascript" src="http://test.thruinc.net/Scripts/jquery-1.3.2.min.js" type="text/javascript"></script> <script language="javascript" type="text/javascript"> //sample with ThruFileFilter $(function(){ var session = '289BEE79-F1B6-4DDE-9A6B-DB5461780FCA'; var url = "https://test.thruinc.net/ExternalJavaUpload.aspx?"; url += "ThruFolderID=" + "1026"; url += "&ThruSessionID=" + session; url += "&ThruSuccessUrl=" + escape("http://someserver/ExtUpload/success.html"); url += "&ThruErrorReportingUrl=" + escape("http://someserver/ExtUpload/error.html"); url += "&ThruFileFilter=" + "Zip files (*.zip, *.7z, *.tar): zip, 7z, tar"; $("#f").attr("src", url); }); </script> </head> <body> <iframe id="f" width="800px" height="800px" src=""></iframe> </body> </html>

<html> <head> <script language="javascript" src="http://test.thruinc.net/Scripts/jquery-1.3.2.min.js" type="text/javascript"></script> <script language="javascript" type="text/javascript"> //sample with ThruFileFilterExceptions $(function(){ var session = '289BEE79-F1B6-4DDE-9A6B-DB5461780FCA'; var url = "https://test.thruinc.net/ExternalJavaUpload.aspx?"; url += "ThruFolderID=" + "1026"; url += "&ThruSessionID=" + session; url += "&ThruSuccessUrl=" + escape("http://someserver/ExtUpload/success.html"); url += "&ThruErrorReportingUrl=" + escape("http://someserver/ExtUpload/error.html"); url += "& ThruFileFilterExceptions=" + "exe,msi,mp3"; $("#f").attr("src", url); }); </script> </head> <body> <iframe id="f" width="800px" height="800px" src=""></iframe> </body> </html>


<html> <head> <script language="javascript" src="http://triton.actimind.com/Scripts/jquery-1.3.2.min.js" type="text/javascript"></script> <script language="javascript" type="text/javascript"> //sample with security token $(function(){ var session = '289BEE79-F1B6-4DDE-9A6B-DB5461780FCA'; var url = "https:// test.thruinc.net/ExternalJavaUpload?"; url += "ThruFolderID=" + " hLmrvNNh7rMjT/fLL27vyQDPXUl/UjBKKwurzLAxmopIxotP/T20Mz5J180jhG3Soqkz8bB1AV6rz3NMcyYtmm3mdo+CLeD0FDfgJZ6cw1Iqs9V+R79KsJ1mzfUKGrgQmrOq1NlosLcBtzmoVPW4+Cqkt+bkNBdYoYw8DITFkHd/VsEHCnk5pjPd89mDATyjTu4xMCXFVH20lP7tTOU75k61LLSj3X6bHzCuorKcUzp7nuvxve0se9cOdFQ3TA6XH78IMGmdoOz9JgDPITyz1Q=="; url += "&ThruSuccessUrl=" + escape("http://someserver/ExtUpload/success.html"); url += "&ThruErrorReportingUrl=" + escape("http://someserver/ExtUpload/error.html"); url += "&ThruFileFilter=" + "Zip files (*.zip, *.7z, *.tar): zip, 7z, tar"; url += "&ThruApplicationID=" + "1"; $("#f").attr("src", url); }); </script> </head> <body> <iframe id="f" width="800px" height="800px" src=""></iframe> </body> </html>

8.1.7 URL Samples

(Session and folderID are fictitious):

With file filter: http://test.thruinc.net/ExternalJavaUpload.aspx?ThruFolderID=1026&ThruSessionID=AF258C14-4425-4B30-834D-0EBD8EC55161&ThruSuccessUrl=http://www.thruinc.com&ThruErrorReportingUrl=http://www.yahoo.com&ThruFileFilter="Zip files (*.zip, *.7z, *.tar): zip, 7z, tar" With exclusion file filter: http://test.thruinc.net/ExternalJavaUpload.aspx?ThruFolderID=1026&ThruSessionID=AF258C14-4425-4B30-834D-0EBD8EC55161&ThruSuccessUrl=http://www.thruinc.com&ThruErrorReportingUrl=http://www.yahoo.com&ThruFileFilterExceptions="exe,msi,mp3” With security token: http://test.thruinc.net/ExternalJavaUpload.aspx?ThruFolderID= hLmrvNNh7rMjT/fLL27vyQDPXUl/UjBKKwurzLAxmopIxotP/T20Mz5J180jhG3Soqkz8bB1AV6rz3NMcyYtmm3mdo+CLeD0FDfgJZ6cw1Iqs9V+R79KsJ1mzfUKGrgQmrOq1NlosLcBtzmoVPW4+Cqkt+bkNBdYoYw8DITFkHd/VsEHCnk5pjPd89mDATyjTu4xMCXFVH20lP7tTOU75k61LLSj3X6bHzCuorKcUzp7nuvxve0se9cOdFQ3TA6XH78IMGmdoOz9JgDPITyz1Q==& ThruSuccessUrl=http://www.thruinc.com&ThruErrorReportingUrl=http://www.yahoo.com&ThruFileFilterExceptions="exe,msi,mp3” "&ThruApplicationID=341893067109


8.2 Java/HTML Download Tool and API

8.2.1 Overview

Any 3rd

party web or native application can use Thru Java download API to transfer files and folders from a Thru server. To download files and folders 3rd party application should call a URL in the following format: https://thruservername/ ExternalJavaDownload.aspx and supply parameters as specified below.

8.2.2 Security Token

The API links calling the download tool can be protected from being manually copied and used by a different user under the existing SessionID.

Token based security is used to protect a call to download tool. Token is encrypted by an application calling Thru API using a secret key shared with Thru. The token it passed to the Thru server and is decrypted using the shared key.

Security token structure for download tool is represented in JSON with following fields:

{

“Version” ,

“FilePublicID”,

“Email”,

“AllowedIP”,

“TimeStamp”

}

Where the parameters are:

Version : version of token object. Supported value: 1. FilePublicID: download ID of the file AccessID returned by the call RetrieveUploadInfo() Email : email of a user to record in audit records with operation. Could be different from a user account which opened a Thru server. AllowedIP : IP address allowed to perform the download, will be checked by Thru server. If the IP address of connecting browser does not match AllowedIP, operation is blocked. TimeStamp : time of token creation, used for token validation to protect against token replay. Thru server will check that token is not beyond expiration time interval defined in Thru server.

Note: Date should be strictly in the format MM/DD/YYY H:MM PM Sample Token: { "Version":"1", " FilePublicID":"0F540NC8ZAMQO", "Email":"[email protected]", "AllowedIP":"64.95.64.190", "TimeStamp":"10/04/2013 11:05:11", }

The following methods and options should be used by calling application to encrypt the token :


Encryption algorithm: Advanced Encryption Standard (AES-256) symmetric algorithm.

Encryptor specified key: shared key in base64string format

Initialization vector (IV): shared key in base64string format

Security token for URL should use base64string format. Sample of token encryption parameters:

Encryptor specified key: AFA3wdfEuCrdFw8QaHFzN6LRXaBoCTHxcWnqNImp7g3=

Initialization vector (IV): JHnmhMkTjkl8fHqYx/l7bA==

Encrypted token in base64string format: jGldNNh7rMjT/fLL27vyQDPXUl/UjBKKfgrzLAxmopIxotP/T20Mz5J180jhG3Soqkz8bB1AV6rz3NMcyYtmm3mdo+CLeD0FDfgJZ6cw1Iqs9V+R79KsJ1mzfUKGrgQmrOq1NlosLcBtzmoVLK4+Cqkt+bkNBdYoYw8DITFkHd/VsEHCnk5pjPd89mDATyjTu4xMCXFVH20lP7tTOU75k61LLSj3X6bHzCuorKcUzp7nuvxve0se9cOdFQ3TA6XH78IMGmdoOz9JgDPIThjeO==

8.2.3 Download Tool URL Parameters, option with no Security Token

ThruSessionId [mandatory] – Unique identifier of the current session.

ThruSuccessUrl [mandatory] : Browser window containing Java download applet will be redirected to this URL on successful download

ThruErrorReportingUrl [mandatory] : Browser window containing Java applet will be redirected to this URL on failed download. If download failed, server will return server error code (see below) in parameter “ThruErrorCode”. If an error occurred and ThruErrorReportingURL is not defined then server will throw an exception in the page which contains Java download applet. Note: the value of ThruErrorReportingUrl is not validated. You should verify it is a valid URL that does exist when integrating Thru java download applet.

ThruFiles [optional] – string of comma separated IDs of files to download. String format: <fileId1>,… <fileIdN> . Example: ThruFiles=“18270,18367”

ThruFolders [optional] – string of comma separated IDs of folders for download. String format: <fileId1>, <fileId2> … <fileIdN> . Example: ThruFolders=“198, 199”

Note: at least one parameter ThruFiles or ThruFolders should not be empty.

8.2.4 Download Tool URL Parameters, option with Security Token

Note: sessionID from Thru is not required of this type of download, user is not authenticated in Thru since calling application is supposed to authenticate a user.

ThruSuccessUrl [mandatory] : Browser window containing download tool will be redirected to this URL on successful download

ThruErrorReportingUrl [mandatory] : Browser window containing download tool will be redirected to this URL on failed download. If download failed, server will return server error code (see below) in parameter “ThruErrorCode”. If an error occurred and ThruErrorReportingURL is not defined then server will throw an exception in the page which contains Java download applet.


Note: the value of ThruErrorReportingUrl is not validated. You should verify it is a valid URL that does exist when integrating Thru download tool.

ThruFiles [optional] : string of comma separated tokens for file for downloads, one token per file. Token is represented in base64string format . String format: <encrypted token in base64format>, < encrypted token2 in base64format > … < encrypted tokenN in base64format >


8.2.5 Server Error Codes

These codes are passed as parameters to the ThruErrorReportingUrl in case any error occurs:

0 Unknown error, information is not available. 1 SessionID is not a valid Guid variable. 2 Unknown ThruSessionID. Supplied session identifier does not exist on server 3 ThruFiles or ThruFolders contain invalid ID integer value 4 ThruFiles or ThruFolders contain ID of the file or folder that does not exist 5 ThruFiles and ThruFolders parameters are empty. Nothing to download 6 Download failed. This is generic error code returned for any unknown error in Download. 7. ApplicationId is not present in URL 8. Token is invalid or expired

8.2.6 JavaScript Samples

(Session and folder IDs are fictitious)

<html><head> <script language="javascript" src="http:// test.thrudownload.com/Scripts/jquery-1.3.2.min.js" type="text/javascript"></script> <script language="javascript" type="text/javascript"> //download by authenticated user with SessionID $(function(){ var session = “dfb039f1-4488-4c96-a2ab-085de3ecf77d”; var url = “http://test.thruinc.net/ExternalJavaDownload.aspx?”; url += "&ThruSessionID=" + session; url += "ThruFiles=" + "18370, 18366"; url += "ThruFolders=" + "198"; url += "&ThruSuccessUrl=" + escape("http://server/ExtDownload/success.html"); url += "&ThruErrorReportingUrl=" + escape("http://server/ExtDownload/error.html"); $("#f").attr("src", url); }); </script> </head> <body> <iframe id="f" width="1px" height="1px" src=""></iframe> </body> </html> <html><head> <script language="javascript" src="http:// test.thrudownload.com/Scripts/jquery-1.3.2.min.js" type="text/javascript"></script> <script language="javascript" type="text/javascript"> //download by using security token $(function(){ var session = “dfb039f1-4488-4c96-a2ab-085de3ecf77d”; var url = “http://test.thruinc.net/ExternalJavaDownload.aspx?”; url += "ThruFiles=" + "hLmrvNNh7rMjT%2ffLL27vyQDPXUl%2fUjBKKwurzLAxmopIxotP%2fT20Mz5J180jhG3Soqkz8bB1AV6rz3NMcyYtmm3mdo%2bCLeD0FDfgJZ6cw1Iqs9V%2bR79KsJ1mzfUKGrgQmrOq1NlosLcBtzmoVPW4%2bCqkt%2bbkNBdYoYw8DITFkHd%2fVsEHCnk5pjPd89mDATyjTu4xMCXFVH20lP7tTOU75k61LLSj3X6bHzCuorKcUzp7nuvxve0se9cOdFQ3TA6XH78IMGmdoOz9JgDPITyz1Q"; url += "&ThruSuccessUrl=" + escape("http://server/ExtDownload/success.html"); url += "&ThruErrorReportingUrl=" + escape("http://server/ExtDownload/error.html"); $("#f").attr("src", url); }); </script>


</head> <body> <iframe id="f" width="1px" height="1px" src=""></iframe> </body> </html>

8.2.7 URL Sample

Download using Session ID for authenticated users: http://test.thruinc.net/ExternalJavaDownload.aspx?ThruSessionID=dfb039f1-4488-4c96-a2ab-085de3ecf77d&ThruFiles=18370,18366&ThruFolders=198&ThruSuccessUrl= http://server/ExtDownload/success.html&ThruErrorReportingUrl=http://server/ExtDownload/error.html

Download using security token:

http:// test.thrudownload.com

/ExternalJavaDownload.aspx?ThruSuccessUrl=http://google.com&ThruErrorReportingUrl=http://yahoo.co

m&ThruFiles=hLmrvNNh7rMjT%2ffLL27vyQDPXUl%2fUjBKKwurzLAxmopIxotP%2fT20Mz5J180jh

G3Soqkz8bB1AV6rz3NMcyYtmm3mdo%2bCLeD0FDfgJZ6cw1Iqs9V%2bR79KsJ1mzfUKGrgQmrOq1

NlosLcBtzmoVPW4%2bCqkt%2bbkNBdYoYw8DITFkHd%2fVsEHCnk5pjPd89mDATyjTu4xMCXFVH

20lP7tTOU75k61LLSj3X6bHzCuorKcUzp7nuvxve0se9cOdFQ3TA6XH78IMGmdoOz9JgDPITyz1Q%3d

%3d&ThruApplicationID=2987490673892


Appendix A – Error Codes returned by REST API

In case of unhandled error the 90000 code will be return to client.

Error Code Error Message

7001 Invalid username.

7002 Invalid password.

7003 Invalid application id.

7004 Invalid client version.

7005 Invalid session guid format.

7006 Invalid folder id.

7007 Invalid parent folder id.

7008 Invalid folder name.

7009 Invalid file id.

7010 Favorites already contain this folder.

7011 Favorites do not contain this folder.

7012 Favorites already contain this file.

7013 Favorites do not contain this file.

7014 Invalid system log operation type.

7015 Invalid mobile receiver application name.

7016 Invalid ticket subject.

7017 Invalid Thru date format.

7018 Collection contains invalid id.

7019 Invalid secure message id.

7020 End date of range is earlier than start date.

7021 Invalid email format.

7022 To recipient should be provided.

7023 Distribution cannot include requested folder:

access denied.

7024 Distribution cannot include requested file:

access denied.


7025 Invalid filter options value.

7026 Currently operation is not supported.

7027 File is quarantined.

7028 Cc invalid email format.

7029 Bcc invalid email format.

7030 Invalid secure message subject.

7031 Expired date does not satisfy server policy.

7032 Invalid secure message priority.


folder does not exist.


file does not exist.


file is quarantined.

7036 Distribution does not contain attached folder.

7037 Distribution does not contain attached file.

7038 Distribution does not contain recipient [Recipient email]

7039 Distribution does not contain attached folders.

7040 Distribution does not contain attached files.

7041 Request login option does not correspond

to the server policy.


folder is deleted.


file is deleted.

7044 Skip value must be greater or equal than 0.

7045 Invalid confirm password

7046 Message can only be discarded before it is sent.

7047 Message has been already sent.

7048 Access Denied, login from any mobile devices for this site is not allowed.


7049 Access Denied, login from this mobile device for this user and application is not allowed.

102 Invalid Username or Password.

103 Requested folder does not exist.

104 File does not exist.

111 Distribution does not exist.

145 Missing new password.

146 Missing old password.

147 Invalid old password.

6 Invalid IP Address.


About Trademarks and Abbreviations

Thru and the Thru logo are registered trademarks of Thru, Inc.

Microsoft, Windows, and Outlook are trademarks of Microsoft Corporation in the United States and/or other countries.

Other company or product names used in this manual and not included in the list above are trademarks of those companies and may be registered in certain jurisdictions.

© 2014 Thru, LLC All rights reserved.

909 Lake Carolyn Parkway, Suite 750 Irving, Texas 75039 Phone: 214.496.0100 Fax: 972.767.4523 www.thruinc.com

http://www.thruinc.com/

Thru rest api_1_0_ref_1_7

Documents

Transcript of Thru rest api_1_0_ref_1_7