Understanding Salesforce Files, Part 2: ContentDocument, ContentVersion & ContentDocumentLink

In Part One of our guide to Salesforce Files, we looked at Files from an end user perspective: how to add and delete them via the Salesforce UI, where to find them in your org, what their basic limitations are, and how their privacy settings work. Now, it's time to dig a little bit deeper and see what's going on underneath the hood. Ready?

First things first: If you're looking for a single "File" object in Salesforce, you won't find it. Instead, the Files data model is underpinned by three separate objects: ContentVersion, ContentDocument, and ContentDocumentLink. Put as simply as possible, here's what they represent:

• ContentDocument, the parent object of both ContentVersion and ContentDocumentLink, represents an individual file in Salesforce.
• ContentVersion records represent all the versions of that file, past and present.
• ContentDocumentLink represents the link to entities the file is shared with, whether it's users, groups, records, or libraries.

Let's try to find a metaphor for that setup. Stay with me here: the Mona Lisa is a ContentDocument. All the individual stages in its creation, from the first layer of primer to the completed painting, are ContentVersions. And ContentDocumentLinks represent its relationships with The Louvre (content library) and Leonardo da Vinci (file owner…the French Republic is still trying to figure out how to edit OwnerId).

That's the short version. Now, let's look at each of these objects in detail and get a better understanding of how they work together.

ContentDocument: The Canvas

What is the ContentDocument object?

ContentDocument represents a document that has been uploaded to a library in Salesforce CRM Content or Salesforce Files. It’s the parent object of both ContentVersion and ContentDocumentLink; when a ContentDocument record is deleted, all its child records are deleted as well.

When is ContentDocument created?

ContentDocument is automatically created when a ContentVersion without an associated ContentDocumentId is added to a Salesforce org. This can occur when a new file is uploaded via the Salesforce UI or when a ContentVersion without ContentDocumentId is created programatically.

ContentDocument Supported Calls

delete(), describeLayout(), describeSObjects(), query(), retrieve(), search(), undelete(), update()

ContentDocument Key fields

• Title – This is a string used to store the title of a document.
• Description – This is a textarea that can be used to store a description of the document.
• LatestPublishedVersionId – This is a lookup field that stores the ID of the current ContentVersion of the document.

Check out Salesforce's Developer Guide for a full breakdown of the ContentDocument object, including a complete list of fields, a rundown of special access rules, usage tips, and more.

ContentVersion: The Paint

What is the ContentVersion object?

ContentVersion represents a specific version of a document that has been uploaded to a library in Salesforce CRM Content or Salesforce Files. This is where the actual content of a file is stored.

When is ContentVersion created?

ContentVersion is created when you upload a file or document to Salesforce or add a new version of an existing one. When you create a ContentVersion that is not associated with an existing ContentDocument, Salesforce automatically creates a parent ContentDocument object and a child ContentDocumentLink that looks up to it.

It may seem counterintuitive that creating ContentVersion is what sparks the creation of its parent ContentDocument and not the other way around, but let's go back to that Mona Lisa metaphor – you don't have a painting to speak of until you've put your first layer of paint on the canvas.

ContentVersion Supported Calls

create(), describeLayout(), describeSObjects(), query(), retrieve(), search(), update(), upsert()

ContentVersion Key fields

• Title – Again, this is the document's title.
• ContentDocumentId – This is a lookup field used to associate the ContentVersion with its parent ContentDocument object. When a ContentVersion is created without an associated ContentDocumentId, it will trigger the creation of a new ContentDocument.
• ContentUrl – This stores the URL for linked files and is used to determine their FileType.
• VersionData – This is a base64 field that contains the actual binary data of the document version.
• VersionNumber – What it says on the label: this is the document version's sequential version number.

Again, comprehensive documentation for the ContentVersion object can be found in Salesforce's Developer Guide.

ContentDocumentLink: The Picture Hook

What is the ContentDocumentLink object?

ContentDocumentLink is a junction object that represents the link between a file and the entities it's shared with: other users, groups, records, and libraries.

When is ContentDocumentLink created?

ContentDocumentLink is created when its parent ContentDocument is created. If a file is added from the Files tab, a single ContentDocumentLink record is created that looks up to its parent document via the  ContentDocumentId field and to the user that uploaded it via the LinkedEntityId field.

However, if a file is added in the context of another object, such as a related list on a record page, two ContentDocumentLink records will be created: one that looks up to the user that uploaded it, and one that looks up to the object it is associated with.

ContentDocumentLink Supported Calls

create(), delete(), describeSObjects(), query(), retrieve(), update(), upsert()

ContentDocumentLink Key fields

• ContentDocumentId – This is a lookup field used to associate the ContentDocumentLink with its parent ContentDocument object.
• LinkedEntityId – This is a reference field that is used to associate the ContentDocumentLink with entities it is linked to, such as users and records.
• ShareType – This is a picklist field that determines the permission granted to the user of the shared file in a library. There are three available options:
  • V – Viewer permission: The user can explicitly view but not edit the shared file.
  • C – Collaborator permission: The user can explicitly view and edit the shared file.
  • I – Inferred permission: The user’s permission is determined by the related record. For shares with a library, this is defined by the permissions the user has in that library.
• Visibility – This is a picklist field that determines whether the file is available to all users, internal users, or shared users.

As always, Salesforce's Developer Guide is your source for full documentation of the ContentDocumentLink object.

What's next?

When you upload a new file via the Salesforce UI, all three of these objects are created automatically: first, ContentVersion, then ContentDocument and ContentDocumentLink. But what if you want to create a file programmatically, via Apex? Stay tuned for Part Three of this series, where we'll walk you through the process.

In the meantime: Understanding Salesforce Files' data model is what allowed us to build Drive Connect, our powerful solution for integrating Salesforce and Google Drive. Whether you're simply linking files, generating documents from Salesforce records, or creating more sophisticated automated processes, Drive Connect leverages the same three key objects you just learned about to connect Google Drive functionality with the Salesforce environment. Give it a spin yourself with a 14-day free trial.