Manage files using Entity class

Level: intermediate

note

This functionality is available for Creatio 8.3.2 and later.

Since version 8.3.2, Creatio lets you manage files using the File API through the Entity class. The API supports CRUD operations for files stored either in the Creatio database or in external file storage, such as AWS S3 or Azure Blob storage. Learn more: File API.

To use the File API through the Entity class, make sure the UseEntityFileApi additional feature is enabled. Instructions: Manage the status of an additional feature. When the feature is enabled, Creatio uses the File API for all operations with file objects. For non-file objects, behavior remains unchanged.

We recommend storing files in external file storage instead of the database, regardless of the access method used (either the File API directly or via the Entity class). This can improve solution reliability, cost efficiency, and maintainability. Learn more: File storage (user documentation).

When managing file records using the File API through the Entity class, avoid specifying the SysFileStorageId, Size, and TotalSize properties explicitly. These values are managed by Creatio automatically for all CRUD operations.

Objects that store files

Creatio stores files in dedicated objects. Each object corresponds either to a specific parent object or to a generic file storage model that can be used across multiple objects. The choice of an object determines how the file is linked to its parent object and which request parameters are required when working with the API.

View examples of objects used for file storage in the table below. The complete list of objects is available in the Creatio. Objects that store files have the "File" suffix.

Object	Description	Parent object
"Uploaded file" (SysFile code)	Generic file storage.	Any object
"File and link of activity" (ActivityFile code)	Files attached to activities.	"Activity" (Activity code)
"Contact attachment" (ContactFile code)	Files attached to contacts.	"Contact" (Contact code)
"File and link of account" (AccountFile code)	Files attached to accounts.	"Account" (Account code)
"Attachments and notes detail object in Cases section" (CaseFile code)	Files attached to support cases.	"Case" (Case code)
"Order files" (OrderFile code)	Files attached to orders.	"Order" (Order code)
"File and link of opportunity" (OpportunityFile code)	Files attached to opportunities.	"Opportunity" (Opportunity code)

In most cases, you can store files using the generic "Uploaded file" (SysFile code) object, which is used automatically for custom apps. We recommend creating a dedicated file object for custom apps that are expected to store a large number of files or require separate file management for a specific business scenario. This approach helps organize file storage better, improves scalability, and aligns with how Creatio implements file storage in some out-of-the-box apps.

Identify file objects

To check whether an "Object" type schema is a file object, use the following code:

Check whether an "Object" type schema represents a file object

EntitySchema schema = userConnection.EntitySchemaManager.GetInstanceByName("SysFile");
bool isFile = schema.IsFile;

If schema.IsFile == true, the "Object" type schema represents a file object, and Creatio lets you manage files using the File API through the Entity class.

Usage examples

Create a file

View the examples that demonstrate different ways to create a file below.

Create a file with immediate data saving

View the example that creates a file record using the "Uploaded file" (SysFile code) object and saves the file content to the storage immediately below.

Create a file with immediate data saving

/* Create a file record using the "SysFile" object and save the file content to
the storage immediately. */
public bool CreateFileWithData(UserConnection userConnection)
{
    /* Retrieve the "SysFile" object. */
    EntitySchema fileSchema = userConnection.EntitySchemaManager.GetInstanceByName("SysFile");

    /* Create a file record using the "Entity" class. */
    Entity fileEntity = fileSchema.CreateEntity(userConnection);

    /* Populate the record using default column values. */
    fileEntity.SetDefColumnValues();

    /* Set the file name. */
    fileEntity.SetColumnValue("Name", "some-file-name.txt");

    /* Convert the file content to a byte array. */
    byte[] fileContent = System.Text.Encoding.UTF8.GetBytes("Some file content");

    /* Assign the binary file content to the "Data" column. */
    fileEntity.SetBytesValue("Data", fileContent);

    /* Save the file record and persist the content to the storage. */
    bool result = fileEntity.Save();

    /* Return the result of the save operation. */
    return result;
}

Create a file with deferred data saving

If you call the Save() method without calling SetBytesValue() first, only file metadata is created. The actual file content is saved to storage only after calling SetBytesValue() followed by Save().

View the example that creates a file record using the "Uploaded file" (SysFile code) object and saves only the file metadata below. The binary file content is added and persisted to the storage in a separate operation.

Create a file with deferred data saving

/* Create a file record using the "SysFile" object without saving file content. */
public Guid CreateFileMetadataOnly(UserConnection userConnection)
{
    /* Retrieve the "SysFile" object. */
    EntitySchema fileSchema = userConnection.EntitySchemaManager.GetInstanceByName("SysFile");

    /* Create a file record using the "Entity" class. */
    Entity fileEntity = fileSchema.CreateEntity(userConnection);

    /* Populate the record using default column values. */
    fileEntity.SetDefColumnValues();

    /* Set the file name. */
    fileEntity.SetColumnValue("Name", "SomeFileName.pdf");

    /* Save the file record metadata without file content. */
    fileEntity.Save();

    /* Return the ID of the created file record. */
    return fileEntity.PrimaryColumnValue;
}

/* Add binary file content to an existing file record and save it to the storage. */
public bool AddFileContent(UserConnection userConnection, Guid fileId)
{
    /* Retrieve the "SysFile" object. */
    EntitySchema fileSchema = userConnection.EntitySchemaManager.GetInstanceByName("SysFile");

    /* Create a file record using the "Entity" class. */
    Entity fileEntity = fileSchema.CreateEntity(userConnection);

    /* Load the existing file record by its ID. */
    if (!fileEntity.FetchFromDB(fileId))
    {
        return false;
    }

    /* Retrieve the file content as a byte array.
    "GetPdfContent()" is a custom method that returns file content. */
    byte[] fileContent = GetPdfContent();

    /* Assign the binary file content to the "Data" column. */
    fileEntity.SetBytesValue("Data", fileContent);

    /* Save the file record and persist the content to the storage. */
    return fileEntity.Save();
}

Create a file linked to a contact

When working with file objects that have a master-detail relationship, for example, ContactFile, ActivityFile, the file record must be linked to its parent record explicitly. To do this, set the reference column value using the SetPropertyValue() method before saving the file record.

View the example that creates a file record using the "Contact attachment" (ContactFile code) object, binds it to a contact record, and saves the file content to the storage below.

Create a file linked to a contact

/* Create a file record using the "ContactFile" object and bind it to a contact. */
public bool CreateContactFile(UserConnection userConnection, Guid contactId)
{
    /* Retrieve the "ContactFile" object. */
    EntitySchema fileSchema = userConnection.EntitySchemaManager.GetInstanceByName("ContactFile");

    /* Create a file record using the "Entity" class. */
    Entity fileEntity = fileSchema.CreateEntity(userConnection);

    /* Populate the record using default column values. */
    fileEntity.SetDefColumnValues();

    /* Set the file name. */
    fileEntity.SetColumnValue("Name", "SomeContactPhoto.jpg");

    /* Bind the file record to the contact record. */
    fileEntity.SetPropertyValue("ContactId", contactId);

    /* Retrieve the file content as a byte array.
    "GetImageBytes()" is a custom method that returns image data. */
    byte[] imageData = GetImageBytes();

    /* Assign the binary file content to the "Data" column. */
    fileEntity.SetBytesValue("Data", imageData);

    /* Save the file record and persist the content to the storage. */
    return fileEntity.Save();
}

Create a file using the generic SysFile object

When working with the generic "Uploaded file" (SysFile code) file object, files are linked to parent records using a polymorphic relationship. Unlike object-specific file objects, SysFile can be linked to records of any object dynamically. In this case, the file record is associated with a parent object by specifying the following parameters before saving the file:

• RecordSchemaName is the code of the parent "Object" type schema.
• RecordId is the ID of the parent record to which the file is attached. Used together with RecordSchemaName to establish the link between the file and the target object.

View the example that creates a file record using the "Uploaded file" (SysFile code) object, binds it to a parent record dynamically, and saves the file content to the storage below.

Create a file using the generic SysFile object

/* Create a file record using the "SysFile" object and bind it to a parent record
using a polymorphic relationship. */
public bool CreateSysFile(UserConnection userConnection, Guid recordId, string schemaName)
{
    /* Retrieve the "SysFile" object. */
    EntitySchema fileSchema = userConnection.EntitySchemaManager.GetInstanceByName("SysFile");

    /* Create a file record using the "Entity" class. */
    Entity fileEntity = fileSchema.CreateEntity(userConnection);

    /* Populate the record using default column values. */
    fileEntity.SetDefColumnValues();

    /* Set the file name. */
    fileEntity.SetColumnValue("Name", "SomeFileName.pdf");

    /* Bind the file record to the parent record by specifying the code of the
    parent "Object" type schema and the ID of the parent record to which the file
    is attached. */
    fileEntity.SetColumnValue("RecordSchemaName", schemaName);
    fileEntity.SetColumnValue("RecordId", recordId);

    /* Retrieve the file content as a byte array.
    "GetPdfContent()" is a custom method that returns file content. */
    byte[] fileContent = GetPdfContent();

    /* Assign the binary file content to the "Data" column. */
    fileEntity.SetBytesValue("Data", fileContent);

    /* Save the file record and persist the content to the storage. */
    return fileEntity.Save();
}

Read a file

The Entity class provides several methods for reading binary file content from the "Data" column. Choose the appropriate method based on the business goals listed in the table below.

Business goal	Method
Read file content as a byte array	byte[] GetBytesValue(string valueName) Parameters valueName The name of the object column that stores binary file content.
Read file content as a stream, for example, to write it to a response or pass it to another API	MemoryStream GetStreamValue(string valueName) Parameters valueName The name of the object column that stores binary file content.

Read file content as a byte array

View the example that retrieves the binary content of an existing file record from the "Uploaded file" (SysFile code) object as a byte array below.

Read file content as a byte array

/* Retrieve the binary content of a file record as a byte array. */
public byte[] ReadFileContent(UserConnection userConnection, Guid fileId)
{
    /* Retrieve the "SysFile" object. */
    EntitySchema fileSchema = userConnection.EntitySchemaManager.GetInstanceByName("SysFile");

    /* Create a file record using the "Entity" class. */
    Entity fileEntity = fileSchema.CreateEntity(userConnection);

    /* Load the existing file record by its ID. */
    if (!fileEntity.FetchFromDB(fileId))
    {
        return null;
    }

    /* Retrieve the binary file content from the "Data" column as a byte array. */
    byte[] fileContent = fileEntity.GetBytesValue("Data");

    /* Return the file content. */
    return fileContent;
}

Read file content as a stream

View the example that retrieves the binary content of an existing file record from the "Uploaded file" (SysFile code) object as a stream below.

Read file content as a stream

/* Retrieve the binary content of a file record as a stream. */
public MemoryStream ReadFileAsStream(UserConnection userConnection, Guid fileId)
{
    /* Retrieve the "SysFile" object. */
    EntitySchema fileSchema = userConnection.EntitySchemaManager.GetInstanceByName("SysFile");

    /* Create a file record using the "Entity" class. */
    Entity fileEntity = fileSchema.CreateEntity(userConnection);

    /* Load the existing file record by its ID. */
    if (!fileEntity.FetchFromDB(fileId))
    {
        return null;
    }

    /* Retrieve the binary file content from the "Data" column as a stream. */
    MemoryStream fileStream = fileEntity.GetStreamValue("Data");

    /* Return the file stream. */
    return fileStream;
}

Update a file

View the example that updates the binary content of an existing file record using the "Uploaded file" (SysFile code) object below.

Update a file

/* Update the binary content of an existing file record. */
public bool UpdateFileContent(UserConnection userConnection, Guid fileId, byte[] newContent)
{
    /* Retrieve the "SysFile" object. */
    EntitySchema fileSchema = userConnection.EntitySchemaManager.GetInstanceByName("SysFile");

    /* Create a file record using the "Entity" class. */
    Entity fileEntity = fileSchema.CreateEntity(userConnection);

    /* Load the existing file record by its ID. */
    if (!fileEntity.FetchFromDB(fileId))
    {
        return false;
    }

    /* Assign the new binary file content to the "Data" column. */
    fileEntity.SetBytesValue("Data", newContent);

    /* Update the file name (optional). */
    fileEntity.SetColumnValue("Name", "NewFileName.txt");

    /* Save the file record and persist the updated content to the storage. */
    return fileEntity.Save();
}

Delete a file

When deleting a file record, both the file metadata and the corresponding binary content are removed automatically. This behavior ensures that no unreferenced files remain in the storage.

View the example that deletes an existing file record created using the "Uploaded file" (SysFile code) object below.

Delete a file

/* Delete an existing file record along with its binary content. */
public bool DeleteFile(UserConnection userConnection, Guid fileId)
{
    /* Retrieve the "SysFile" object. */
    EntitySchema fileSchema = userConnection.EntitySchemaManager.GetInstanceByName("SysFile");

    /* Create a file record using the "Entity" class. */
    Entity fileEntity = fileSchema.CreateEntity(userConnection);

    /* Load the existing file record by its ID. */
    if (!fileEntity.FetchFromDB(fileId))
    {
        return false;
    }

    /* Delete the file record. Both the metadata and the file content are removed from the storage. */
    bool result = fileEntity.Delete();

    /* Return the result of the delete operation. */
    return result;
}

---

See also

File API

Manage the database records

Data access through ORM

File storage (user documentation)

Manage an existing additional feature