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:
- Create an implementation of the Terrasoft.File.Abstractions.Content.IFileContentStorage interface that describes the API required for working with the file storage.
- 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.
- 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. |
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. |
Terrasoft.File.Abstractions namespace.
The Terrasoft.File.Abstractions.IFile interface provides essential file management methods applicable in any file storage. 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.
Properties
The file locator connected to the current instance of the class that implements the IFile interface.
File name.
The size of the current file in bytes.
Date and time the file was created.
Date and time the file was modified.
Checks if the current file exists.
Methods
Copies the current file to the new target asynchronously.
Moves the current file to the new target asynchronously.
Deletes the current file asynchrously.
Writes the contents of the current file to the stream asynchronously.
Reads the contents of the current file asynchronously.
Saves the metadata of the current file asynchronously.
Sets value of the name attribute for the current file.
Returns the attribute value or the default value for the current file.
Terrasoft.File.Abstractions namespace.
The Terrasoft.File.Abstractions.IFileFactory interface provides a set of methods to get or create an instance of the class that implements the Terrasoft.File.Abstractions.IFile interface.
Terrasoft.File namespace.
The Terrasoft.File.EntityFileMetadata class implements the Terrasoft.File.Abstractions.Metadata.FileMetadata abstract class. This class describes the file metadata in the [Attachments] object and provide the methods to manage them.
Terrasoft.File namespace.
The Terrasoft.File.FileFactoryUtils class provides extension methods for the UserConnection class and factory class that implements the Terrasoft.File.AbstractionsIFileFactory interface. This way, the class provides access to the factory for creating new or getting existing files. Therefore, an instance of UserConnection or SystemUserConnection is required for file management.
Methods
An extension method for the UserConnection class that returns an instance of the class that implements the IFileFactory interface.
An extension method for the UserConnection class that returns an instance of the class that implements the IFile interface from a given fileLocator.
An extension method for the UserConnection class that creates an instance of the class that implements the IFile interface from a given fileLocator.
An extension method for the class that implements the IFileFactory interface. Returns an instance of the class that implements the IFile interface for a given fileLocator.
An extension method for the class that implements the IFileFactory interface. Creates an instance of the class that implements the IFile interface for a given fileLocator.
An extension method for the class that implements the IFileFactory interface. Returns an instance of the class that implements the IFileFactory interface configured without the access permissions of the user.
Terrasoft.File.Abstractions.Metadata namespace.
The Terrasoft.File.Abstractions.Metadata.FileMetadata abstract class provides the properties of file metadata and methods for metadata management,
Terrasoft.File.Abstractions namespace.
The Terrasoft.File.Abstractions.FileUtils class provides extension methods for file management.
Methods
Sets the file attributes to the values passed in the attributes collection.
Saves the metadata of the file.
Reads the content of the file.
Writes the content of the file.
source | The file whose contents is to be written |
stream | The stream that provides the file content. |
writeOptions | Parameters for writing the file. |
content | The file content as an array of bytes. |
Deletes the specified file.
Copies the existing source file to the new target file.
Moves the existing source file to the new target destination.