Skip to main content
Version: 8.3

File data model and relationship patterns

Level: advanced
note

This functionality is available for Creatio 8.3.2 and later.

Since version 8.3.2, Creatio provides a dedicated API exposed via OData 4 for managing files. The API enables CRUD operations for files stored either in the Creatio database or in an external file storage, such as AWS S3 or Azure Blob storage. Learn more: Endpoints for working with files via OData 4.

We recommend storing files in external file storage instead of the database. This can improve solution reliability, cost efficiency, and maintainability. Learn more: File storage (user documentation).

Use the following URL to access Creatio objects for executing CRUD operations with files via the OData 4 protocol for .NET Framework: {CreatioURL}/0/odata/{FileObjectName}, where {FileTableName} is a file object.

For example, use https://mycreatio.com/0/odata/ContactFile to work with files attached to contacts.

For .NET, the /0 prefix is optional. The endpoint structure is otherwise identical.

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 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.

Relationship patterns​

When creating a file using OData 4, it is important to understand how files are linked to business objects in Creatio. The selected relationship pattern determines:

  • which object to use
  • which request parameters are required
  • how file metadata references the parent object

Creatio supports the following approaches for linking files to objects:

  • a polymorphic relationship via the "Uploaded file" (SysFile code) object for flexible integrations
  • a direct foreign key relationship via object-specific file objects for scenarios with a predefined parent object

Choose the appropriate relationship pattern based on the integration scenarios listed in the table below.

Relationship pattern

Integration scenarios

Polymorphic relationship via the "Uploaded file" (SysFile code) object

  • Attach files to different object types using a single integration
  • Determine the parent object dynamically at runtime
  • Implement generic or reusable file management logic
  • Minimize object-specific dependencies in integrations

Direct foreign key relationship via object-specific file objects. For example, "Contact attachment" (ContactFile code), "File and link of activity" (ActivityFile code).

  • Attach files to a known object type, such as Contact, Account, or Opportunity
  • Simplify OData requests by using a dedicated reference column
  • Ensure strong typing and clearer data relationships
  • Reduce integration complexity for object-specific scenarios

Polymorphic relationship via the SysFile object​

"Uploaded file" (SysFile code) object is a universal object that stores files related to any Creatio object. Instead of a direct foreign key, SysFile uses the following columns to identify the parent record:

  • 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.
Important

Use the RecordSchemaName and RecordId body parameters in the request that creates a file metadata record in the "Uploaded file" (SysFile code) object via OData 4.

Use the polymorphic relationship when your integration must attach files to different types of objects or when the parent object is determined at runtime dynamically.

Direct foreign key relationship via object-specific file objects​

Object-specific file objects, such as "Contact attachment" (ContactFile code), "File and link of activity" (ActivityFile code), "File and link of account" (AccountFile code), provide a strong, type-safe link to the parent object using a dedicated reference column, for example, ContactId, ActivityId, AccountId.

This approach simplifies requests, improves validation, and ensures that files can only be attached to the intended object type.

See also​

Endpoints for working with files via OData 4

File storage (user documentation)