---
name: system-module
description: "Reference for the built-in System module — User, FileDocument, Image, workflow and queue entities, and the associations you are allowed to make to them. Use when linking a record to System.User, handling file uploads, or working with workflow entities."
---

# Mendix System Module Reference

The `System` module is a built-in Mendix module present in every application. It provides core entities for user management, file handling, workflows, task queues, HTTP services, and more. These entities are not defined in the application's domain model but are available for use in microflows, pages, associations, and Java actions.

## Access to System entities has a ceiling

**No project module can widen access to `System.User`, `System.Workflow` or
`System.WorkflowUserTask`.** Their access comes from the System module's own roles,
and a `grant` in your module cannot raise it — so any UI over them is
Administrator-only unless the data is denormalised into your own entities or reached
through a microflow data source (microflows bypass entity access by default).

It fails **silently**: a combo box over `System.User` lists the current user only, a
grid over `System.Workflow` renders empty, and both `mx check` and `mxcli lint` pass.
See the System-module ceiling section in [manage-security](../manage-security/SKILL.md)
for the three ways around it.

## Reference files

- [`reference/workflow-and-queues.md`](reference/workflow-and-queues.md) — the
  workflow engine's entities (`WorkflowInstance`, `UserTask`, the state
  enumerations and how they relate), plus task queues and scheduled events. Open
  it when querying workflow state or wiring anything to a queue.

## When to Use This Skill

Use this skill when:
- Creating associations to System entities (e.g., linking a record to `System.User`)
- Working with file uploads/downloads (`System.FileDocument`, `System.Image`)
- Implementing workflow-related features
- Writing microflows that reference System types
- Understanding what's available out of the box in Mendix
- Designing security models that reference `System.User` and `System.UserRole`

## How to Reference System Entities

In MDL, reference System entities with the `System.` prefix:

```mdl
-- Association to the current user. The direction is not a style choice: YOUR
-- entity must be the FROM side (see "The FROM entity must be yours" below).
create association MyModule.Order_CreatedBy
from MyModule.Order to System.User
type reference;

-- Entity that generalizes FileDocument for file uploads
create persistent entity MyModule.Invoice extends System.FileDocument (
  InvoiceNumber: string(50),
  IssueDate: datetime
);

-- Entity that generalizes Image for image uploads
create persistent entity MyModule.ProductPhoto extends System.Image (
  PhotoCaption: string(200),
  IsPrimary: boolean default false
);
```

### The FROM entity must be yours

An association is stored in the module of its **FROM** entity — Mendix has no
other place to put it. So `from System.User to MyModule.Order` is not a
differently-shaped association; it is one Mendix cannot store. Written anyway,
its `ParentPointer` names an element in the System unit and the **project stops
opening**:

```
KeyNotFoundException: The given key '4a25f08b-…' was not present in the dictionary
  at StreamingBsonUnitReader.ResolvePostponedProperties()
```

That is a *load* failure, not a build error, so Studio Pro cannot open it either
and the stack trace names no document. mxcli refuses it as **MDL070** at check
time, before anything is written.

This is not about System. Any remote FROM module does the same thing —
`create association MyModule.X from Administration.Account to MyModule.Y` fails
identically. The rule is the module boundary.

Three ways out, in the order to consider them:

| Situation | Do this |
|---|---|
| The FK genuinely belongs on your entity | Reverse it: `from MyModule.Order to System.User` |
| Many-to-many across the boundary | A **join entity** in your module with a reference to each side |
| The association really belongs to the other module | Declare it there — but never in `System` or a Marketplace module, which must not be written to |

The join entity is usually the better model anyway: a row that says "this user
plans this department" is something you can hang attributes and XPath
constraints on, which a bare reference set is not.


---

## 1. User Management & Authentication

### System.User

The central user entity. All application users are instances of `System.User` or a specialization (e.g., `Administration.Account`).

| Attribute | Type | Description |
|-----------|------|-------------|
| Name | String | Username (login name) |
| Password | String | Hashed password (write-only) |
| LastLogin | DateTime | Timestamp of last successful login |
| Blocked | Boolean | Whether user account is blocked |
| BlockedSince | DateTime | When the account was blocked |
| Active | Boolean | Whether the account is active |
| FailedLogins | Integer | Count of consecutive failed login attempts |
| WebServiceUser | Boolean | Whether this is a web service account |
| IsAnonymous | Boolean | Whether this is an anonymous user |

| Association | Target | Type | Description |
|-------------|--------|------|-------------|
| UserRoles | System.UserRole | Many-to-Many | Roles assigned to this user. In XPath it is `System.UserRoles` — **not** `System.User_UserRoles`, which fails the build with CE1613 "The selected association … no longer exists" |
| User_Language | System.Language | Many-to-One | User's preferred language |
| User_TimeZone | System.TimeZone | Many-to-One | User's timezone |

**Common usage patterns:**
- Associate application entities to `System.User` for audit trails (CreatedBy, ModifiedBy)
- Specialize `System.User` (via `Administration.Account`) to add custom profile attributes
- Use `[%CurrentUser%]` token in XPath to filter by logged-in user
- Check `$user/Active` and `$user/Blocked` for access control

### System.UserRole

Represents an application user role (e.g., Administrator, User, Manager).

| Attribute | Type | Description |
|-----------|------|-------------|
| ModelGUID | String | GUID from the model definition |
| Name | String | Role name as defined in the model |
| Description | String | Role description |

| Association | Target | Type | Description |
|-------------|--------|------|-------------|
| UserRole_GrantableRoles | System.UserRole | Many-to-Many | Roles that holders of this role can assign to others |

### System.Session

Active user sessions.

| Attribute | Type | Description |
|-----------|------|-------------|
| SessionId | String | Unique session identifier |
| CSRFToken | String | Cross-site request forgery token |
| LastActive | DateTime | Last activity timestamp |

| Association | Target | Type | Description |
|-------------|--------|------|-------------|
| Session_User | System.User | Many-to-One | User who owns this session |

### System.Language

Available languages for internationalization.

| Attribute | Type | Description |
|-----------|------|-------------|
| Code | String | Language code (e.g., `en_US`, `nl_NL`) |
| Description | String | Human-readable language name |

### System.TimeZone

Available time zones.

| Attribute | Type | Description |
|-----------|------|-------------|
| Code | String | Timezone identifier (e.g., `Europe/Amsterdam`) |
| Description | String | Human-readable timezone name |
| RawOffset | Integer | Offset from UTC in milliseconds |

### System.TokenInformation

Authentication tokens (e.g., for "remember me" or API tokens).

| Attribute | Type | Description |
|-----------|------|-------------|
| Token | String | Hashed token value (write-only) |
| ExpiryDate | DateTime | When the token expires |
| UserAgent | String | Browser/client user agent |

| Association | Target | Type | Description |
|-------------|--------|------|-------------|
| TokenInformation_User | System.User | Many-to-One | User who owns this token |

---

## 2. File Management

### System.FileDocument

Base entity for all file storage. Specialize this entity to create custom file types.

| Attribute | Type | Description |
|-----------|------|-------------|
| FileID | Long | Internal file identifier |
| Name | String | File name (including extension) |
| DeleteAfterDownload | Boolean | Auto-delete after first download |
| Contents | Binary | The file binary content |
| HasContents | Boolean | Whether file content has been uploaded |
| Size | Long | File size in bytes |

**Usage:** Create a specialization to store typed files:

```mdl
create persistent entity MyModule.Attachment extends System.FileDocument (
  description: string(500),
  Category: MyModule.AttachmentCategory
);

create association MyModule.Order_Attachments
from MyModule.Order to MyModule.Attachment
type reference_set;
```

### System.Image

Extends `System.FileDocument` with image-specific features.

| Attribute | Type | Description |
|-----------|------|-------------|
| PublicThumbnailPath | String | Path to auto-generated thumbnail |
| EnableCaching | Boolean | Whether the browser should cache this image |

**Usage:** Specialize for application images:

```mdl
create persistent entity MyModule.ProductPhoto extends System.Image (
  PhotoCaption: string(200),
  SortOrder: integer default 0
);
```

### System.SynchronizationErrorFile

File attachment for offline synchronization errors. Extends `System.FileDocument`.

---

## 3. HTTP / Web Services

### System.HttpMessage (base, non-persistent)

Base entity for HTTP messages. Not stored in the database.

| Attribute | Type | Description |
|-----------|------|-------------|
| HttpVersion | String | HTTP version (e.g., `1.1`) |
| Content | String | Message body content |

### System.HttpRequest (extends HttpMessage, non-persistent)

| Attribute | Type | Description |
|-----------|------|-------------|
| Uri | String | Request URI |

### System.HttpResponse (extends HttpMessage, non-persistent)

| Attribute | Type | Description |
|-----------|------|-------------|
| StatusCode | Integer | HTTP status code (200, 404, 500, etc.) |
| ReasonPhrase | String | Status reason phrase |

### System.HttpHeader (non-persistent)

| Attribute | Type | Description |
|-----------|------|-------------|
| Key | String | Header name |
| Value | String | Header value |

| Association | Target | Type | Description |
|-------------|--------|------|-------------|
| HttpHeaders | System.HttpMessage | Many-to-One | Parent HTTP message |

**Usage:** These entities are used in published/consumed REST services and Java actions that handle HTTP requests and responses directly.

### System.ConsumedODataConfiguration

Configuration for consumed OData services.

| Attribute | Type | Description |
|-----------|------|-------------|
| ServiceUrl | String | OData service endpoint URL |
| ProxyConfiguration | Enum (ProxyConfiguration) | Proxy setting: UseAppSettings, Override, NoProxy |
| ProxyHost | String | Proxy hostname (when Override) |
| ProxyPort | Integer | Proxy port (when Override) |
| ProxyUsername | String | Proxy authentication username |
| ProxyPassword | String | Proxy authentication password |

### System.ODataResponse

| Attribute | Type | Description |
|-----------|------|-------------|
| Count | Long | Total record count from OData response |

---

## 4. Error Handling

### System.Error (non-persistent)

| Attribute | Type | Description |
|-----------|------|-------------|
| ErrorType | String | Error category/type |
| Message | String | Error message |
| Stacktrace | String | Full stack trace |

### System.SoapFault (extends Error, non-persistent)

SOAP-specific fault information. Extends `System.Error` with SOAP fault details.

### System.SynchronizationError

Tracks offline mobile synchronization failures.

| Attribute | Type | Description |
|-----------|------|-------------|
| Reason | String | Why synchronization failed |
| ObjectId | String | ID of the object that failed |
| ObjectType | String | Entity type of the failed object |
| ObjectContent | String | Serialized state of the object |

---

## 7. Utility Entities

### System.Paging (non-persistent)

Paging information for data retrieval in custom Java actions.

| Attribute | Type | Description |
|-----------|------|-------------|
| PageNumber | Long | Current page number |
| IsSortable | Boolean | Whether sorting is supported |
| SortAttribute | String | Attribute to sort by |
| SortAscending | Boolean | Sort direction |
| HasMoreData | Boolean | Whether more pages exist |

### System.UserReportInfo

Information for user management reports (internal use).

### System.ProxyConfiguration

HTTP proxy settings (internal use).

---

## 8. Enumerations

Inspect any of these from the CLI rather than copying from here — the values are
**case-sensitive**, and a wrong one is only caught at build time as **CE1613**
"The selected enumeration value no longer exists":

```bash
mxcli -p app.mpr describe enumeration System.WorkflowActivityType
mxcli -p app.mpr show enumerations            # includes the System module
```

Two of these names are easy to confuse, and mixing them up is the mistake that
CE1613 usually reports: **`WorkflowActivityState`** has `Finished`, while
**`WorkflowActivityExecutionState`** has `Completed`. They are different
enumerations on different entities.

System enumerations are **read-only** — they are built into the platform, not
stored in the project, so `create`/`alter`/`drop`/`move enumeration System.…` is
refused. `describe` prints them as `--` comment lines for that reason.

### ContextType
`System`, `User`, `Anonymous`, `ScheduledEvent`

### DeviceType
`Phone`, `Tablet`, `Desktop`

### EventStatus
`Running`, `Completed`, `Error`, `Stopped`

### ProxyConfiguration
`UseAppSettings`, `Override`, `NoProxy`

### QueueTaskStatus
`Idle`, `Running`, `Completed`, `Failed`, `Retrying`, `Aborted`, `Incompatible`

### UnreferencedFileState
`New`, `Obsolete`, `Deleted`

### UserType
`Internal`, `External`

### WorkflowActivityExecutionState
`Created`, `InProgress`, `Completed`, `Paused`, `Aborted`, `Failed`

### WorkflowActivityState
`Started`, `Suspended`, `Finished`, `Replaced`, `Aborted`, `Failed`

### WorkflowActivityType
`Start`, `End`, `ExclusiveSplit`, `ParallelSplit`, `ParallelSplitBranchStopper`, `ParallelSplitMerge`, `UserTask`, `CallMicroflow`, `CallWorkflow`, `JumpTo`, `MultiInputUserTask`, `WaitForNotification`, `WaitForTimer`, `EndOfBoundaryEventPath`, `NonInterruptingTimerEvent`, `InterruptingTimerEvent`

### WorkflowCurrentActivityAction
`DoNothing`, `JumpTo`

### WorkflowEventType
`WorkflowCompleted`, `WorkflowInitiated`, `WorkflowRestarted`, `WorkflowFailed`, `WorkflowAborted`, `WorkflowPaused`, `WorkflowUnpaused`, `WorkflowRetried`, `WorkflowUpdated`, `WorkflowUpgraded`, `WorkflowConflicted`, `WorkflowResolved`, `WorkflowJumpToOptionApplied`, `StartEventExecuted`, `EndEventExecuted`, `DecisionExecuted`, `JumpExecuted`, `ParallelSplitExecuted`, `ParallelMergeExecuted`, `CallWorkflowStarted`, `CallWorkflowEnded`, `CallMicroflowStarted`, `CallMicroflowEnded`, `WaitForNotificationStarted`, `WaitForNotificationEnded`, `WaitForTimerStarted`, `WaitForTimerEnded`, `UserTaskStarted`, `MultiUserTaskOutcomeSelected`, `UserTaskEnded`, `NonInterruptingTimerEventExecuted`, `InterruptingTimerEventExecuted`

### WorkflowState
`InProgress`, `Paused`, `Completed`, `Aborted`, `Incompatible`, `Failed`

### WorkflowUserTaskCompletionType
`Single`, `Veto`, `Consensus`, `Majority`, `Threshold`, `Microflow`

### WorkflowUserTaskState
`Created`, `InProgress`, `Completed`, `Paused`, `Aborted`, `Failed`

## 9. Inheritance Hierarchies

```
System.User
  └── Administration.Account (adds FullName, Email, etc.)

System.FileDocument
  ├── System.Image
  └── System.SynchronizationErrorFile

System.HttpMessage (non-persistent)
  ├── System.HttpRequest
  └── System.HttpResponse

System.Error (non-persistent)
  └── System.SoapFault
```

**Key point for MDL:** When creating entities that store files or images, use `extends`:

```mdl
create persistent entity MyModule.Document extends System.FileDocument (
  title: string(200),
  version: integer default 1
);

create persistent entity MyModule.Photo extends System.Image (
  AltText: string(200)
);
```

## 10. Common Patterns

### Audit Trail (CreatedBy / ModifiedBy)

```mdl
create association MyModule.Order_CreatedBy
from MyModule.Order to System.User
type reference;

create association MyModule.Order_ModifiedBy
from MyModule.Order to System.User
type reference;
```

### File Attachments

```mdl
create persistent entity MyModule.Attachment extends System.FileDocument (
  description: string(500)
);

create association MyModule.Order_Attachments
from MyModule.Order to MyModule.Attachment
type reference_set;
```

### Workflow Context Object

```mdl
-- Application entity that serves as workflow context
create persistent entity MyModule.ExpenseReport (
  Amount: decimal,
  description: string(500),
  status: MyModule.ApprovalStatus default 'Draft'
);

-- Associate with workflow instance
create association MyModule.ExpenseReport_Workflow
from MyModule.ExpenseReport to System.Workflow
type reference;
```

### Task Inbox Page

User tasks can be displayed in pages by retrieving `System.WorkflowUserTask` where the current user is in the target users or assignees.

### XPath Tokens for System Entities

```
[%CurrentUser%]     -- The logged-in System.User
[%CurrentObject%]   -- The current context object
```

## Source

This reference was extracted from the Java proxy files in `javasource/system/proxies/` of a Mendix 10.x application. The System module domain model is not exposed in MPR/BSON files but is defined internally by the Mendix runtime. Proxy files serve as the definitive reference for available entities, attributes, and associations.