Static Entities and Structures

Quick Answer: OutSystems provides two special data constructs beyond standard entities: Static Entities, which are fixed enumerations of values defined at design time, and Structures, which are composite types that group multiple fields into a single record or DTO. Each serves a distinct purpose, and the Associate Developer exam frequently tests when to use which construct.

Static Entities as Enumerations

A Static Entity is an entity whose records are a fixed, predefined set of values defined at design time in Service Studio. Think of it as an enumeration (enum) that lives in the database. When you publish, OutSystems creates the physical table and inserts the defined records with stable identifiers. Each record in a Static Entity has an identifier and a label, and you reference individual records in your logic by name — for example, OrderStatus.Pending or CustomerType.Gold.

Static Entities are ideal for status fields, category fields, priority levels, and any domain where the value set is small, stable, and known at design time. Common examples include OrderStatus (Pending, Shipped, Delivered, Cancelled), Priority (Low, Medium, High), and Gender (Male, Female, Other). You create a Static Entity in the Data tab and add records in the Records section.

The key behavioral difference from a regular entity: you should not add, update, or delete Static Entity records at runtime. The record set is fixed at publish time and changing it requires a new publish. If you need values that users can add to at runtime (e.g., a category list that administrators maintain through a management screen), use a regular entity, not a Static Entity. The exam tests this distinction directly: Static Entity = design-time fixed enumeration that never changes without a republish; regular entity = runtime-maintained lookup table that users can add to, edit, or delete from the UI.

When you reference a Static Entity record in logic, you use the dot notation EntityName.RecordName, which resolves to the record's identifier at compile time. To compare a status attribute against a static value, you write Order.OrderStatusId = OrderStatus.Pending, not a string comparison like Order.StatusText = "Pending". This type-safe reference prevents typos and breaks at compile time if a record is renamed or removed — a key advantage over string-based enumerations that only fail at runtime.

A critical property of Static Entity records: their identifiers are stable across environments. When you publish to development, test, and production, the same Static Entity record has the same identifier value. This stability is why you can safely reference OrderStatus.Pending by name in logic without worrying about environment-specific ID values.

Structures as Composite Types

A Structure is a composite data type that groups multiple fields of different types into a single named unit. Structures do NOT map to database tables — they have no physical storage. They exist only in memory and are used to shape data flowing between screens, actions, and external integrations. A Structure is the OutSystems equivalent of a DTO (Data Transfer Object) or a record type in other languages.

You define a Structure in the Data tab of Service Studio by adding fields with types. Each field can be any OutSystems data type (Text, Integer, Decimal, Boolean, Date Time), another Structure for nesting, or even an entity identifier type. Structures can nest: a CustomerDTO Structure might contain a BillingAddress Structure as one of its fields, enabling hierarchical data shapes that mirror complex API payloads.

Structures are essential when consuming REST APIs. When you add a consumed REST API method, the platform asks you to define or select a Structure that represents the response JSON. The Structure's fields map to JSON properties by name, and nested JSON objects map to nested Structures.

When to Use Each

Use a Static Entity when you have a fixed set of named values that represent a domain enumeration and you want type-safe references backed by database storage for a reference attribute. The Static Entity becomes the type of a reference attribute on another entity, creating a foreign-key-like relationship that enforces referential integrity at the database level. For example, an Order entity's StatusId attribute would be of type OrderStatus Identifier, linking to the Static Entity.

Use a Structure when you need to pass a shaped bundle of data between logic components without persisting it. The most common scenarios are: shaping a consumed REST API response (the external service returns JSON that maps to a Structure's fields, with nested objects mapping to nested Structures), grouping multiple action output parameters into a single return value for cleaner action signatures, and defining the shape of a local variable that holds intermediate computed results.

A frequent exam trap: you cannot use a Structure as an entity attribute type. Entity attributes hold primitive types (Text, Integer, Decimal, Boolean, Date Time) or references to other entities via typed identifiers. Structures are for parameters and variables only. Conversely, you should not use a regular entity where a Static Entity is appropriate — if the value set is fixed and known at design time, a Static Entity gives you compile-time safety that a regular entity cannot provide.