20 File Services, Version 1.0

This chapter provides the information necessary to send messages contained in Version 1.0 of the File Services API, which is used to facilitate downloading files generated by Customer Engagement and uploading XML files for batch import.

File Services is a RESTful API rather than SOAP. The information presented describes the methods and classes.The format of the method and any arguments is shown along with an explanation of what the method does and any other information that is necessary to use the method properly. If an argument is shown in dark blue, it is a class and the class name is a link to a description of the class and its attributes.

The class section shows the attributes of the classes along with an explanation of each attribute and when necessary, when they are used.

Note:

Authentication is required. See Introduction for information on creating and implementing an authentication key.

Methods

This section presents the methods used in Version 1.0 of the File Services API.

Create Pre-Authenticated Request

Use this service to create a Pre-Authenticated Request (PAR) for a resource in Object Storage. The PAR response contains a URL to a file or location to either download an existing file or upload a new file. The URL takes no additional authorization to use.

Note:

Files names referenced in the message body are case sensitive. Requesting a PAR to download a file, for example, must have the objectName field match the file in Object Storage exactly.

POST	https://<host>/ws/v1/FileServices/par

Message Body Schema

Value	Type	Description
accessType	enum	ObjectRead - Read only access to existing file; allows GET method to created URI.ObjectWrite - Write only access to a file; can be used to overwrite existing file; allows PUT method to created URI.ObjectReadWrite - Read access to existing file and write access to new or existing file.AnyObjectWrite - Write access for many new files; used on conjunction with objectNames field
name	string	Name of the PAR; value can be anything.
objectName	string	Name of file with folder prefix.Ignored when using AnyObjectWrite access type.
objectNames[]	string	Array of file names with folder prefix.Used when requesting a multi-file upload PAR with access type AnyObjectWrite.

Response

Value	Type	Description
id	string	Identifier value generated by Object Storage for this PAR.
name	string	Name of PAR echoed back from request detail.
accessUrl	string	URL to resource on Object Storage to read existing file or upload new file.
objectName	string	Name of file echoed from request detail.
objectNames[]	string	Array of file names echoed from request detail.
accessType	enum	Access type echoed from request detail.
timeExpires	string	Date and time the PAR expires, after which attempting GET/PUT/POST against the access URI will result in an error from Object Storage.Times in UTC ISO-8601 format YYYY-MM-DDThh:mm:ss.sTZD
timeCreated	string	Date and time the PAR was created.Times in UTC ISO-8601 format YYYY-MM-DDThh:mm:ss.sTZD

Get List of Files

Retrieve a list of files currently in Object Storage for this client environment. Several query parameters allow filtering the search results in a variety of ways.

Note:

The folder prefix and file name searches are case insensitive, making it easier to find relevant files. However, the exact file name must be used in the objectName field when requesting a Pre-Authenticated Request to download the file.

GET	https://<host>/ws/v1/FileServices/object

Parameters

Value	Type	Description
prefix	string	Folder name used to filter the file list.
contains	string	Search for files containing this string.
scanStatus	enum	Retrieve files with this specific virus scan status. Valid values:PendingScanningPassedFailed
nameStart	string	Lexicographic comparison of file names.Equivalent to "file name greater than or equal to nameStart"
nameEnd	string	Lexicographic comparison of file names.Equivalent to "file name less than nameEnd"
limit	integer	Limits response to a fixed number of data items to control paging of results. Use is optional.
offset	integer	Starting index for the page of results to retrieve.
sort	string	Name of field to sort search results. All fields in the response are sortable.Expected format: [field name]:[asc or desc]Defaults to ascending if direction is not provided.Defaults to Last Modified descending if NO sort order provided in request. Last Modified descending is added as a secondary sort to all search results.

Response

Value	Type	Description
resultSet[]	object	List of ObjectSummary objects.
totalResults	integer	Total number of rows that match the search results.
limit	integer	Limit value echoed from request parameter, or if value was not provided the default limit.
offset	integer	Offset value echoed from request parameter.
hasMore	boolean	true if there are more records beyond the current offset and page of results.false if there are no more rows beyond the current page.

ObjectSummary Type

Value	Type	Description
name	string	Name of file.
size	long	Size of the file in bytes.
md5	string	MD5 hash
etag	string	String generated by Object Storage that is a unique identifier for this file.
createdDate	string	Date file was uploaded to Object Storage.Times in UTC ISO-8601 format YYYY-MM-DDThh:mm:ss.sTZD
modifiedDate	string	Reserved for future use. Currently same value as createdDate.Times in UTC ISO-8601 format YYYY-MM-DDThh:mm:ss.sTZD
scanStatus	string	Retrieve files with this specific virus scan status.Pending - File has not been virus scanned yet.Scanning - Virus scan is actively in progress.Passed - Virus scan passed.Failed - Virus scan failed.
scanMessage	string	Result of virus scan. May be a pass or fail message or general error text.
scanDate	string	Date of last virus scan attempt.