Files and export

Learn how to import files, create exports, inspect attachments, and manage file and view sharing in Ninox scripts.

Files help you move data into and out of Ninox. You can import attachments, create text or spreadsheet exports, bundle files, generate links, and control who can access shared files and views. This chapter shows you the core file functions for common automation and reporting tasks.

Function (A-Z)	Task
appendTempFile()	Add content to a temporary file
createTempFile()	Create a temporary file for staged output
createTextFile()	Create a plain text file
createXLSX()	Export data to an XLSX file
createZipFile()	Bundle several files into a ZIP archive
file()	Return a single file reference
fileMetadata()	Return file details such as name, size, and date
files()	Return multiple file references
fileUrl()	Return a download link for a file
importFile()	Import a file into Ninox
loadFileAsBase64()	Return file content as a Base64 string
loadFileAsBase64URL()	Return file content as a Base64 data URL
printAndSaveRecord()	Print a PDF from a record and return its download link
removeFile()	Delete a file
renameFile()	Rename a file
urlOf()	Return a URL for a record

Import, create, and process files

Use these functions when you want to bring a file into Ninox, generate output, or work with one or more file objects in a script.

Import a file with importFile()

Use importFile() to bring a file into Ninox where file import is supported.

Use it when you want to:

• Add external content to a workflow.
• Move a source file into Ninox before further processing.
• Attach a file from a URL to a record.
• Save generated file output into a file field.

importFile(nid, string) importFile(nid, link) importFile(nid, string, string) importFile(nid, link, string)

• nid target record
• string or link (second argument of the record form): source URL or file link
• string (optional third argument of the record form): filename to save

importFile() returns a file object.

Let’s take a look at an example:

importFile(this, "https://ninox.com/example.jpg", "Image.jpg")

Imports the file from the URL and attaches it to the current record as "Image.jpg".

Use valid characters when generating file names. Slashes / are not allowed. For example, do not use an unformatted today() value if it produces 08/23/2026. Format the date as shown above. Otherwise, PDF generation fails.

Create and save a PDF from a record with printAndSaveRecord()

Use printAndSaveRecord() to generate a PDF from a record using a print layout. It saves the PDF in Ninox and returns a download link.

Use it when you want to:

• Save a PDF version of a printed document.
• Combine printing with file output in one step.
• Use the returned file link to import the file as an attachment.

printAndSaveRecord(nid, string)

• nid the record you want to print
• string the print layout name

printAndSaveRecord() returns a download link to the saved PDF file.

printAndSaveRecord() runs only on the server. Run it inside a do as server ... end block.

Examples

do as server
printAndSaveRecord(this, "Invoice")
end

Generates a PDF for the current record and returns a link to the saved file.

Combine printAndSaveRecord() with importFile() to import the file, attach it to the current record, and display it in the "Invoice" field.

do as server
invoice := importFile(this, printAndSaveRecord(this, "Invoice layout"), invoice_number + ".pdf")
end

Prints the current record with the "Invoice layout" and saves the PDF in the "Invoice" file field. Its filename combines the "Invoice number" field value with ".pdf".

Tips:

• Use clear layout names so scripts stay readable.
• Pair print layouts with format() for clean numbers and dates.
• Pass a filename with importFile() when the source URL does not provide a useful name.
• You can use importFile() with generated file links, not just external URLs.

Build files with createTextFile()

Use createTextFile() when you already have the final content and want a ready file immediately.

createTextFile(nid, string, string) createTextFile(nid, string, string, any)

• nid target record
• string (second argument) file content
• string (third argument) filename
• any options such as { encoding: "utf8" }. The following encodings are available:

  • utf8
  • utf16le
  • latin1
  • base64
  • base64url
  • hex
  • ascii

Let’s take a look at some examples:

let myFile := createTextFile(this, "Hello", "notes.txt");
myFile

Creates a text file named "notes.txt" with the content "Hello".

let myFile := createTextFile(this, text(rich_text), "MyTextFileExample.txt");
myFile

Creates a plain text file from the visible text content of the rich text field.

let myFile := createTextFile(this, raw(rich_text), "MyTextFileExample.html");
myFile

Creates an HTML file from the raw rich text content.

do as server 
    createTextFile(this,raw(rich_text),"MyTextFileExample_UTF8.html",{
        encoding: "utf8"
    })
end

Creates the file with explicit UTF-8 encoding.

Tips:

• You can choose any filename and extension, for example, .txt, .csv, or .html.
• If you do not save the returned file elsewhere, for example in a File field, Ninox attaches it to the record.

The encoding option is available only in server context. Therefore, you need to run createTextFile() inside do as server ... end if you use the encoding option.

createTempFile() creates a temporary file on the Ninox server with initial content and returns a link to that file.

Create files and append content with createTempFile() and appendTempFile()

appendTempFile() adds content to a temporary file on the Ninox server by using the link returned from createTempFile().

Use them when you want to:

• Build large exports in several steps.
• Write logs or report lines one after another.
• Generate a plain text attachment for download or sharing.

createTempFile(string, string)

• string (1st argument) initial content for the temporary file
• string (2nd argument) filename for the temporary file

createTempFile() returns a link to the temporary file.

Because this file is temporary, it is automatically deleted after 24 hours.

appendTempFile(link, string) appendTempFile(string, string)

• link or string (1st argument) the temporary file link returned by createTempFile
• string (2nd argument) the content chunk to append

Let’s take a look at some examples:

do as server
	let header := "Name,email
	";
	url_field := createTempFile(header, "export.csv");
end

This creates a temporary CSV file with a header line. It stores the file link in the "URL field" of the current record.

do as server
	let linebreak := "
";
	for myC in select contacts do
		let line := myC.name + "," + myC.email + linebreak;
		appendTempFile(url_field, line)
	end
end

This appends one line for each contact to the temporary CSV file. The "URL field" in the current record links to the file.

do as server
	let linebreak := "
";
	let header := "Name,email" + linebreak;
	url_field := createTempFile(header, "export.csv");
	for myC in select contacts do
		let line := myC.name + "," + myC.email + linebreak;
		appendTempFile(url_field, line)
	end
end

This creates a temporary CSV file, writes the header, and appends a line for each contact in one script.

Tips:

• Use a temporary file when the content is assembled over a short time as temporary files are deleted automatically after some time.
• createTempFile() creates the file only when the initial content is not empty.
• The temporary file must still exist when appendTempFile() runs.
• appendTempFile() is useful for large or long-running exports.

Both functions must run on the server. Run them inside a do as server ... end block.

Export data with createXLSX()

Use createXLSX() to dynamically create customizable, styled, multi-sheet Excel files directly from your app.

Use it when you want to:

• Send filtered records to a user.
• Build styled Excel files with custom columns and rows.
• Create multi-sheet exports for reporting or handoff workflows.

The resulting file is saved directly in Ninox, offering dynamic data management and formatting options.

createXLSX(nid, any, string)

• nid target record, where the file should be saved
• any workbook or worksheet definition
• string filename for the XLSX export

createXLSX() returns a file object.

Let’s take a look at some examples:

Due to the complexity of this function, let's split the examples into the following steps:

1. Define the columns and rows.
2. Define the worksheet structure.
3. Use the createXLSX function.
4. Define styles and formatting (optional).

Define columns and rows

First, create an object to define the columns:

let columns := [
    {
        header: "Name",
        key: "name",
        width: 10,
    },
    {
        header: "Age",
        key: "age",
        width: 10
    },
    {
        header: "URL",
        key: "url",
        width: 30
    },
    {
        header: "Description",
        key: "description",
        width: 20
    }
];

Next, define the rows. You can use supported special fields (described below) if needed:

let rows := [
{
name: "Luis Gómez",
age: 30,
url: {
text: "www.google.com",
hyperlink: "http://www.google.com",
tooltip: "www.google.com"
}
},
{
name: "Maria Silva",
age: 25,
url: {
text: "www.google.com",
hyperlink: "http://www.google.com",
tooltip: "www.google.com"
}
},
{
name: "Ayesha Khan",
age: 35,
url: {
text: "www.google.com",
hyperlink: "http://www.google.com",
tooltip: "www.google.com"
}
},
{
name: "Li Wei",
age: 40,
url: {
text: "www.google.com",
hyperlink: "http://www.google.com",
tooltip: "www.google.com"
}
},
{
name: "Rajesh Kumar",
age: 21,
url: {
text: "www.google.com",
hyperlink: "http://www.google.com",
tooltip: "www.google.com"
}
},
{
name: "Sofia Müller",
age: 24,
url: {
text: "www.google.com",
hyperlink: "http://www.google.com",
tooltip: "www.google.com"
}
}
];

Define worksheet structure

Define a worksheet with columns and rows:

let worksheets := {
Sheet1: {
columns: columns,
rows: rows
}
};

Use createXLSX

Call the createXLSX function with the defined worksheets:

my_file_field := createXLSX(this, worksheets, "example.xlsx")

Saves the created file in the Files tab of the current record and displays it in a field field of your form view.

createXLSX(this, worksheets, "example.xlsx")

Saves the file only in the Files tab of the current record.

Define styles and formatting (optional)

Apply a style to a header cell:

let columns := [{
    header: "Name",
    key: "name",
    width: 10,
    headerStyle: {
        font: {
            bold: true
        }
    }
}];

Apply style to an entire column except the header:

let columns := [{
			header: "Name",
			key: "name",
			width: 10,
			style: {
				font: {
					name: "Comic Sans MS"
				}
			}
		}]

Apply style to an entire row:

let rows := [
{
name: "Luis Gómez",
age: 30,
url: {
text: "www.google.com",
hyperlink: "http://www.google.com",
tooltip: "www.google.com"
},
			styles: [{
					fill: {
						type: "pattern",
						pattern: "solid",
						fgColor: {
							argb: "F08080"
						}
					}
				}]]
}
];

Apply style to specific cells in a row:

let rows := [
{
name: "Luis Gómez",
age: 30,
url: {
text: "www.google.com",
hyperlink: "http://www.google.com",
tooltip: "www.google.com"
},
styles: [
{
targets: ["name", "age"],
fill: {
type: "pattern",
pattern: "solid",
fgColor: {
argb: "F08080"
}
}
}
]
}
];

Finally, when you've saved your script, click the button to create an Excel file.

Supported styles and formatting options

Font

{
  font: {
    name: "Arial Black",
    color: { argb: "FF00FF00" },
    family: 2,
    size: 14,
    italic: true,
    underline: true,
    bold: true
  }
}

Font formatting options

Font property	Description	Example value(s)
name	Specifies the font name.	"Arial" "Calibri" etc.
family	Specifies the font family for fallback as an integer value.	1 - Serif 2 - Sans Serif 3 - Mon Others - unknown
scheme	Specifies the font scheme.	"minor" "major" "none"
charset	Specifies the font character set as an integer value.	1 2 etc.
size	Specifies the font size as an integer value.	9 10 12 16 etc.
color	Specifies the font color as an ARGB object.	{ argb: "FFFF0000" }
bold	Specifies whether the font is bold, indicating weight.	true false
italic	Specifies whether the font is italic, indicating slope.	true false
underline	Specifies the font underline style.	true false "none" "single" "double" "singleAccounting" "doubleAccounting"
strike	Specifies whether the font has strikethrough.	true false
outline	Specifies whether the font has an outline.	true false
vertAlign	Specifies the font's vertical alignment.	"superscript" "subscript"

Alignment

{ alignment: { vertical: "top", horizontal: "left" }

Alignment formatting options

horizontal	vertical	wrapText	shrinkToFit	indent	readingOrder	text Rotation
left	top	true	true	integer	rtl	0 to 90
center	middle	false	false		ltr	-1 to -90
right	bottom					vertical
fill	distributed
justify	justify
centerContinuous
distributed

Border

// set single thin border
{
  border: {
    top: { style: "thin" },
    left: { style: "thin" },
    bottom: { style: "thin" },
    right: { style: "thin" }
  }
}

// set double thin green border
{
  border: {
    top: { style: "double", color: { argb: "FF00FF00" } },
    left: { style: "double", color: { argb: "FF00FF00" } },
    bottom: { style: "double", color: { argb: "FF00FF00" } },
    right: { style: "double", color: { argb: "FF00FF00" } }
  }
}

// set thick red cross
{
  border: {
    diagonal: { up: true, down: true, style: "thick", color: { argb: "FFFF0000" } }
  }
}

Valid border styles

• thin
• dotted
• dashDot
• hair

• dashDotDot
• slantDashDot
• mediumDashed
• mediumDashDotDot

• mediumDashDot
• medium
• double
• thick

Patterned fill

// fill with red dark vertical stripes
{
  fill: {
    type: "pattern",
    pattern: "darkVertical",
    fgColor: { argb: "FFFF0000" }
  }
}

// fill with yellow dark trellis and blue behind
{
  fill: {
    type: "pattern",
    pattern: "darkTrellis",
    fgColor: { argb: "FFFFFF00" },
    bgColor: { argb: "FF0000FF" }
  }
}

// fill with solid coral
{
  fill: {
    type: "pattern",
    pattern: "solid",
    fgColor: { argb: "F08080" }
  }
}

// fill with blue-white-blue gradient from left to right
{
  fill: {
    type: "gradient",
    gradient: "angle",
    degree: 0,
    stops: [
      { position: 0, color: { argb: "FF0000FF" } },
      { position: 0.5, color: { argb: "FFFFFFFF" } },
      { position: 1, color: { argb: "FF0000FF" } }
    ]
  }
}

// fill with red-green gradient from center
{
  fill: {
    type: "gradient",
    gradient: "path",
    center: { left: 0.5, top: 0.5 },
    stops: [
      { position: 0, color: { argb: "FFFF0000" } },
      { position: 1, color: { argb: "FF00FF00" } }
    ]
  }
}

Pattern fill options

Property	Required	Description
type	Yes	Specifies that this fill uses a pattern.
pattern	Yes	Specifies the type of pattern. See Valid pattern types below.
fgColor	No	Specifies the pattern's foreground color. The default color is black.
bgColor	No	Specifies the pattern's background color. The default color is white.

To fill a cell using the solid pattern, you don't need to specify bgColor.

Valid pattern types

• none
• solid
• darkGray
• mediumGray
• lightGray
• gray125
• gray0625

• darkHorizontal
• darkVertical
• darkDown
• darkUp
• darkGrid
• darkTrellis

• lightHorizontal
• lightVertical
• lightDown
• lightUp
• lightGrid
• lightTrellis

Gradient fill

Property	Required	Description
type	Yes	Specifies that this fill uses a gradient.
gradient	Yes	Defines the type of gradient, which can be either "angle" or "path."
degree	angle	Indicates the gradient's direction. A value of 0 places it from left to right. Values from 1 to 359 rotate the direction clockwise.
center	path	Specifies the relative coordinates for the start of the gradient path. "Left" and "Top" values range from 0 to 1.
stops	Yes	Specifies the gradient's color sequence. An array of objects defines the position and color, starting at position 0 and ending at position 1. Additional positions can specify other colors on the path.

Supported special fields

The function supports special fields like hyperlinks, rich text, and formulas:

• Hyperlinks provide links to web content or internal references.
• Rich text allows for mixed-format text, including bold, italic, and other font styles.
• Formulas enable cells to compute values dynamically.
• Dates can be used directly from Ninox.

Hyperlink

// link to web
value := {
  text: "www.mylink.com",
  hyperlink: "http://www.mylink.com",
  tooltip: "www.mylink.com"
};
// internal link
value := {
  text: "Sheet2",
  hyperlink: "#'Sheet2'!A1"
};

Rich text (in XLSX)

value := {
  richText: [
    { text: "This is" },
    { font: {italic: true}, text: "italic" },
  ]
};

Formula (XLSX)

value := { formula: "A1+A2" };
value := { formula: "SUM(A1,A2)" };

Date (XLSX)

let columns := [{
    header: "Birthdate",
    key: "birthdate",
    width: 10,
    date: true
}];

Tips:

• Filter the selection before export when the file should contain only relevant records.
• Use a clear filename so recipients know what they received.
• Use the workbook form when you need custom columns, styles, or multiple sheets.
• Special cell values can include hyperlinks, rich text, formulas, and dates.
• Save the returned file in a file field to make it visible on the form view in a specific data context.

Bundle files with createZipFile()

Use createZipFile() to combine several files into one ZIP archive.

Use it when you want to:

• Deliver several files in one download.
• Package reports and attachments together.
• Reduce manual steps for the recipient.

createZipFile(nid, [file], string)

• nid target record
• [file] files to include
• string ZIP filename

createZipFile() returns a file object and saves it in the Files tab of the assigned nid.

Let’s take a look at some examples:

do as server
    let products := (select products).photo;
    createZipFile(this, products, "Products.zip")
end

Creates a ZIP archive with all files from the "Photo" field in the selected Products records.

do as server
    createZipFile(this, files(this), "Product.zip")
end

Creates a ZIP archive with all files attached to the current record.

do as server
    createZipFile(this, [photo], "Product.zip")
end

Creates a ZIP archive from one file in a file field by wrapping it in an array.

Tips:

• createZipFile() currently works only in server context, therefore wrap the function always in do as server ... end.
• Use files(this) when you want to ZIP all files attached to the current record.
• Wrap a single file in an array when you want to create a ZIP from one attachment.

Creating and sharing files can vary by client capabilities. Test export and sharing scripts in the environments your team uses most.

Return one or more file objects with file() and files()

Use file() when you need one file reference. Use files() when you need the full list of files attached to a record.

Use them when you want to:

• Pass file objects to other file functions.
• Pick one specific attachment by filename from a record.

file(nid, string) files(nid)

• nid record that contains the file attachment(s)
• string exact filename of the attachment you want to return

files() returns an array of file objects.

Let’s take a look at some examples:

files(this)

Returns all attachments of the current record as an array.

count(files(this))

Returns the number of attachments on the current record.

file(this, "My wanted document.pdf")

Returns the file attachment from the current record with the name "My wanted document.pdf".

Tips:

• Use files() when users can attach several files and you want all of them.
• Use file() with the record ID and exact name of the file, when a record has several attachments and you need one exact file.
• Match the filename exactly when you use the record-and-name form.

Check file details with fileMetadata()

Use fileMetadata() to inspect a file before you share, export, or process it.

Use it when you want to:

• Check file size, name or modification date.
• Read file details from a record when you know the filename.

fileMetadata(nid, string)

• nid record that contains the file attachment
• string exact filename of the attachment you want to inspect

fileMetadata() returns JSON with details such as name, size, and modifiedDate.

Let’s take a look at some examples:

fileMetadata(this, "Invoice_001.pdf")

Returns file metadata such as:

{ "name": "Invoice_001.pdf", "size": 95935, "modifiedDate": 1661385600000 }

let myName := item(split(item(split(text(invoice), ":"), 3), """"), 1);
metadata_field := fileMetadata(this, myName)

Returns the metadata for the file whose name is extracted with text and strings functions from the "Invoice" file field.

Tips:

• Check metadata before sending large or sensitive files.
• Use metadata checks in approval or export workflows.
• Use the record-and-name form when a record has several attachments and you need one exact file.
• modifiedDate is returned as a timestamp.

Rename or remove files

Use these functions when you want to manage existing files after creation, import, or export.

Rename or remove a file with renameFile() and removeFile()

Use renameFile() to change the filename. Use removeFile() to delete a file.

Use them when you want to:

• Standardize export names.
• Clean up temporary output.
• Remove outdated or incorrect files.

renameFile(file, string) renameFile(nid, string, string) removeFile(file) removeFile(nid, string)

• file file object you want to rename or remove
• string new filename for renameFile
• nid record that contains the file you want to rename or remove
• string (second argument of renameFile) current filename
• string (third argument of renameFile) new filename
• string (second argument of removeFile) exact filename you want to remove

Let’s take a look at some examples:

let myFile := createTextFile( "Hello", "notes.txt");
renameFile(myFile, "readme.txt")

Renames the file to "readme.txt".

image := renameFile(image, "A1234_Front_0729.jpg")

Renames the file in the "Image" field and updates the field with the renamed file.

renameFile(this, "Offer_0724.pdf", "Offer_0724-1.pdf")

Renames the attached file on the current record.

removeFile(Image);
Image := null

Removes the file behind the "Image" field and then clears the field reference.

removeFile(this, "Offer_0724.pdf")

Removes the file "Offer_0724.pdf" from the current record.

Tips:

• Remove files only when you are sure they are no longer needed.
• On native apps, run renameFile() and removeFile() in server context.
• Use the form removeFile(nid, string) when a record has several attachments and you want to remove one exact file.

Use record URLs to link to specific data

Use these functions when you want to create a link to a record.

Return a record URL with urlOf()

Use urlOf() to return a record URL.

Use it when you want to:

• Share a direct link to the current record.
• Store a record URL in a message or an export.
• Pass a link to another system.

urlOf(nid)

• nid the record whose URL you want to retrieve

urlOf() returns a record URL.

Let's take a look at an example:

urlOf(this)

Returns the URL of the current record.

Create a link with fileUrl()

Use fileUrl() to return a URL for a file.

Use it when you want to:

• Show or send a download link.
• Link to one specific attachment on a record.

fileUrl(nid, string)

• nid the record that contains the file attachment
• string the exact filename of the attached file you want to link to

fileUrl() returns a link.

Let’s take a look at an example:

let fileName := item(split(raw(image), """"), 11);
fileUrl(this, fileName)

Extracts the filename from the metadata of the "Image" field and returns a link to that specific file.

Tips:

• fileUrl() is designed for client-side use.
• You cannot use fileUrl() in triggers or inside do as server, do as transaction, or do as deferred blocks.
• The generated link uses information from the currently logged-in user, so it is not available in server-side execution.

Load files as Base64 for APIs and embedding

Use these functions when you need the actual file content, not just the file object or a link.

Return file content with loadFileAsBase64() and loadFileAsBase64URL()

Use loadFileAsBase64() to return raw Base64 text. Use loadFileAsBase64URL() when you need a ready data: URL.

Use them when you want to:

• Send file content to an API.
• Embed a file in generated output.
• Store binary file content as text for a follow-up request.

loadFileAsBase64(file) loadFileAsBase64(nid, string) loadFileAsBase64URL(file) loadFileAsBase64URL(nid, string)

• file the file object or supported file source to encode
• nid the record that contains the file attachment
• string the exact filename of the attachment you want to encode

loadFileAsBase64() returns the file content as a Base64 string.

loadFileAsBase64URL() returns the file content as a Base64 data URL.

Let’s take a look at some examples:

loadFileAsBase64(this, "myFoto.jpg")

Returns the attachment "myFoto.jpg" from the current record as a Base64 string.

loadFileAsBase64(photo)

Returns the file in the "Photo" field as a Base64 string.

loadFileAsBase64URL(this, "myPhoto.jpg")

Returns the attachment "myPhoto.jpg" from the current record as a Base64 data URL.

let myIm := first((select contacts where score = 100).submitted_photo);
let myWin := loadFileAsBase64URL(myIm);
winners_photo := myWin;

Retrieves the record with a "Score" of 100 from the "Contacts" table. Gets the file from the "Submitted Photo" field. The file is converted to a Base64 data URL. The URL is stored in the "Winner's photo" field. Use the value, for example, in a REST API call.

Tips:

• Base64 increases the payload size.
• Use it only when the target system really needs inline content.
• Use the record-and-name form when a record has several attachments and you need one exact file.
• Use loadFileAsBase64URL() when the target expects a ready data: URL instead of raw Base64 text.

Avoid storing large numbers of Base64 strings. If you need to keep them, use createTextFile() to convert each string into a file. Then use importFile() to save it as an attachment.