File type

Overview #

This type enables the storage of references to files. The UI and APIs also facilitate file uploads using this field.

Available features #

Display options #

Enable preview #

If this flag is enabled, a button to preview the file will be displayed in the UI. Otherwise, the only available option will be to download the file.

REST API #

Read format #

It’s a JSON with the following fields:

• id: This is the ID of the referenced file.
• name: This is the name of the referenced file. It might include the size as well.

Sample user field in JSON format:

"file": {
    "id": "58866b5d3b063a0007604eab",
    "name": "logo.png (41.5kB)"
}

Write format #

You can provide only the ID and avoid the name field:

"file": {"id": "57fe52ade4b0ce322b0cea32"}

You can also provide the ID directly as a string:

"file": "57fe52ade4b0ce322b0cea32"

Finally you can provide the file encoded in Base 64 and it will be uploaded:

"file": {
  "name": "test1.txt",
  "contentType": "text/plain",
  "content": "dGVzdCBmaWxlIQ=="
}

Where:

• name: This is the name of the file.
• contentType: This is the content type of the file.
• content: This is the content of the file encoded in Base 64.

JavaScript API #

Read format #

The val() method within the wrapper will return an object:

{
  "id": "58866b5d3b063a0007604eab",
  "name": "logo.png (41.5kB)"
}

Where:

• id: This is the ID of the referenced file.
• name: This is the name of the referenced file. It might include the size of the file.

However, in most cases, instead of obtaining the raw value of the relationship, you will use the methods available in the wrapper to directly access the ID or the full name.

Write format #

There are several ways to pass the value of a user in the JavaScript API.

You can pass only the ID:

record.field("file").val({id: "58866b5d3b063a0007604eab"});

You can also pass the ID directly as a string:

record.field("file").val("58866b5d3b063a0007604eab");

The Javascript API also allows to set a user wrapper like this:

file1.field('file').val(file2.field('file'));

Or you can pass a new file that will be created:

var file = sys.data.createRecord('files');
file.field('code').val('test-b');
file.field('file').val({
  name: 'test1.txt',
  contentType: 'text/plain',
  content: 'dGVzdCBmaWxlIQ=='
});
sys.data.save(file);

Wrapper method:
id() #

The id() method returns the ID of the referenced file or null if the field is empty.

Returns #

string - The ID of the referenced file.

Samples #

// prints the ID of attachements of a task
var record = sys.data.findOne('tasks', {number: 1});
record.field('attachments').each(function(attachment) {
  log('file id: '+attachment.id());
});

Wrapper method:
name() #

The name() method returns the name of the referenced file or null if the field is empty.

Returns #

string - The name of the referenced file.

Samples #

// prints the name of attachments of a task
var record = sys.data.findOne('tasks', {number: 1});
record.field('attachments').each(function(attachment) {
  log('file name: '+attachment.name());
});

Wrapper method:
name(name) #

Sets the name of the file. This only works if you are uploading a new file, otherwise an exception will be thrown.

Parameters #

Exceptions #

badRequests If the file already exists

Samples #

// adds a new attachment to a task
var record = sys.data.findOne('tasks', {number: 1});
record.field('attachments[1]').name('test1.txt');
record.field('attachments[1]').contentType('text/plain');
record.field('attachments[1]').content('dGVzdCBmaWxlIQ==');
record = sys.data.save(record);
log('file id: '+record.field('attachments').last().id());

Wrapper method:
hash() #

Returns the hash code of the referenced file.

Returns #

string - The hash code of the referenced file.

Samples #

// prints the hash of attachements of a task
var record = sys.data.findOne('tasks', {number: 1});
record.field('attachments').each(function(attachment) {
  log('file hash: '+attachment.hash());
});

Wrapper method:
contentType() #

Returns the content type of the referenced file or null if the field is empty.

Returns #

string - The content type of the referenced file.

Samples #

// prints the content type of attachments of a task
var record = sys.data.findOne('tasks', {number: 1});
record.field('attachments').each(function(attachment) {
  log('content type: '+attachment.contentType());
});

Wrapper method:
contentType(contentType) #

Sets the content type of the file. This only works if you are uploading a new file, otherwise an exception will be thrown.

Parameters #

Exceptions #

badRequest If the file already exists.

Samples #

// adds a new attachment to a task
var record = sys.data.findOne('tasks', {number: 1});
record.field('attachments[1]').name('test1.txt');
record.field('attachments[1]').contentType('text/plain');
record.field('attachments[1]').content('dGVzdCBmaWxlIQ==');
record = sys.data.save(record);
log('file id: '+record.field('attachments').last().id());

Wrapper method:
content() #

Returns the content of the file encoded in Base 64. If the file is bigger than 10MB this method will throw an exception.

Returns #

string - The content of the referenced file encoded in Base 64.

Exceptions #

badRequest If the content of the file is bigger than 10MB.

Samples #

// prints the content of attachments of a task
var record = sys.data.findOne('tasks', {number: 1});
record.field('attachments').each(function(attachment) {
  log('content in base 64: '+attachment.content());
});

Wrapper method:
content(content) #

Sets the content type of the file (it should be encoded in Base 64). This only works if you are uploading a new file, otherwise an exception will be thrown.

Parameters #

Exceptions #

badRequest If the file already exists.

Samples #

// adds a new attachment to a task
var record = sys.data.findOne('tasks', {number: 1});
record.field('attachments[1]').name('test1.txt');
record.field('attachments[1]').contentType('text/plain');
record.field('attachments[1]').content('dGVzdCBmaWxlIQ==');
record = sys.data.save(record);
log('file id: '+record.field('attachments').last().id());

Wrapper method:
size() #

Returns the size of the file in bytes.

Returns #

number - The size of the referenced file.

Samples #

// prints the size of attachments of a task
var record = sys.data.findOne('tasks', {number: 1});
record.field('attachments').each(function(attachment) {
  log('file size: '+attachment.size());
});

Wrapper method:
link() #

Returns an absolute URL of the file.

Returns #

string - The URL of the referenced file.

Samples #

// prints the url of attachments of a task
var record = sys.data.findOne('tasks', {number: 1});
record.field('attachments').each(function(attachment) {
  log('file url: ' + attachment.link());
});

Export/Import #

Export format #

The export format is the name of the file:

"fileField1","fileField2"
"logo.png (4kB)","data.zip (41.5kB)"

Import format #

It is not possible to import file fields.

Queries #

For more information, please refer to the Query Language Documentation.

Available operators #

Query formats #

By default, the file name will be used for the various query operators.

For example, to query tasks with an attachment where the name is similar to 'logo.png'. We use 'like' because the name can include the file size, so using 'equals' might not yield the expected results:

// finds a task with attachment 'logo.png' 
var records_sample = sys.data.find('tasks', {attachments: 'like(logo.png)'});
log('total: '+records_sample.count());
while (records_sample.hasNext()) {
    log(records_sample.next().label());
}

// finds a task with attachment 'logo.png' 
var query_sample = sys.data.createQuery('tasks')
    .field('attachments').like('logo.png')
var records_sample = sys.data.find(query_sample);
log('total: '+records_sample.count());
while (records_sample.hasNext()) {
    log(records_sample.next().label());
}

// finds a task with attachment 'logo.png' 
GET /data/contacts?attachments=like(logo.png)

You could also query by the ID:

// finds a task by attachment's ID 
var records_sample2 = sys.data.find('tasks', {'attachments.id': '58866b5d3b063a0007604eab'});
log('total: '+records_sample2.count());
while (records_sample2.hasNext()) {
    log(records_sample2.next().label());
}

// finds a task by attachment's ID 
var query_sample2 = sys.data.createQuery('tasks')
    .field('attachments').equals('58866b5d3b063a0007604eab')
var records_sample2 = sys.data.find(query_sample2);
log('total: '+records_sample2.count());
while (records_sample2.hasNext()) {
    log(records_sample2.next().label());
}

// finds a task by attachment's ID 
GET /data/contacts?attachments.id=58866b5d3b063a0007604eab

Notice again that the query builder will automatically detect the ID, so you don’t need to use the 'id' suffix there.

Remember that when using the query builder, you can utilize any of the formats available in the JavaScript API.

Aggregate queries #

Please refer to the Aggregate Queries Documentation for more detailed information.

Available operators #

UI queries #

Please refer to the UI Queries Documentation for more detailed information.

Matching of values #

Available operators #