Structr

References

System Keywords

General Keywords

Built-in keywords that are available in all scripting contexts.

Markdown Rendering Hint: Children of Topic(General Keywords) not rendered because MarkdownTableFormatter prevents rendering of children.

Page Keywords

Built-in keywords that are available in page rendering contexts.

Markdown Rendering Hint: Children of Topic(Page Keywords) not rendered because MarkdownTableFormatter prevents rendering of children.

Special Keywords

Built-in keywords that are only available in special contexts.

Markdown Rendering Hint: Children of Topic(Special Keywords) not rendered because MarkdownTableFormatter prevents rendering of children.

Built-in Functions

Access Control Functions

Markdown Rendering Hint: Children of Topic(Access Control Functions) not rendered because MarkdownTableWithDetailsFormatter prevents rendering of children.

Collection Functions

Markdown Rendering Hint: Children of Topic(Collection Functions) not rendered because MarkdownTableWithDetailsFormatter prevents rendering of children.

Conversion Functions

Markdown Rendering Hint: Children of Topic(Conversion Functions) not rendered because MarkdownTableWithDetailsFormatter prevents rendering of children.

Database Functions

Markdown Rendering Hint: Children of Topic(Database Functions) not rendered because MarkdownTableWithDetailsFormatter prevents rendering of children.

Deployment Functions

Markdown Rendering Hint: Children of Topic(Deployment Functions) not rendered because MarkdownTableWithDetailsFormatter prevents rendering of children.

EMail Functions

Markdown Rendering Hint: Children of Topic(EMail Functions) not rendered because MarkdownTableWithDetailsFormatter prevents rendering of children.

Geocoding Functions

Markdown Rendering Hint: Children of Topic(Geocoding Functions) not rendered because MarkdownTableWithDetailsFormatter prevents rendering of children.

Http Functions

Markdown Rendering Hint: Children of Topic(Http Functions) not rendered because MarkdownTableWithDetailsFormatter prevents rendering of children.

Input Output Functions

Markdown Rendering Hint: Children of Topic(Input Output Functions) not rendered because MarkdownTableWithDetailsFormatter prevents rendering of children.

Logic Functions

Markdown Rendering Hint: Children of Topic(Logic Functions) not rendered because MarkdownTableWithDetailsFormatter prevents rendering of children.

MQTT Functions

Markdown Rendering Hint: Children of Topic(MQTT Functions) not rendered because MarkdownTableWithDetailsFormatter prevents rendering of children.

Mathematical Functions

Markdown Rendering Hint: Children of Topic(Mathematical Functions) not rendered because MarkdownTableWithDetailsFormatter prevents rendering of children.

Miscellaneous Functions

Markdown Rendering Hint: Children of Topic(Miscellaneous Functions) not rendered because MarkdownTableWithDetailsFormatter prevents rendering of children.

Predicate Functions

Markdown Rendering Hint: Children of Topic(Predicate Functions) not rendered because MarkdownTableWithDetailsFormatter prevents rendering of children.

Process Engine Functions

Markdown Rendering Hint: Children of Topic(Process Engine Functions) not rendered because MarkdownTableWithDetailsFormatter prevents rendering of children.

Rendering Functions

Markdown Rendering Hint: Children of Topic(Rendering Functions) not rendered because MarkdownTableWithDetailsFormatter prevents rendering of children.

Schema Functions

Markdown Rendering Hint: Children of Topic(Schema Functions) not rendered because MarkdownTableWithDetailsFormatter prevents rendering of children.

Scripting Functions

Markdown Rendering Hint: Children of Topic(Scripting Functions) not rendered because MarkdownTableWithDetailsFormatter prevents rendering of children.

Security Functions

Markdown Rendering Hint: Children of Topic(Security Functions) not rendered because MarkdownTableWithDetailsFormatter prevents rendering of children.

String Functions

Markdown Rendering Hint: Children of Topic(String Functions) not rendered because MarkdownTableWithDetailsFormatter prevents rendering of children.

System Functions

Markdown Rendering Hint: Children of Topic(System Functions) not rendered because MarkdownTableWithDetailsFormatter prevents rendering of children.

Validation Functions

Markdown Rendering Hint: Children of Topic(Validation Functions) not rendered because MarkdownTableWithDetailsFormatter prevents rendering of children.

System Types

System types are built-in types that provide core functionality in Structr. They include types for users and groups, files and folders, pages and templates, email handling, and more. Each system type comes with predefined properties and methods. You can use these types directly or extend them in your schema to add custom properties and behavior. For details on extending types, see the Data Model chapter.

DataFeed

Fetches and stores content from RSS and Atom feeds. Structr periodically checks configured feeds and creates FeedItem objects for new entries. Key properties include url for the feed location, updateInterval for automatic refresh timing, lastUpdated for tracking, and maxItems and maxAge for limiting stored entries.

Details

Feed items include title, author, publication date, content, and any enclosures like images or audio files. The updateIfDue() method checks whether enough time has passed since the last fetch and updates only when necessary. Use cleanUp() to remove old items based on your retention settings. You can extend DataFeed or FeedItem with custom properties and add an onCreate method on FeedItem to process new entries automatically – for example, sending notifications or importing content into your application.

Methods

Markdown Rendering Hint: Children of SystemType(DataFeed) not rendered because SystemTypeMarkdownFormatter prevents rendering of children.

EMailMessage

Stores email messages fetched from mailboxes or saved from outgoing mail. Key properties include subject, from, fromMail, to, cc, bcc, content (plain text), htmlContent, sentDate, receivedDate, messageId, inReplyTo for threading, header (all headers as JSON), mailbox, and attachedFiles.

Details

Attachments are stored as linked File objects in a date-based folder structure. Add an onCreate method to process incoming emails automatically – for example, creating support tickets. You can extend EMailMessage with custom properties and configure the subtype on the Mailbox via overrideMailEntityType.

Properties

Markdown Rendering Hint: Children of SystemType(EMailMessage) not rendered because SystemTypeMarkdownFormatter prevents rendering of children.

File

Represents files in Structr’s virtual filesystem. Files can live on different storage backends – local disk, Amazon S3, or archive systems – while keeping consistent metadata and permissions. Key properties include name, contentType for MIME type, size, parent for folder location, and isTemplate for dynamic content evaluation.

Details

Structr automatically calculates checksums, extracts text via Apache Tika for full-text search, and supports OCR when Tesseract is installed. Files use the same permission system as all other objects. You can extend the File type with custom properties or create subtypes like InvoiceDocument or ProductImage.

Methods

Properties

Markdown Rendering Hint: Children of SystemType(File) not rendered because SystemTypeMarkdownFormatter prevents rendering of children.

Folder

Represents directories in Structr’s virtual filesystem. The folder structure you see is independent of where files are physically stored – you can reorganize freely without moving actual data. Key properties include name, parent for the containing folder, and children for contained files and subfolders.

Details

You can mount folders to external storage locations like local directories or cloud providers, with automatic change detection. Each folder can use a different storage backend, so frequently accessed files can live on fast storage while archives go somewhere cheaper. Permissions on folders affect visibility of their contents. You can extend the Folder type or create subtypes for specialized use cases.

Properties

Markdown Rendering Hint: Children of SystemType(Folder) not rendered because SystemTypeMarkdownFormatter prevents rendering of children.

Group

Organizes users for easier permission management. Instead of granting permissions to individual users, you grant them to groups – when a user joins a group, they automatically inherit all its permissions. Key properties include name and members for the collection of users and nested groups.

Details

Groups can contain other groups, so you can build hierarchies where permissions flow down automatically. In the Admin UI, you manage membership via drag-and-drop. Groups also serve as integration points for LDAP, letting you map external directory groups to Structr. You can extend the Group type or create subtypes like Department or Team.

Methods

Properties

Markdown Rendering Hint: Children of SystemType(Group) not rendered because SystemTypeMarkdownFormatter prevents rendering of children.

Image

Extends File with specialized image handling. When you upload an image, Structr automatically extracts EXIF metadata (camera info, GPS coordinates, date taken) and stores the dimensions. Two thumbnails are generated on first access and linked to the original via database relationships.

Details

Supported formats include JPEG, PNG, GIF, WebP, and TIFF. You can scale, crop, and convert between formats. The Admin UI offers a built-in image editor and an optimized view mode for browsing image folders. With Tesseract OCR installed, Structr can extract text from images for full-text search. You can extend Image or create subtypes like ProductImage.

Methods

Properties

Markdown Rendering Hint: Children of SystemType(Image) not rendered because SystemTypeMarkdownFormatter prevents rendering of children.

MailTemplate

Defines reusable email content for automated messages like registration confirmations or password resets. Key properties include name for referencing in code, locale for language variants, and content fields for subject, plain text, and HTML body. Use ${...} expressions for dynamic values like ${link} or ${me.name}.

Details

Structr uses predefined template names for built-in workflows: CONFIRM_REGISTRATION_* for self-registration and RESET_PASSWORD_* for password reset. The Admin UI provides a Template Wizard that generates these automatically, plus a visual editor with live preview. Each template can have multiple locale variants for multi-language support.

Properties

Markdown Rendering Hint: Children of SystemType(MailTemplate) not rendered because SystemTypeMarkdownFormatter prevents rendering of children.

Mailbox

Configures an email account for automatic fetching from IMAP or POP3 servers. The MailService periodically checks all mailboxes and stores new messages as EMailMessage objects. Key properties include host, mailProtocol (imaps or pop3), port, user, password, and folders to monitor.

Details

The service fetches messages newest first, detects duplicates via Message-ID, and extracts attachments as File objects. Use overrideMailEntityType to specify a custom subtype for incoming emails, enabling lifecycle methods for automatic processing. You can trigger immediate fetching with FetchMailsCommand or list available folders with FetchFoldersCommand.

Methods

Properties

Markdown Rendering Hint: Children of SystemType(Mailbox) not rendered because SystemTypeMarkdownFormatter prevents rendering of children.

MessageClient

Methods

Markdown Rendering Hint: Children of SystemType(MessageClient) not rendered because SystemTypeMarkdownFormatter prevents rendering of children.

Page

Represents a complete web page. Structr renders pages on the server, so browsers receive ready-to-display HTML rather than JavaScript that builds the page client-side. Key properties include name (also determines the URL), contentType for output format, position for start page selection, showOnErrorCodes for error pages, and sites for multi-site hosting.

Details

Pages support template expressions for dynamic content, repeaters for collections, partial reloads without full page refresh, and show/hide conditions. Permissions control both data access and what renders – you can make entire page sections visible only to certain users. URL Routing lets you define custom paths with typed parameters that Structr validates automatically.

Properties

Markdown Rendering Hint: Children of SystemType(Page) not rendered because SystemTypeMarkdownFormatter prevents rendering of children.

Scratchpad

Methods

Markdown Rendering Hint: Children of SystemType(Scratchpad) not rendered because SystemTypeMarkdownFormatter prevents rendering of children.

Site

Controls which pages are served for which domain. A single Structr instance can host multiple websites – useful for running public and internal sites side by side, serving localized versions under country domains, or operating staging and production on the same server. Key properties include name, hostname, and an optional port for exact matching.

Details

When a request arrives, Structr checks hostname and port against configured sites and serves only the assigned pages. Pages without site assignment are served everywhere (the default behavior). A page can belong to multiple sites. Sites control page visibility only – files remain accessible regardless of domain. Site configurations are included in deployment exports.

Properties

Markdown Rendering Hint: Children of SystemType(Site) not rendered because SystemTypeMarkdownFormatter prevents rendering of children.

Template

Contains text or markup that outputs directly into pages. Unlike HTML elements, templates give you full control over where children appear – you call render(children) explicitly. This lets you define layouts with multiple insertion points like sidebars and main content areas. Key properties include name, content, contentType (Markdown, AsciiDoc, HTML, JSON, XML, plaintext), and repeater settings.

Details

The render() function controls exactly where each child appears, while include() pulls content from elsewhere in the page tree. The Main Page Template typically sits below the Page element and defines the overall structure. Templates can also produce non-HTML output by setting the content type to application/json or text/xml.

Properties

Markdown Rendering Hint: Children of SystemType(Template) not rendered because SystemTypeMarkdownFormatter prevents rendering of children.

User

Represents user accounts in your application. Every request to Structr runs in the context of a user – either authenticated or anonymous. Users can log in via HTTP headers, session cookies, JWT tokens, or OAuth providers. Key properties include name and eMail for identification, password (stored as secure hash), isAdmin for full system access, blocked for disabling accounts, and locale for localization.

Details

Structr supports two-factor authentication via TOTP and automatically locks accounts after too many failed login attempts. For self-service scenarios, users can register themselves and confirm their account via email. You can extend the User type with custom properties or create subtypes like Employee or Customer.

Methods

Properties

Markdown Rendering Hint: Children of SystemType(User) not rendered because SystemTypeMarkdownFormatter prevents rendering of children.

Widget

Provides reusable building blocks for pages – from simple HTML snippets to complete configurable components. Structr parses the widget’s HTML source when you insert it into a page. Key properties include name, source for HTML content, configuration for customizable variables (JSON), selectors for context menu suggestions, treePath for categories, and isPageTemplate for page creation.

Details

Template expressions in square brackets like [variableName] become configurable options that users fill in when inserting. The configuration JSON defines input types, defaults, and help text. Widgets can define shared components with <structr:shared-template> tags. The Widgets flyout shows both local and remote widgets, enabling sharing across applications.

Properties

Markdown Rendering Hint: Children of SystemType(Widget) not rendered because SystemTypeMarkdownFormatter prevents rendering of children.

Services

CronService

Executes user-defined functions, static schema methods and service class methods on a configurable schedule. Tasks run as superuser.

Settings

Markdown Rendering Hint: Children of Service(CronService) not rendered because ServiceMarkdownFormatter prevents rendering of children.

FtpService

Provides FTP access to Structr’s virtual filesystem. Users authenticate with their Structr credentials and see files according to their permissions.

Settings

Markdown Rendering Hint: Children of Service(FtpService) not rendered because ServiceMarkdownFormatter prevents rendering of children.

MailService

Periodically fetches emails from configured Mailbox objects via IMAP or POP3 and stores them as EMailMessage objects. Detects duplicates using Message-ID headers and extracts attachments automatically.

Settings

Related Types

Mailbox, EMailMessage

Markdown Rendering Hint: Children of Service(MailService) not rendered because ServiceMarkdownFormatter prevents rendering of children.

SSHService

Provides SSH access to an interactive Admin Console and SFTP/SSHFS access to Structr’s virtual filesystem. Only admin users can connect. Authentication requires a public key configured in the user’s publicKey property.

Settings

Markdown Rendering Hint: Children of Service(SSHService) not rendered because ServiceMarkdownFormatter prevents rendering of children.

StorageSyncService

Synchronizes the Structr filesystem (File and Folder nodes) with external storage backends. Storage providers that support synchronization monitor their backend themselves and report changes to this service, which creates, updates, moves and deletes the corresponding nodes. Replaces the former DirectoryWatchService; the old service name is still accepted in configured.services as a deprecated alias.

Configuration

A file or folder is synchronized when it is directly linked to a StorageConfiguration whose provider supports synchronization. For the local filesystem provider, mount a directory by adding a mountTarget entry to the storage configuration. The service watches for changes and periodically rescans the backend.

Folder Properties

Storage Configuration Entries

Settings

Notes

• Nested folders with their own StorageConfiguration are synchronized independently of their parent
• File contents remain in the external storage and are not imported into the database
• Changes made to files in Structr are written to the external storage by the storage provider

Markdown Rendering Hint: Children of Service(StorageSyncService) not rendered because ServiceMarkdownFormatter prevents rendering of children.

Maintenance Commands

Maintenance commands perform administrative operations on the database and application. They run with full privileges and are available only to admin users. You can execute maintenance commands through the Admin UI (Schema → Admin menu), the REST API (POST /structr/rest/maintenance/<command>), or programmatically using the maintenance() function. For details on execution methods, see the Maintenance chapter.

changeNodePropertyKey

Migrates property values from one property key to another.

Parameters

Use this command when you rename a property in your schema and need to move existing data to the new key.

clearDatabase

Removes all nodes and relationships from the database.

Notes

• Warning: This action cannot be reversed. It deletes your entire application and all data, including non-Structr nodes and relationships.

copyRelationshipProperties

Copies property values from one key to another on all relationships.

Parameters

createLabels

Updates Neo4j type labels on nodes to match their Structr type hierarchy.

Parameters

Use this command after changing type inheritance or when labels are out of sync.

The command reads each node’s type property, resolves the inheritance hierarchy, and creates a label for each type in the chain.

Notes

• Only works for nodes that have a value in their type property.

deleteSpatialIndex

Removes legacy spatial index nodes from the database.

Deletes all nodes with bbox and gtype properties.

Notes

• This is a legacy command for cleaning up old spatial indexes. You will probably never need it.

detachedNodes

Reports (and optionally repairs) DOM nodes that belong to no page.

A DOM node that has no ownerDocument still renders, because rendering walks the parent, so the
application looks healthy. Deployment export walks documents instead - the pages and the
ShadowDocument - so such a node is silently left out of the export, while every page that
references it keeps the reference. The next import then produces empty page shells, and a page
whose root element is such a node fails to import at all.

The command reports three kinds:

• ADOPTABLE: no document of its own, but an element above it has one. This is damage, and the
  repair gives it that document.
• ORPHANED_MASTER: no document and no parent, but instances of it still exist. It is a shared
  component that lost the ShadowDocument, and the repair puts it back.
• RECYCLE_BIN: no document, no parent, nothing referring to it. That is how deleted content
  looks in Structr, so it is reported and never touched.

It runs as a DRY RUN unless repair=true is passed.

Notes

• The same repair runs automatically at startup (see MigrationService), so this command is for inspecting an instance or repairing one without restarting it.

migrate

Runs the startup migrations, either reporting what they would change or applying them.

Structr migrates data and schema at startup, governed by application.migration.mode. This
command runs the same steps on a running instance, with the mode given as a parameter instead
of read from the configuration.

• mode=dry-run (default): every step runs and logs what it would change, and the change is
  rolled back. Each step is rolled back on its own, so the command never holds more in one
  transaction than that step would have committed by itself.
• mode=apply: the steps migrate for real.

Two of the steps only ever read and report: the check for notion properties that need attention,
and the report on calls to the HTTP functions that still use the pre-7.0 signature. Those run in
both modes.

The results are written to the server log, not returned to the caller.

Notes

• Unlike the dry run at startup, this one does not stop the instance: it is already running, and the rollback leaves the database as it was.
• On a cluster the migrations run on the coordinator only, so this command does nothing on the other members.

deployData

Exports or imports application data.

Parameters

Exports or imports data only, not the schema or application structure. Use this for backing up or migrating data between environments.

deploy

Exports or imports a Structr application without data.

Parameters

Exports or imports the schema, pages, files, and security configuration. The export creates a text-based format suitable for version control.

This is the same mechanism used by the Dashboard deployment feature.

directFileImport

Imports files from a server filesystem directory into Structr’s virtual filesystem.

Parameters

Notes

• When using Docker, copy files into the container first or use a mounted volume.

fixNodeProperties

Converts property values that were stored with an incorrect type.

Parameters

Use this command after changing a property’s type in the schema, for example from String to Integer.

flushCaches

Clears all internal caches.

Use this command to reduce memory consumption or resolve cache invalidation issues.

letsencrypt

Creates or renews an SSL certificate using Let’s Encrypt.

Parameters

Notes

• The letsencrypt.domains setting must contain the full domain name (or space-separated full domain names) for the certificate.
• For mode=dns, a user-defined method onAcmeChallenge is called to enable automating the creation of the required TXT records. Parameters are { type: ‘dns’, domain: , record: , digest: }.
• If a user-defined method afterAcmeChallenge exists, it will be called after a certificate retrieval. Parameters are { success: boolean, errors: [string...] }.

maintenanceMode

Enables or disables the maintenance mode.

Parameters

When the maintenance mode is started, the following services are shut down:

• FtpService
• HttpService
• SSHService
• AgentService
• CronService
• StorageSyncService
• LDAPService
• MailService

After a short delay, the following services are restarted on different ports:

• FtpService
• HttpService
• SSHService

Notes

• Active processes will keep running until they are finished. If for example a cron job is running, it will not be halted. Only the services are stopped so no new processes are started.

rebuildIndex

Rebuilds database indexes by removing and re-adding all indexed properties.

Parameters

Use this command after bulk imports or when search results are inconsistent.

setNodeProperties

Sets property values on all nodes of a given type.

Parameters

All parameters except type and newType are treated as property key-value pairs to set on matching nodes.

Notes

• Warning: After changing the type property, run createLabels to update node labels. Otherwise, nodes may not be accessible through their new type.

setRelationshipProperties

Sets property values on all relationships of a given type.

Parameters

All parameters except type are treated as property key-value pairs to set on matching relationships.

Notes

• You cannot change a relationship’s type with this command. To change the type, delete and recreate the relationship.

setUuid

Generates UUIDs for nodes and relationships that lack an id property.

Parameters

Settings

The following table lists all configuration settings available in Structr. You can view and modify these settings in the Configuration Interface, which opens in a separate browser tab when you click the wrench icon in the Admin UI header bar. The Configuration Interface requires authentication with the superuser name and password from structr.conf. Alternatively, you can edit the structr.conf file directly and restart the server.

Note: The configuration file uses Java .properties format and follows its escaping rules; certain characters are escaped when saved (e.g. the value DOMAIN\user is stored as DOMAIN\\\\user and used by the application as DOMAIN\user).

Advanced Settings

Markdown Rendering Hint: Children of Topic(Advanced Settings) not rendered because MarkdownTableWithDetailsFormatter prevents rendering of children.

Application Configuration Settings

Markdown Rendering Hint: Children of Topic(Application Configuration Settings) not rendered because MarkdownTableWithDetailsFormatter prevents rendering of children.

Cron Jobs Settings

Markdown Rendering Hint: Children of Topic(Cron Jobs Settings) not rendered because MarkdownTableWithDetailsFormatter prevents rendering of children.

Database Configuration Settings

Markdown Rendering Hint: Children of Topic(Database Configuration Settings) not rendered because MarkdownTableWithDetailsFormatter prevents rendering of children.

General Settings

Markdown Rendering Hint: Children of Topic(General Settings) not rendered because MarkdownTableWithDetailsFormatter prevents rendering of children.

LDAP Settings

Markdown Rendering Hint: Children of Topic(LDAP Settings) not rendered because MarkdownTableWithDetailsFormatter prevents rendering of children.

Licensing Settings

Markdown Rendering Hint: Children of Topic(Licensing Settings) not rendered because MarkdownTableWithDetailsFormatter prevents rendering of children.

MCP Settings

Markdown Rendering Hint: Children of Topic(MCP Settings) not rendered because MarkdownTableWithDetailsFormatter prevents rendering of children.

Mail Configuration Settings

Markdown Rendering Hint: Children of Topic(Mail Configuration Settings) not rendered because MarkdownTableWithDetailsFormatter prevents rendering of children.

Miscellaneous Settings

Markdown Rendering Hint: Children of Topic(Miscellaneous Settings) not rendered because MarkdownTableWithDetailsFormatter prevents rendering of children.

OAuth Settings

Markdown Rendering Hint: Children of Topic(OAuth Settings) not rendered because MarkdownTableWithDetailsFormatter prevents rendering of children.

Rate Limiting Settings

Markdown Rendering Hint: Children of Topic(Rate Limiting Settings) not rendered because MarkdownTableWithDetailsFormatter prevents rendering of children.

Security Settings

Markdown Rendering Hint: Children of Topic(Security Settings) not rendered because MarkdownTableWithDetailsFormatter prevents rendering of children.

Server Settings

Markdown Rendering Hint: Children of Topic(Server Settings) not rendered because MarkdownTableWithDetailsFormatter prevents rendering of children.

Servlet Settings

Markdown Rendering Hint: Children of Topic(Servlet Settings) not rendered because MarkdownTableWithDetailsFormatter prevents rendering of children.

Glossary

A