File Field Type | Yext Hitchhikers Platform
The File Field Type allows you to store files directly on your entities.
The File Field Type is available to Custom Field Types as well as Custom Fields. To learn more about Custom Fields as well as Custom Field Types, visit the Custom Fields Hitchhikers module.
Field Definition
Field Model
The File Field type is composed of the following five properties:
Property | Description |
---|---|
sourceURL |
Source URL of the file. Only populates if uploaded by providing a hosted URL. |
url |
The Yext-Hosted URL of the file. |
mimeType |
The MIME Type of the file. Currently all MIME types are supported. |
name |
The display name of the file. User-settable. |
size |
The size of the file in bytes. |
Files field types can be configured to support one file or support a list of files. This will automatically create a maximum file upload validation of 1 or 5,000 respectively.
Available Validation
At this time validation for the file Field type is File Format and File Size.
File Format
All File Formats are allowed by default. You can restrict uploaded files to a subset of allowed file types by their MIME type. This validation will support the Common Mime Types . If you select all subtypes of a given MIME type, you will be opted into all future subtypes added.
For example, let’s say you have a field with validation enabled to accept all subtypes of application (e.g., application/ms-word
, application/gzip
, etc.). If application/vnd.hzn-3d-crossword
is added by Mozilla as a common MIME type, that subtype will automatically be added to the list of MIME types your field supports.
If you see a MIME type that is not currently supported by validation that you would like us to add, reach out to us on the Ideas Board .
File Size
You can set a maximum file size that can be uploaded to a File Type field. You can set this limit in Bytes, Kilobytes or Megabytes. The value set needs to be a whole number.
If the specified size and unit indicated can be stored as a whole number of a larger file unit, the unit will change automatically. For example, entering a validation of a maximum file size of 2,048 Bytes will automatically convert the maximum file size to 2 Kilobytes.
Storing Files
Files may be stored in all interfaces where you edit your Knowledge Graph:
- Entity Edit
- Entity Upload
- Connectors
- API
- Configuration as Code
Each file must be smaller than 1,000 MB. We accept all MIME type formats including application/pdf, video/mp4, application/vnd.ms-excel.
From a Publicly Available Source URL
All above interfaces accept files as URLs referencing the file data already hosted somewhere online.
Uploading Files
To store a file that is already being hosted, users will indicate the hosted URL using the url
property. This provided url will then be propagated to the sourceUrl
property, while the url field will change to be the Yext hosted url of this file.
Updating Files
If you want to change what file is being stored on an entity, you’ll want to update the value of the url
property to be the new hosted file’s URL. Sending updates to the sourceUrl
property is not supported. Any update to the url
property will trigger us to fetch the associated file, even if that url’s value does not change.
The user-agent string that we use to download files is YextBot YextFileDownloader/1.0
.
From Local File System
Uploading Files
Only Entity Edit allows users to upload files from a local filesystem.
Updating Files
Only Entity Edit allows users to update files to be from a local filesystem.
Accessing Stored Files
Opening the URL stored in the url
property will download the file onto your local device. Here’s an example of what this would look like on an Entities: GET
.
With other fields elided, the response looks like this:
{
"response": {
"entities": [{
"c_pdfFile": [{
"sourceUrl": "https://www.pdfs.com/123",
"url":"https://a.mktgcdn.com/f/3912636/123",
"mimeType": "application/pdf",
"name": "Instruction Manual for Turtlehead Tacos",
"size": 2001
}]
}]
}
}
Entity Edit
Files can be downloaded from the url property. The edit state of this field will show all properties of the File field. Properties of a file cannot be edited in Entity Edit, except for the name of the file.
Usage Patterns
There are two common ways to set up file support within the Knowledge Graph
Reusable: A dedicated entity is set up with the File field type and used to store both the file and relevant metadata. This entity is then referenced via an entity relationship field from related entities. This pattern will be common if a given file is shared across many entities.
- E.g., A Terms & Conditions PDF that is shared across all Product Entities in a Knowledge Graph
Entity-Specific: A File field is added directly to the entity schema. This allows for file upload directly on a given entity itself. This pattern will be common if files are specific to each entity.
- E.g., A Product Manual PDF that is specific to each Product Entity in a Knowledge Graph
Limitations
- Validation on uncommon MIME types is not supported.
- Uploading local files via Entity Upload, Connectors, API, and Configuration as Code is not supported at this time.
- The name property cannot be mapped via connector, but can be set or edited on all other interfaces.
- We are currently experiencing a known issue with JSonFormat printer that is affecting Configuration as Code where
maxSize
will be returned as a string when pulled. However, when applied, this property needs to be a number.