API for file management

Level: intermediate

Creatio core provides a set of file management classes and interfaces in version 7.17.2 and up:

• Terrasoft.File.Abstractions namespace – interfaces and abstract classes that specify the file management logic in Creatio.
• Terrasoft.File namespace – concrete implementations of the abstractions used in Creatio.

The location of a file and file locators

The location of a file is specified using a file locator, which is an object that implements the Terrasoft.File.Abstractions.IFileLocator interface.

A file locator must contain a unique file identifier: RecordId.

You can create different file locator implementations for different file storages. Depending on the file storage mechanics, the file locator may have extra properties for the identification of the file location. For example, the Terrasoft.File.EntityFileLocator class is an implementation of the file locator for the current [Attachments] file storage in Creatio. An EntityFileLocator object has the base RecordId property and an EntitySchemaName property: the name of the object schema where the file is stored, for example: "ActivityFile" or "CaseFile".

All file management methods employ file locators.

Files and file storages

File structure in Creatio:

• file metadata
• file content.

Metadata describe the file properties:

• name
• size in bytes
• creation date, etc.

File metadata are based on the Terrasoft.File.Abstractions.Metadata.FileMetadata abstract class. Let’s consider the Terrasoft.File.Metadata.EntityFileMetadata class as its concrete implementation. This class describes the metadata of the [Attachments] object files.

“Content” is the contents of the file.

In Creatio, the file metadata and content are stored in different storages.

• The file metadata storage must implement the Terrasoft.File.Abstractions.Metadata.IFileMetadataStorage interface.
• The file content storage must implement the Terrasoft.File.Abstractions.Metadata.IFileContentStorage interface.

Specific implementations of these interfaces cover all subtle aspects of interaction with different file storage systems: Creatio [Attachments], the filesystem of the server, Amazon S3. Google Drive, etc.

The Terrasoft.File.Abstractions.IFile interface provides essential file management methods applicable in any file storage. In terms of Creatio, a file is an implementation of this interface. The methods of this interface are used for asynchronous file management. Synchronous file management methods are available in the Terrasoft.File.Abstractions.FileUtils derived class.

Get a file (IFileFactory)

The Terrasoft.File.Abstractions.IFileFactory interface provides methods for creating and getting objects of a class that implements the Terrasoft.File.Abstractions.IFile interface. This interface is implemented by a factory accessed using the methods of the Terrasoft.File.FileFactoryUtils class that extends the UserConnection class. Therefore, an instance of UserConnection or SystemUserConnection is required for file management.

The location of a new or existing file is unambiguously determined by its file locator. To access an existing file, its RecordId identifier is required. For a new file, create an identifier and pass it to the locator creation method.

Implement and register a new file storage type

To implement a new file storage type:

1. Create an implementation of the Terrasoft.File.Abstractions.Content.IFileContentStorage interface that describes the API required for working with the file storage.
2. If the current file metadata storage (Terrasoft.File.Metadata.EntityFileMetadataStorage) is not sufficient for your tasks, implement your own metadata storage, metadata type, and file locator type:
   • The file metadata storage must implement the Terrasoft.File.Abstractions.Metadata.IFileMetadataStorage interface.
   • The file locator must implement the Terrasoft.File.Abstractions.IFileLocator interface.
   • The metadata class must inherit from the Terrasoft.File.Abstractions.Metadata.FileMetadata class.
3. The new file content storage and file metadata storage must be registered in the corresponding “SysFileContentStorage” and “SysFileMetadataStorage” lookups*.*

File management exceptions

Exception type	Message	Exception conditions
Terrasoft.File.Abstractions. FileNotFoundByLocatorException	File not found by locator '{locator_type}{locator.ToString}’	When accessing any properties or methods of the IFile interface if the file metadata are not found.
System.InvalidOperationException	Can't delete new file: '{locator_type}{locator.ToString}'	When attempting to delete a newly created file: FileMetadata.StoringState == FileStoringState.New
Terrasoft.Common.NullOrEmptyException	File name cannot be null or empty	When attempting to save a file with the Name field left blank
System.InvalidOperationException	Can't find a metadata storage for the '{locator_type}' locator type	If a file metadata storage compatible by the locator type is not found.
System.InvalidOperationException	Can't find a content storage for the '{metadata_type}' metadata type	If a file content storage compatible by the metadata type is not found.