Start free trial

Custom Fields

Updated 2 May 2026 MaSH

Custom Fields - dynamic metadata for Files

Foldr allows users to assign custom metadata to files using Custom Fields. These field values can also be assigned by extracting data from documents using Foldr Captur. In MaSH we can read from and write to these custom fields.

Custom Field Types

Custom Fields in Foldr are configured to contain a specific data type. Foldr will transform input into the correct type when the field’s data is set. These types are string, text, number, boolean and date.

The Fields Property

A File’s Custom Fields are accessible via its fields property. This returns a dictionary-like object which allows us to interact with the fields and their data. The keys in the dictionary correspond to the names of the custom fields.

Natural

set myFile to mash.files.get(12, "path/to/file.txt", "b8236683-6426-4658-bf6f-0e78068ca327")

printline myFile.fields.all()

Standard

myFile = mash.files.get(12, "path/to/file.txt", "b8236683-6426-4658-bf6f-0e78068ca327")

printline(myFile.fields.all())

Output

Collection {
  "Issued": {
	  "id": 2,
	  "name": "Issued",
	  "type": 4,
	  "multivalue": false,
	  "extra": null,
	  "created_at": "2020-11-09 16:37:05",
	  "updated_at": "2020-11-09 16:37:05",
	  "data": [
		  {
			  "id": 1830459,
			  "data": "2021-12-01T09:00:40+00:00",
			  "input": "2021-12-01T09:00:40.042Z",
			  "order_column": 0,
			  "extra": null,
			  "user_id": "cc039b6f-128d-40ce-be04-e1cd888b113c",
			  "context_user_id": "cc039b6f-128d-40ce-be04-e1cd888b113c",
			  "updated_by": null,
			  "created_at": "2022-02-16 09:34:56",
			  "updated_at": "2022-02-16 09:34:56"
		  }
	  ]
  },
  "Items": {
	  "id": 52,
	  "name": "Items",
	  "type": 0,
	  "multivalue": true,
	  "extra": null,
	  "created_at": "2021-07-08 09:23:04",
	  "updated_at": "2021-07-08 11:08:39",
	  "data": [
		  {
			  "id": 177634,
			  "data": "FDR-D-20U-BUS",
			  "input": "FDR-D-20U-BUS",
			  "order_column": 125430,
			  "extra": {
				  "page": 1,
				  "table": {
					  "page": 1,
					  "row": 0,
					  "column": 0
				  }
			  },
			  "user_id": "__captur__",
			  "context_user_id": null,
			  "updated_by": null,
			  "created_at": "2021-08-01 12:09:49",
			  "updated_at": "2021-08-01 12:09:49"
		  },
		  {
			  "id": 177636,
			  "data": "FDR-D-1U+-BUS",
			  "input": "FDR-D-1U+-BUS",
			  "order_column": 125432,
			  "extra": {
				  "page": 1,
				  "table": {
					  "page": 1,
					  "row": 1,
					  "column": 0
				  }
			  },
			  "user_id": "__captur__",
			  "context_user_id": null,
			  "updated_by": null,
			  "created_at": "2021-08-01 12:09:49",
			  "updated_at": "2021-08-01 12:09:49"
		  }
	  ]
  }
}

Field Objects

The fields object on a file contains all of the individual field objects. The whole object can be iterated using loops and individual field objects can be retrieved using the get method.

Natural

set myFile to mash.files.get(12, "path/to/file.txt", "b8236683-6426-4658-bf6f-0e78068ca327")

printline myFile.fields.get("Issued")

printline

each myFile.fields as key, field
	printline field
end

Standard

myFile = mash.files.get(12, "path/to/file.txt", "b8236683-6426-4658-bf6f-0e78068ca327")

printline(myFile.fields.get("Issued"))

printline

each (myFile.fields as key, field) {
	printline(field)
}

Output

CustomField {
	"id": 2,
	"name": "Issued",
	"type": 4,
	"multivalue": false,
	"extra": null,
	"created_at": "2020-11-09 16:37:05",
	"updated_at": "2020-11-09 16:37:05",
	"data": [
		{
			"id": 1830459,
			"data": "2021-12-01T09:00:40+00:00",
			"input": "2021-12-01T09:00:40.042Z",
			"order_column": 0,
			"extra": null,
			"user_id": "cc039b6f-128d-40ce-be04-e1cd888b113c",
			"context_user_id": "cc039b6f-128d-40ce-be04-e1cd888b113c",
			"updated_by": null,
			"created_at": "2022-02-16 09:34:56",
			"updated_at": "2022-02-16 09:34:56"
		}
	]
}

CustomField {
	"id": 2,
	"name": "Issued",
	"type": 4,
	"multivalue": false,
	"extra": null,
	"created_at": "2020-11-09 16:37:05",
	"updated_at": "2020-11-09 16:37:05",
	"data": [
		{
			"id": 1830459,
			"data": "2021-12-01T09:00:40+00:00",
			"input": "2021-12-01T09:00:40.042Z",
			"order_column": 0,
			"extra": null,
			"user_id": "cc039b6f-128d-40ce-be04-e1cd888b113c",
			"context_user_id": "cc039b6f-128d-40ce-be04-e1cd888b113c",
			"updated_by": null,
			"created_at": "2022-02-16 09:34:56",
			"updated_at": "2022-02-16 09:34:56"
		}
	]
}
CustomField {
	"id": 52,
	"name": "Items",
	"type": 0,
	"multivalue": true,
	"extra": null,
	"created_at": "2021-07-08 09:23:04",
	"updated_at": "2021-07-08 11:08:39",
	"data": [
		{
			"id": 177634,
			"data": "FDR-D-20U-BUS",
			"input": "FDR-D-20U-BUS",
			"order_column": 125430,
			"extra": {
				"page": 1,
				"table": {
					"page": 1,
					"row": 0,
					"column": 0
				}
			},
			"user_id": "__captur__",
			"context_user_id": null,
			"updated_by": null,
			"created_at": "2021-08-01 12:09:49",
			"updated_at": "2021-08-01 12:09:49"
		},
		{
			"id": 177636,
			"data": "FDR-D-1U+-BUS",
			"input": "FDR-D-1U+-BUS",
			"order_column": 125432,
			"extra": {
				"page": 1,
				"table": {
					"page": 1,
					"row": 1,
					"column": 0
				}
			},
			"user_id": "__captur__",
			"context_user_id": null,
			"updated_by": null,
			"created_at": "2021-08-01 12:09:49",
			"updated_at": "2021-08-01 12:09:49"
		}
	]
}

Accessing Field Objects and their values

Accessing a specific field by name using array access or dot notation within a file’s fields object provides a shortcut to its data.

Natural

set myFile to mash.files.get(12, "path/to/file.txt", "b8236683-6426-4658-bf6f-0e78068ca327")

# Access a specific field's data using array access
printline myFile.fields["Issued"]

# Access a specific field's data using dot notation
printline myFile.fields.Issued

Standard

myFile = mash.files.get(12, "path/to/file.txt", "b8236683-6426-4658-bf6f-0e78068ca327")

# Access a specific field's data using array access
printline(myFile.fields["Issued"])

# Access a specific field's data using dot notation
printline(myFile.fields.Issued)

Output

2021-12-01T09:00:40+00:00

Notes

If a field name contains a space you must access its data using array access and not dot notation.

Storing and updating field data

Field data can be updated by setting the value using array access or dot notation on the fields object. Foldr’s Custom Fields are fairly smart when it comes to transforming input data to match their field type.

Natural

set myFile to mash.files.get(12, "path/to/file.txt", "b8236683-6426-4658-bf6f-0e78068ca327")

# Access a specific field's data using array access
printline myFile.fields["Issued"]

set now to mash.date()

# Set a specific field's data using dot notation
set myFile.fields.Issued to now

printline myFile.fields.Issued

# Set a date field's data using a string. In this instance, where possible, Foldr will convert this into a valid date object.
set myFile.fields.Issued to "today at 2pm"

printline myFile.fields.Issued

Standard

myFile = mash.files.get(12, "path/to/file.txt", "b8236683-6426-4658-bf6f-0e78068ca327")

printline(myFile.fields["Issued"])

now = mash.date()

# Set a specific field's data using dot notation
myFile.fields.Issued = now

printline(myFile.fields.Issued)

# Set a date field's data using a string. In this instance, where possible, Foldr will convert this into a valid date object.
myFile.fields.Issued = "today at 2pm"

printline(myFile.fields.Issued)

Output

2021-12-01T09:00:40+00:00
2022-02-16T10:00:00+00:00
2022-02-16T14:00:00+00:00

← All articles