Centralized File Storage

The Centralized File Storage System (CFS) is a special In-Process API that orchestrates all file management within Verint Community. It is used by plugins and external applications to interact with files (create, update, delete, retrieve, list, etc) within one or more file stores with files stored via a specific provider in one or more physical locations

When Would I use the CFS?

Oftentimes, interaction with the CFS is indirect. Uploading a file into a media gallery, for example, is an abstraction of basic CFS interaction for media galleries. Custom integrated extensions to the Verint Community platform may require a location to store files directly as part of their implementation can can interact with the CFS more directly by defining new file stores. It is also possible to change where the CFS physically stores files by implementing a custom file storage provider.

Creating New File Stores

New file stores are created by implementing the ICentralizedFileStore plugin type. See the tutorial for more details and extensions. Generally plugins or sets of plugins should only interact with file stores they directly define and any general-purpose access should be exposed as a new APIs.

Creating New File Storage Providers

The CFS can be configured to store files physically on the file system (either local or on a UNC share) or on Amazon S3 by default. New providers can be defined to enable physically storing files using other services as well. See the tutorial for more details and extensions.

CFS Concepts

File Stores

A file store is a collection of files that serve a common purpose. Examples of a file store would include user avatars, media gallery files, or widget source files. File stores are created by implementing ICentralizedFileStore and its extensions and is identified within the CFS API via its file store key, a string name that uniquely identifies the file store.

Within file stores, files are stored using a path and a file name.

The path can have multiple components, separated by periods. Paths must be between 0 and 769 characters and cannot contain characters that are invalid on Windows file systems. A path must not exist prior to being used (unlike windows file systems) and, when it contains no files, the CFS will generally remove all references to empty paths.

File names uniquely identify files within a path in a file store. File names must be between 1 and 255 characters and cannot contain characters that are invalid on Windows file systems.

File Storage Providers

A file storage provider enables the CFS to store one or more file stores at a new physical location. Verint Community, by default, has support for local filesystem storage and storage in Amazon's S3 service. New file storage providers can be created to support storing files elsewhere, if desired.

The association of a provider to one or more file stores is defined within the communityserver.config file.

Interacting With Files

Within plugins, the CFS is exposed by the CentralizedFileStorage API. This API provides events, properties and methods to:

Validate paths, file names, and file access
Retrieve file stores
Format paths
Handle file-related events
Generate URLs to files and determine which file is identified by a URL

Adding, updating, deleting, and retrieving files is exposed through a specific file store which is represented using a configured CFS providerfor the file store. Files retrieved from the CFS are implementations of ICentralizedFile which provides files details such as the name, URL, stream, and length.

Adding a File

Generally, you would not add a file directly to a CFS file store unless your code also defined the file store. Usually a more use-specific API is exposed on top of a file store. However, if you want to use a file store that you also defined, you can use code like the following:

CentralizedFileStore fileStore = CentralizedFileStorage.GetFileStore("myfilestorekey");
CentralizedFile file = null;
if (fileStore != null)
    file = fileStore.AddFile("fileName.txt", new System.IO.MemoryStream(System.Text.Encoding.UTF8.GetBytes("Content of the file")), new AddFileOptions
	{
		Path = CentralizedFileStorage.MakePath(["folder1", "folder2"]),
		OverwriteOption = OverwriteOptions.Overwrite
	});

First, we retrieve the file store implementation by name (where we've first created a file store named "myfilestorekey"). If the file store can be retrieved, the result will be a CentralizedFileStore instance. Using the fileStore instance, we can call AddFile() with a file name ("fileName.txt"), content (the resulting stream of the UTF8 bytes representing "Content of the file"), and options.

Listing Files

As with adding a file, listing files is a function of the file store's implementation. To list the file we added (and any other files in the same path):

CentralizedFileStore fileStore = CentralizedFileStorage.GetFileStore("myfilestorekey");
System.Collections.Generic.IEnumerable<CentralizedFile> files = null;
if (fileStore != null)
	files = fileStore.GetFiles(new GetFilesOptions
	{
		Path = CentralizedFileStorage.MakePath("folder1", "folder2"),
		SearchOptions = PathSearchOption.TopLevelPathOnly
	});

When listing files, the GetFiles() method supports filtering to a specific path and including either files directly in that path only (PathSearchOption.TopLevelPathOnly) or all files in that path or sub-paths (PathSearchOption.AllPaths).

Deleting a File

To delete a file, again we use the file store instance:

CentralizedFileStore fileStore = CentralizedFileStorage.GetFileStore("myfilestorekey");
if (fileStore != null)
	fileStore.Delete(new DeleteOptions
	{
		FileName = "fileName.txt",
		Path = CentralizedFileStorage.MakePath(["folder1", "folder2"])
	});

Note that no exception will be raised if the file doesn't exist. If the file exists, it is deleted. If it doesn't exist, the method returns normally. The Delete() method can also delete all files in path or in an entire file store. When deleting a path, any files matching that path as a prefix are deleted (for example, deleting the path "path.t" would delete the path "path.to" as well as "path.two", if both existed).

Generating a URL to a File

When generating a URL to a file, the use and duration of the URL should be considered. URLs can be retrieved one of two ways:

Generic URLs

Generic URLs are suitable for persisting within content for long periods of time (for example, saving to a database) and are not directly related to delivery configuration (CDN enablement or implementation). These URLs reference the CFS system directly. To get a generic URL:

CentralizedFileStore fileStore = CentralizedFileStorage.GetFileStore("myfilestorekey");
CentralizedFile file = null;
string genericUrl = null;

if (fileStore != null)
	file = fileStore.GetFile("fileName.txt", new GetFileOptions
	{
		Path = CentralizedFileStorage.MakePath(["folder1", "folder2"])
	});

if (file != null)
	genericUrl = file.GetGenericUrl();

Delivery URLs

Delivery URLs are suitable only for presentation rendering. Delivery URLs will link to the CDN if applicable or fallback to the generic URL (if a CDN is not currently configured or is not capable of delivering the requested file). To get a delivery URL:

CentralizedFileStore fileStore = CentralizedFileStorage.GetFileStore("myfilestorekey");
CentralizedFile file = null;
string deliveryUrl = null;

if (fileStore != null)
	file = fileStore.GetFile("fileName.txt", new GetFileOptions
	{
		Path = CentralizedFileStorage.MakePath(["folder1", "folder2"])
	});

if (file != null)
	deliveryUrl = file.GetDeliveryUrl();

Retrieving a File using its URL

When you have a URL and want to check if it is stored in the CFS, the IsCentralizedFile() and GetCentralizedFileByUrl() methods are useful:

string url = "http://example.com/sys/file/__key/myfilestorekey/path-to-file/fileName.txt";
CentralizedFile file = null;

if (CentralizedFileStorage.IsCentralizedFileUrl(url))
	file = CentralizedFileStorage.GetCentralizedFileByUrl(url);

Note that these methods only work when the URL is of the generic format (see Generating a URL to a File above).