Describes utilities in the Javascript API to work with text files.

sys.files

This package contains methods to read and write text files.

open(fileId, fileType, options)

Opens a file as stream. In the case that the type of the file to be read is text/csv a proper CSV handler will be returned.

Parameters

Name Type Required Default Description

fileId

string

yes

ID of the file to be read.

fileType

string

yes

Text based content type of the file. Some valid types are:

  • text/plain
  • text/csv
  • text/richtext
  • text/html

options

string

yes

Configuration options to open the file.

For text/csv the following options are available:

  • separator: the delimiter to use for separating entries.
  • quoteChar: the character to use for quoted elements.
  • hasHeaders: if the file to be opened contains headers.

Returns

sys.files.FileReader or sys.files.CsvFileReader - The reader to read the file.

Exceptions

badRequest

If any of the parameter is invalid.

notFound

If no file found with the given ID.

unknown

If there are problems opening the file.

Samples

// reads a text file and prints the content

var record = sys.data.findOne('files', {code: 'test'});
var fileId = record.field('file').id();
var fileReader = sys.files.open(fileId, 'text/plain');
try {
    var line;
    while (line = fileReader.readLine()) {
        log(line);
    }
} finally {
    fileReader.close();
}

create(fileName, fileType)

Opens a new file stream to write in it. In the case that the type of the file to be written is text/csv a proper CSV handler will be returned

Parameters

Name Type Required Default Description

fileName

string

yes

The name of the file to be created.

fileType

string

yes

Text based content type of the file. Some valid types are:

  • text/plain
  • text/csv
  • text/richtext
  • text/html

Returns

sys.files.FileWriter or sys.files.CsvFileWriter - The writer to write in the file.

Exceptions

badRequest

If fileName or fileType are invalid.

unknown

If there are problems creating the file.

Samples

// write a text file

var fileWriter = sys.files.create('test1.txt', 'text/plain');
try {
    fileWriter.writeLine('test file!');
} finally {
    fileWriter.close();
}
// now assocaite the file to a record
var record = sys.data.findOne('files', {code: 'temporary-file'});
if (!record) {
  record = sys.data.createRecord('files');
  record.field('code').val('temporary-file');
}
record.field('file').val({
  id: fileWriter.descriptor().id(),
  name: fileWriter.descriptor().name()
});
sys.data.save(record);
log('file record saved!');


// write a CSV file

var fileWriter = sys.files.create('test2.csv', 'text/csv');
try {
    fileWriter.writeHeaders(['name', 'email']);
    fileWriter.writeRow(['john', 'john@test.com']);
    fileWriter.writeRow(['adam', 'adam@test.com']);
} finally {
    fileWriter.close();
}
// now assocaite the file to a record
var record = sys.data.findOne('files', {code: 'temporary-csv-file'});
if (!record) {
  record = sys.data.createRecord('files');
  record.field('code').val('temporary-csv-file');
}
record.field('file').val({
  id: fileWriter.descriptor().id(),
  name: fileWriter.descriptor().name()
});
sys.data.save(record);
log('file record saved!');

share(fileId, ttl)

Shares a file by returning a public URL for it. This link is valid for an hour.

Parameters

Name Type Required Default Description

fileId

string

yes

ID of the file to share.

ttl

number

no

3600000 (1 hour)

Time in milliseconds to expire.

Returns

string - The public URL for the file which is valid for the ttl set or an hour.

Exceptions

badRequest

If fileId is invalid or ttl is not a number.

notFound

If no file found with the given ID.

Samples

// prints a public URL for a file

var record = sys.data.findOne('files', {code: 'test'});
var publicUrl = sys.files.share(record.field('file').id());
log(publicUrl);


// prints a public URL for a file with expiration equals to a minute

var record = sys.data.findOne('files', {code: 'test'});
var publicUrl = sys.files.share(record.field('file').id(), 60000);
log(publicUrl);

unshare(fileId)

Stops sharing a file that was shared before.

Parameters

Name Type Required Default Description

fileId

string

yes

ID of the file to unshare.

Exceptions

badRequest

If fileId is invalid.

notFound

If no file found with the given ID.

Samples

// prints a public URL for a file

sys.files.unshare(record.field('file').id());

sys.files.FileReader

Allows to read a text file line by line. The file must be stored in the app.

descriptor()

Returns the metadata information of the opened file.

Returns

sys.files.FileDescriptor - The file descriptor of the opened file.

Samples

// opens a file and logs the name of the file from the descriptor

var record = sys.data.findOne('files', {code: 'test'});
var fileId = record.field('file').id();
var fileReader = sys.files.open(record.field('file').id(), 'text/plain');
try {
  var descriptor = fileReader.descriptor();
  log('file name: '+descriptor.name());
} finally {
  fileReader.close();
}

readLine()

Reads the next line of the the opened file. If there isn’t any more data, it returns null.

Returns

string - Line of text or null if no more data.

Exceptions

unknown

If there are problems reading the file.

Samples

// reads a text file and prints the content

var record = sys.data.findOne('files', {code: 'test'});
var fileId = record.field('file').id();
var fileReader = sys.files.open(fileId, 'text/plain');
try {
    var line;
    while (line = fileReader.readLine()) {
        log(line);
    }
} finally {
    fileReader.close();
}

close()

Closes this file stream and releases any system resources associated with the stream.

Exceptions

unknown

If there are errors closing the file.

Samples

// close the file after reading it

var record = sys.data.findOne('files', {code: 'test'});
var fileId = record.field('file').id();
var fileReader = sys.files.open(fileId, 'text/plain');
try {
    var line;
    while (line = fileReader.readLine()) {
        log(line);
    }
} finally {
    fileReader.close();
}

sys.files.FileWriter

Allows to write a text file line by line. The file will be stored in the app.

descriptor()

Returns the metadata information of the opened file.

Returns

sys.files.FileDescriptor - The file descriptor of the opened file.

Samples

// creates a new file and logs the id, name, type and size

var fileWriter = sys.files.create('test1.txt', 'text/plain');
try {
    fileWriter.writeLine('test file!');
} finally {
    fileWriter.close();
}
var descriptor = fileWriter.descriptor();
log('id: '+descriptor.id());
log('name: '+descriptor.name());
log('type: '+descriptor.type());
log('size: '+descriptor.size());

writeLine(line)

Appends a new line to the file.

Parameters

Name Type Required Default Description

line

string

yes

The text to write to the file.

Exceptions

unknown

If there are problems writing to the file.

Samples

// writes a few lines in a file

var fileWriter = sys.files.create('test1.txt', 'text/plain');
try {
    fileWriter.writeLine('line 1');
    fileWriter.writeLine('line 2');
    fileWriter.writeLine('line 3');
} finally {
    fileWriter.close();
}
log('id: '+fileWriter.descriptor().id());

close()

Closes this file stream and releases any system resources associated with the stream.

Exceptions

unknown

If there are errors closing the file.

Samples

// close the file after writing it

var fileWriter = sys.files.create('test1.txt', 'text/plain');
try {
    fileWriter.writeLine('test file!');
} finally {
    fileWriter.close();
}

sys.files.CsvFileReader

Allows to read a CSV file row by row. An object of this type will be returned by the sys.files.open() method when the type is text/csv.

It inherits all methods from sys.files.FileReader.

readHeaders()

Returns the headers of the CSV file.

You don’t need to call this method before reading rows. It will be done automatically when the CSV file is opened. This method just returns the headers that were read at that time.

Returns

string[] - An array with the headers of the CSV file

Samples

// reads a text file and prints the content

var record = sys.data.findOne('files', {code: 'test-companies'});
var fileReader = sys.files.open(record.field('file').id(), 'text/csv');
try {
  var headers = fileReader.readHeaders();
  log('headers: '+JSON.stringify(headers));
} finally {
  fileReader.close();
}

readRow()

Returns the values of the next row in an array.

Returns

string[] - An array with the values of the row.

Samples

// reads a text file and prints the content

var record = sys.data.findOne('files', {code: 'test-companies'});
var fileReader = sys.files.open(record.field('file').id(), 'text/csv');
var count = 1, row;
try {
  var headers = fileReader.readHeaders();
  log('headers: '+JSON.stringify(headers));
  while (row = fileReader.readRow()) {
    log('row '+count+': '+JSON.stringify(row));
  }
} finally {
  fileReader.close();
}

readRowMap()

Returns the values of the next row in a map using the headers as the key.

Returns

object - A map with the values of the row using the headers as keys

Samples

// reads a text file and prints the content

var record = sys.data.findOne('files', {code: 'test-companies'});
var fileReader = sys.files.open(record.field('file').id(), 'text/csv');
var count = 1, row;
try {
  while (row = fileReader.readRowMap()) {
    log('row '+count+': '+JSON.stringify(row));
  }
} finally {
  fileReader.close();
}

readRowStr()

Returns the values of the next row as a string.

Returns

string - A string with the row values.

Samples

// reads a text file and prints the content

var record = sys.data.findOne('files', {code: 'test-companies'});
var fileReader = sys.files.open(record.field('file').id(), 'text/csv');
var count = 1, row;
try {
  var headers = fileReader.readHeaders();
  log('headers: '+JSON.stringify(headers));
  while (row = fileReader.readRowStr()) {
    log('row '+count+': '+row);
  }
} finally {
  fileReader.close();
}

sys.files.CsvFileWriter

Allows to write a CSV file row by row. An object of this type will be returned by the sys.files.create method when the type is text/csv.

It inherits all methods from sys.files.FileWriter.

writeHeaders(headers)

Writes the headers of the CSV file.

You should call this method before writing rows. If you start writing rows, the first row will be taken as the headers.

Parameters

Name Type Required Default Description

headers

string[]

yes

An array of strings with the headers.

Samples

// writes headers and rows for a CSV file

var fileWriter = sys.files.create('test2.csv', 'text/csv');
try {
  fileWriter.writeHeaders(['name', 'email']);
  fileWriter.writeRow(['john', 'john@test.com']);
  fileWriter.writeRow(['adam', 'adam@test.com']);
} finally {
  fileWriter.close();
}
log('id: '+fileWriter.descriptor().id());

writeRow(row)

Appends a row the the CSV file.

Parameters

Name Type Required Default Description

row

string[]

yes

An array with the values of the row. You should use the same order as headers.

Samples

// writes headers and rows for a CSV file

var fileWriter = sys.files.create('test2.csv', 'text/csv');
try {
  fileWriter.writeHeaders(['name', 'email']);
  fileWriter.writeRow(['john', 'john@test.com']);
  fileWriter.writeRow(['adam', 'adam@test.com']);
} finally {
  fileWriter.close();
}
log('id: '+fileWriter.descriptor().id());

writeRowMap(row)

Appends a row to the CSV file from a map. It will take care of the positioning of values in the row automatically based on the headers.

Parameters

Name Type Required Default Description

row

object

yes

A map with the row values. Keys should be the headers.

Samples

// writes headers and rows for a CSV file

var fileWriter = sys.files.create('test2.csv', 'text/csv');
try {
  fileWriter.writeHeaders(['name', 'email']);
  fileWriter.writeRowMap({name: 'john', email: 'john@test.com'});
  fileWriter.writeRowMap({name: 'adam', email: 'adam@test.com'});
} finally {
  fileWriter.close();
}
log('id: '+fileWriter.descriptor().id());

writeRowStr(row)

Appends a row to the CSV file from a plain string. The string will be appended as it is, without any processing.

Parameters

Name Type Required Default Description

row

string

yes

The row to append to the CSV file.

Samples

// writes headers and rows for a CSV file

var fileWriter = sys.files.create('test2.csv', 'text/csv');
try {
  fileWriter.writeHeaders(['name', 'email']);
  fileWriter.writeRowStr('john,john@test.com');
  fileWriter.writeRowStr('adam,adam@test.com');
} finally {
  fileWriter.close();
}
log('id: '+fileWriter.descriptor().id());

sys.files.FileDescriptor

Handles metadata of the file.

id()

Returns the ID of the file in the app.

Returns

string - The ID of the file in the app

name()

Returns the name of the file.

Returns

string - The name of the file.

hash()

Returns the hash code of the file.

Returns

string - The hash code of the file.

type()

Returns the content type of the file. Some valid types are:

  • text/plain
  • text/csv
  • text/richtext
  • text/html

Returns

string - The type of the file

size()

Returns the size of the file in bytes.

Returns

number - The size of the file in bytes.

Back to top